Interfaccia LLM di Ultralytics#

LLM è una piccola interfaccia per chiamare modelli di linguaggio e visione tramite un'API compatibile con OpenAI. Prepara input di testo o immagini, inoltra gli argomenti della richiesta all'SDK Python ufficiale di OpenAI e restituisce l'oggetto di risposta nativo dell'SDK. Questo rende semplice aggiungere ragionamento linguistico o visivo accanto a una pipeline YOLO senza incapsulare tipi di risposta specifici del 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 di 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 di dati JPEG. Gli array NumPy usano l'ordine dei canali BGR di OpenCV. Una stringa passata come source, come 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 la sua forma di risposta nativa:

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 multimodale:

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

Passa oggetti messaggio nativi quando hai bisogno della cronologia della conversazione. Vengono inoltrati così come sono.

Streaming e Chiamate Asincrone#

Gli argomenti della richiesta SDK vengono passati così come sono, 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 richieste concorrenti:

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 del provider, il nome del modello e la chiave 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)

La stessa configurazione funziona con server locali compatibili. I nomi dei modelli, il supporto per le immagini, gli argomenti delle richieste e le API supportate variano a seconda del provider, quindi controlla la 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 di messaggi nativi o un oggetto immagine. image accetta un URL di immagine, URI di dati, percorso, array NumPy o immagine PIL. Chiamare model() con un prompt configurato invia il prompt da solo.

LLM è solo per inferenza e non è esposto tramite la CLI yolo. Non implementa train, val, export, track o benchmark.

FAQ#