使用 Ultralytics YOLO 进行模型预测#
简介#
在机器学习和计算机视觉领域中,理解视觉数据的过程通常称为推理或预测。Ultralytics YOLO26 提供了一项名为预测模式的强大功能,专为各类数据源的高性能实时推理而设计。
查看尚未发布的 YOLO27 预览版,了解计划中的推理示例。
观看: 如何从 Ultralytics YOLO26 任务中提取结果,用于自定义项目 🚀
实际应用#
| 制造业 | 体育 | 安全 |
|---|---|---|
| 车辆备件检测 | 足球运动员检测 | 人员跌倒检测 |
为什么使用 Ultralytics YOLO 进行推理?#
以下是你应该考虑使用 YOLO26 预测模式来满足各种推理需求的原因:
- 灵活性:可对图像、视频甚至实时流进行推理。
- 高性能:专为实时高速处理而设计,同时不牺牲准确率。
- 易于使用:直观的 Python 和 CLI 接口,可快速部署和测试。
- 高度可定制:提供各种设置和参数,可根据你的具体需求调整模型的推理行为。
- 可用于生产环境:将模型部署为 Ultralytics Platform 推理端点,并启用自动扩缩容和监控;也可以在本地运行推理。
预测模式的主要特性#
YOLO26 预测模式经过专门设计,具备出色的稳健性和灵活性,其特性包括:
- 兼容多种数据源:无论你的数据是单张图像、图像集合、视频文件还是实时视频流,预测模式都能轻松处理。
- 流式模式:使用流式功能生成内存高效的
Results对象生成器。在预测器的调用方法中设置stream=True即可启用此功能。默认行为(stream=False)会返回包含所有结果的列表,而stream=True会逐个生成结果,因此尤其适用于长视频和实时流。 - 批处理:在单个批次中处理多张图像或多个视频帧,进一步缩短总推理时间。
- 便于集成:凭借灵活的 API,可轻松集成到现有数据管道和其他软件组件中。
Ultralytics YOLO 模型会返回 stream=True 传入模型进行推理时的结果:返回由 Results 对象组成的 Python 列表,或内存高效的 Results 对象生成器。
from ultralytics import YOLO
# 加载模型
model = YOLO("yolo26n.pt") # 预训练的 YOLO26n 模型
# 对图像列表进行批量推理
results = model(["image1.jpg", "image2.jpg"]) # 返回 Results 对象列表
# 处理结果列表
for result in results:
boxes = result.boxes # 用于边界框输出的 Boxes 对象
masks = result.masks # 用于分割掩码输出的 Masks 对象
keypoints = result.keypoints # 用于姿态输出的 Keypoints 对象
probs = result.probs # 用于分类输出的 Probs 对象
obb = result.obb # 用于 OBB 输出的 Oriented boxes 对象
result.show() # 显示到屏幕上
result.save(filename="result.jpg") # 保存到磁盘推理数据源#
如下表所示,YOLO26 可以处理不同类型的推理输入源,包括静态图像、视频流和各种数据格式。表格还标明了每种数据源是否支持通过参数 stream=True ✅ 启用流式模式。流式模式适合处理视频或实时流,因为它会生成结果生成器,而不是将所有帧都加载到内存中。
处理长视频或大型数据集时,请使用 stream=True 以高效管理内存。当使用 stream=False 时,所有帧或数据点的结果都会存储在内存中;对于大型输入,内存占用会迅速增加,可能导致内存不足错误。相比之下,stream=True 使用生成器,只将当前帧或数据点的结果保留在内存中,从而显著降低内存占用并避免内存不足问题。
| 数据源 | 示例 | 类型 | 备注 |
|---|---|---|---|
| 图像 | 'image.jpg' | str 或 Path | 单个图像文件。 |
| URL | 'https://ultralytics.com/images/bus.jpg' | str | 图像的 URL。 |
| 屏幕截图 | 'screen' | str | 截取屏幕截图。 |
| PIL | Image.open('image.jpg') | PIL.Image | 采用 RGB 通道的 HWC 格式。 |
| OpenCV | cv2.imread('image.jpg') | np.ndarray | 采用 BGR 通道的 HWC 格式 uint8 (0-255)。 |
| NumPy | np.zeros((640,1280,3)) | np.ndarray | 采用 BGR 通道的 HWC 格式 uint8 (0-255)。 |
| torch | torch.zeros(16,3,320,640) | torch.Tensor | 采用 RGB 通道的 BCHW 格式 float32 (0.0-1.0)。 |
| CSV | 'sources.csv' | str 或 Path | 包含图像、视频或目录路径的 CSV 文件。 |
| 视频 ✅ | 'video.mp4' | str 或 Path | MP4、AVI 等格式的视频文件。 |
| 目录 ✅ | 'path/' | str 或 Path | 包含图像或视频的目录路径。 |
| glob ✅ | 'path/*.jpg' | str | 用于匹配多个文件的 Glob 模式。使用 * 字符作为通配符。 |
| YouTube ✅ | 'https://youtu.be/LNwODJXcvt4' | str | YouTube 视频的 URL。 |
| 流 ✅ | 'rtsp://example.com/media.mp4' | str | 流媒体协议(例如 RTSP、RTMP、TCP)或 IP 地址的 URL。 |
| 多路流 ✅ | 'list.streams' | str 或 Path | *.streams 文本文件,每行包含一个流 URL;例如,8 路流将以批次大小 8 运行。 |
| 网络摄像头 ✅ | 0 | int | 要运行推理的已连接摄像头设备的索引。 |
以下是使用各种数据源类型的代码示例:
对图像文件运行推理。
from ultralytics import YOLO
# 加载预训练的 YOLO26n 模型
model = YOLO("yolo26n.pt")
# 定义图像文件的路径
source = "path/to/image.jpg"
# 对数据源运行推理
results = model(source) # Results 对象列表推理参数#
model.predict() 接受多个参数,你可以在推理时传入这些参数以覆盖默认值:
固定形状与最小矩形(rect)#
默认情况下,predict 使用 rect=True,并在条件允许时启用最小矩形填充。图像会缩放至 imgsz 内,并且只填充到最接近的步幅倍数,因此最终张量可能小于 imgsz。只有在批次中的所有图像形状相同且后端支持时,才会使用最小矩形填充(PyTorch .pt,或动态 ONNX 等动态形状导出模型)。否则,图像会填充至完整的 imgsz 目标尺寸。
使用 rect=False 始终填充至完整的 imgsz 目标尺寸。当你需要固定输入尺寸以匹配导出的模型(ONNX、TensorRT 等)时,建议使用此选项。
整数与元组 imgsz
- 整数
imgsz=640会在步幅取整后变为正方形目标(640, 640)。 - 元组
imgsz=(384, 672)会设置矩形目标。使用rect=True时,实际张量可能小于此目标尺寸。
训练与 predict/export
训练只接受单个整数 imgsz([h, w] 列表会被转换为其中的最大值)。predict 和 export 接受整数或 (height, width) 元组。
from ultralytics import YOLO
# 加载预训练的 YOLO26n 模型
model = YOLO("yolo26n.pt")
# 使用参数对 'bus.jpg' 运行推理
model.predict("https://ultralytics.com/images/bus.jpg", save=True, imgsz=320, conf=0.25)推理参数:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
source | str 或 int 或 None | None | 指定推理的数据源。可以是图像路径、视频文件、目录、URL,或实时画面的设备 ID。如果未指定,系统会记录警告,并使用内置演示资源(ultralytics/assets;对于 OBB,则使用演示 URL)作为模型输入。此功能支持多种格式和来源,可灵活应用于不同类型的输入。 |
conf | float | 0.25 | 设置检测的最低置信度阈值。置信度低于此阈值的检测结果会被忽略。调整此值有助于减少误报。 |
iou | float | 0.7 | 用于非极大值抑制(NMS)的交并比(IoU)阈值。较低的值会通过消除重叠框来减少检测结果,有助于减少重复检测。 |
imgsz | int 或 tuple | 640 | Letterbox 的目标尺寸。整数表示正方形N×N;元组表示(height, width)。使用rect=True时,由于采用最小矩形填充,实际张量可能小于此目标尺寸。使用rect=False可设为固定尺寸。请参阅固定尺寸与最小矩形。 |
rect | bool | True | 如果为True,则在条件允许时使用最小矩形填充(批次中图像形状相同且后端支持)。如果为False,则始终填充至完整的imgsz。请参阅固定尺寸与最小矩形。 |
quantize | int 或 str | None | 推理精度:16/"fp16" 和 32/"fp32"/unset 用于为 PyTorch 和 TorchScript 模型选择 FP16 或 FP32 计算(CPU 上为 FP32);其他格式使用其模型文件和运行时所选的精度。在 16 中,OpenVINO 仍会在客户端将输入舍入为 FP16,再扩展回 FP32,但不会更改运行时精度。INT8/PTQ 量化在导出期间配置,然后通过加载导出的模型来使用。此参数替代已弃用的 half 标志。 |
device | str | None | 指定推理使用的设备(例如 cpu、cuda:0、0、npu 或 npu:0)。用户可以选择 CPU、特定 GPU、华为昇腾 NPU 或其他计算设备来运行模型。 |
dnn | bool | False | 如果 True,则使用 OpenCV DNN 模块,而不是 ONNX Runtime 执行 ONNX 模型推理。 |
data | str | None | 数据集 YAML 文件的路径(例如 coco8.yaml)。仅读取其中的 names,且仅当加载的模型没有自带类别名称时才会读取:例如第三方导出模型,或与随附元数据分离的 Ultralytics 导出模型。否则,此类模型会报告 class0、class1 等。 |
batch | int | 1 | 指定推理的批次大小(仅在来源为目录、视频文件或 .txt 文件时有效)。较大的批次大小可以提高吞吐量,缩短推理所需的总时间。 |
max_det | int | 300 | 每张图像允许检测的最大数量。限制模型在单次推理中可检测的对象总数,避免密集场景中产生过多输出。 |
vid_stride | int | 1 | 视频输入的帧步长。允许跳过视频帧以加快处理速度,但会降低时间分辨率。值为 1 时处理每一帧;值越大,跳过的帧越多。 |
stream_buffer | bool | False | 决定是否为视频流的传入帧排队。如果 False,则会丢弃旧帧以容纳新帧(针对实时应用进行了优化)。如果 True,则会将新帧放入缓冲区,确保不跳过任何帧;但如果推理 FPS 低于视频流 FPS,就会产生延迟。 |
visualize | bool | False | 在每个预测结果旁保存类别激活热力图,显示哪些像素提高了预测类别的分数。遵循 conf 和 classes,因此 classes=[0] 只映射该类别。仅适用于 Ultralytics PyTorch 模型。 |
augment | bool | False | 为预测启用测试时增强(TTA),可能提升检测的稳健性,但会降低推理速度。仅适用于 Ultralytics PyTorch 模型。 |
agnostic_nms | bool | False | 启用类别无关的非极大值抑制(NMS),抑制不同类别之间得分较低且重叠的框,而不只是同一类别内的框。适用于类别间常有重叠的多类别检测场景。对于无 NMS 推理(YOLO26 或 YOLOv10 上的 nms=False),此选项仅防止同一检测结果带有多个类别标签(IoU=1.0 的重复项),不会根据 IoU 阈值抑制不同的框。 |
classes | list[int] | None | 将预测结果筛选为指定的类别 ID。只返回属于指定类别的检测结果。适用于在多类别检测任务中聚焦相关对象。 |
retina_masks | bool | False | 返回高分辨率分割掩码。启用后,返回的掩码(masks.data)将与原始图像尺寸一致。禁用后,掩码尺寸与推理时使用的图像尺寸一致。 |
embed | list[int] | None | 指定要提取特征向量或嵌入的层。使用 model.embed(source) 获取倒数第二层的嵌入,或使用 model.predict(source, embed=[layer]) 选择特定层。适用于聚类或相似度搜索等下游任务。仅适用于 Ultralytics PyTorch 模型。 |
project | str | None | 启用 save 时,保存预测输出的项目目录名称。 |
name | str | None | 预测运行的名称。启用 save 时,用于在项目文件夹中创建子目录以存储预测输出。 |
stream | bool | False | 通过返回 Results 对象生成器,而不是一次性将所有帧加载到内存中,为长视频或大量图像启用节省内存的处理方式。 |
verbose | bool | True | 控制是否在终端中显示详细的推理日志,以实时反馈预测过程。 |
compile | bool 或 str | False | 使用backend='inductor'启用 PyTorch 2.x torch.compile图编译。接受True → "default"、False → 禁用,或"default"、"reduce-overhead"、"max-autotune-no-cudagraphs"等字符串模式。如果不受支持,则会发出警告并回退到即时执行模式。 |
channels_last | bool | None | 对原生 PyTorch 推理使用 channels_last(NHWC)内存格式。对于启用了 oneDNN 的 Linux 和 Windows x86 CPU,且 PyTorch 版本为 1.13 或更高版本时,None 会自动启用该格式;False 会禁用该格式;True 会在受支持的 x86 CPU 或 CUDA 设备上请求使用该格式。ARM64、MPS、较旧的 PyTorch 版本、未启用 oneDNN 的 CPU,以及 TensorRT 和 ONNX 等导出格式均不受影响。 |
nms | bool,可选 | None | 默认使用 NMS 执行一对多推理(None 或 True)。设置 False 可在可用时使用无 NMS 的一对一检测头。详情请参阅端到端检测指南。 |
可视化参数:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
show | bool | False | 如果 True,则在窗口中显示带标注的图像或视频。适用于在开发或测试期间即时查看结果。 |
save | bool | False or True | 启用后将带标注的图像或视频保存到文件。适用于文档编写、进一步分析或分享结果。使用 CLI 时默认为 True,在 Python 中使用时默认为 False。 |
save_frames | bool | False | 处理视频时,将单独的帧保存为图像。适用于提取特定帧或逐帧详细分析。 |
save_txt | bool | False | 按照 [class] [x_center] [y_center] [width] [height] [confidence] 格式将检测结果保存到文本文件。适用于与其他分析工具集成。 |
save_conf | bool | False | 在保存的文本文件中包含置信度分数。增加可用于后处理和分析的详细信息。 |
save_crop | bool | False | 保存检测对象的裁剪图像。适用于数据集增强、分析,或为特定对象创建专用数据集。 |
show_labels | bool | True | 在可视化输出中显示每个检测结果的标签,便于立即了解检测到的对象。 |
show_conf | bool | True | 在每个检测结果的标签旁显示置信度分数,帮助了解模型对该检测结果的确信程度。 |
show_boxes | bool | True | 在检测到的对象周围绘制边界框,便于在图像或视频帧中直观识别和定位对象。 |
line_width | int or None | None | 指定边界框的线宽。如果 None,则会根据图像尺寸自动调整线宽,便于自定义显示效果并提高清晰度。 |
图像和视频格式#
YOLO26 支持多种图像和视频格式,具体格式见 ultralytics/data/utils.py。请参阅下表,了解有效后缀和 predict 命令示例。
图像#
下表列出了有效的 Ultralytics 图像格式。
HEIC/HEIF 格式需要 pi-heif,首次使用时会自动安装。Pillow 原生支持 AVIF。
| 图像后缀 | predict 命令示例 | 参考 |
|---|---|---|
.avif | yolo predict source=image.avif | AV1 图像文件格式 |
.bmp | yolo predict source=image.bmp | Microsoft BMP 文件格式 |
.dng | yolo predict source=image.dng | Adobe DNG |
.heic | yolo predict source=image.heic | 高效图像文件格式 |
.heif | yolo predict source=image.heif | 高效图像文件格式 |
.jp2 | yolo predict source=image.jp2 | JPEG 2000 |
.jpeg | yolo predict source=image.jpeg | JPEG |
.jpg | yolo predict source=image.jpg | JPEG |
.mpo | yolo predict source=image.mpo | 多图像对象 |
.png | yolo predict source=image.png | 便携式网络图形 |
.tif | yolo predict source=image.tif | 标记图像文件格式 |
.tiff | yolo predict source=image.tiff | 标记图像文件格式 |
.webp | yolo predict source=image.webp | WebP |
视频#
下表列出了有效的 Ultralytics 视频格式。
| 视频后缀 | predict 命令示例 | 参考 |
|---|---|---|
.asf | yolo predict source=video.asf | 高级系统格式 |
.avi | yolo predict source=video.avi | 音视频交错格式 |
.gif | yolo predict source=video.gif | 图形交换格式 |
.m4v | yolo predict source=video.m4v | MPEG-4 第 14 部分 |
.mkv | yolo predict source=video.mkv | Matroska |
.mov | yolo predict source=video.mov | QuickTime 文件格式 |
.mp4 | yolo predict source=video.mp4 | MPEG-4 第 14 部分 - 维基百科 |
.mpeg | yolo predict source=video.mpeg | MPEG-1 第 2 部分 |
.mpg | yolo predict source=video.mpg | MPEG-1 第 2 部分 |
.ts | yolo predict source=video.ts | MPEG 传输流 |
.wmv | yolo predict source=video.wmv | Windows Media 视频 |
.webm | yolo predict source=video.webm | WebM 项目 |
处理 Results#
所有 Ultralytics predict() 调用都会返回一个 Results 对象列表:
from ultralytics import YOLO
# 加载预训练的 YOLO26n 模型
model = YOLO("yolo26n.pt")
# 对图像进行推理
results = model("https://ultralytics.com/images/bus.jpg")
results = model(
[
"https://ultralytics.com/images/bus.jpg",
"https://ultralytics.com/images/zidane.jpg",
]
) # 批量推理Results 对象具有以下属性:
| 属性 | 类型 | 说明 |
|---|---|---|
orig_img | np.ndarray | 原始图像的 NumPy 数组。 |
orig_shape | tuple | 原始图像的形状,格式为 (高度, 宽度)。 |
boxes | Boxes, optional | 包含检测边界框的 Boxes 对象。 |
masks | Masks, optional | 包含检测掩码的 Masks 对象。 |
probs | Probs, optional | 包含分类任务中每个类别概率的 Probs 对象。 |
keypoints | Keypoints, optional | 包含每个对象检测到的关键点的 Keypoints 对象。 |
obb | OBB, optional | 包含有向边界框的 OBB 对象。 |
semantic_mask | SemanticMask, optional | 包含密集逐像素类别映射的 SemanticMask 对象。 |
depth | DepthMap, optional | 包含密集逐像素深度图的 DepthMap 对象。 |
speed | dict | 一个字典,记录每张图像的预处理、推理和后处理耗时(毫秒)。 |
names | dict | 一个将类别索引映射到类别名称的字典。 |
path | str | 图像文件的路径。 |
save_dir | str, optional | 保存结果的目录。 |
各任务的 Results#
下方填充哪些字段取决于模型的任务;如果你还没有选定任务,请比较检测、分割、语义分割、深度估计、分类、姿态和 OBB。每次预测都会为每张图像或每一帧返回一个 Results 对象。上面列出的通用字段始终可用,而任务专属的预测数据则存储在下方字段中。YOLO 坐标和置信度张量为 torch.float32;除非使用 FP16 推理(quantize=16),此时概率张量为 torch.float16,否则概率张量为 torch.float32。在 result.numpy() 之后,张量会转换为具有相应 NumPy 数据类型的 NumPy 数组。实例掩码是 torch.uint8 二值张量,而语义掩码会根据类别数量,使用实用范围内最小的整数数据类型表示类别 ID:torch.uint8、torch.int16 或 torch.int32。
| 属性 | 类型 | 形状 | 说明 |
|---|---|---|---|
result.boxes | Boxes | (N) | 检测框。 |
result.boxes.data | torch.float32 | (N,6/7) | 原始 [x1,y1,x2,y2,conf,cls],以及可选的跟踪 ID。 |
result.boxes.xyxy | torch.float32 | (N,4) | xyxy 像素框。 |
result.boxes.conf | torch.float32 | (N,) | 置信度分数。 |
result.boxes.cls | torch.float32 | (N,) | 类别 ID;转换为 int 可获取类别名称。 |
Results 对象包含以下方法:
| 方法 | 返回类型 | 说明 |
|---|---|---|
update() | None | 使用框、掩码、概率、obb、关键点、语义掩码或深度等新数据更新 Results 对象。 |
cpu() | Results | 返回 Results 对象的副本,其中所有张量都已移至 CPU 内存。 |
numpy() | Results | 返回 Results 对象的副本,其中所有张量都已转换为 NumPy 数组。 |
cuda() | Results | 返回 Results 对象的副本,其中所有张量都已移至 GPU 内存。 |
to() | Results | 返回 Results 对象的副本,其中张量已移至指定设备并转换为指定数据类型。 |
new() | Results | 创建一个新的 Results 对象,其 image、path、names 和 speed 属性与原对象相同。 |
plot() | np.ndarray | 在输入的 BGR 图像上绘制检测结果,并返回标注后的图像。 |
show() | None | 显示带有推理结果标注的图像。 |
save() | str | 将标注后的推理结果图像保存到文件,并返回文件名。 |
verbose() | str | 为每项任务返回一条日志字符串,详细说明检测和分类结果。 |
save_txt() | str | 将检测结果保存到文本文件,并返回已保存文件的路径。 |
save_crop() | None | 将裁剪后的检测图像保存到指定目录。 |
summary() | List[Dict[str, Any]] | 将推理结果转换为摘要字典,可选择进行归一化。 |
to_df() | DataFrame | 将检测结果转换为 Polars DataFrame。 |
to_csv() | str | 将检测结果转换为 CSV 格式。 |
to_json() | str | 将检测结果转换为 JSON 格式。 |
如需了解更多详情,请参阅Results 类文档。
框#
Boxes 对象可用于索引、操作边界框,并将其转换为不同格式。
from ultralytics import YOLO
# 加载预训练的 YOLO26n 模型
model = YOLO("yolo26n.pt")
# 对图像进行推理
results = model("https://ultralytics.com/images/bus.jpg") # 结果列表
# 查看结果
for r in results:
print(r.boxes) # 打印包含检测边界框的 Boxes 对象以下是 Boxes 类的方法和属性表格,其中包括名称、类型和说明:
| 名称 | 类型 | 说明 |
|---|---|---|
cpu() | 方法 | 将对象移至 CPU 内存。 |
numpy() | 方法 | 将对象转换为 NumPy 数组。 |
cuda() | 方法 | 将对象移至 CUDA 内存。 |
to() | 方法 | 将对象移至指定设备。 |
xyxy | 属性(torch.Tensor) | 以 xyxy 格式返回框。 |
conf | 属性(torch.Tensor) | 返回框的置信度值。 |
cls | 属性(torch.Tensor) | 返回框的类别值。 |
id | 属性(torch.Tensor) | 返回框的跟踪 ID(如果有)。 |
xywh | 属性(torch.Tensor) | 以 xywh 格式返回框。 |
xyxyn | 属性(torch.Tensor) | 返回以原始图像尺寸归一化后的 xyxy 格式框。 |
xywhn | 属性(torch.Tensor) | 返回以原始图像尺寸归一化后的 xywh 格式框。 |
如需了解更多详情,请参阅Boxes 类文档。
掩码#
Masks 对象可用于索引和操作掩码,并将掩码转换为分段。
from ultralytics import YOLO
# 加载预训练的 YOLO26n-seg 分割模型
model = YOLO("yolo26n-seg.pt")
# 对图像进行推理
results = model("https://ultralytics.com/images/bus.jpg") # 结果列表
# 查看结果
for r in results:
print(r.masks) # 打印包含检测到的实例掩码的 Masks 对象以下是 Masks 类的方法和属性表格,其中包括名称、类型和说明:
| 名称 | 类型 | 说明 |
|---|---|---|
data | 属性(torch.Tensor) | torch.uint8 二值掩码张量,形状为 (N,H,W),值为 0 或 1。 |
cpu() | 方法 | 返回位于 CPU 内存中的掩码张量。 |
numpy() | 方法 | 以 NumPy 数组形式返回掩码张量。 |
cuda() | 方法 | 返回位于 GPU 内存中的掩码张量。 |
to() | 方法 | 返回具有指定设备和数据类型的掩码张量。 |
xyn | 属性(list[np.ndarray]) | 归一化掩码多边形列表。 |
xy | 属性(list[np.ndarray]) | 像素坐标中的掩码多边形列表。 |
如需了解更多详情,请参阅Masks 类文档。
SemanticMask#
SemanticMask 为语义分割结果存储一张密集类别图。与 Masks 不同,它不包含每个对象对应的二值掩码,也不提供多边形辅助方法。
from ultralytics import YOLO
# 加载预训练的 YOLO26n-sem 语义分割模型
model = YOLO("yolo26n-sem.pt")
# 对图像进行推理
results = model("https://ultralytics.com/images/bus.jpg") # 结果列表
# 查看结果
for r in results:
print(r.semantic_mask.data) # 打印 H x W 类别 ID 图| 名称 | 类型 | 说明 |
|---|---|---|
data | 属性(torch.Tensor) | 形状为 (H,W) 的类别 ID 图。数据类型为 torch.uint8、torch.int16 或 torch.int32,具体取决于类别数量。 |
shape | 属性(tuple) | 类别图的形状,通常与 result.orig_shape 相同。 |
cpu() | 方法 | 返回位于 CPU 内存中的语义掩码张量。 |
numpy() | 方法 | 以 NumPy 数组形式返回语义掩码张量。 |
cuda() | 方法 | 返回位于 GPU 内存中的语义掩码张量。 |
to() | 方法 | 返回具有指定设备和数据类型的语义掩码张量。 |
关键点#
Keypoints 对象可用于索引、操作和归一化坐标。
from ultralytics import YOLO
# 加载预训练的 YOLO26n-pose 姿态模型
model = YOLO("yolo26n-pose.pt")
# 对图像进行推理
results = model("https://ultralytics.com/images/bus.jpg") # 结果列表
# 查看结果
for r in results:
print(r.keypoints) # 打印包含检测到的关键点的 Keypoints 对象以下是 Keypoints 类的方法和属性表格,其中包括名称、类型和说明:
| 名称 | 类型 | 说明 |
|---|---|---|
cpu() | 方法 | 返回位于 CPU 内存中的关键点张量。 |
numpy() | 方法 | 以 NumPy 数组形式返回关键点张量。 |
cuda() | 方法 | 返回位于 GPU 内存中的关键点张量。 |
to() | 方法 | 返回具有指定设备和数据类型的关键点张量。 |
xyn | 属性(torch.Tensor) | 形状为 (N,K,2) 的归一化关键点坐标。 |
xy | 属性(torch.Tensor) | 形状为 (N,K,2) 的像素关键点坐标。 |
conf | 属性(torch.Tensor) | 如果有,则返回关键点的置信度值;否则返回 None。 |
如需了解更多详情,请参阅Keypoints 类文档。
概率#
Probs 对象可用于获取 top1 和 top5 分类索引及分数。
from ultralytics import YOLO
# 加载预训练的 YOLO26n-cls 分类模型
model = YOLO("yolo26n-cls.pt")
# 对图像进行推理
results = model("https://ultralytics.com/images/bus.jpg") # 结果列表
# 查看结果
for r in results:
print(r.probs) # 打印包含检测到的类别概率的 Probs 对象以下是 Probs 类的方法和属性汇总表:
| 名称 | 类型 | 说明 |
|---|---|---|
cpu() | 方法 | 返回位于 CPU 内存中的 probs 张量副本。 |
numpy() | 方法 | 返回 probs 张量的 NumPy 数组副本。 |
cuda() | 方法 | 返回位于 GPU 内存中的 probs 张量副本。 |
to() | 方法 | 返回具有指定设备和数据类型的 probs 张量副本。 |
top1 | 属性(int) | 排名第 1 的类别索引。 |
top5 | 属性(list[int]) | 排名前 5 的类别索引。 |
top1conf | 属性(torch.Tensor) | 排名第 1 的类别置信度。 |
top5conf | 属性(torch.Tensor) | 排名前 5 的类别置信度。 |
如需了解更多详情,请参阅Probs 类文档。
OBB#
OBB 对象可用于索引、处理和转换不同格式的定向边界框。
from ultralytics import YOLO
# 加载预训练的 YOLO26n 模型
model = YOLO("yolo26n-obb.pt")
# 对图像进行推理
results = model("https://ultralytics.com/images/boats.jpg") # 结果列表
# 查看结果
for r in results:
print(r.obb) # 打印包含定向检测边界框的 OBB 对象以下是 OBB 类的方法和属性表格,其中包括名称、类型和说明:
| 名称 | 类型 | 说明 |
|---|---|---|
cpu() | 方法 | 将对象移至 CPU 内存。 |
numpy() | 方法 | 将对象转换为 NumPy 数组。 |
cuda() | 方法 | 将对象移至 CUDA 内存。 |
to() | 方法 | 将对象移至指定设备。 |
conf | 属性(torch.Tensor) | 返回框的置信度值。 |
cls | 属性(torch.Tensor) | 返回框的类别值。 |
id | 属性(torch.Tensor) | 返回框的跟踪 ID(如果有)。 |
xyxy | 属性(torch.Tensor) | 以 xyxy 格式返回水平边界框。 |
xywhr | 属性(torch.Tensor) | 以 xywhr 格式返回旋转边界框。 |
xyxyxyxy | 属性(torch.Tensor) | 以 xyxyxyxy 格式返回旋转边界框。 |
xyxyxyxyn | 属性(torch.Tensor) | 以根据图像尺寸归一化后的 xyxyxyxy 格式返回旋转边界框。 |
如需了解更多详情,请参阅OBB 类文档。
绘制结果#
Results 对象中的 plot() 方法通过将检测到的对象(例如边界框、掩码、关键点和概率)叠加到原始图像上,帮助你可视化预测结果。该方法以 NumPy 数组的形式返回带标注的图像,方便你显示或保存。
from PIL import Image
from ultralytics import YOLO
# Load a pretrained YOLO26n model
model = YOLO("yolo26n.pt")
# Run inference on 'bus.jpg'
results = model(["https://ultralytics.com/images/bus.jpg", "https://ultralytics.com/images/zidane.jpg"]) # results list
# Visualize the results
for i, r in enumerate(results):
# Plot results image
im_bgr = r.plot() # BGR-order numpy array
im_rgb = Image.fromarray(im_bgr[..., ::-1]) # RGB-order PIL image
# Show results to screen (in supported environments)
r.show()
# Save results to disk
r.save(filename=f"results{i}.jpg")plot() 方法参数#
plot() 方法支持多种参数,可用于自定义输出:
| 参数 | 类型 | 说明 | 默认值 |
|---|---|---|---|
conf | bool | 包含检测置信度分数。 | True |
line_width | float | 边界框的线宽。如果 None,线宽会随图像尺寸缩放。 | None |
font_size | float | 文本字号。如果 None,字号会随图像尺寸缩放。 | None |
font | str | 文本标注的字体名称。 | 'Arial.ttf' |
pil | bool | 以 PIL Image 对象的形式返回图像。 | False |
img | np.ndarray | torch.Tensor | 备用图像。张量必须是连续的 HWC BGR uint8 格式。 | None |
kpt_radius | int | 绘制关键点的半径。 | 5 |
kpt_line | bool | 用线条连接关键点。 | True |
labels | bool | 在标注中包含类别标签。 | True |
boxes | bool | 在图像上叠加边界框。 | True |
masks | bool | 在图像上叠加掩码。 | True |
probs | bool | 包含分类概率。 | True |
show | bool | 使用默认图像查看器直接显示带标注的图像。 | False |
save | bool | 将带标注的图像保存到 filename 指定的文件中。 | False |
filename | str | 如果 save 为 True,则指定保存带标注图像的文件路径和名称。 | None |
color_mode | str | 指定颜色模式,例如 'instance' 或 'class'。 | 'class' |
txt_color | tuple[int, int, int] | 分类标签的 BGR 文本颜色。 | (255, 255, 255) |
线程安全推理#
在多个线程中并行运行多个 YOLO 模型时,确保推理过程的线程安全至关重要。线程安全推理可确保每个线程的预测结果彼此隔离、互不干扰,从而避免竞态条件,并确保输出一致且可靠。
在多线程应用中使用 YOLO 模型时,为每个线程实例化单独的模型对象,或使用线程本地存储来避免冲突,这一点很重要:
在每个线程中实例化一个模型,以实现线程安全推理:
from threading import Thread
from ultralytics import YOLO
def thread_safe_predict(model, image_path):
"""Performs thread-safe prediction on an image using a locally instantiated YOLO model."""
model = YOLO(model)
results = model.predict(image_path)
# 处理结果
# 启动各自拥有模型实例的线程
Thread(target=thread_safe_predict, args=("yolo26n.pt", "image1.jpg")).start()
Thread(target=thread_safe_predict, args=("yolo26n.pt", "image2.jpg")).start()如需深入了解 YOLO 模型的线程安全推理和分步说明,请参阅我们的 YOLO 线程安全推理指南。本指南将提供你所需的全部信息,帮助你避免常见问题,并确保多线程推理顺畅运行。
流式来源 for 循环#
下面是一个使用 OpenCV(cv2)和 YOLO 对视频帧运行推理的 Python 脚本。此脚本假设你已安装所需的软件包(opencv-python 和 ultralytics)。
import cv2
from ultralytics import YOLO
# 加载 YOLO 模型
model = YOLO("yolo26n.pt")
# 打开视频文件
video_path = "path/to/your/video/file.mp4"
cap = cv2.VideoCapture(video_path)
# 遍历视频帧
while cap.isOpened():
# 读取视频帧
success, frame = cap.read()
if success:
# 对该帧运行 YOLO 推理
results = model(frame)
# 可视化该帧上的结果
annotated_frame = results[0].plot()
# 显示带标注的帧
cv2.imshow("YOLO Inference", annotated_frame)
# 如果按下 'q',则退出循环
if cv2.waitKey(1) & 0xFF == ord("q"):
break
else:
# 如果到达视频末尾,则退出循环
break
# 释放视频捕获对象并关闭显示窗口
cap.release()
cv2.destroyAllWindows()此脚本会对视频的每一帧运行预测、可视化结果,并在窗口中显示结果。按下 'q' 即可退出循环。
接下来做什么#
准备好不再局限于预训练模型了吗?确认你的任务符合问题需求,使用数据集指南整理自己的数据,然后用这些数据训练。
常见问题#
Ultralytics YOLO 是一款先进的实时目标检测、实例分割、语义分割、深度估计、分类、姿态估计和定向边界框(OBB)检测模型。其 predict 模式支持用户对图像、视频和实时流等多种数据源执行高速推理。该模式兼顾性能与灵活性,还支持批处理和流式处理。有关其功能的更多详情,请查看 Ultralytics YOLO predict 模式。
Ultralytics YOLO 可以处理多种数据源,包括单张图像、视频、目录、URL 和流。你可以在
model.predict()调用中指定数据源。例如,对本地图像使用'image.jpg',对 URL 使用'https://ultralytics.com/images/bus.jpg'。请查看文档中的详细示例,了解各种推理数据源。若要优化推理速度并高效管理内存,可以在预测器的调用方法中设置
stream=True,以启用流式模式。流式模式会生成内存高效的Results对象生成器,而不是将所有帧加载到内存中。对于处理长视频或大型数据集,流式模式尤其有用。了解更多关于流式模式的信息。YOLO 中的
model.predict()方法支持多种参数,例如conf、iou、imgsz、device等。你可以使用这些参数自定义推理过程,设置置信度阈值、图像尺寸和计算设备等参数。你可以在推理参数部分查看这些参数的详细说明。使用
model.embed(source)从倒数第二层提取特征嵌入向量,或将embed=[layer_index]传递给model.predict(),以选择特定层。from ultralytics import YOLO model = YOLO("yolo26n.pt") source = "https://ultralytics.com/images/bus.jpg" results = model.predict(source) # 结果对象 embeddings = model.embed(source) # torch.Tensor 嵌入向量列表使用 YOLO 运行推理后,
Results对象会提供用于显示和保存带标注图像的方法。你可以使用result.show()和result.save(filename="result.jpg")等方法来可视化并保存结果。如果文件名路径中缺少上级目录,系统会自动创建(例如result.save("path/to/result.jpg"))。如需查看这些方法的完整列表,请参阅处理结果部分。