本文是 Ultralytics YOLO Python API 的核心入门指南，面向刚完成 环境搭建与安装指南 的开发者。我们将从最基础的"加载模型→运行推理→处理结果"三条主线出发，逐步带你掌握 Python API 的核心使用方式。本文不会深入训练、导出等高级话题——它们在后续页面中有专门讲解。

Sources: model.py, results.py

第一步：理解 API 的整体调用流程

在动手写代码之前，先用一张流程图建立全局认知。Ultralytics YOLO 的 Python API 围绕一个核心类 YOLO 展开，所有操作——推理、验证、训练、导出——都通过这个统一入口完成。

核心调用模式只有三行代码：导入 → 实例化 → 推理。model.predict() 和 model() 是等价的——__call__ 方法直接代理了 predict()，因此你可以选择更简洁的调用风格。

Sources: model.py, model.py

第二步：创建模型实例

2.1 基础用法

from ultralytics import YOLO

# 从预训练权重文件加载（首次使用会自动从网络下载）
model = YOLO("yolo26n.pt")

# 从 YAML 配置文件创建新模型（随机初始化权重，用于训练）
model = YOLO("yolo26n.yaml")

YOLO 类的构造函数接受三个参数：

参数	类型	默认值	说明
model	str | Path	"yolo26n.pt"	模型文件路径或名称
task	str | None	None	任务类型，自动推断
verbose	bool	False	是否在加载时显示详细信息

Sources: model.py

2.2 模型加载的内部路由

当你传入一个模型标识时，YOLO.__init__ 会根据文件名自动判断模型类型并进行路由分发。这个过程对开发者完全透明，但理解它有助于排查问题：

关键细节：.pt 文件会通过 load_checkpoint() 加载，并自动从检查点中恢复任务类型（detect/segment/classify/pose/obb）；.yaml 文件则会构建一个全新的模型结构，权重随机初始化。如果你传入的是一个已导出的格式（如 .onnx），框架会走 AutoBackend 路径，这类模型只支持 predict 和 val 操作。

Sources: model.py, model.py

2.3 任务类型自动推断

你通常不需要手动指定 task 参数。框架会从模型本身推断出任务类型：

模型文件示例	自动推断的任务	说明
yolo26n.pt	detect	目标检测
yolo26n-seg.pt	segment	实例分割
yolo26n-cls.pt	classify	图像分类
yolo26n-pose.pt	pose	姿态估计
yolo26n-obb.pt	obb	旋转目标检测

如果需要显式指定（例如使用自定义模型时），可以传入 task 参数：

model = YOLO("my_custom_model.pt", task="detect")

Sources: model.py, init.py

2.4 可用的模型类

Ultralytics 提供了 7 种模型类，它们共享统一的 Model 基类接口：

from ultralytics import YOLO, YOLOWorld, YOLOE, NAS, SAM, FastSAM, RTDETR

模型类	用途	典型用法
YOLO	通用目标检测/分割/分类/姿态/OBB	最常用的入口，自动路由到子类
YOLOWorld	开放词汇检测（用文本描述检测任意物体）	model.set_classes(["person", "car"])
YOLOE	增强型检测与分割	支持视觉和文本位置嵌入
RTDETR	基于 Transformer 的实时检测器	从头训练或推理
SAM / FastSAM	通用图像分割	支持提示点/框/文本分割
NAS	神经架构搜索	自动搜索最优网络结构

对于绝大多数场景，直接使用 YOLO 类即可——它会在内部自动判断是否需要切换到 YOLOWorld、YOLOE 或 RTDETR。

Sources: init.py, models/init.py

第三步：运行推理（predict）

3.1 最简单的推理

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# 方式一：标准调用
results = model.predict("image.jpg")

# 方式二：简写（等价于 predict）
results = model("image.jpg")

# 方式三：不传 source，使用默认示例图片
results = model.predict()

predict() 方法的核心签名如下：

参数	类型	默认值	说明
source	多种类型	None	输入源（详见下节）
stream	bool	False	是否以流式模式返回结果
predictor	BasePredictor	None	自定义预测器（高级用法）
**kwargs	-	-	覆盖配置参数

当 source 为 None 时，框架会使用内置的示例图片并发出警告。

Sources: model.py

3.2 支持的输入源类型

source 参数极其灵活，支持以下所有类型：

输入类型	示例	说明
文件路径	"image.jpg"	单张图片
目录路径	"path/to/images/"	目录下所有图片
URL	"https://ultralytics.com/images/bus.jpg"	自动下载
视频文件	"video.mp4"	逐帧推理
摄像头	0	整数表示设备索引
RTSP 流	"rtsp://server/stream"	实时视频流
PIL Image	Image.open("img.jpg")	PIL 图像对象
NumPy 数组	np.ndarray (HWC, BGR)	OpenCV 格式数组
PyTorch 张量	torch.Tensor (BCHW, RGB, 0-1)	归一化张量
文件列表	["img1.jpg", "img2.jpg"]	批量推理
glob 模式	"path/*.jpg"	通配符匹配
文本文件	"sources.txt"	每行一个路径

实际代码示例——混合输入源批量推理：

import cv2
from PIL import Image
from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# 从文件
results = model("image.jpg")

# 从 PIL 图像
pil_img = Image.open("image.jpg")
results = model(pil_img)

# 从 NumPy 数组
cv_img = cv2.imread("image.jpg")
results = model(cv_img)

# 从 PyTorch 张量
import torch
tensor = torch.rand(1, 3, 640, 640)  # BCHW, RGB, 0-1
results = model(tensor)

# 混合多种类型批量推理
batch = ["image.jpg", pil_img, cv_img]
results = model(batch)

Sources: model.py, predictor.py

3.3 推理配置参数

predict() 支持通过 **kwargs 传入大量配置参数，这些参数会覆盖默认配置。以下是最常用的参数：

参数	类型	默认值	说明
conf	float	0.25	置信度阈值，低于此值的检测被过滤
iou	float	0.7	NMS 的 IoU 阈值
imgsz	int | list	640	推理图像尺寸
half	bool	False	是否使用 FP16 半精度推理
device	str | int	自动选择	推理设备，如 "cpu", 0, "[0,1]"
max_det	int	300	单张图片最大检测数量
classes	list[int]	None	只保留指定类别的检测
augment	bool	False	测试时增强（TTA）
agnostic_nms	bool	False	类别无关的 NMS
save	bool	False	是否保存标注后的图片
show	bool	False	是否显示推理结果窗口
save_txt	bool	False	是否保存结果为 .txt 文件
save_crop	bool	False	是否保存裁剪的检测区域
verbose	bool	True	是否打印详细日志

使用示例：

# 只检测 person (class 0) 和 car (class 2)，置信度阈值 0.5
results = model.predict("image.jpg", conf=0.5, classes=[0, 2])

# 使用 GPU 推理，FP16 加速，更大输入尺寸
results = model.predict("image.jpg", device=0, half=True, imgsz=1280)

# 保存标注图片和裁剪区域
results = model.predict("image.jpg", save=True, save_crop=True)

Sources: default.yaml, model.py

3.4 流式推理（stream 模式）

处理视频或大量图片时，默认模式会将所有结果存储在内存中，可能导致内存溢出。使用 stream=True 可以返回一个生成器，逐帧消费结果：

# 默认模式：所有结果存入列表（可能 OOM）
results = model("video.mp4")  # list[Results]

# 流式模式：逐帧生成结果（推荐用于视频/大量图片）
results = model("video.mp4", stream=True)  # generator of Results
for r in results:
    boxes = r.boxes
    # 逐帧处理...

模式	返回类型	内存占用	适用场景
stream=False（默认）	list[Results]	全部加载	少量图片
stream=True	Generator[Results]	帧级占用	视频、流媒体、大批量

Sources: predictor.py, model.py

第四步：处理推理结果（Results 对象）

predict() 返回一个 Results 对象列表，每个元素对应一张输入图像。Results 是一个功能丰富的数据容器，包含了所有推理输出。

4.1 Results 对象结构

不同任务类型会填充不同的属性。例如，检测模型只会填充 boxes，分割模型会同时填充 boxes 和 masks，分类模型只填充 probs。未使用的属性为 None。

Sources: results.py

4.2 检测结果（Boxes）

这是最常用的结果类型。Boxes 提供了多种坐标格式，满足不同场景的需求：

from ultralytics import YOLO

model = YOLO("yolo26n.pt")
results = model("bus.jpg")

for result in results:
    boxes = result.boxes
    
    # 获取检测数量
    num_detections = len(boxes)
    
    # 坐标格式（任选其一）
    xyxy = boxes.xyxy      # [x1, y1, x2, y2] 像素坐标
    xywh = boxes.xywh      # [cx, cy, w, h] 像素坐标
    xyxyn = boxes.xyxyn    # [x1, y1, x2, y2] 归一化坐标 (0-1)
    xywhn = boxes.xywhn    # [cx, cy, w, h] 归一化坐标 (0-1)
    
    # 置信度和类别
    confidences = boxes.conf   # 每个检测的置信度 (N,)
    class_ids = boxes.cls      # 每个检测的类别 ID (N,)
    
    # 遍历每个检测框
    for box in boxes:
        x1, y1, x2, y2 = box.xyxy[0].tolist()
        conf = box.conf.item()
        cls_id = int(box.cls.item())
        cls_name = result.names[cls_id]
        print(f"检测到 {cls_name}，置信度 {conf:.2f}，位置 [{x1:.0f}, {y1:.0f}, {x2:.0f}, {y2:.0f}]")

坐标格式速查表：

属性	格式	单位	典型用途
xyxy	[x1, y1, x2, y2]	像素	绘图、裁剪
xywh	[cx, cy, w, h]	像素	中心点计算
xyxyn	[x1, y1, x2, y2]	归一化 0-1	数据集标注
xywhn	[cx, cy, w, h]	归一化 0-1	YOLO 标签格式

Sources: results.py

4.3 分割结果（Masks）

分割模型在 boxes 之外还会输出 masks：

model = YOLO("yolo26n-seg.pt")
results = model("image.jpg")

for result in results:
    if result.masks is not None:
        masks = result.masks
        
        # 获取像素级分割多边形坐标
        for i, segment in enumerate(masks.xy):
            # segment 是一个 (N, 2) 的 NumPy 数组，包含多边形顶点
            print(f"第 {i} 个掩码有 {len(segment)} 个顶点")
        
        # 归一化坐标（相对于原始图像尺寸）
        normalized_segments = masks.xyn

Sources: results.py

4.4 分类结果（Probs）

分类模型的输出存储在 probs 属性中：

model = YOLO("yolo26n-cls.pt")
results = model("image.jpg")

for result in results:
    if result.probs is not None:
        probs = result.probs
        
        # Top-1 预测
        top1_id = probs.top1           # 类别索引
        top1_name = result.names[top1_id]  # 类别名称
        top1_conf = probs.top1conf.item()  # 置信度
        print(f"分类结果: {top1_name} ({top1_conf:.2f})")
        
        # Top-5 预测
        for idx, conf in zip(probs.top5, probs.top5conf.tolist()):
            print(f"  {result.names[idx]}: {conf:.4f}")

Sources: results.py

4.5 姿态估计结果（Keypoints）

model = YOLO("yolo26n-pose.pt")
results = model("person.jpg")

for result in results:
    if result.keypoints is not None:
        kpts = result.keypoints
        
        # 获取关键点坐标 (N, K, 2) —— N个人，K个关键点
        xy = kpts.xy           # 像素坐标
        xyn = kpts.xyn         # 归一化坐标
        
        # 关键点置信度（仅当模型输出可见性时可用）
        if kpts.has_visible:
            conf = kpts.conf   # (N, K) 每个关键点的可见性置信度

Sources: results.py

4.6 旋转框结果（OBB）

model = YOLO("yolo26n-obb.pt")
results = model("aerial.jpg")

for result in results:
    if result.obb is not None:
        obb = result.obb
        xywhr = obb.xywhr       # [cx, cy, w, h, rotation]
        corners = obb.xyxyxyxy  # 8个角点坐标
        conf = obb.conf         # 置信度
        cls = obb.cls           # 类别

Sources: results.py

4.7 可视化与导出结果

Results 提供了丰富的可视化和数据导出方法：

results = model("image.jpg")
result = results[0]

# 1. 在图像上绘制检测结果（返回 BGR NumPy 数组）
annotated = result.plot()
# 可选参数：conf=True, line_width=None, labels=True, boxes=True, masks=True

# 2. 弹窗显示（需要在有 GUI 的环境中运行）
result.show()

# 3. 保存标注后的图片到文件
result.save("output.jpg")

# 4. 获取人类可读的摘要字符串
print(result.verbose())
# 输出类似: "2 persons, 1 car, 3 traffic lights, "

# 5. 获取结构化摘要（字典列表）
summary = result.summary()
# [{"name": "person", "class": 0, "confidence": 0.92, "box": {...}}, ...]

# 6. 保存为 YOLO 格式的 .txt 文件
result.save_txt("detections.txt", save_conf=True)

# 7. 保存裁剪的检测区域
result.save_crop("crops_dir/")

# 8. 设备转移
result_cpu = result.cpu()      # 所有张量转移到 CPU
result_np = result.numpy()     # 所有张量转为 NumPy 数组
result_gpu = result.cuda()     # 所有张量转移到 GPU

Sources: results.py, results.py, results.py

第五步：完整实战示例

将以上知识组合成一个完整的推理脚本：

"""
Ultralytics YOLO Python API 完整推理示例
"""
from ultralytics import YOLO


def main():
    # ===== 1. 加载模型 =====
    model = YOLO("yolo26n.pt")  # 加载预训练检测模型
    
    # ===== 2. 运行推理 =====
    results = model.predict(
        source="image.jpg",  # 输入源
        conf=0.25,           # 置信度阈值
        imgsz=640,           # 推理尺寸
        save=True,           # 保存标注图片
    )
    
    # ===== 3. 处理结果 =====
    for result in results:
        # 打印摘要
        print(f"图片: {result.path}")
        print(f"检测到: {result.verbose()}")
        print(f"耗时: 预处理 {result.speed['preprocess']:.1f}ms, "
              f"推理 {result.speed['inference']:.1f}ms, "
              f"后处理 {result.speed['postprocess']:.1f}ms")
        
        # 遍历每个检测框
        for box in result.boxes:
            cls_id = int(box.cls)
            cls_name = result.names[cls_id]
            conf = box.conf.item()
            x1, y1, x2, y2 = box.xyxy[0].tolist()
            print(f"  [{cls_name}] 置信度={conf:.2f} "
                  f"位置=({x1:.0f},{y1:.0f},{x2:.0f},{y2:.0f})")
        
        # 保存可视化结果
        result.save("result_output.jpg")


if __name__ == "__main__":
    main()

Sources: model.py, results.py

常见问题速查

问题	原因与解决方案
模型文件找不到	首次使用时会自动下载；也可手动指定本地路径
推理结果为空	调低 conf 阈值（如 conf=0.1），确认输入图片有效
GPU 内存不足	减小 imgsz，启用 half=True 使用半精度
处理视频时内存溢出	使用 stream=True 模式
导出的 ONNX/TensorRT 模型无法训练	导出格式仅支持 predict 和 val，训练需要 .pt 格式
想检测特定类别	使用 classes=[0, 2] 参数过滤
想获取更多信息	查看 result.speed（耗时）、result.names（类别映射）、result.orig_shape（原始尺寸）

Sources: model.py, predictor.py