使用 Ultralytics YOLO 进行模型预测

Ultralytics YOLO ecosystem and integrations

介绍

在机器学习和计算机视觉领域，理解视觉数据的过程通常被称为推理或预测。Ultralytics YOLO26 提供了一种强大的功能，称为 predict 模式，专为跨各种数据源的高性能实时推理而量身定制。

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

实际应用

制造业	体育运动	安全防护

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

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

以下是你应该考虑将 YOLO26 的 predict 模式用于各种推理需求的理由：

多功能性： 能够对图像、视频甚至实时流进行推理。
高性能： 专为实时、高速处理而设计，且不会牺牲准确率。
易用性： 提供直观的 Python 和 CLI 接口，便于快速部署和测试。
高度可定制： 提供多种设置和参数，可以根据你的特定需求调整模型的推理行为。
生产就绪： 可以将模型部署为 Ultralytics Platform 上的 API 端点，并支持自动缩放和监控，也可以在本地运行推理。

Predict 模式的核心功能

YOLO26 的 predict 模式旨在保持健壮性和多功能性，其特性包括：

多数据源兼容性： 无论你的数据是单张图像、图像集合、视频文件还是实时视频流，predict 模式都能满足你的需求。
流式模式 (Streaming Mode)： 使用流式功能生成 Results 对象的内存高效生成器。通过在预测器调用方法中设置 stream=True 来启用此功能。
批量处理： 在单个批次中处理多张图像或视频帧，进一步减少总推理时间。
集成友好： 得益于其灵活的 API，可以轻松与现有数据流水线和其他软件组件集成。

Ultralytics YOLO models return either a Python list of Results objects or a memory-efficient generator of Results objects when stream=True is passed to the model during inference:

预测

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() 接受多个可在推理时传递的参数，以覆盖默认设置：

固定尺寸 vs 最小矩形 (`rect`)

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

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

整数 vs 元组 imgsz

整数 imgsz=640 在步长取整后将成为正方形目标 (640, 640)。
元组 imgsz=(384, 672) 设置一个矩形目标。当 rect=True 和 auto=True 时，实际张量可以小于此目标。

训练 vs 预测/导出

训练仅接受单个整数 imgsz（[h, w] 列表会被强制转换为最大值）。预测和导出既接受整数，也接受 (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`	用于非极大值抑制 (NMS) 的交并比 (IoU) 阈值。较低的值通过消除重叠框来减少检测结果，有助于减少重复。
`imgsz`	`int` 或 `tuple`	`640`	Letterbox 目标尺寸。整数表示正方形 `N×N`；元组表示 `(height, width)`。使用 `rect=True` 时，由于最小矩形填充，实际张量可能小于此目标。使用 `rect=False` 可获得固定尺寸。请参阅固定形状与最小矩形。
`rect`	`bool`	`True`	如果为 `True`，则在可能时使用最小矩形填充（相同形状的批次和支持的后端）。如果为 `False`，则始终填充到完整的 `imgsz`。请参阅固定形状与最小矩形。
`half`	`bool`	`False`	启用半精度 (FP16) 推理，这可以在支持的 GPU 上加快模型推理速度，且对准确率的影响极小。
`device`	`str`	`None`	指定推理设备（例如 `cpu`、`cuda:0`、`0`、`npu` 或 `npu:0`）。允许用户在 CPU、特定 GPU、华为昇腾 NPU 或其他计算设备之间选择以执行模型。
`batch`	`int`	`1`	指定推理的批次大小（仅当源为目录、视频文件或 `.txt` 文件时有效）。较大的批次大小可以提供更高的吞吐量，从而缩短推理所需的总时间。
`max_det`	`int`	`300`	每张图片允许的最大检测数量。限制模型在单次推理中可以检测到的对象总数，防止在密集场景中输出过多结果。
`vid_stride`	`int`	`1`	视频输入的帧步长。允许在视频中跳帧，以牺牲时间分辨率为代价加快处理速度。数值为 1 时处理每一帧，更高的数值则会跳过部分帧。
`stream_buffer`	`bool`	`False`	确定是否为视频流对输入帧进行排队。如果设为 `False`，旧帧将被丢弃以容纳新帧（针对实时应用进行了优化）。如果设为 `True`，会将新帧放入缓冲区队列，确保不丢失任何帧，但在推理 FPS 低于视频流 FPS 时会导致延迟。
`visualize`	`bool`	`False`	在推理过程中激活模型特征可视化，深入了解模型“看到”的内容。这对于调试和模型解释非常有用。
`augment`	`bool`	`False`	为预测启用测试时增强 (TTA)，这可能会提高检测的稳健性，但会牺牲一定的推理速度。
`agnostic_nms`	`bool`	`False`	启用类别无关的非极大值抑制 (NMS)，它会合并不同类别的重叠框。这在类别重叠常见的多类检测场景中非常有用。对于端到端模型（YOLO26、YOLOv10），这仅防止同一检测结果以多个类别标签出现（IoU=1.0 的重复项），而不会对不同框之间执行基于 IoU 阈值的抑制。
`classes`	`list[int]`	`None`	将预测结果过滤为指定的一组类别 ID。仅返回属于指定类别的检测结果。对于在多类检测任务中专注于相关对象非常有用。
`retina_masks`	`bool`	`False`	返回高分辨率分割掩码。如果启用，返回的掩码 (`masks.data`) 将与原始图像大小匹配。如果禁用，它们将具有推理过程中使用的图像大小。
`embed`	`list[int]`	`None`	指定从中提取特征向量或嵌入的层。这对聚类或相似度搜索等下游任务非常有用。
`project`	`str`	`None`	如果启用了 `save`，预测结果保存的项目目录名称。
`name`	`str`	`None`	预测运行的名称。用于在项目文件夹内创建子目录，如果启用了 `save`，预测结果将存储在其中。
`stream`	`bool`	`False`	通过返回 Results 对象的生成器而不是一次性将所有帧加载到内存中，为长视频或大量图像启用内存高效处理。
`verbose`	`bool`	`True`	控制是否在终端显示详细的推理日志，提供有关预测过程的实时反馈。
`compile`	`bool` 或 `str`	`False`	启用 PyTorch 2.x `torch.compile` 图编译，使用 `backend='inductor'`。接受 `True` → `"default"`，`False` → 禁用，或字符串模式如 `"default"`、`"reduce-overhead"`、`"max-autotune-no-cudagraphs"`。如果不支持，将回退到 eager 模式并显示警告。
`end2end`	`bool`	`None`	覆盖支持无 NMS 推理的 YOLO 模型（YOLO26、YOLOv10）中的端到端模式。将其设置为 `False` 可以让你使用传统的 NMS 流水线运行预测，并允许你利用 `iou` 参数。详见端到端检测指南。

可视化参数：

参数	类型	默认值	描述
`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`	微软 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 Part 14
`.mkv`	`yolo predict source=video.mkv`	Matroska
`.mov`	`yolo predict source=video.mov`	QuickTime 文件格式
`.mp4`	`yolo predict source=video.mp4`	MPEG-4 Part 14 - 维基百科
`.mpeg`	`yolo predict source=video.mpeg`	MPEG-1 Part 2
`.mpg`	`yolo predict source=video.mpg`	MPEG-1 Part 2
`.ts`	`yolo predict source=video.ts`	MPEG 传输流
`.wmv`	`yolo predict source=video.wmv`	Windows 媒体视频
`.webm`	`yolo predict source=video.webm`	WebM 项目

处理结果

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

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`	原始图像的形状，格式为 (高, 宽)。
`boxes`	`Boxes, optional`	一个包含检测边界框的 Boxes 对象。
`masks`	`Masks, optional`	一个包含检测掩码的 Masks 对象。
`probs`	`Probs, optional`	一个包含分类任务中每个类别概率的 Probs 对象。
`keypoints`	`Keypoints, optional`	一个包含每个对象检测到的关键点的 Keypoints 对象。
`obb`	`OBB, optional`	一个包含旋转边界框的 OBB 对象。
`speed`	`dict`	一个包含预处理、推理和后处理速度的字典，单位为毫秒/图像。
`names`	`dict`	一个将类别索引映射到类别名称的字典。
`path`	`str`	图像文件的路径。
`save_dir`	`str, optional`	用于保存结果的目录。

Results 对象具有以下方法：

方法	返回类型	描述
`update()`	`None`	使用新的检测数据（boxes、masks、probs、obb、keypoints）更新 Results 对象。
`cpu()`	`Results`	返回一个将所有张量移至 CPU 内存的 Results 对象副本。
`numpy()`	`Results`	返回一个将所有张量转换为 NumPy 数组的 Results 对象副本。
`cuda()`	`Results`	返回一个将所有张量移至 GPU 内存的 Results 对象副本。
`to()`	`Results`	返回一个将张量移至指定设备和数据类型的 Results 对象副本。
`new()`	`Results`	创建一个具有相同图像、路径、名称和速度属性的新 Results 对象。
`plot()`	`np.ndarray`	在输入 RGB 图像上绘制检测结果并返回带注释的图像。
`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

Boxes 对象可用于索引、操作边界框并将边界框转换为不同格式。

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

Masks 对象可用于索引、操作掩码并将掩码转换为分割。

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 类方法和属性的表格，包括名称、类型和描述：

名称	类型	描述
`cpu()`	方法	返回 CPU 内存上的掩码张量。
`numpy()`	方法	返回作为 NumPy 数组的掩码张量。
`cuda()`	方法	返回 GPU 内存上的掩码张量。
`to()`	方法	返回具有指定设备和数据类型的掩码张量。
`xyn`	属性 (`torch.Tensor`)	一组以张量表示的归一化分割。
`xy`	属性 (`torch.Tensor`)	一组以像素坐标表示并以张量呈现的分割。

有关更多详细信息，请参阅 Masks 类文档。

Keypoints

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

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()`	方法	返回具有指定设备和数据类型的关键点张量。
`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()`	方法	将 probs 张量作为 NumPy 数组返回副本。
`cuda()`	方法	返回 GPU 内存中 probs 张量的副本。
`to()`	方法	返回具有指定设备和数据类型的 probs 张量副本。
`top1`	属性 (`int`)	Top 1 类别索引。
`top5`	属性 (`list[int]`)	Top 5 类别索引。
`top1conf`	属性 (`torch.Tensor`)	Top 1 类别的置信度。
`top5conf`	属性 (`torch.Tensor`)	Top 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 类文档。

绘制结果

The plot() method in Results objects facilitates visualization of predictions by overlaying detected objects (such as bounding boxes, masks, keypoints, and probabilities) onto the original image. This method returns the annotated image as a NumPy array, allowing for easy display or saving.

绘图

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`	用于绘图的替代图像。如果为 `None`，则使用原始图像。	`None`
`im_gpu`	`torch.Tensor`	用于更快掩码绘制的 GPU 加速图像。形状：(1, 3, 640, 640)。	`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]`	用于边界框和图像分类标签的 RGB 文本颜色。	`(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' 可退出循环。

常见问题 (FAQ)

什么是 Ultralytics YOLO 及其用于实时推理的预测模式？

Ultralytics YOLO 是用于实时目标检测、分割和分类的最先进模型。它的 预测模式 允许用户对图像、视频和实时流等各种数据源执行高速推理。它专为高性能和多功能性而设计，还提供了批处理和流处理模式。有关其功能的更多详细信息，请查看 Ultralytics YOLO 预测模式。

我该如何使用 Ultralytics YOLO 在不同数据源上运行推理？

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

我该如何优化 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")）。有关这些方法的完整列表，请参考使用结果部分。

Contributors

GLglenn-jocher³⁵ RIRizwanMunawar¹¹ LALaughing-q⁴ RAraimbekovm³ MAMatthewNoyce³ Y-Y-T-G² AFAffanBinFaisal¹RORonald Eddy Jr¹PDpderrenger¹ BAbanu4prasad¹ JKjk4e¹ SEsergiuwaxmann¹ IVIvorZhu331¹ BUBurhan-Q¹ PLplashchynski¹ TEtensorturtle¹

Created 2023年11月12日Updated 17小时前

使用 Ultralytics YOLO 进行模型预测

介绍

实际应用

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

Predict 模式的核心功能

推理数据源

推理参数

固定尺寸 vs 最小矩形 (rect)

图像和视频格式

图像

视频

处理结果

Boxes

Masks

Keypoints

Probs

OBB

绘制结果

plot() 方法参数

线程安全推理

流式源 for 循环

常见问题 (FAQ)

什么是 Ultralytics YOLO 及其用于实时推理的预测模式？

我该如何使用 Ultralytics YOLO 在不同数据源上运行推理？

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

Ultralytics YOLO 支持哪些推理参数？

我该如何可视化并保存 YOLO 预测结果？

评论

固定尺寸 vs 最小矩形 (`rect`)

`plot()` 方法参数

流式源 `for` 循环