Ultralytics YOLO27:
Get Started

使用 Ultralytics YOLO 进行模型预测#

Ultralytics YOLO ecosystem and integrations

简介#

在机器学习和计算机视觉领域中,理解视觉数据的过程通常称为推理或预测。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截取屏幕截图。
PILImage.open('image.jpg')PIL.Image采用 RGB 通道的 HWC 格式。
OpenCVcv2.imread('image.jpg')np.ndarray采用 BGR 通道的 HWC 格式 uint8 (0-255)。
NumPynp.zeros((640,1280,3))np.ndarray采用 BGR 通道的 HWC 格式 uint8 (0-255)。
torchtorch.zeros(16,3,320,640)torch.Tensor采用 RGB 通道的 BCHW 格式 float32 (0.0-1.0)。
CSV'sources.csv'str 或 Path包含图像、视频或目录路径的 CSV 文件。
视频 ✅'video.mp4'str 或 PathMP4、AVI 等格式的视频文件。
目录 ✅'path/'str 或 Path包含图像或视频的目录路径。
glob ✅'path/*.jpg'str用于匹配多个文件的 Glob 模式。使用 * 字符作为通配符。
YouTube ✅'https://youtu.be/LNwODJXcvt4'strYouTube 视频的 URL。
流 ✅'rtsp://example.com/media.mp4'str流媒体协议(例如 RTSP、RTMP、TCP)或 IP 地址的 URL。
多路流 ✅'list.streams'str 或 Path*.streams 文本文件,每行包含一个流 URL;例如,8 路流将以批次大小 8 运行。
网络摄像头 ✅0int要运行推理的已连接摄像头设备的索引。

以下是使用各种数据源类型的代码示例:

预测数据源

对图像文件运行推理。

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)

推理参数:

参数类型默认值说明
sourcestr 或 int 或 NoneNone指定推理的数据源。可以是图像路径、视频文件、目录、URL,或实时画面的设备 ID。如果未指定,系统会记录警告,并使用内置演示资源(ultralytics/assets;对于 OBB,则使用演示 URL)作为模型输入。此功能支持多种格式和来源,可灵活应用于不同类型的输入。
conffloat0.25设置检测的最低置信度阈值。置信度低于此阈值的检测结果会被忽略。调整此值有助于减少误报。
ioufloat0.7用于非极大值抑制(NMS)的交并比(IoU)阈值。较低的值会通过消除重叠框来减少检测结果,有助于减少重复检测。
imgszint 或 tuple640Letterbox 的目标尺寸。整数表示正方形N×N;元组表示(height, width)。使用rect=True时,由于采用最小矩形填充,实际张量可能小于此目标尺寸。使用rect=False可设为固定尺寸。请参阅固定尺寸与最小矩形。
rectboolTrue如果为True,则在条件允许时使用最小矩形填充(批次中图像形状相同且后端支持)。如果为False,则始终填充至完整的imgsz。请参阅固定尺寸与最小矩形。
quantizeint 或 strNone推理精度:16/"fp16" 和 32/"fp32"/unset 用于为 PyTorch 和 TorchScript 模型选择 FP16 或 FP32 计算(CPU 上为 FP32);其他格式使用其模型文件和运行时所选的精度。在 16 中,OpenVINO 仍会在客户端将输入舍入为 FP16,再扩展回 FP32,但不会更改运行时精度。INT8/PTQ 量化在导出期间配置,然后通过加载导出的模型来使用。此参数替代已弃用的 half 标志。
devicestrNone指定推理使用的设备(例如 cpu、cuda:0、0、npu 或 npu:0)。用户可以选择 CPU、特定 GPU、华为昇腾 NPU 或其他计算设备来运行模型。
dnnboolFalse如果 True,则使用 OpenCV DNN 模块,而不是 ONNX Runtime 执行 ONNX 模型推理。
datastrNone数据集 YAML 文件的路径(例如 coco8.yaml)。仅读取其中的 names,且仅当加载的模型没有自带类别名称时才会读取:例如第三方导出模型,或与随附元数据分离的 Ultralytics 导出模型。否则,此类模型会报告 class0、class1 等。
batchint1指定推理的批次大小(仅在来源为目录、视频文件或 .txt 文件时有效)。较大的批次大小可以提高吞吐量,缩短推理所需的总时间。
max_detint300每张图像允许检测的最大数量。限制模型在单次推理中可检测的对象总数,避免密集场景中产生过多输出。
vid_strideint1视频输入的帧步长。允许跳过视频帧以加快处理速度,但会降低时间分辨率。值为 1 时处理每一帧;值越大,跳过的帧越多。
stream_bufferboolFalse决定是否为视频流的传入帧排队。如果 False,则会丢弃旧帧以容纳新帧(针对实时应用进行了优化)。如果 True,则会将新帧放入缓冲区,确保不跳过任何帧;但如果推理 FPS 低于视频流 FPS,就会产生延迟。
visualizeboolFalse在每个预测结果旁保存类别激活热力图,显示哪些像素提高了预测类别的分数。遵循 conf 和 classes,因此 classes=[0] 只映射该类别。仅适用于 Ultralytics PyTorch 模型。
augmentboolFalse为预测启用测试时增强(TTA),可能提升检测的稳健性,但会降低推理速度。仅适用于 Ultralytics PyTorch 模型。
agnostic_nmsboolFalse启用类别无关的非极大值抑制(NMS),抑制不同类别之间得分较低且重叠的框,而不只是同一类别内的框。适用于类别间常有重叠的多类别检测场景。对于无 NMS 推理(YOLO26 或 YOLOv10 上的 nms=False),此选项仅防止同一检测结果带有多个类别标签(IoU=1.0 的重复项),不会根据 IoU 阈值抑制不同的框。
classeslist[int]None将预测结果筛选为指定的类别 ID。只返回属于指定类别的检测结果。适用于在多类别检测任务中聚焦相关对象。
retina_masksboolFalse返回高分辨率分割掩码。启用后,返回的掩码(masks.data)将与原始图像尺寸一致。禁用后,掩码尺寸与推理时使用的图像尺寸一致。
embedlist[int]None指定要提取特征向量或嵌入的层。使用 model.embed(source) 获取倒数第二层的嵌入,或使用 model.predict(source, embed=[layer]) 选择特定层。适用于聚类或相似度搜索等下游任务。仅适用于 Ultralytics PyTorch 模型。
projectstrNone启用 save 时,保存预测输出的项目目录名称。
namestrNone预测运行的名称。启用 save 时,用于在项目文件夹中创建子目录以存储预测输出。
streamboolFalse通过返回 Results 对象生成器,而不是一次性将所有帧加载到内存中,为长视频或大量图像启用节省内存的处理方式。
verboseboolTrue控制是否在终端中显示详细的推理日志,以实时反馈预测过程。
compilebool 或 strFalse使用backend='inductor'启用 PyTorch 2.x torch.compile图编译。接受True → "default"、False → 禁用,或"default"、"reduce-overhead"、"max-autotune-no-cudagraphs"等字符串模式。如果不受支持,则会发出警告并回退到即时执行模式。
channels_lastboolNone对原生 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 等导出格式均不受影响。
nmsbool,可选None默认使用 NMS 执行一对多推理(None 或 True)。设置 False 可在可用时使用无 NMS 的一对一检测头。详情请参阅端到端检测指南。

可视化参数:

参数类型默认值说明
showboolFalse如果 True,则在窗口中显示带标注的图像或视频。适用于在开发或测试期间即时查看结果。
saveboolFalse or True启用后将带标注的图像或视频保存到文件。适用于文档编写、进一步分析或分享结果。使用 CLI 时默认为 True,在 Python 中使用时默认为 False。
save_framesboolFalse处理视频时,将单独的帧保存为图像。适用于提取特定帧或逐帧详细分析。
save_txtboolFalse按照 [class] [x_center] [y_center] [width] [height] [confidence] 格式将检测结果保存到文本文件。适用于与其他分析工具集成。
save_confboolFalse在保存的文本文件中包含置信度分数。增加可用于后处理和分析的详细信息。
save_cropboolFalse保存检测对象的裁剪图像。适用于数据集增强、分析,或为特定对象创建专用数据集。
show_labelsboolTrue在可视化输出中显示每个检测结果的标签,便于立即了解检测到的对象。
show_confboolTrue在每个检测结果的标签旁显示置信度分数,帮助了解模型对该检测结果的确信程度。
show_boxesboolTrue在检测到的对象周围绘制边界框,便于在图像或视频帧中直观识别和定位对象。
line_widthint or NoneNone指定边界框的线宽。如果 None,则会根据图像尺寸自动调整线宽,便于自定义显示效果并提高清晰度。

图像和视频格式#

YOLO26 支持多种图像和视频格式,具体格式见 ultralytics/data/utils.py。请参阅下表,了解有效后缀和 predict 命令示例。

图像#

下表列出了有效的 Ultralytics 图像格式。

注意

HEIC/HEIF 格式需要 pi-heif,首次使用时会自动安装。Pillow 原生支持 AVIF。

图像后缀predict 命令示例参考
.avifyolo predict source=image.avifAV1 图像文件格式
.bmpyolo predict source=image.bmpMicrosoft BMP 文件格式
.dngyolo predict source=image.dngAdobe DNG
.heicyolo predict source=image.heic高效图像文件格式
.heifyolo predict source=image.heif高效图像文件格式
.jp2yolo predict source=image.jp2JPEG 2000
.jpegyolo predict source=image.jpegJPEG
.jpgyolo predict source=image.jpgJPEG
.mpoyolo predict source=image.mpo多图像对象
.pngyolo predict source=image.png便携式网络图形
.tifyolo predict source=image.tif标记图像文件格式
.tiffyolo predict source=image.tiff标记图像文件格式
.webpyolo predict source=image.webpWebP

视频#

下表列出了有效的 Ultralytics 视频格式。

视频后缀predict 命令示例参考
.asfyolo predict source=video.asf高级系统格式
.aviyolo predict source=video.avi音视频交错格式
.gifyolo predict source=video.gif图形交换格式
.m4vyolo predict source=video.m4vMPEG-4 第 14 部分
.mkvyolo predict source=video.mkvMatroska
.movyolo predict source=video.movQuickTime 文件格式
.mp4yolo predict source=video.mp4MPEG-4 第 14 部分 - 维基百科
.mpegyolo predict source=video.mpegMPEG-1 第 2 部分
.mpgyolo predict source=video.mpgMPEG-1 第 2 部分
.tsyolo predict source=video.tsMPEG 传输流
.wmvyolo predict source=video.wmvWindows Media 视频
.webmyolo predict source=video.webmWebM 项目

处理 Results#

所有 Ultralytics predict() 调用都会返回一个 Results 对象列表:

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_imgnp.ndarray原始图像的 NumPy 数组。
orig_shapetuple原始图像的形状,格式为 (高度, 宽度)。
boxesBoxes, optional包含检测边界框的 Boxes 对象。
masksMasks, optional包含检测掩码的 Masks 对象。
probsProbs, optional包含分类任务中每个类别概率的 Probs 对象。
keypointsKeypoints, optional包含每个对象检测到的关键点的 Keypoints 对象。
obbOBB, optional包含有向边界框的 OBB 对象。
semantic_maskSemanticMask, optional包含密集逐像素类别映射的 SemanticMask 对象。
depthDepthMap, optional包含密集逐像素深度图的 DepthMap 对象。
speeddict一个字典,记录每张图像的预处理、推理和后处理耗时(毫秒)。
namesdict一个将类别索引映射到类别名称的字典。
pathstr图像文件的路径。
save_dirstr, 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.boxesBoxes(N)检测框。
result.boxes.datatorch.float32(N,6/7)原始 [x1,y1,x2,y2,conf,cls],以及可选的跟踪 ID。
result.boxes.xyxytorch.float32(N,4)xyxy 像素框。
result.boxes.conftorch.float32(N,)置信度分数。
result.boxes.clstorch.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 不同,它不包含每个对象对应的二值掩码,也不提供多边形辅助方法。

SemanticMask
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 对象可用于索引、处理和转换不同格式的定向边界框。

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() 方法支持多种参数,可用于自定义输出:

参数类型说明默认值
confbool包含检测置信度分数。True
line_widthfloat边界框的线宽。如果 None,线宽会随图像尺寸缩放。None
font_sizefloat文本字号。如果 None,字号会随图像尺寸缩放。None
fontstr文本标注的字体名称。'Arial.ttf'
pilbool以 PIL Image 对象的形式返回图像。False
imgnp.ndarray | torch.Tensor备用图像。张量必须是连续的 HWC BGR uint8 格式。None
kpt_radiusint绘制关键点的半径。5
kpt_linebool用线条连接关键点。True
labelsbool在标注中包含类别标签。True
boxesbool在图像上叠加边界框。True
masksbool在图像上叠加掩码。True
probsbool包含分类概率。True
showbool使用默认图像查看器直接显示带标注的图像。False
savebool将带标注的图像保存到 filename 指定的文件中。False
filenamestr如果 save 为 True,则指定保存带标注图像的文件路径和名称。None
color_modestr指定颜色模式,例如 'instance' 或 'class'。'class'
txt_colortuple[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)。

流式 for 循环
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"))。如需查看这些方法的完整列表,请参阅处理结果部分。

评论