在 GitHub 上编辑页面 (EN)

推理

Ultralytics Platform 提供了一个用于测试训练后模型的推理 API。使用基于浏览器的 Predict 选项卡进行快速验证，或者使用 REST API 进行程序化访问。

带有检测覆盖图的 Ultralytics Platform 模型预测选项卡

预测标签页

每个模型都包含一个 Predict 选项卡，用于进行基于浏览器的推理：

  1. 导航到你的模型
  2. 点击 Predict 选项卡
  3. 上传图片、使用示例或打开你的摄像头
  4. 通过边界框覆盖图即时查看预测结果

Ultralytics Platform 预测选项卡图片上传拖拽区

输入方法

预测面板支持多种输入方法：

方法描述
图片上传拖放或点击以上传图片
示例图片点击内置示例（数据集图片或默认图片）
摄像头捕捉带有单帧捕捉功能的实时摄像头馈送
graph LR
    A[Upload Image] --> D[Auto-Inference]
    B[Example Image] --> D
    C[Webcam Capture] --> D
    D --> E[Results + Overlays]

    style D fill:#2196F3,color:#fff
    style E fill:#4CAF50,color:#fff

上传图片

拖放或点击以上传：

  • 支持的格式：JPEG, PNG, WebP, AVIF, HEIC, JP2, TIFF, BMP, DNG, MPO
  • 最大大小：10MB
  • 自动推理：结果在上传后自动显示
自动推理

当你上传图片、选择示例或捕捉摄像头帧时，预测面板会自动运行推理。无需点击按钮。

示例图片

预测面板会显示来自你模型关联数据集的示例图片。如果未关联数据集，则使用默认示例：

图片内容
bus.jpg带有车辆的街景
zidane.jpg带有人的体育场景

对于 OBB 模型，将显示船只和机场的航拍图像。

预加载图片

示例图片在页面加载时会预加载，因此点击示例可触发近乎即时的推理，无需等待下载。

摄像头

点击摄像头卡片以启动实时摄像头馈送：

  1. 在提示时授予摄像头权限
  2. 点击视频预览以捕捉一帧
  3. 推理会在捕捉到的帧上自动运行
  4. 再次点击以重启摄像头

查看结果

推理结果显示：

  • 边界框以及作为 SVG 覆盖图的类别标签
  • 每次检测的置信度分数
  • 类别颜色（来自你数据集的配色方案或 Ultralytics 默认配色方案）
  • 速度分解：预处理、推理、后处理和网络时间

带有检测结果和速度统计的 Ultralytics Platform 预测选项卡结果

结果面板显示：

字段描述
检测列表每个带有类别名称和置信度的检测结果
速度统计预处理、推理、后处理、网络 (ms)
JSON 响应代码块中的原始 API 响应

推理参数

在可折叠的 Parameters 部分中使用参数调整检测行为：

Ultralytics Platform 预测选项卡参数滑块

参数范围默认值描述
置信度0.01 – 1.00.25最低置信度阈值
IoU0.0 – 0.950.7NMS IoU 阈值
图像大小320, 640, 1280 (UI 切换)640输入调整尺寸（API 接受 32 – 1280 之间的任何值）
自动重运行

更改任何参数都会自动在当前图片上以 500ms 的去抖动时间重新运行推理。无需重新上传。

置信度阈值

按置信度过滤预测：

  • 更高 (0.5+)：更少、更确定的预测
  • 更低 (0.1-0.25)：更多预测，包含一些噪声
  • 默认 (0.25)：适用于大多数用例的平衡设置

IoU 阈值

控制非极大值抑制 (NMS)：

  • 更高 (0.7+)：允许更多重叠的框
  • 更低 (0.3-0.5)：更积极地合并附近的检测结果
  • 默认 (0.7)：适用于大多数用例的平衡 NMS 行为

部署预测

每个正在运行的 专用端点 都在其部署卡片上包含一个 Predict 选项卡。这会使用部署自身的推理服务而不是共享的预测服务，让你能够从浏览器测试你的已部署端点。

REST API

以编程方式访问推理：

身份验证

在请求中包含你的 API 密钥：

Authorization: Bearer YOUR_API_KEY
需要 API 密钥

要在你自己的脚本、笔记本或应用程序中运行推理，请包含 API 密钥。在 Settings > API Keys 中生成一个。

端点

POST https://platform.ultralytics.com/api/models/{modelId}/predict

请求

import requests

url = "https://platform.ultralytics.com/api/models/MODEL_ID/predict"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
files = {"file": open("image.jpg", "rb")}
data = {"conf": 0.25, "iou": 0.7, "imgsz": 640}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())

Ultralytics Platform 预测选项卡 Python 代码示例选项卡

响应

{
    "images": [
        {
            "shape": [1080, 1920],
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                },
                {
                    "class": 2,
                    "name": "car",
                    "confidence": 0.87,
                    "box": { "x1": 400, "y1": 200, "x2": 600, "y2": 350 }
                }
            ],
            "speed": {
                "preprocess": 1.2,
                "inference": 12.5,
                "postprocess": 2.3
            }
        }
    ],
    "metadata": {
        "imageCount": 1,
        "functionTimeCall": 0.018,
        "model": "model.pt",
        "version": {
            "ultralytics": "8.x.x",
            "torch": "2.6.0",
            "torchvision": "0.21.0",
            "python": "3.13.0"
        }
    }
}

Ultralytics Platform 预测选项卡 JSON 响应视图

响应字段

字段类型描述
images数组已处理图片的列表
images[].shape数组图片尺寸 [高度, 宽度]
images[].results数组检测结果列表
images[].results[].name字符串类别名称
images[].results[].confidencefloat检测置信度 (0-1)
images[].results[].box对象边界框坐标
images[].speed对象处理耗时（毫秒）
metadata对象请求元数据和版本信息

特定任务响应

响应格式因任务而异：

{
  "class": 0,
  "name": "person",
  "confidence": 0.92,
  "box": {"x1": 100, "y1": 50, "x2": 300, "y2": 400}
}

账单

共享推理（Predict 选项卡和 /api/models/{id}/predict 端点）在所有方案中均为免费提供。共享推理不收取单次请求费用。

对于需要更高吞吐量的生产工作负载，请部署专用端点。

速率限制

共享推理的速率限制为每个 API key 每分钟 20 次请求。当触发限流时，API 将返回 429 状态码以及 Retry-After 标头。有关所有端点类别的完整信息，请参阅速率限制参考。

需要更高吞吐量？

部署一个专用端点即可获得无限制的推理，没有速率限制、吞吐量可预测且延迟始终较低。有关本地推理的信息，请参阅预测模式指南。

错误处理

常见错误响应：

代码消息解决方案
400无效图像检查文件格式
401未经授权验证 API key
404未找到模型检查模型 ID
429达到速率限制请等待后重试，或使用专用端点以获得无限吞吐量
500服务器错误重试请求

常见问题 (FAQ)

我可以对视频进行推理吗？

两种推理方法均接受视频文件：

  • 专用端点直接接受视频文件。支持的格式（最大 100 MB）：ASF、AVI、GIF、M4V、MKV、MOV、MP4、MPEG、MPG、TS、WEBM、WMV。系统将逐帧处理并返回每帧的结果。详情请参阅专用端点。
  • 共享推理 (/api/models/{id}/predict) 使用相同的预测服务并接受相同的视频格式。但是，UI 中的浏览器 Predict 选项卡仅支持上传图像——对于视频工作流，请直接使用 REST API 或专用端点。共享端点同样受每 API key 每分钟 20 次请求的速率限制，因此对于繁重的视频工作负载，专用端点是更好的选择。

如何获取标注后的图像？

API 返回 JSON 格式的预测结果。若要进行可视化：

  1. 使用预测结果在本地绘制边界框
  2. 使用 Ultralytics 的 plot() 方法：
from ultralytics import YOLO

model = YOLO("yolo26n.pt")
results = model("image.jpg")
results[0].save("annotated.jpg")

有关完整的 API 结果和可视化选项，请参阅预测模式文档。

图像最大尺寸是多少？

  • 上传限制：10MB
  • 推荐：小于 5MB 以实现快速推理
  • 自动调整大小：图像会被调整为所选的 Image Size 参数大小

大尺寸图像会在保持纵横比的同时自动调整大小。

我可以运行批量推理吗？

当前的 API 每次请求处理一张图像。若要进行批量处理：

  1. 发送并发请求
  2. 使用专用端点以获得更高的吞吐量
  3. 针对大批量任务考虑使用本地推理
使用 Python 进行批量推理
import concurrent.futures

import requests

url = "https://predict-abc123.run.app/predict"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
images = ["img1.jpg", "img2.jpg", "img3.jpg"]

def predict(image_path):
    with open(image_path, "rb") as f:
        return requests.post(url, headers=headers, files={"file": f}).json()

with concurrent.futures.ThreadPoolExecutor(max_workers=4) as executor:
    results = list(executor.map(predict, images))
Contributors
在 GitHub 上编辑页面 (EN)
GLglenn-jocher8T-t-hakobyan1SEsergiuwaxmann1LALaughing-q1

评论