YOLO Vision 2026：

推理#

Ultralytics Platform 提供基于浏览器的推理功能来测试训练好的模型，以及用于程序化访问的专用端点。

Ultralytics Platform Model Predict Tab With Detections Overlay

预测选项卡#

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

  1. 导航到你的模型
  2. 点击 Predict 选项卡
  3. 上传图像、使用示例或打开摄像头
  4. 查看特定任务的叠加层、预测摘要、耗时和原始响应

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

Ultralytics Platform Predict Tab Image Upload Dropzone

输入方式#

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

方法描述
图像上传拖放或点击以上传图像
示例图像点击内置示例（数据集图像或默认图像）
摄像头捕获带有单帧捕获功能的实时相机画面
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
  • 自动推理：结果在上传后自动显示
自动推断

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

客户端调整大小

在上传之前，面板会调整图像大小，使最长的一边匹配选定的 Image Size，并请求归一化坐标。这可以保持浏览器测试的快速；你自行发送的请求不会被调整大小。

示例图像#

预测面板最多显示来自你模型关联数据集的两个示例图像，优先使用 val 拆分，然后是 test，接着是 train。如果未关联数据集，则使用默认示例：

图像内容
bus.jpg带车辆的街道场景
zidane.jpg带人物的体育场景

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

预加载图像

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

网络摄像头#

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

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

查看结果#

推理结果会显示适合该模型任务的输出：边界框、掩码、关键点、旋转框、分类得分、语义覆盖或深度图。如果可用，对象结果将使用数据集类别颜色。面板还显示预处理、推理、后处理和网络耗时。

Ultralytics Platform Predict Tab Results With Detections And Speed Stats 结果面板显示：

字段描述
结果摘要每个检测结果的列表，或者分类和语义模型的前 5 个类别
速度统计预处理、推理、后处理和网络（毫秒）
版本Ultralytics 和 PyTorch 版本，以及适用的深度范围或掩码大小
JSON 响应代码块中的原始 API 响应，其中省略了 base64 地图数据

结果出来后，预览上方会出现两个控件：点击图像可以在保持叠加层完好的情况下将其放大，并使用下载按钮保存当前结果带标注的 JPEG。

推理参数#

使用图片下方的三个滑块调整推理行为：

Ultralytics Platform Predict Tab Parameters Sliders

参数范围默认值描述
置信度0.01 – 1.0，步长为 0.010.25最低置信度阈值
IoU0.0 – 0.95，步长为 0.010.7NMS IoU 阈值
Image Size32 – 1280，步长为 32640输入调整尺寸
自动重新运行

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

置信度阈值#

按置信度过滤预测：

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

IoU 阈值#

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

  • 较高 (0.7+)：允许更多重叠的框
  • 较低 (0.3-0.5)：更积极地抑制重叠检测
  • 默认 (0.7)：平衡大多数用例的 NMS 行为

部署预测#

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

专属端点 API#

模型 Predict 标签页中的 API Docs 卡片包含示例 Python、JavaScript 和 cURL 请求，其中预先填入了当前在滑块上设置的置信度、IoU 和图像大小。在部署模型之前，URL 和密钥是占位符——代码标签页旁边的 Deploy 按钮会跳转到模型的 Deploy 标签页。部署后，部署卡片的 Code 标签页会填充该端点的 URL 以及（对于工作空间所有者）其绑定的 API 密钥，随时可复制并运行。

身份验证#

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

Authorization: Bearer YOUR_API_KEY
需要 API 密钥

要从你自己的脚本、笔记本或应用中运行推理，请包含一个 API 密钥。在 Settings > API Keys 中生成一个。专用端点仅接受创建它时所用的单个密钥；共享模型 API 接受工作空间中的任何活动密钥，公开模型也接受匿名请求。

端点#

专用端点在其自己的 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=...) 进行独立部署：

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

Ultralytics Platform Predict Tab Code Examples Python Tab

请求参数#

参数类型默认值范围描述
file文件--图像或视频文件（除非设置了 source，否则为必填）
conffloat0.250.01 – 1.0最低置信度阈值
ioufloat0.70.0 – 0.95NMS IoU 阈值
imgszint64032 – 1280输入图像尺寸（以像素为单位）
normalize布尔值false-将边界框坐标返回为 0 – 1
decimalsint50 – 10坐标值的小数精度
bitsint88, 12, 16深度图量化，仅限深度模型
sourcestring--图像 URL 或 base64 字符串（file 的替代方案）

响应#

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

Ultralytics Platform Predict Tab Json Response View

响应字段#

字段类型描述
imagesarray已处理图像列表，视频则为每个视频帧对应一个条目
images[].shapearray图像尺寸 [高度, 宽度]
images[].resultsarray检测结果列表
images[].results[].classint类别索引（整数 ID）
images[].results[].namestring类别名称
images[].results[].confidencefloat检测置信度 (0-1)
images[].results[].box对象边界框坐标
images[].semantic_mask对象逐像素类别图（仅限语义模型）
images[].depth对象逐像素深度图（仅限深度模型）
images[].speed对象处理耗时（毫秒）
metadata对象图像计数、服务耗时、任务以及 Ultralytics/PyTorch 版本

特定任务响应#

响应格式随任务而异：

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

速率限制#

共享模型 API 对每个 API key、登录调用者或匿名 IP 限制为 20 requests/minute。当受到频率限制时，API 会返回包含 Retry-After 标头的 429。请参阅完整的rate-limit reference了解所有端点类别。

需要更高的吞吐量？

直接发送到专用端点的请求不会通过 Platform API 速率限制器。当端点暂时满负荷时，它仍会通过 429 和 Retry-After 标头来分流负载。有关高容量本地推理，请参阅Predict mode guide。

错误处理#

常见错误响应：

代码消息解决方案
400无效图像检查文件格式，或者模型是否具有已训练的权重
401未经授权验证 API key
404未找到模型检查所有者、项目和模型名称
413输入过大将文件大小减小到端点限制以下
429速率受限等待并重试，或者直接将请求发送到专用端点
500服务器错误重试请求
503服务不可用Predict 服务正在启动或无法连接；请稍等片刻再重试

常见问题解答#

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

    • 专用端点直接接受视频文件。支持的格式（最大 100 MB）：ASF、AVI、GIF、M4V、MKV、MOV、MP4、MPEG、MPG、TS、WEBM、WMV。每个帧都单独处理，并按帧返回结果。详见专用端点。
    • 共享推理（POST /api/models/{owner}/{project}/{model}/predict）使用相同的预测服务并接受相同的视频格式。浏览器 Predict 标签页仅选择图像，因此请使用 API 或专用端点处理视频。

  • 在 Predict 标签页中，预览上方的下载按钮可将当前结果保存为带标注的 JPEG。API 本身返回 JSON 预测。要将其可视化：

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

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

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

    • Predict 选项卡限制：10 MB
    • API 限制：共享推理和专用端点均为 100 MB
    • Predict 标签页中的自动调整大小：图像在上载前会被调整为选定的 Image Size

    大型图像会在浏览器中自动调整大小，同时保持纵横比。你自行发送的请求不会被调整大小，因此超出限制的图像会被 413 拒绝。

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

    1. 为每张图片发送单独的请求
    2. 在适当时将请求分发到各个专属端点
    3. 对大批量数据使用本地推理
    使用 Python 进行批量推理
    import concurrent.futures

import requests

url = "https://YOUR_DEPLOYMENT_URL.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))
贡献者
GLglenn-jocher19LAlaodouya1T-t-hakobyan1SEsergiuwaxmann1LALaughing-q1

评论