示例代码

Ultralytics YOLO 模型在进行推理时返回一个 Python Results 对象列表，或者当传入 stream=True 时，返回一个内存高效的 Python Results 对象生成器：

from ultralytics import YOLO
​
# 加载模型
model = YOLO('yolov8n.pt')  # 预训练的 YOLOv8n 模型
​
# 在图片列表上运行批量推理
results = model(['im1.jpg', 'im2.jpg'])  # 返回 Results 对象列表
​
# 处理结果列表
for result in results:
    boxes = result.boxes  # 边界框输出的 Boxes 对象
    masks = result.masks  # 分割掩码输出的 Masks 对象
    keypoints = result.keypoints  # 姿态输出的 Keypoints 对象
    probs = result.probs  # 分类输出的 Probs 对象

推理来源

YOLOv8 可以处理推理输入的不同类型，如下表所示。来源包括静态图像、视频流和各种数据格式。表格还表示了每种来源是否可以在流式模式下使用，使用参数 stream=True ✅。流式模式对于处理视频或实时流非常有利，因为它创建了结果的生成器，而不是将所有帧加载到内存。

使用 stream=True 处理长视频或大型数据集来高效地管理内存。当 stream=False 时，所有帧或数据点的结果都将存储在内存中，这可能很快导致内存不足错误。相对地，stream=True 使用生成器，只保留当前帧或数据点的结果在内存中，显著减少了内存消耗，防止内存不足问题。

推理参数

下面是每个参数的解释：

• source：输入源的目录，可以是图像或视频文件。

• conf：目标检测的对象置信度阈值。只有置信度高于此阈值的对象才会被检测出来。默认值为0.25。

• iou：非极大值抑制（NMS）的交并比（IoU）阈值。用于在重叠较大的候选框中选择最佳的检测结果。默认值为0.7。

• half：是否使用半精度（FP16）进行推理。半精度可以减少计算量，但可能会牺牲一些精度。默认值为False。

• device：模型运行的设备，可以是cuda设备（cuda device=0/1/2/3）或CPU（device=cpu）。

• show：是否显示检测结果。如果设置为True，则会在屏幕上显示检测到的对象。默认值为False。

• save：是否保存带有检测结果的图像。如果设置为True，则会将检测结果保存为图像文件。默认值为False。

• save_txt：是否将检测结果保存为文本文件（.txt）。默认值为False。

• save_conf：是否将检测结果与置信度分数一起保存。默认值为False。

• save_crop：是否保存裁剪后的带有检测结果的图像。默认值为False。

• hide_labels：是否隐藏标签。如果设置为True，则在显示检测结果时不显示对象标签。默认值为False。

• hide_conf：是否隐藏置信度分数。如果设置为True，则在显示检测结果时不显示置信度分数。默认值为False。

• max_det：每张图像的最大检测数。如果检测到的对象数超过此值，将保留置信度高低来保留。默认值为300。

• vid_stride：视频帧率步长。默认值为False，表示使用默认的帧率。

• line_width：边界框的线宽。如果设置为None，则根据图像大小进行自动缩放。默认值为None。

• visualize：是否可视化模型特征。默认值为False。

• augment：是否对预测源应用图像增强。默认值为False。

• agnostic_nms：是否使用类别无关的NMS。默认值为False。

• retina_masks：是否使用高分辨率的分割掩膜。默认值为False。

• classes：按类别过滤结果。可以指定单个类别（例如class=0）或多个类别（例如class=[0,2,3]）。默认值为None，表示不进行类别过滤。

• boxes：在分割预测中显示边界框。默认值为True。

使用Results对象

Results对象包含以下组件：

Results.boxes：用于操作边界框的属性和方法的对象

Results.masks：用于索引掩膜或获取分段坐标的对象

Results.probs：包含类别概率或逻辑值的张量（tensor）

Results.orig_img：加载在内存中的原始图像

Results.path：包含输入图像的路径

result对象默认是torch.Tensor对象，也可以转为其他对象

results = results.cuda()
results = results.cpu()
results = results.to('cpu')
results = results.numpy()

Boxes

Boxes对象可用于索引、操作边界框，并将其转换为不同的格式。Box格式转换结果是缓存的，这意味着每个对象只计算一次，并且这些值将在将来的调用中重复使用。

results = model(img)
boxes = results[0].boxes
box = boxes[0]  # returns one box
box.xyxy

Boxes 的属性有

boxes.xyxy  #  xyxy 形式的目标框, (N, 4)
boxes.xywh  # xywh 形式的目标框, (N, 4)
boxes.xyxyn  # xyxy 形式的目标框且归一化, (N, 4)
boxes.xywhn  #  xywh 形式的目标框且归一化, (N, 4)
boxes.conf  # 置信度的分数, (N, 1)
boxes.cls  # 类别, (N, 1)
boxes.data  # 原始目标框参数坐标 (x, y, w, h)、置信度以及类别, (N, 6) or boxes.boxes

Masks

Masks可以被索引、操作修改、将Masks转换为分割结果。也可以缓存段转换操作。

results = model(inputs)
masks = results[0].masks  # Masks object
masks.xy  # x, y segments (pixels), List[segment] * N
masks.xyn  # x, y segments (normalized), List[segment] * N
masks.data  # raw masks tensor, (N, H, W) or masks.masks 

Probs 置信度

包含了所有类别的置信度

results = model(inputs)
results[0].probs  # cls prob, (num_class, )

更多文档可以参考 https://docs.ultralytics.com/reference/yolo/engine/results/

绘制结果

YOLOV8提供了plot函数绘制结果，可以绘制边框，分割结果,分类结果类别等等。不在需要像YOLOV5那样直接写后处理nms等，很方便。

from PIL import Image
from ultralytics import YOLO
​
# 加载预训练的YOLOv8n模型
model = YOLO('yolov8n.pt')
​
# 在'bus.jpg'上运行推理
results = model('bus.jpg')  # 结果列表
​
# 展示结果
for r in results:
    im_array = r.plot()  # 绘制包含预测结果的BGR numpy数组
    im = Image.fromarray(im_array[..., ::-1])  # RGB PIL图像
    im.show()  # 显示图像
    im.save('results.jpg')  # 保存图像

plot()方法支持以下参数：

线程安全推理

在多线程中并行运行多个YOLO模型时，确保推理过程的线程安全性至关重要。线程安全的推理保证了每个线程的预测结果是隔离的，不会相互干扰，避免竞态条件，确保输出的一致性和可靠性。

在多线程应用中使用YOLO模型时，重要的是为每个线程实例化单独的模型对象，或使用线程本地存储来防止冲突：

!!! Example "线程安全推理"

#在每个线程内实例化单个模型以实现线程安全的推理：
from ultralytics import YOLO
from threading import Thread
​
def thread_safe_predict(image_path):
    # 在线程内实例化新模型
    local_model = YOLO("yolov8n.pt")
    results = local_model.predict(image_path)
    # 处理结果
​
# 启动拥有各自模型实例的线程
Thread(target=thread_safe_predict, args=("image1.jpg",)).start()
Thread(target=thread_safe_predict, args=("image2.jpg",)).start()

有关YOLO模型线程安全推理的深入讨论和逐步指导，请参阅我们的YOLO线程安全推理指南。该指南将为您提供避免常见陷阱并确保多线程推理顺利进行所需的所有必要信息。

流媒体源for循环

以下是使用OpenCV（cv2）和YOLOv8在视频帧上运行推理的Python脚本。此脚本假设您已经安装了必要的包（opencv-python和ultralytics）。

import cv2
from ultralytics import YOLO

# 加载YOLOv8模型
model = YOLO('yolov8n.pt')

# 打开视频文件
video_path = "path/to/your/video/file.mp4"
cap = cv2.VideoCapture(video_path)

# 遍历视频帧
while cap.isOpened():
    # 从视频中读取一帧
    success, frame = cap.read()

    if success:
        # 在该帧上运行YOLOv8推理
        results = model(frame)

        # 在帧上可视化结果
        annotated_frame = results[0].plot()

        # 显示带注释的帧
        cv2.imshow("YOLOv8推理", annotated_frame)

        # 如果按下'q'则中断循环
        if cv2.waitKey(1) & 0xFF == ord("q"):
            break
    else:
        # 如果视频结束则中断循环
        break

# 释放视频捕获对象并关闭显示窗口
cap.release()
cv2.destroyAllWindows()

此脚本将对视频的每一帧进行预测，可视化结果，并在窗口中显示。按下'q'键可以退出循环。