Interface LLM do Ultralytics#

LLM é uma interface simples para chamar modelos de linguagem e visão por meio de uma API compatível com OpenAI. Ela prepara entradas de texto ou imagem, encaminha os argumentos da solicitação ao SDK oficial do OpenAI para Python e retorna o objeto de resposta nativo do SDK. Isso facilita adicionar raciocínio de linguagem ou visão ao lado de um pipeline YOLO, sem encapsular tipos de resposta específicos de cada provedor.

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

Instalação#

Instale o Ultralytics com a dependência opcional de LLM:

pip install "ultralytics[llm]"

Para usar o OpenAI, defina a chave da API no ambiente:

export OPENAI_API_KEY="your-api-key"

API Responses#

A API Responses é a opção padrão. Passe um prompt e leia output_text:

from ultralytics import LLM

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

Entrada multimodal#

Passe um caminho, URL HTTP, URI de dados, array NumPy ou imagem PIL por meio de 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)

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

Use prompt para definir uma instrução compartilhada por todas as solicitações:

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

Chat Completions#

Selecione Chat Completions quando o endpoint exigir e leia o formato de resposta nativo:

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)

A mesma interface aceita entradas multimodais:

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

Passe objetos de mensagem nativos quando precisar do histórico da conversa. Eles são encaminhados sem alterações.

Chamadas de streaming e assíncronas#

Os argumentos das solicitações do SDK são encaminhados sem alterações, incluindo 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)

Use async_call para solicitações simultâneas:

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

Provedores compatíveis com OpenAI#

LLM funciona com provedores que oferecem uma API Responses ou Chat Completions compatível com OpenAI, incluindo DeepSeek, Kimi, Z.AI GLM e OpenRouter. Defina base_url do provedor, 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 de solicitação e as APIs compatíveis variam conforme o provedor; por isso, consulte a documentação vinculada.

Combine YOLO e um LLM#

Execute o YOLO primeiro e chame o LLM somente quando uma pessoa for detectada:

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]
# Chame o LLM somente quando o YOLO detectar uma pessoa.
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 nativa de mensagens ou um objeto de imagem. image aceita uma URL de imagem, URI de dados, caminho, array NumPy ou imagem PIL. Chamar llm() sem entrada e com prompt configurado envia apenas o prompt.

LLM serve apenas para inferência e não está disponível pela CLI yolo. Não implementa train, val, export, track nem benchmark.

Perguntas frequentes#