Interface LLM da Ultralytics#

LLM é uma interface pequena para chamar modelos de linguagem e visão através de uma API compatível com OpenAI. Prepara entradas de texto ou imagem, encaminha os argumentos da solicitação para o SDK oficial do OpenAI para Python e devolve o objeto de resposta nativo do SDK. Isto facilita adicionar raciocínio de linguagem ou visão junto de um pipeline YOLO sem encapsular tipos de resposta específicos de cada fornecedor.

A API predefinida é responses; usa api="chat.completions" para fornecedores que implementam apenas Chat Completions.

Instalação#

Instala a Ultralytics com a dependência opcional de LLM:

pip install "ultralytics[llm]"

Para o OpenAI, define a chave da API no ambiente:

export OPENAI_API_KEY="your-api-key"

API Responses#

A API Responses é a predefinição. Passa um prompt e lê output_text:

from ultralytics import LLM

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

Entrada multimodal#

Passa um caminho, URL HTTP, URI de dados, array NumPy ou imagem PIL através de 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)

Os ficheiros locais e os objetos de imagem são codificados como URIs de dados JPEG. Os arrays NumPy utilizam a ordem de canais BGR do OpenCV. Uma string passada como source, como llm("bus.jpg"), é tratada como texto; usa o argumento image para enviar uma imagem.

Usa prompt para uma instrução partilhada por todas as solicitações:

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

Chat Completions#

Seleciona Chat Completions quando o endpoint o exigir e lê o formato de resposta 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)

A mesma interface aceita entradas multimodais:

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

Passa objetos de mensagem nativos quando precisares do histórico da conversa. Estes são encaminhados sem alterações.

Chamadas em fluxo e assíncronas#

Os argumentos das solicitações do SDK são transmitidos sem alterações, incluindo 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 para solicitações simultâneas:

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

Fornecedores compatíveis com OpenAI#

LLM funciona com fornecedores que expõem uma API Responses ou Chat Completions compatível com OpenAI, incluindo DeepSeek, Kimi, Z.AI GLM e OpenRouter. Define o base_url do fornecedor, o nome do modelo e a chave da 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)

A mesma configuração funciona com servidores locais compatíveis. Os nomes dos modelos, o suporte a imagens, os argumentos das solicitações e as APIs suportadas variam consoante o fornecedor, por isso consulta a documentação associada.

Combinar YOLO e um LLM#

Executa primeiro o YOLO e, em seguida, chama o LLM apenas quando for detetada uma pessoa:

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)

Referência da API#

source aceita texto, uma lista de mensagens nativas ou um objeto de imagem. image aceita um URL de imagem, URI de dados, caminho, array NumPy ou imagem PIL. Chamar model() com um prompt configurado envia apenas o prompt.

LLM serve apenas para inferência e não é exposto através da CLI yolo. Não implementa train, val, export, track nem benchmark.

Perguntas frequentes#