Interfaccia LLM di Ultralytics#

LLM è una piccola interfaccia per chiamare modelli linguistici e di visione tramite un'API compatibile con OpenAI. Prepara input testuali o immagini, inoltra gli argomenti della richiesta all'SDK ufficiale OpenAI per Python e restituisce l'oggetto di risposta nativo dell'SDK. Questo semplifica l'aggiunta di funzionalità di ragionamento linguistico o visivo accanto a una pipeline YOLO, senza dover racchiudere i tipi di risposta specifici dei diversi provider.

L'API predefinita è responses; usa api="chat.completions" per i provider che implementano solo Chat Completions.

Installazione#

Installa Ultralytics con la dipendenza LLM opzionale:

pip install "ultralytics[llm]"

Per OpenAI, imposta la chiave API nell'ambiente:

export OPENAI_API_KEY="your-api-key"

API Responses#

L'API Responses è quella predefinita. Passa un prompt e leggi output_text:

from ultralytics import LLM

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

Input multimodale#

Passa un percorso, un URL HTTP, un URI dati, un array NumPy o un'immagine PIL tramite 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)

I file locali e gli oggetti immagine vengono codificati come URI dati JPEG. Gli array NumPy utilizzano l'ordine dei canali BGR di OpenCV. Una stringa passata come source, ad esempio llm("bus.jpg"), viene trattata come testo; usa l'argomento image per inviare un'immagine.

Usa prompt per un'istruzione condivisa da ogni richiesta:

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

Chat Completions#

Seleziona Chat Completions quando richiesto dall'endpoint e leggi il relativo formato di risposta nativo:

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)

La stessa interfaccia accetta input multimodali:

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

Passa oggetti messaggio nativi quando ti serve la cronologia della conversazione. Vengono inoltrati senza modifiche.

Chiamate in streaming e asincrone#

Gli argomenti della richiesta dell'SDK vengono inoltrati senza modifiche, incluso 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)

Usa async_call per le richieste simultanee:

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())

Provider compatibili con OpenAI#

LLM funziona con i provider che espongono un'API Responses o Chat Completions compatibile con OpenAI, inclusi DeepSeek, Kimi, Z.AI GLM e OpenRouter. Imposta base_url, il nome del modello e la chiave API del provider:

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)

La stessa configurazione funziona con i server locali compatibili. I nomi dei modelli, il supporto delle immagini, gli argomenti delle richieste e le API supportate variano in base al provider, quindi consulta la relativa documentazione collegata.

Combina YOLO e un LLM#

Esegui prima YOLO, quindi chiama l'LLM solo quando viene rilevata una persona:

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)

Riferimento API#

source accetta testo, un elenco nativo di messaggi o un oggetto immagine. image accetta un URL di immagine, un URI dati, un percorso, un array NumPy o un'immagine PIL. La chiamata a model() con un prompt configurato invia solo il prompt.

LLM è destinato esclusivamente all'inferenza e non è esposto tramite la CLI yolo. Non implementa train, val, export, track o benchmark.

FAQ#