Ultralytics YOLO27：

推理#

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

Ultralytics Platform 模型预测选项卡及检测叠加层

预测选项卡#

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

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

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

Ultralytics Platform 预测选项卡图像上传拖放区

输入方式#

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

方法描述
图像上传拖放图像，或点击上传图像
示例图像点击内置示例（数据集图像或默认图像）
网络摄像头捕获实时摄像头画面，支持单帧捕获
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 预测选项卡参数滑块

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

更改任何参数都会在 500 毫秒防抖后，使用当前图像自动重新运行推理。无需重新上传。

置信度阈值#

按置信度筛选预测结果：

  • 较高（0.5+）：预测结果更少，但更确定
  • 较低（0.1-0.25）：预测结果更多，但包含一些噪声
  • 默认（0.25）：适合大多数使用场景的平衡值

IoU 阈值#

控制非极大值抑制：

  • 较高（0.7+）：允许更多重叠框
  • 较低（0.3-0.5）：更积极地抑制重叠检测结果
  • 默认（0.7）：适合大多数使用场景的平衡 NMS 行为

部署预测#

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

在启用了监控功能的付费端点上，处理后的图像也会计入Monitoring tab。其抽样示例和聚合图表是保存在内存中的轻量级临时数据；停止、重启、重新部署、调整大小或替换模型可能会清除这些数据。将示例保存到数据集中即可保留这些示例。

专用端点 API#

模型 Predict 选项卡中的 API 文档卡片包含 Python、JavaScript 和 cURL 请求示例，并预先填入 当前滑块设置的置信度、IoU 和图像大小。在部署模型之前，URL 和密钥都是占位符——代码选项卡旁的 部署按钮会跳转到模型的 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 预测选项卡代码示例 Python 选项卡

请求参数#

参数类型默认值范围描述
filefile--图像或视频文件（除非设置了 source，否则为必需）
conffloat0.250.01 – 1.0最小置信度阈值
ioufloat0.70.0 – 0.95NMS IoU 阈值
imgszint64032 – 1280输入图像大小（像素）
normalizeboolfalse-将边界框坐标作为 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 预测选项卡 JSON 响应视图

响应字段#

字段类型描述
images数组已处理图像的列表；对于视频，每个视频帧对应一个条目
images[].shape数组图像尺寸 [高度, 宽度]
images[].results数组检测结果列表
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 密钥、已登录调用方或匿名 IP 的限制为每分钟 20 个请求。受到限流时，API 会返回429以及一个Retry-After标头。有关所有端点类别，请参阅完整的速率限制参考。

需要更高吞吐量？

直接发送到专用端点的请求不会经过 Platform API 速率限制器。当端点暂时达到容量上限时，仍会通过429和Retry-After标头来减载。有关高吞吐量本地推理，请参阅Predict 模式指南。

错误处理#

常见错误响应：

代码消息解决方案
400无效图像检查文件格式，或确认模型包含已训练的权重
401未授权验证 API 密钥
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 服务，并接受相同的视频格式。浏览器中的 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 模式文档。

    • 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-jocher20SEsergiuwaxmann2LAlaodouya1T-t-hakobyan1LALaughing-q1

评论