推理#

Ultralytics Platform 提供基于浏览器的推理功能，用于测试训练好的模型；还提供专用端点，供程序调用。

预测标签页#

每个包含权重的模型都带有一个 Predict 标签页，可用于基于浏览器的推理：

1. 转到你的模型
2. 点击 预测 标签页
3. 上传图像、使用示例图像，或打开网络摄像头
4. 查看任务专属的叠加层、预测摘要、耗时和原始响应

没有权重的模型会显示空状态——请先训练模型或上传权重。

输入方式#

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

graph LR
    A[Upload Image]:::start --> D[Auto-Inference]:::proc
    B[Example Image]:::start --> D
    C[Webcam Capture]:::start --> D
    D --> E[Results + Overlays]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff

上传图像#

拖放图像或点击以上传：

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

示例图像#

预测面板最多显示两张来自模型关联数据集的示例图像，优先使用 val 划分，然后是 test，再然后是 train。如果没有关联数据集，则使用默认示例：

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

网络摄像头#

在图像区域上方选择 网络摄像头，即可启动实时摄像头画面：

1. 出现提示时，授予摄像头权限
2. 点击视频预览以捕获画面
3. 系统会自动对捕获的画面运行推理
4. 点击 返回网络摄像头，即可回到实时画面

在你自有部署的 Predict 选项卡中，网络摄像头会持续运行推理。请参阅实时摄像头推理。

查看结果#

推理结果会根据模型任务显示相应输出：边界框、掩码、关键点、旋转框、分类分数、语义覆盖区域或深度图。有可用数据集类别颜色时，对象结果会使用这些颜色。面板还会显示预处理、推理、后处理和网络耗时。

结果面板会显示：

显示结果后，预览上方会出现两个控件：点击图像可在保留叠加层的情况下放大图像；使用下载按钮可保存当前结果的标注 JPEG 图像。

推理参数#

使用图片下方的三个滑块调整推理行为（深度模型仅显示 Image Size）：

置信度阈值#

按置信度筛选预测结果：

• 较高 (0.5+)：预测结果更少，但确定性更高
• 较低 (0.1-0.25)：预测结果更多，也会包含一些噪声
• 默认 (0.25)：适用于大多数场景的均衡设置

IoU 阈值#

控制非极大值抑制：

• 较高 (0.7+)：允许更多重叠框
• 较低 (0.3-0.5)：更积极地抑制重叠检测结果
• 默认 (0.7)：适用于大多数场景的均衡 NMS 设置

部署预测#

每个运行中的专用端点都会在其部署页面中包含一个 Predict 选项卡。此选项卡使用部署自身的推理服务，而不是共享预测服务，因此你可以直接在浏览器中测试已部署的端点。

对于处于就绪状态的端点，已处理的图片也会显示在监控选项卡中。示例和汇总图表是轻量、临时的内存数据；停止、重启、重新部署、调整大小或替换模型都可能清除这些数据。将示例保存到数据集即可保留。

实时摄像头推理#

在你拥有的部署的 Predict 选项卡中，选择 网络摄像头 或 IP 摄像头，即可在实时视频上运行端点：

实时推理使用端点绑定的 API 密钥，只有工作区所有者可以加载该密钥；对于其他团队成员，网络摄像头会逐帧捕获单张图像，且 IP 摄像头不可用，与模型的 Predict 选项卡相同。IP 摄像头必须可从互联网访问：端点会拒绝 192.168.x.x 等本地网络地址。每次推理结果对应最新画面，因此推理跟不上时会跳过画面。滑块更改会应用于下一帧网络摄像头画面，并重启 IP 摄像头流。浏览器选项卡隐藏时，实时推理会暂停。点击预览即可捕获画面；点击 断开连接 可停止查看 IP 摄像头。

后台摄像头#

配备自定义 CPU 和内存规格的端点可以持续监控一个 IP 摄像头，即使你断开连接或关闭页面也不受影响。连接的摄像头开始显示结果后，开启 在后台持续运行。部署页眉会显示 摄像头已开启，结果会作为临时示例和预测统计信息显示在监控选项卡中。

• 设置：后台摄像头始终使用默认置信度 (0.25)、IoU (0.7) 和模型的训练图像尺寸；滑块设置不适用于后台摄像头。
• 费用：后台摄像头在端点的预热实例上运行，不额外收费；无论摄像头开启还是关闭，都按小时收取运行时长费用。
• 更改：开启、关闭摄像头或切换到另一台摄像头都会重启端点实例。端点会保持就绪状态，但临时监控数据会被清除。
• 停止：关闭开关即可。断开连接或关闭页面不会停止摄像头；将端点调整为默认规格会移除后台摄像头。如果摄像头离线，端点会持续尝试重新连接。
• 端点生命周期：停止端点会停止摄像头并终止相关费用；重新启动端点后，会恢复已保存的摄像头。

默认规格端点支持实时网络摄像头和 IP 摄像头推理，但不提供后台选项。要通过 API 保存后台摄像头，请使用部署的 camera 操作。

从 API 流式接收结果#

将 RTSP 或 RTSPS URL 作为 source 发送到专用端点 URL，并在 Accept: text/event-stream 标头中提供相应内容，即可通过服务器发送事件接收结果：

curl -N -X POST \
  "https://YOUR_DEPLOYMENT_URL.run.app/predict" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream" \
  -F "source=rtsp://user:password@camera.example.com:554/stream" \
  -F "conf=0.25"

每个帧事件都会在响应结构中携带 images，其中包含归一化 (0-1) 坐标、该帧的 preview JPEG 数据 URL，以及包含任务和类别名称的 metadata。只有 conf、iou 和 imgsz 会生效；流式传输端点的后台摄像头 URL 时使用默认设置。仅包含 status 的事件不携带画面；包含 error 消息的事件（摄像头无法读取，或端点无法运行模型）会终止流。端点重启或请求达到时限时，流也会关闭；如果流结束时没有错误，请使用退避策略重新连接。Platform API 的部署预测路由和 SDK 不支持流式传输；请使用绑定的 API 密钥，将摄像头请求发送到端点 URL。摄像头 source 若未携带标头，则会返回 400。

专用端点 API#

模型 Predict 选项卡中的 API Docs 卡片包含 Python、JavaScript 和 cURL 请求示例，其中已填入滑块当前设置的置信度、IoU 和图像尺寸。在部署模型之前，URL 和密钥都是占位符——代码选项卡旁边的 Deploy 按钮会跳转到模型的 Deploy 选项卡。部署后，部署页面的 Predict 选项卡中的 Docs 结果选项卡会填入该端点的 URL，并为工作区所有者填入绑定的 API 密钥，供你复制并运行。

身份验证#

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

Authorization: Bearer YOUR_API_KEY

端点#

专用端点通过各自的 URL 接收请求：

POST https://YOUR_DEPLOYMENT_URL.run.app/predict

共享推理通过 Platform API 使用模型的完整路径：

POST https://platform.ultralytics.com/api/models/{owner}/{project}/{model}/predict

两者都接受相同的 multipart/form-data 请求体，并返回相同结构的响应。使用 Python SDK 时，共享推理使用 client.models.predict(owner, project, model, body=...)，专用部署使用 client.deployments.predict(owner, deployment, body=...)。这两种 SDK 方法都会调用 Platform API，因此会受到其速率限制和请求大小限制。要避免这些限制，请按请求部分所示，直接向专用端点 URL 发送请求。共享推理示例：

from ultralytics_platform import Platform

client = Platform()  # reads ULTRALYTICS_API_KEY
with open("image.jpg", "rb") as f:
    results = client.models.predict("acme-vision", "inspection", "v3", body={"file": f, "conf": 0.25})

请求#

import requests

url = "https://YOUR_DEPLOYMENT_URL.run.app/predict"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
data = {"conf": 0.25, "iou": 0.7, "imgsz": 640}

with open("image.jpg", "rb") as image_file:
    response = requests.post(url, headers=headers, files={"file": image_file}, data=data)
print(response.json())

请求参数#

响应#

{
    "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,
        "classNames": ["person", "bicycle", "car", "..."],
        "functionTimeAlive": 1284.51,
        "functionTimeCall": 0.018,
        "task": "detect",
        "version": {
            "ultralytics": "8.x.x",
            "torch": "2.6.0",
            "torchvision": "0.21.0",
            "python": "3.13.0"
        }
    }
}

响应字段#

特定任务的响应#

响应格式因任务而异：

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

速率限制#

共享模型 API 对每个 API 密钥、已登录的调用方或匿名 IP 的限制均为 20 次请求/分钟。Platform 部署预测路由（POST /api/deployments/{owner}/{deployment}/predict）也有相同限制。触发限流时，API 会返回 429，并附带 Retry-After 请求头。请查看完整的速率限制参考，了解所有端点类别。

错误处理#

常见错误响应：

常见问题#