Link to this section推理#

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

Link to this section预测选项卡#

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

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

Link to this section输入方式#

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

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

Link to this section上传图像#

拖放或点击以上传：

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

Link to this section示例图像#

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

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

Link to this section网络摄像头#

点击摄像头卡片以启动实时相机画面：

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

Link to this section查看结果#

推理结果显示：

• 边界框：带有类标签的 SVG 叠加层
• 置信度得分：针对每次检测
• 类别颜色：来自你数据集的配色方案（或 Ultralytics 默认配色方案）
• 速度明细：预处理、推理、后处理和网络时间

结果面板显示：

Link to this section推理参数#

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

Link to this section置信度阈值#

按置信度过滤预测：

• 较高 (0.5+)：预测结果较少，更确定
• 较低 (0.1-0.25)：预测结果较多，包含一些噪声
• 默认 (0.25)：平衡大多数用例

Link to this sectionIoU 阈值#

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

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

Link to this section部署预测#

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

Link to this sectionREST API#

程序化访问推理：

Link to this section身份验证#

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

Authorization: Bearer YOUR_API_KEY

Link to this section端点#

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

Link to this section请求#

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

Link to this section请求参数#

Link to this section响应#

{
    "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"
        }
    }
}

Link to this section响应字段#

Link to this section特定任务响应#

响应格式随任务而异：

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

Link to this section账单#

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

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

Link to this section速率限制#

共享推理的速率限制为 每个 API key 每分钟 20 次请求。当受到限制时，API 将返回 429 以及 Retry-After 标头。请参阅完整的 速率限制参考 以了解所有端点类别。

Link to this section错误处理#

常见错误响应：

Link to this section常见问题解答#

Link to this section我可以对视频进行推理吗？#

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

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

Link to this section如何获取标注后的图像？#

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

1. 使用预测结果在本地绘制框
2. 使用 Ultralytics 的 plot() 方法：

from ultralytics import YOLO

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

请参阅 Predict 模式文档 以了解完整的 API 结果和可视化选项。

Link to this section最大图像尺寸是多少？#

• 上传限制：10MB
• 建议：<5MB 以获得快速推理
• 自动调整大小：图像会被调整为选定的 Image Size 参数

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

Link to this section我可以运行批量推理吗？#

当前的 API 每次请求处理一张图像。如需批量处理：

1. 发送并发请求
2. 使用专用端点以获得更高的吞吐量
3. 对于大批量任务，请考虑本地推理

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