Interface de LLM da Ultralytics#

LLM é uma pequena interface para chamar modelos de linguagem e de visão através de uma API compatível com a OpenAI. Ela prepara a entrada de texto ou imagem, encaminha os argumentos da requisição para o SDK oficial da Python da OpenAI e retorna o objeto de resposta nativo do SDK. Isso facilita a adição de raciocínio de linguagem ou visão ao lado de um pipeline do YOLO sem precisar encapsular tipos de resposta específicos do provedor.

A API padrão é responses; usa api="chat.completions" para provedores que implementam apenas Chat Completions.

Instalação#

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

pip install "ultralytics[llm]"

Para a OpenAI, define a chave de API no ambiente:

export OPENAI_API_KEY="your-api-key"

API de Responses#

A API de Responses é a padrã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, matriz 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)

Arquivos locais e objetos de imagem são codificados como URIs de dados JPEG. Matrizes NumPy usam 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 compartilhada por cada requisição:

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 exigido pelo endpoint e lê o seu 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 entrada multimodal:

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

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

Chamadas de Streaming e Assíncronas#

Os argumentos de requisição do SDK passam 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 requisições concorrentes:

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

Provedores Compatíveis com a OpenAI#

LLM funciona com provedores que expõem uma API de Responses ou Chat Completions compatível com a OpenAI, incluindo DeepSeek, Kimi, Z.AI GLM e OpenRouter. Define o base_url, o nome do modelo e a chave de API do provedor:

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. Nomes de modelos, suporte a imagens, argumentos de requisição e APIs suportadas variam de acordo com o provedor, portanto consulta a documentação associada.

Combina o YOLO e uma LLM#

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

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 uma URL de imagem, URI de dados, caminho, matriz NumPy ou imagem PIL. Chamar model() com um prompt configurado envia apenas o prompt por si só.

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

FAQ#