跳转至内容

推理

Ultralytics Platform 提供用于测试训练模型的推理API。使用基于浏览器的 Predict 标签页用于快速验证或 REST API 用于程序化访问。

Ultralytics 模型预测标签页（带检测叠加层）

预测标签

每个模型都包含一个 Predict 浏览器推理标签页：

  1. 导航到您的模型
  2. 点击“预测”选项卡
  3. 上传图片、使用示例或打开网络摄像头
  4. 即时查看带有边界框叠加层的预测结果

Ultralytics 预测标签图像上传拖放区域

输入法

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

方法描述
图片上传拖放或点击上传图片
示例图片点击内置示例（数据集图像或默认选项）
网络摄像头捕获实时摄像头画面，支持单帧抓取
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带有人物的体育场景

对于旋转框检测 ，则展示船只和机场的航拍图像。

预加载的图片

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

网络摄像头

点击网络摄像头卡片即可启动实时摄像头画面：

  1. 在系统提示时授予相机权限
  2. 点击视频预览以捕获帧
  3. 推理在捕获的帧上自动运行
  4. 再次点击以重新启动网络摄像头

查看结果

推理结果显示：

  • 带有类标签的边界框作为SVG叠加层
  • 置信度分数（针对每次 detection）
  • 从数据集的颜色调色板（Ultralytics ）中获取类别颜色
  • 速度分解：预处理、推理、后处理和网络时间

Ultralytics 通过检测与速度统计预测标签结果

结果面板显示：

字段描述
检测列表每次检测结果包含类别名称和置信度
速度统计预处理、推理、后处理、网络（毫秒）
JSON响应代码块中的原始API响应

Inference 参数

通过可折叠的"参数"部分中的参数调整检测行为：

Ultralytics 标签参数滑块

参数范围默认值描述
置信度0.01-1.00.25最小置信度阈值
IoU0.0-0.950.70NMS IoU 阈值
图像大小320, 640, 1280640输入尺寸调整（按钮切换）

自动重试

修改任何参数后，系统将自动对当前图像重新进行推理，并设置500毫秒的防抖时间。无需重新上传。

置信度阈值

按置信度过滤预测结果：

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

IoU 阈值

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

  • 更高（0.7+）：允许更多重叠的框
  • 较低（0.3-0.5）：更积极地合并邻近检测结果
  • 默认 (0.70)：适用于大多数使用场景的NMS

部署预测

每次运行 专用端点 包括一个 Predict 直接在其部署卡上使用 tab。这会使用部署自身的推理服务而非共享预测服务，使您能够从浏览器测试已部署的端点。

REST API

以编程方式访问推理:

身份验证

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

Authorization: Bearer YOUR_API_KEY

需要API密钥

要从您自己的脚本、笔记本或应用程序中运行推理，请包含一个 API 密钥。在以下位置生成一个： Settings （个人资料选项卡中的API密钥部分）。

端点

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

curl -X POST \
  "https://platform.ultralytics.com/api/models/MODEL_ID/predict" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@image.jpg" \
  -F "conf=0.25" \
  -F "iou=0.7" \
  -F "imgsz=640"

const formData = new FormData();
formData.append("file", fileInput.files[0]);
formData.append("conf", "0.25");
formData.append("iou", "0.7");
formData.append("imgsz", "640");

const response = await fetch(
  "https://platform.ultralytics.com/api/models/MODEL_ID/predict",
  {
    method: "POST",
    headers: { Authorization: "Bearer YOUR_API_KEY" },
    body: formData,
  }
);

const result = await response.json();
console.log(result);

Ultralytics 预测标签代码示例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.4.14",
            "torch": "2.6.0",
            "torchvision": "0.21.0",
            "python": "3.13.0"
        }
    }
}

Ultralytics 预测标签JSON响应视图

响应字段

字段类型描述
images数组已处理图像列表
images[].shape数组图像尺寸 [高度, 宽度]
images[].results数组detect 列表
images[].results[].name字符串类别名称
images[].results[].confidence浮点数detect 置信度 (0-1)
images[].results[].box对象边界框坐标
images[].speed对象处理时间（单位：毫秒）
metadata对象请求元数据和版本信息

特定任务响应

响应格式因任务而异:

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

{
  "class": 0,
  "name": "person",
  "confidence": 0.92,
  "box": {"x1": 100, "y1": 50, "x2": 300, "y2": 400},
  "segments": [[100, 50], [150, 60], ...]
}

{
  "class": 0,
  "name": "person",
  "confidence": 0.92,
  "box": {"x1": 100, "y1": 50, "x2": 300, "y2": 400},
  "keypoints": [
    {"x": 200, "y": 75, "conf": 0.95},
    ...
  ]
}

{
  "results": [
    {"class": 0, "name": "cat", "confidence": 0.95},
    {"class": 1, "name": "dog", "confidence": 0.03}
  ]
}

{
  "class": 0,
  "name": "ship",
  "confidence": 0.89,
  "box": {"x1": 100, "y1": 50, "x2": 300, "y2": 400},
  "obb": {"x1": 105, "y1": 48, "x2": 295, "y2": 55, "x3": 290, "y3": 395, "x4": 110, "y4": 402}
}

速率限制

共享推理受速率限制 每个API密钥每分钟20次请求当受限时，API返回 429 带着 Retry-After 标题。查看完整内容 速率限制参考 适用于所有端点类别。

需要更高的吞吐量？

部署专用端点以实现无限制推理，无速率限制，可预测吞吐量，并保持稳定的低延迟响应。有关本地推理，请参阅预测模式指南。

错误处理

常见错误响应:

代码消息解决方案
400无效图像检查文件格式
401未经授权验证 API 密钥
404未找到模型检查模型ID
429请求频率受限等待并重试，或使用专用端点实现无限吞吐量
500服务器错误重试请求

常见问题

我可以在视频上运行 Inference 吗？

API 接受单个帧。对于视频：

  1. 在本地提取帧
  2. 将每个帧发送到 API
  3. 聚合结果

对于实时视频，请考虑部署专用端点。

如何获取标注图像？

该 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
  • Recommended: <5MB for fast inference
  • 自动调整大小: 图片被调整为所选尺寸 Image Size 参数

大图像会自动调整大小，同时保持宽高比。

我可以运行批量 Inference 吗？

当前 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))


📅 创建于 1 个月前 ✏️ 更新于 5 天前
glenn-jochersergiuwaxmannLaughing-q

评论