yolo-inference

推理、Results API 与跟踪

最快路径：在 Platform 中测试并部署

Platform 中的每个模型都有一个 Predict 选项卡：上传图像、选择示例，或捕获摄像头画面；系统会自动运行推理，并显示任务叠加层、摘要、原始 JSON 和耗时。使用与下文相同的含义调整 conf、iou 和 imgsz。

在生产环境中，打开 Deploy，选择附近的区域，然后等待专用端点变为 Ready。其部署页面提供运行状况、指标、日志、Predict 面板，以及开箱即用的 Python/JavaScript/cURL 示例。使用部署绑定的 API 密钥作为 bearer 令牌调用 /predict：

import requests

with open("image.jpg", "rb") as image_file:
    response = requests.post(
        "https://YOUR_DEPLOYMENT_URL.run.app/predict",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        files={"file": image_file},
        data={"conf": 0.25, "iou": 0.7, "imgsz": 640},
    )
response.raise_for_status()
print(response.json())

默认规格的端点会缩容至零，因此在空闲一段时间后可能会遇到冷启动；自定义规格则会保留一个运行中的实例，并按运行时间计费。请参阅 Platform Inference 和 Dedicated Endpoints。

快速入门

from ultralytics import YOLO

model = YOLO("yolo26n.pt")  # or your runs/detect/train/weights/best.pt
results = model("image.jpg")  # list[Results], one per image
results[0].show()

yolo predict model=yolo26n.pt source="image.jpg" save=True

视频/流媒体的唯一规则：stream=True。 默认行为会在 RAM 中构建包含所有结果的列表——长视频会导致 OOM。stream=True 会返回一个生成器：

for r in model("video.mp4", stream=True):
    ...

数据源

可直接接受：图像/视频路径、目录、glob、URL、摄像头索引（0）、RTSP/RTMP/HTTP 流、YouTube URL（需要 pytubefix）、PIL 图像、numpy 数组（默认按 BGR 处理）、torch 张量，或这些数据源组成的列表。vid_stride=N 表示每隔 N 帧处理一帧。

重要参数

参数	默认值	说明
conf	0.25	值越低 → 召回率越高，误报也越多
iou	0.7	NMS 阈值；NMS-free 检测头（nms=False）会忽略此参数
nms	None	默认：一对多检测头 + NMS；False：更快的 NMS-free YOLO26 检测头；True：导出时嵌入 NMS。导出结果会保留此选择
imgsz	模型	继承自检查点；需要使用不同尺寸时请显式设置（静态导出始终以导出时的尺寸运行）
classes	None	仅保留这些 ID，例如 classes=[0]
max_det	300	密集场景下可调高
quantize	None	16 表示为 PyTorch/TorchScript 选择 FP16 计算；其他情况采用制品/运行时精度；请参阅下文的注意事项
batch	1	>1 可加快使用 stream=True 处理文件夹/视频的速度
retina_masks	False	使用全分辨率掩码（速度较慢，但边缘更清晰）
augment	False	仅检测时使用的测试时增强（准确率更高，速度约慢 3 倍）；nms=False 和导出场景会发出警告并执行普通推理
verbose	True	在循环中设为 False 可关闭逐帧日志

quantize=16 也会将 OpenVINO 输入舍入为 FP16。它取代了已弃用的 half 参数。

保存/绘图：save、save_txt、save_conf、save_crop、show、line_width → runs/<task>/predict*/。

Results API

每个 Results 都包含任务的载荷——.boxes、.masks、.keypoints、.probs（分类）、.obb、.semantic_mask、.depth——以及 .names（id→名称）、.orig_img（BGR）、.speed 和方法 .plot()、.show()、.save()、.save_txt()、.save_crop() 及 .summary()。仅有的导出器是 to_df()、to_csv() 和 to_json()。

r = results[0]
r.boxes.xyxy / .xywh / .xyxyn / .xywhn   # (N,4) boxes, pixel / normalized
r.boxes.conf, r.boxes.cls, r.boxes.id    # confidence, class ids, track ids (track mode)
r.masks.xy                                # list of (K,2) pixel polygons per instance
r.keypoints.xy, r.keypoints.conf          # (N,K,2), (N,K)
r.probs.top1, r.probs.top1conf            # classify; r.names[r.probs.top1] → label
r.obb.xyxyxyxy, r.obb.xywhr               # oriented boxes

from collections import Counter
counts = Counter(r.names[int(c)] for c in r.boxes.cls)   # count per class

model.embed("image.jpg") 会返回特征向量（用于相似度搜索、聚类）。

跟踪（跨帧持久 ID）

for r in model.track("video.mp4", stream=True):
    ids = r.boxes.id  # tensor of track ids, or None

# Frame-by-frame loop with your own capture: persist=True is REQUIRED
r = model.track(frame, persist=True)[0]  # else the tracker resets every frame

• 有六种跟踪器，通过 tracker= 选择：tracktrack.yaml（默认）、botsort.yaml、bytetrack.yaml、ocsort.yaml、deepocsort.yaml、fasttrack.yaml。ByteTrack 最轻量；BoT-SORT/TrackTrack/DeepOCSORT 支持 ReID（with_reid: True）和摄像机运动补偿（gmc_method）。
• 自定义行为：从 ultralytics/cfg/trackers/ 复制 YAML 文件，调整参数（track_buffer = 丢失的跟踪目标可保留的帧数，track_high_thresh），然后传入文件路径。
• 跟踪接受所有预测参数，但默认 conf=0.1，以便跟踪器能处理低置信度边界框。务必检查 r.boxes.id is not None。

写入带标注视频的模式

import cv2

cap = cv2.VideoCapture("in.mp4")
w, h, fps = (int(cap.get(p)) for p in (cv2.CAP_PROP_FRAME_WIDTH, cv2.CAP_PROP_FRAME_HEIGHT, cv2.CAP_PROP_FPS))
out = cv2.VideoWriter("out.mp4", cv2.VideoWriter_fourcc(*"mp4v"), fps, (w, h))
for r in model.track("in.mp4", stream=True):
    out.write(r.plot())  # .plot() returns annotated BGR frame
cap.release()
out.release()

性能检查清单

1. 对于在支持的 GPU 上运行的 PyTorch/TorchScript，将 quantize=16 与 FP32 进行基准测试。
2. 导出到目标原生后端（TensorRT/OpenVINO/CoreML）并进行基准测试（参见 yolo-export；导出的模型可直接重新载入 YOLO()）。
3. 使用更小的模型或 imgsz，或使用无 NMS 的 YOLO26 检测头（nms=False）。
4. 离线处理文件夹时设置 batch>1；不需要每一帧时使用 vid_stride。
5. 设置 verbose=False；只需要坐标时跳过 .plot()。
6. 每个线程使用一个 YOLO() 实例——切勿在线程间共享。

故障排除

症状	原因 / 解决方法
可见目标没有检测结果	conf 过高；权重错误；imgsz 与训练尺寸相差较大
边界框偏移	你手动调整了图像尺寸——传入原始图像，预处理会在内部完成
PIL/matplotlib 中红蓝颜色对调	Results 数组（orig_img、.plot()）使用 BGR；使用 cv2.cvtColor(..., cv2.COLOR_BGR2RGB) 转换
视频处理时 RAM 持续增长	缺少 stream=True
boxes.id is None 导致崩溃	检查是否为 None；在手动循环中设置 persist=True
重复边界框	降低 iou；移除 nms=False（无 NMS 检测头会忽略 iou；重新导出此类产物）；添加 agnostic_nms=True 以处理跨类别重复目标
数量上限为 300 个目标	提高 max_det
首次推理较慢	进行预热——从第二次调用开始进行基准测试

相关页面

• solutions.md（此文件夹）——在手动实现计数、热力图、速度估算、区域逻辑、队列、停车、锻炼计数或隐私模糊处理之前，请先阅读：几乎肯定已有预构建的 Solution。

如果已安装的版本不接受某个参数，请以错误文本和 yolo cfg 为准，而不是本文档。