Ultralytics YOLO27：
Get Started

Ultralytics LLM 接口#

LLM 是一个轻量级接口，可通过兼容 OpenAI 的 API 调用语言和视觉模型。它会准备文本或图像输入，将请求参数转发给官方 OpenAI Python SDK，并返回 SDK 原生的响应对象。这样，你就可以轻松地在 YOLO 流水线旁加入语言或视觉推理，而无需封装特定于各提供商的响应类型。

默认 API 是 responses；对于只实现 Chat Completions 的提供商，请使用 api="chat.completions"。

安装#

安装带有可选 LLM 依赖项的 Ultralytics：

pip install "ultralytics[llm]"

对于 OpenAI，请在环境变量中设置 API 密钥：

export OPENAI_API_KEY="your-api-key"

Responses API#

Responses API 是默认选项。传入提示并读取 output_text：

from ultralytics import LLM

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

多模态输入#

通过 image 传入路径、HTTP URL、数据 URI、NumPy 数组或 PIL 图像：

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)

本地文件和图像对象会编码为 JPEG 数据 URI。NumPy 数组使用 OpenCV 的 BGR 通道顺序。作为 source 传入的字符串（例如 llm("bus.jpg")）会被视为文本；要发送图像，请使用 image 参数。

使用 prompt 为每个请求设置通用指令：

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

Chat Completions#

如果端点要求使用 Chat Completions，请选择该 API，并读取其原生响应格式：

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)

同一个接口也接受多模态输入：

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

需要对话历史时，请传入原生消息对象。它们会原样转发。

流式处理与异步调用#

SDK 请求参数会原样传递，包括 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)

使用 async_call 发送并发请求：

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

兼容 OpenAI 的提供商#

LLM 可与提供兼容 OpenAI 的 Responses 或 Chat Completions API 的服务商配合使用，包括 DeepSeek、Kimi、Z.AI GLM 和 OpenRouter。设置提供商的 base_url、模型名称和 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)

同样的配置也适用于兼容的本地服务器。不同提供商支持的模型名称、图像支持、请求参数和 API 各不相同，因此请查阅其链接的文档。

结合使用 YOLO 和 LLM#

先运行 YOLO，然后仅在检测到人时调用 LLM：

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]
# 仅在 YOLO 检测到人时调用 LLM。
if any(result.names[int(cls)] == "person" for cls in result.boxes.cls):
    response = llm("Describe the scene.", image=image)
    print(response.output_text)

API 参考#

参数默认值说明
model"gpt-6-luna"发送到所选端点的模型标识符
api"responses"API 格式："responses" 或 "chat.completions"
base_urlNone可选的兼容 OpenAI 的端点
api_keyNoneAPI 密钥；否则 SDK 会读取 OPENAI_API_KEY
promptNone添加到纯文本和图像请求前面的指令
**kwargs默认 SDK 请求参数；每次调用传入的参数会覆盖构造函数中对应的值

source 接受文本、原生消息列表或图像对象。image 接受图像 URL、数据 URI、路径、NumPy 数组或 PIL 图像。如果未传入输入内容，但已配置 prompt，调用 llm() 会单独发送提示。

LLM 仅用于推理，不通过 yolo CLI 提供。它不实现 train、val、export、track 或 benchmark。

常见问题#

  • LLM 默认使用 Responses API。对于 Chat Completions 端点，请设置 api="chat.completions"。

  • 你可以使用 OpenAI 或其他兼容 API 的提供商，例如 DeepSeek、Kimi、Z.AI GLM 或 OpenRouter。请使用提供商的模型名称、基础 URL 和 API 密钥。

  • 将提示作为第一个参数，并通过 image 传入本地路径、URL、数据 URI、NumPy 数组或 PIL 图像。图像支持情况取决于所选模型和提供商。

  • 不可以。LLM 仅提供同步和异步推理。计算机视觉训练、验证、预测、导出、跟踪和基准测试请使用 Ultralytics YOLO。

贡献者
GLglenn-jocher1ONonuralpszr1

评论