使用 Ultralytics YOLO 进行模型预测

Ultralytics YOLO ecosystem and integrations

简介

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

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

实际应用

制造业	体育	安全

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

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

以下是你应该考虑将 YOLO26 的预测模式用于各种推理需求的原因：

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

预测模式的主要功能

YOLO26 的预测模式设计健壮且多功能，具有以下特点：

多数据源兼容性： 无论你的数据是单张图像、图像集合、视频文件还是实时视频流，预测模式都能满足你的需求。
流式模式 (Streaming Mode)： 使用流式功能生成 Results 对象的内存高效生成器。通过在预测器的调用方法中设置 stream=True 来启用此功能。
批处理 (Batch Processing)： 在单个批次中处理多个图像或视频帧，进一步减少总推理时间。
易于集成： 得益于其灵活的 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() 接受多个可以在推理时传递以覆盖默认值的参数：

固定形状与最小矩形 (`rect`)

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

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

整数与元组 imgsz

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

训练与预测/导出

训练仅接受单个整数 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`	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 部分 - 维基百科
`.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 媒体视频
`.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`	以 (height, width) 格式呈现的原始图像形状。
`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 对象可用于索引、操作和归一化坐标。

关键点

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 内存中概率张量的副本。
`numpy()`	方法	返回作为 NumPy 数组的概率张量副本。
`cuda()`	方法	返回 GPU 内存中概率张量的副本。
`to()`	方法	返回具有指定设备和数据类型（dtype）的概率张量副本。
`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 图像对象返回。	`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 是一款用于实时目标检测、实例分割、语义分割和分类的前沿模型。其 预测模式 (predict mode) 允许用户在各种数据源（如图像、视频和实时流）上执行高速推理。该模式专为性能和多功能性而设计，还提供了批处理和流式模式。有关其功能的更多详细信息，请查看 Ultralytics YOLO 预测模式。

如何使用 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")）。关于这些方法的完整列表，请参考 working with results 部分。

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 25分钟前

使用 Ultralytics YOLO 进行模型预测

简介

实际应用

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

预测模式的主要功能

推理来源

推理参数

固定形状与最小矩形 (rect)

图像和视频格式

图像

视频

使用结果

Boxes

Masks

关键点

概率 (Probs)

OBB

绘制结果

plot() 方法参数

线程安全推理

流式源 for 循环

常见问题 (FAQ)

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

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

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

Ultralytics YOLO 支持哪些推理参数？

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

评论

固定形状与最小矩形 (`rect`)

`plot()` 方法参数

流式源 `for` 循环