Interfaccia LLM di Ultralytics#

LLM è una piccola interfaccia per chiamare modelli linguistici e visivi 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. In questo modo puoi aggiungere facilmente capacità di ragionamento linguistico o visivo a una pipeline YOLO, senza dover adattare tipi di risposta specifici dei provider.

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

Installazione#

Installa Ultralytics con la dipendenza LLM facoltativa:

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-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-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 usano 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 tutte le richieste:

llm = LLM("gpt-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 formato nativo della risposta:

from ultralytics import LLM

llm = LLM("gpt-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 hai bisogno della cronologia della conversazione. Vengono inoltrati senza modifiche.

Chiamate in streaming e asincrone#

Gli argomenti delle richieste SDK vengono inoltrati senza modifiche, compreso stream=True:

llm = LLM("gpt-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-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 provider che offrono un'API Responses o Chat Completions compatibile con OpenAI, tra cui 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 alle immagini, gli argomenti delle richieste e le API supportate variano in base al provider, quindi consulta la documentazione collegata.

Combina YOLO e un LLM#

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

from ultralytics import LLM, YOLO

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

result = yolo(image)[0]
# Chiama l'LLM solo quando YOLO rileva una persona.
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. Se chiami llm() senza input e hai configurato prompt, viene inviato solo il prompt.

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

Domande frequenti#