什么是 Ultralytics YOLO，以及它的 predict 模式如何用于实时推理？

Ultralytics YOLO 是一种用于实时目标检测、实例分割、语义分割、深度估计和分类的先进模型。其 predict 模式支持用户对图像、视频和实时流等各种数据源执行高速推理。它专为性能和多功能性而设计，同时还提供批处理和流式处理模式。如需详细了解其功能，请查看 Ultralytics YOLO predict 模式。

如何使用 Ultralytics YOLO 对不同数据源运行推理？

Ultralytics YOLO 可以处理各种数据源，包括单张图像、视频、目录、URL 和流。你可以在 model.predict() 调用中指定数据源。例如，对本地图像使用 'image.jpg'，对 URL 使用 'https://ultralytics.com/images/bus.jpg'。请查看文档中关于各种推理源的详细示例。

如何优化 YOLO 推理速度和内存使用？

要优化推理速度并高效管理内存，你可以在预测器的调用方法中设置 stream=True，以使用流式模式。流式模式会生成由 Results 对象组成的内存高效生成器，而不是将所有帧加载到内存中。对于处理长视频或大型数据集，流式模式尤其有用。详细了解流式模式。

Ultralytics YOLO 支持哪些推理参数？

YOLO 中的 model.predict() 方法支持各种参数，例如 conf、iou、imgsz、device 等。这些参数可以让你自定义推理过程，设置置信度阈值、图像大小和用于计算的设备等参数。你可以在推理参数部分查看这些参数的详细说明。

如何可视化和保存 YOLO 预测结果？

使用 YOLO 运行推理后，Results 对象包含用于显示和保存带注释图像的方法。你可以使用 result.show() 和 result.save(filename="result.jpg") 等方法来可视化和保存结果。如果文件名路径中缺少父目录，系统会自动创建这些目录（例如：result.save("path/to/result.jpg")）。如需查看这些方法的完整列表，请参阅处理结果部分。

使用 Ultralytics YOLO 进行模型预测#

Q: 如何从 YOLO 模型中提取嵌入？

使用 model.embed(source) 从倒数第二层提取特征嵌入，或将 embed=[layer_index] 传递给 model.predict() 以选择特定层。

Ultralytics YOLO ecosystem and integrations

简介#

在机器学习和计算机视觉领域，将视觉数据转换为有意义信息的过程通常称为推理或预测。Ultralytics YOLO26 提供了一项称为预测模式的强大功能，专为各种数据源上的高性能实时推理而设计。

请参阅unreleased YOLO27 preview以了解计划中的推理示例。

Watch: How to Extract Results from Ultralytics YOLO26 Tasks for Custom Projects 🚀

实际应用#

制造业	体育	安全

车辆备件检测	足球运动员检测	人员跌倒检测

为什么使用 Ultralytics YOLO 进行推理？#

以下是你应考虑使用 YOLO26 预测模式来满足各种推理需求的原因：

**多功能性：**能够对图像、视频，甚至实时流执行推理。
**性能：**专为实时高速处理而设计，同时不牺牲准确率。
**易用性：**直观的 Python 和 CLI 接口，便于快速部署和测试。
**高度可定制：**提供各种设置和参数，可根据你的具体需求调整模型的推理行为。
**可用于生产环境：**将模型部署为带有自动扩缩容和监控功能的 Ultralytics Platform 推理端点，或在本地运行推理。

预测模式的主要功能#

YOLO26 的预测模式设计稳健且灵活，具备以下功能：

**兼容多种数据源：**无论你的数据是单张图像、图像集合、视频文件还是实时视频流，预测模式都能满足需求。
**流式模式：**使用流式功能生成内存高效的 Results 对象生成器。在预测器的调用方法中设置 stream=True 即可启用该功能。与返回包含所有结果的列表的默认行为（stream=False）不同，stream=True 会逐个生成结果，因此特别适合长视频和实时流。
**批处理：**在单个批次中处理多张图像或多个视频帧，进一步缩短总推理时间。
**易于集成：**凭借灵活的 API，可轻松与现有数据管道及其他软件组件集成。

Ultralytics YOLO 模型在推理期间接收 stream=True 时，会返回由 Results 对象组成的 Python 列表，或由 Results 对象组成的内存高效生成器：

Predict

from ultralytics import YOLO

# Load a model
model = YOLO("yolo26n.pt")  # pretrained YOLO26n model

# Run batched inference on a list of images
results = model(["image1.jpg", "image2.jpg"])  # return a list of Results objects

# Process results list
for result in results:
    boxes = result.boxes  # Boxes object for bounding box outputs
    masks = result.masks  # Masks object for segmentation masks outputs
    keypoints = result.keypoints  # Keypoints object for pose outputs
    probs = result.probs  # Probs object for classification outputs
    obb = result.obb  # Oriented boxes object for OBB outputs
    result.show()  # display to screen
    result.save(filename="result.jpg")  # save to disk

推理源#

如下面的表格所示，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 等流式协议的 URL，或 IP 地址。
多流 ✅	`'list.streams'`	`str` 或 `Path`	`*.streams` 文本文件，每行包含一个流 URL，即 8 个流将以批次大小 8 运行。
摄像头 ✅	`0`	`int`	要执行推理的已连接摄像头设备索引。

下面是使用每种源类型的代码示例：

预测源

对图像文件执行推理。

from ultralytics import YOLO

# Load a pretrained YOLO26n model
model = YOLO("yolo26n.pt")

# Define path to the image file
source = "path/to/image.jpg"

# Run inference on the source
results = model(source)  # list of Results objects

推理参数#

model.predict() 接受多个参数，这些参数可以在推理时传入以覆盖默认值：

固定形状与最小矩形（`rect`）#

默认情况下，predict 使用 rect=True，在可能的情况下启用最小矩形填充。图像会缩放以适应 imgsz，并且只填充到最近的步幅倍数，因此最终张量可能小于 imgsz。只有当批次中的所有图像形状相同且后端支持时，才会使用最小矩形填充（PyTorch .pt，或动态 ONNX / Triton）。否则，图像会填充到完整的 imgsz 目标尺寸。

使用 rect=False 始终填充到完整的 imgsz 目标尺寸。当你需要固定输入尺寸以匹配导出模型（ONNX、TensorRT 等）时，建议使用此选项。

整数与元组 imgsz

整数 imgsz=640 在步幅取整后会变为正方形目标 (640, 640)。
元组 imgsz=(384, 672) 会设置矩形目标尺寸。使用 rect=True 和 auto=True 时，实际张量可能小于该目标尺寸。

训练与 predict/export

训练只接受单个整数 imgsz（[h, w] 列表会被强制转换为最大值）。Predict 和 export 接受整数或 (height, width) 元组。

示例

from ultralytics import YOLO

# Load a pretrained YOLO26n model
model = YOLO("yolo26n.pt")

# Run inference on 'bus.jpg' with arguments
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`	交并比 (IoU) 阈值，用于非极大值抑制 (NMS)。较低的值会通过消除重叠框来减少检测结果，有助于减少重复检测。
`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"`/未设置为 PyTorch 和 TorchScript 模型选择 FP16 或 FP32 计算；其他格式则在其构件与运行时所选的精度下进行计算。在 `16` 下，OpenVINO 仍在客户端将输入进行 FP16 舍入并将其展宽回 FP32，但这不会改变运行时实际的计算精度。INT8/PTQ 量化在导出期间进行配置，然后通过加载导出的模型来使用。该参数替代了已弃用的 `half` 标志。
`device`	`str`	`None`	指定推理设备（例如 `cpu`、`cuda:0`、`0`、`npu` 或 `npu:0`）。允许你在 CPU、特定 GPU、华为 Ascend NPU 或其他计算设备之间进行选择，以执行模型推理。
`dnn`	`bool`	`False`	如果为 `True`，则在 ONNX 模型推理中使用 OpenCV DNN 模块，而不是 ONNX Runtime。
`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"` 等字符串模式。不支持时会发出警告并回退到 eager 模式。
`channels_last`	`bool`	`None`	对原生 PyTorch 推理使用 channels_last (NHWC) 内存格式。`None` 会在启用 oneDNN 的 Linux 和 Windows x86 CPU 上、PyTorch 1.13 或更高版本中自动启用该格式，`False` 会禁用该格式，`True` 会在受支持的 x86 CPU 或 CUDA 设备上请求该格式。ARM64、MPS、较旧的 PyTorch 版本、不支持 oneDNN 的 CPU，以及 TensorRT 和 ONNX 等导出格式均保持不变。
`nms`	`bool`，可选	`None`	默认运行带 NMS 的一对多推理（`None` 或 `True`）。设置 `False` 以在可用时使用无 NMS 的一对一（one-to-one）头。详见端到端检测指南。

可视化参数：

参数	类型	默认值	描述
`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。有效后缀和示例预测命令请参阅下表。

图像#

下表包含有效的 Ultralytics 图像格式。

注意

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

图像后缀	示例预测命令	参考
`.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 视频格式。

视频后缀	示例预测命令	参考
`.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 部分 - Wikipedia
`.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

# Load a pretrained YOLO26n model
model = YOLO("yolo26n.pt")

# Run inference on an image
results = model("https://ultralytics.com/images/bus.jpg")
results = model(
    [
        "https://ultralytics.com/images/bus.jpg",
        "https://ultralytics.com/images/zidane.jpg",
    ]
)  # batch inference

Results 对象具有以下属性：

属性	类型	描述
`orig_img`	`np.ndarray`	作为 NumPy 数组的原始图像。
`orig_shape`	`tuple`	采用 (height, width) 格式的原始图像形状。
`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 对象。
`speed`	`dict`	一个字典，记录预处理、推理和后处理速度，单位为每张图像的毫秒数。
`names`	`dict`	将类别索引映射到类别名称的字典。
`path`	`str`	图像文件的路径。
`save_dir`	`str, optional`	用于保存结果的目录。

按任务划分的 Results#

下面填充哪些字段取决于你的模型任务——如果你还没选好，请对比检测、分割、语义分割、深度估计、分类、姿态和OBB。每次预测每张图像或每帧返回一个 Results 对象。上面的通用字段始终可用，而特定于任务的预测数据存储在下面的字段中。YOLO坐标和置信度张量是 torch.float32；概率张量是 torch.float32，除非使用半精度，此时为 torch.float16。在 result.numpy() 之后，张量会变成具有相应 NumPy 数据类型的 NumPy 数组。实例掩码是 torch.uint8 二进制张量，而语义掩码使用适合类别的最小实际整数数据类型：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`	返回一个副本，其中所有张量都已转换为 NumPy 数组。
`cuda()`	`Results`	返回一个副本，其中所有张量都已移动到 GPU 内存。
`to()`	`Results`	返回一个副本，其中张量已移动到指定设备并转换为指定 dtype。
`new()`	`Results`	创建一个新的 Results 对象，其中包含相同的图像、路径、名称和速度属性。
`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

# Load a pretrained YOLO26n model
model = YOLO("yolo26n.pt")

# Run inference on an image
results = model("https://ultralytics.com/images/bus.jpg")  # results list

# View results
for r in results:
    print(r.boxes)  # print the Boxes object containing the detection bounding 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

# Load a pretrained YOLO26n-seg Segment model
model = YOLO("yolo26n-seg.pt")

# Run inference on an image
results = model("https://ultralytics.com/images/bus.jpg")  # results list

# View results
for r in results:
    print(r.masks)  # print the Masks object containing the detected instance masks

下面的表格列出了 Masks 类的方法和属性，包括其名称、类型和描述：

名称	类型	描述
`data`	属性（`torch.Tensor`）	形状为 `(N,H,W)`、值为 `0` 或 `1` 的 `torch.uint8` 二值掩码张量。
`cpu()`	方法	返回位于 CPU 内存中的掩码张量。
`numpy()`	方法	以 NumPy 数组形式返回掩码张量。
`cuda()`	方法	返回位于 GPU 内存中的掩码张量。
`to()`	方法	返回位于指定设备上并具有指定 dtype 的掩码张量。
`xyn`	属性（`list[np.ndarray]`）	归一化掩码多边形列表。
`xy`	属性（`list[np.ndarray]`）	以像素坐标表示的掩码多边形列表。

有关更多详情，请参阅 Masks 类文档。

SemanticMask#

SemanticMask 存储语义分割结果的一张稠密类别图。与 Masks 不同，它不包含每个对象对应的一张二值掩码，也不提供多边形辅助方法。

SemanticMask

from ultralytics import YOLO

# Load a pretrained YOLO26n-sem Semantic model
model = YOLO("yolo26n-sem.pt")

# Run inference on an image
results = model("https://ultralytics.com/images/bus.jpg")  # results list

# View results
for r in results:
    print(r.semantic_mask.data)  # print the H x W class-ID map

名称	类型	描述
`data`	属性（`torch.Tensor`）	形状为 `(H,W)` 的类别 ID 图。dtype 为 `torch.uint8`、`torch.int16` 或 `torch.int32`，具体取决于类别数量。
`shape`	属性（`tuple`）	类别图的形状，通常与 `result.orig_shape` 匹配。
`cpu()`	方法	返回位于 CPU 内存中的语义掩码张量。
`numpy()`	方法	以 NumPy 数组形式返回语义掩码张量。
`cuda()`	方法	返回位于 GPU 内存中的语义掩码张量。
`to()`	方法	返回位于指定设备上并具有指定 dtype 的语义掩码张量。

关键点#

Keypoints 对象可用于索引、操作坐标并进行归一化。

关键点

from ultralytics import YOLO

# Load a pretrained YOLO26n-pose Pose model
model = YOLO("yolo26n-pose.pt")

# Run inference on an image
results = model("https://ultralytics.com/images/bus.jpg")  # results list

# View results
for r in results:
    print(r.keypoints)  # print the Keypoints object containing the detected keypoints

下面的表格列出了 Keypoints 类的方法和属性，包括其名称、类型和描述：

名称	类型	描述
`cpu()`	方法	返回位于 CPU 内存中的关键点张量。
`numpy()`	方法	以 NumPy 数组形式返回关键点张量。
`cuda()`	方法	返回位于 GPU 内存中的关键点张量。
`to()`	方法	返回位于指定设备上并具有指定 dtype 的关键点张量。
`xyn`	属性（`torch.Tensor`）	以张量表示的归一化关键点列表。
`xy`	属性（`torch.Tensor`）	以张量表示的像素坐标关键点列表。
`conf`	属性（`torch.Tensor`）	如果可用，则返回关键点的置信度值，否则返回 None。

有关更多详情，请参阅 Keypoints 类文档。

Probs#

Probs 对象可用于获取 top1 和 top5 分类索引及分数。

Probs

from ultralytics import YOLO

# Load a pretrained YOLO26n-cls Classify model
model = YOLO("yolo26n-cls.pt")

# Run inference on an image
results = model("https://ultralytics.com/images/bus.jpg")  # results list

# View results
for r in results:
    print(r.probs)  # print the Probs object containing the detected class probabilities

下面的表格总结了 Probs 类的方法和属性：

名称	类型	描述
`cpu()`	方法	返回位于 CPU 内存中的 probs 张量副本。
`numpy()`	方法	以 NumPy 数组形式返回 probs 张量副本。
`cuda()`	方法	返回位于 GPU 内存中的 probs 张量副本。
`to()`	方法	返回位于指定设备上并具有指定 dtype 的 probs 张量副本。
`top1`	属性（`int`）	排名第 1 的类别索引。
`top5`	属性（`list[int]`）	排名前 5 的类别索引。
`top1conf`	属性（`torch.Tensor`）	排名第 1 的类别置信度。
`top5conf`	属性（`torch.Tensor`）	排名前 5 的类别置信度。

有关更多详情，请参阅 Probs 类文档。

OBB#

OBB 对象可用于索引、操作定向边界框，并将其转换为不同格式。

OBB

from ultralytics import YOLO

# Load a pretrained YOLO26n model
model = YOLO("yolo26n-obb.pt")

# Run inference on an image
results = model("https://ultralytics.com/images/boats.jpg")  # results list

# View results
for r in results:
    print(r.obb)  # print the OBB object containing the oriented detection bounding boxes

下面的表格列出了 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)
    # Process results

# Starting threads that each have their own model instance
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

# Load the YOLO model
model = YOLO("yolo26n.pt")

# Open the video file
video_path = "path/to/your/video/file.mp4"
cap = cv2.VideoCapture(video_path)

# Loop through the video frames
while cap.isOpened():
    # Read a frame from the video
    success, frame = cap.read()

    if success:
        # Run YOLO inference on the frame
        results = model(frame)

        # Visualize the results on the frame
        annotated_frame = results[0].plot()

        # Display the annotated frame
        cv2.imshow("YOLO Inference", annotated_frame)

        # Break the loop if 'q' is pressed
        if cv2.waitKey(1) & 0xFF == ord("q"):
            break
    else:
        # Break the loop if the end of the video is reached
        break

# Release the video capture object and close the display window
cap.release()
cv2.destroyAllWindows()

此脚本将对视频的每一帧运行预测、可视化结果，并在窗口中显示结果。按“q”键即可退出循环。

接下来做什么#

准备好超越预训练模型了吗？先确认你的任务符合问题需求，使用数据集指南格式化自己的数据，然后在其上进行训练。

常见问题#

Ultralytics YOLO 是一种用于实时目标检测、实例分割、语义分割、深度估计和分类的先进模型。其 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)  # Results objects
embeddings = model.embed(source)  # list of torch.Tensor embeddings

使用 YOLO 运行推理后，Results 对象包含用于显示和保存带注释图像的方法。你可以使用 result.show() 和 result.save(filename="result.jpg") 等方法来可视化和保存结果。如果文件名路径中缺少父目录，系统会自动创建这些目录（例如：result.save("path/to/result.jpg")）。如需查看这些方法的完整列表，请参阅处理结果部分。

创建时间 2023年11月12日更新时间 4天前