واجهة Ultralytics لـ LLM#

إنَّ LLM واجهة صغيرة لاستدعاء نماذج اللغة والرؤية من خلال API متوافق مع OpenAI. وهي تجهّز إدخالًا نصيًا أو صوريًا، وتمرير وسائط الطلب إلى OpenAI Python SDK الرسمي، وتعيد كائن الاستجابة الأصلي الخاص بـ SDK. وهذا يسهّل إضافة الاستدلال اللغوي أو البصري بجوار مسار YOLO من دون تغليف أنواع الاستجابات الخاصة بكل مزوّد.

واجهة API الافتراضية هي responses؛ استخدم api="chat.completions" مع المزوّدين الذين يطبّقون Chat Completions فقط.

التثبيت#

ثبّت Ultralytics مع تبعية LLM الاختيارية:

pip install "ultralytics[llm]"

بالنسبة إلى OpenAI، عيّن مفتاح API في البيئة:

export OPENAI_API_KEY="your-api-key"

Responses API#

واجهة Responses API هي الافتراضية. مرّر مطالبة واقرأ output_text:

from ultralytics import LLM

llm = LLM("gpt-5.6-luna")
response = llm("What is YOLO?")
print(response.output_text)

الإدخال متعدد الوسائط#

مرّر مسارًا أو عنوان URL عبر HTTP أو URI للبيانات أو مصفوفة NumPy أو صورة PIL من خلال image:

from ultralytics import LLM

llm = LLM("gpt-5.6-luna")
response = llm("What is happening in this image?", image="https://ultralytics.com/images/bus.jpg")
print(response.output_text)

تُرمَّز الملفات المحلية وكائنات الصور بصيغة URI لبيانات JPEG. وتستخدم مصفوفات NumPy ترتيب قنوات BGR الخاص بـ OpenCV. وتُعامَل السلسلة النصية المُمرَّرة بصفتها source، مثل llm("bus.jpg")، على أنها نص؛ استخدم الوسيطة image لإرسال صورة.

استخدم prompt لتحديد تعليمة مشتركة بين كل طلب:

llm = LLM("gpt-5.6-luna", prompt="Answer in one sentence.")
response = llm("Describe this image.", image="bus.jpg")

Chat Completions#

حدّد Chat Completions عندما تكون مطلوبة من نقطة النهاية، واقرأ بنية استجابتها الأصلية:

from ultralytics import LLM

llm = LLM("gpt-5.6-luna", api="chat.completions")
response = llm("What is non-maximum suppression?")
print(response.choices[0].message.content)

تقبل الواجهة نفسها إدخالًا متعدد الوسائط:

response = llm("Describe this image.", image="bus.jpg")
print(response.choices[0].message.content)

مرّر كائنات الرسائل الأصلية عندما تحتاج إلى سجل المحادثة. ويُعاد تمريرها دون تغيير.

البث والاستدعاءات غير المتزامنة#

تُمرَّر وسائط طلبات SDK دون تغيير، بما في ذلك stream=True:

llm = LLM("gpt-5.6-luna")
for event in llm("Explain object detection.", stream=True):
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

استخدم async_call للطلبات المتزامنة:

import asyncio

from ultralytics import LLM

llm = LLM("gpt-5.6-luna")

async def main():
    response = await llm.async_call("What is YOLO?")
    print(response.output_text)

asyncio.run(main())

المزوّدون المتوافقون مع OpenAI#

يعمل LLM مع المزوّدين الذين يوفّرون Responses API أو Chat Completions API متوافقًا مع OpenAI، بما في ذلك DeepSeek وKimi وZ.AI GLM وOpenRouter. عيّن base_url الخاص بالمزوّد، واسم النموذج، ومفتاح API:

from ultralytics import LLM

llm = LLM(
    "provider-model",
    api="chat.completions",
    base_url="https://provider.example/v1",
    api_key="your-api-key",
)
response = llm("What tasks does YOLO support?")
print(response.choices[0].message.content)

يعمل الإعداد نفسه مع الخوادم المحلية المتوافقة. وتختلف أسماء النماذج ودعم الصور ووسائط الطلب وواجهات API المدعومة باختلاف المزوّد، لذا راجع وثائقه المرتبطة.

دمج YOLO مع LLM#

شغّل YOLO أولًا، ثم استدعِ LLM فقط عند اكتشاف شخص:

from ultralytics import LLM, YOLO

yolo = YOLO("yolo26n.pt")
llm = LLM("gpt-5.6-luna")
image = "https://ultralytics.com/images/bus.jpg"

result = yolo(image)[0]
# Call the LLM only when YOLO detects a person.
if any(result.names[int(cls)] == "person" for cls in result.boxes.cls):
    response = llm("Describe the scene.", image=image)
    print(response.output_text)

مرجع API#

يقبل source نصًا أو قائمة رسائل أصلية أو كائن صورة. ويقبل image عنوان URL لصورة أو URI لبيانات أو مسارًا أو مصفوفة NumPy أو صورة PIL. ويؤدي استدعاء model() مع ضبط prompt إلى إرسال المطالبة وحدها.

إنَّ LLM مخصص للاستدلال فقط، ولا يُتاح من خلال CLI الخاص بـ yolo. ولا يطبّق train أو val أو export أو track أو benchmark.

الأسئلة الشائعة#