Ultralytics YOLO Python 接口全指南：从模型加载、训练验证到推理跟踪与导出的实战手册

Ultralytics YOLO Python 接口全指南：从模型加载、训练验证到推理跟踪与导出的实战手册

【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics

导读

本文是 Ultralytics YOLO（YOLO26 / YOLO11 / YOLOv8 等）在 Python 项目中的权威使用指南。你将掌握统一的YOLO类如何覆盖目标检测（detect）、实例分割（segment）、语义分割（semantic）、深度估计（depth）、图像分类（classify）、姿态估计（pose）与旋转框检测（obb）等多种任务，并学会用几行代码完成"新建/加载模型 → 训练 → 验证 → 推理 → 导出"的完整工作流。阅读完本文，你可以直接在自己的数据集上复现官方示例，也能进一步深入源码理解每个模式背后的实现机制。

快速上手：一次跑通完整工作流

Ultralytics YOLO 的 Python 接口高度统一：无论你做什么任务，都从from ultralytics import YOLO开始。下面这段代码演示了从零创建模型、加载预训练权重、训练、验证、推理以及导出 ONNX 的完整闭环（见 官方示例文档）：

from ultralytics import YOLO # Create a new YOLO model from scratch model = YOLO("yolo26n.yaml") # Load a pretrained YOLO model (recommended for training) model = YOLO("yolo26n.pt") # Train the model using the 'coco8.yaml' dataset for 3 epochs results = model.train(data="coco8.yaml", epochs=3) # Evaluate the model's performance on the validation set results = model.val() # Perform object detection on an image using the model results = model("https://ultralytics.com/images/bus.jpg") # Export the model to ONNX format success = model.export(format="onnx")

几点值得注意的设计（可由 engine/model.py 与 models/yolo/model.py 印证）：

• YOLO类默认模型为"yolo26n.pt"；文件名含-world或yoloe时构造器会自动切换到YOLOWorld/YOLOE子类。
• model(...)与model.predict(...)等价，二者最终都进入Model.predict方法，只是predict暴露了更完整的参数面。
• 调用model.train(data=..., epochs=...)训练结束后，model对象会被替换为best.pt（或last.pt）对应的权重，并更新内部overrides，因此训练后直接调用model.val()、model(...)都作用于最新权重。

模型加载的三种方式

从预训练权重加载（推荐）

from ultralytics import YOLO model = YOLO("yolo26n.pt") # pass any model type

传入*.pt时，模型加载完整权重，适合直接推理、迁移学习与断点续训。官方权重命名规则为"架构 + 规模 + 任务后缀"，例如yolo26n.pt（检测）、yolo26n-seg.pt（实例分割）、yolo26n-pose.pt（姿态）、yolo26n-cls.pt（分类），以及yolo11n.pt、yolov8n.pt等历史版本。任务类型会根据权重自动识别，无需手工指定。

从 YAML 架构文件从零构建

model = YOLO("yolo26n.yaml")

传入*.yaml时仅构建网络结构、不加载训练好的权重（此时模型权重是随机的），必须搭配data一起训练。YAML 架构文件位于 ultralytics/cfg/models 下的26/、11/、v8/等目录中，例如yolo26n.yaml对应ultralytics/cfg/models/26/yolo26n.yaml。

任务与训练器自动映射

从源码看，YOLO.task_map（models/yolo/model.py）把"模型 / 训练器 / 验证器 / 预测器"四个类绑定在一起：

因此YOLO("yolo26n-seg.pt")加载后，内部会自动选择分割任务的训练器与验证器，这正是"一个类覆盖所有任务"的实现基础。完整任务侧文档见 目标检测、实例分割、语义分割、深度估计、图像分类、姿态估计、旋转框检测。

Train：训练自定义数据集

Train 模式 用于在自定义数据集上训练 YOLO 模型。训练的本质是通过梯度优化最小化损失函数，使模型能够准确预测图像中目标的类别与位置。

官方文档给出了三种训练入口，全部继承并扩展如下：

从预训练权重继续训练（推荐）

from ultralytics import YOLO model = YOLO("yolo26n.pt") # pass any model type results = model.train(epochs=5)

从预训练权重开始通常收敛更快、精度更高，官方文档始终推荐该方式。

从零开始训练

from ultralytics import YOLO model = YOLO("yolo26n.yaml") results = model.train(data="coco8.yaml", epochs=5)

断点续训（Resume）

from ultralytics import YOLO model = YOLO("last.pt") results = model.train(resume=True)

实现要点：训练过程中会在实验目录保存last.pt（最近权重）与best.pt（验证指标最佳权重）。从源码（engine/model.py）看，resume=True会尝试把当前模型当作可续训检查点——只有当 checkpoint 中包含epoch与optimizer状态时才真正续训，否则会告警并重新开始新训练。此外data还支持传一个数据集列表（如["coco8.yaml", "african-wildlife.yaml"]），实现单基座模型跨数据集串行微调。

训练关键参数

训练参数全部可在 default.yaml 中查询默认值，以下是高频参数：

各任务还有专属损失项：分割的overlap_mask、mask_ratio；姿态的pose、kobj、rle；obb 的angle；深度任务的dlog、dgrad、dlam等，均已在配置文件中给出注释默认值，可按需微调。完整参数说明见 usage/cfg。

训练背后的源码机制

model.train(...)在 engine/model.py 中实现：它会合并模型自带 overrides、方法默认值与调用者传入的 kwargs（右侧参数优先级最高），随后通过self._smart_load("trainer")依据task_map实例化对应训练器并执行trainer.train()。BaseTrainer负责数据集构建、优化器配置、DDP 初始化、回调触发等通用逻辑（engine/trainer.py）。训练结束后还会把self.model替换为最优 checkpoint，并重置self.predictor，保证后续val()/推理使用同一权重对象。

Val：验证模型精度与泛化能力

Val 模式 用于在验证集上评估训练后模型的精度与泛化能力，也可用于超参数调优决策。

训练后在同一数据上验证

from ultralytics import YOLO # Load a YOLO model model = YOLO("yolo26n.yaml") # Train the model model.train(data="coco8.yaml", epochs=5) # Validate on training data model.val()

在另一份数据上验证

from ultralytics import YOLO model = YOLO("yolo26n.yaml") model.train(data="coco8.yaml", epochs=5) # Validate on separate data model.val(data="path/to/separate/data.yaml")

底层实现（engine/model.py）：val()设置rect=True（矩形批量验证）、mode="val"，同样按task_map加载验证器，validator(model=self.model)执行验证并把结果写入self.metrics。返回值类型随任务而定，例如目标检测返回DetMetrics，其中results.box.map即 mAP50-95 指标；也可传入data、split、conf、iou、batch、imgsz、device等参数改变验证配置。若数据集路径无效，底层check_det_dataset（data/utils.py）会提示自动下载/解压。

Predict：对图像与视频做预测

Predict 模式 使用训练好的 checkpoint 对新的图像或视频执行推理，预测目标的类别与位置。其核心特点是source 输入格式极其灵活，可接受图片/目录/路径/URL/视频/PIL/ndarray，其中0表示摄像头。

从各类数据源推理

import cv2 from PIL import Image from ultralytics import YOLO model = YOLO("model.pt") # accepts all formats - image/dir/Path/URL/video/PIL/ndarray. 0 for webcam results = model.predict(source="0") results = model.predict(source="folder", show=True) # Display preds. Accepts all YOLO predict arguments # from PIL im1 = Image.open("bus.jpg") results = model.predict(source=im1, save=True) # save plotted images # from ndarray im2 = cv2.imread("bus.jpg") results = model.predict(source=im2, save=True, save_txt=True) # save predictions as labels # from list of PIL/ndarray results = model.predict(source=[im1, im2])

补充说明：

• predict若不传source，源码（engine/model.py）会默认使用ASSETS目录并打印告警，因此示例中"model.pt"这种相对路径权重需要你自己准备好文件。
• 关键默认值：conf=0.25（置信度阈值）、batch=1、mode="predict"。其余常用参数见下表，默认值均可在 default.yaml 查询：

Results 对象的使用

默认情况下predict返回一个Results对象列表，覆盖一张图的所有预测；当图片很多（尤其是分割任务）时列表会占用大量内存。通过stream=True可让predict返回生成器，逐张产出结果，对内存更友好：

# results would be a list of Results object including all the predictions by default # but be careful as it could occupy a lot memory when there're many images, # especially the task is segmentation. # 1. return as a list results = model.predict(source="folder") # results would be a generator which is more friendly to memory by setting stream=True # 2. return as a generator results = model.predict(source=0, stream=True) for result in results: # Detection result.boxes.xyxy # box with xyxy format, (N, 4) result.boxes.xywh # box with xywh format, (N, 4) result.boxes.xyxyn # box with xyxy format but normalized, (N, 4) result.boxes.xywhn # box with xywh format but normalized, (N, 4) result.boxes.conf # confidence score, (N, 1) result.boxes.cls # cls, (N, 1) # Segmentation result.masks.data # masks, (N, H, W) result.masks.xy # x,y segments (pixels), List[segment] * N result.masks.xyn # x,y segments (normalized), List[segment] * N # Classification result.probs # cls prob, (num_class, ) # Each result is composed of torch.Tensor by default, # in which you can easily use following functionality: result = result.cuda() result = result.cpu() result = result.to("cpu") result = result.numpy()

这些属性都由 engine/results.py 中的Results类及其子组件（Boxes、Masks、Keypoints、Probs等）提供：

• 检测：boxes.xyxy/xywh及归一化版本xyxyn/xywhn，形状(N, 4)；boxes.conf、boxes.cls分别为置信度与类别。
• 分割：masks.data原始掩码张量(N, H, W)，masks.xy/masks.xyn给出像素或归一化坐标下的多边形分段。
• 分类：probs为各类别概率，另可通过top1、top5、top1conf快速取得 Top 结果。
• 姿态：result.keypoints.xy/xyn、keypoints.conf。
• 跟踪场景还可访问result.boxes.id获取目标 ID。
• 每个Results内含torch.Tensor，支持cuda()、cpu()、to(device)、numpy()自由切换张量位置与形式；此外还有result.plot()、result.show()、result.save()、result.save_txt()、result.save_crop()、result.summary()等便捷方法用于可视化与导出。

FAQ 中给出的可视化最小示例同样值得牢记：

from ultralytics import YOLO model = YOLO("yolo26n.pt") results = model("https://ultralytics.com/images/bus.jpg") for result in results: result.show()

输入视频或流时，若未指定source且任务为 obb，Model.predict会默认取 boats 示例图（engine/model.py）。内存敏感场景请优先stream=True。

Export：导出为部署格式

Export 模式 把 YOLO 模型转换为可在其他软件或硬件上运行的部署格式，对生产环境落地至关重要。

导出为 ONNX（动态尺寸）

from ultralytics import YOLO model = YOLO("yolo26n.pt") model.export(format="onnx", dynamic=True)

dynamic=True使导出模型支持动态 batch 与动态图像尺寸。

导出为 TensorRT Engine

from ultralytics import YOLO model = YOLO("yolo26n.pt") model.export(format="engine", device=0)

device=0指定在 CUDA 设备上完成 TensorRT 引擎构建，以获得 GPU 加速。

支持的导出格式（见 default.yaml 的注释）：torchscript | onnx | openvino | engine | coreml | saved_model | pb | edgetpu | paddle | mnn | ncnn | imx | rknn | executorch | axelera | deepx | qnn | litert | hailo | ascend。从 engine/exporter.py 的export_formats()与各export_*方法可以看出，每种格式都有独立导出实现（如 ONNX 走export_onnx、OpenVINO 走export_openvino、LiteRT 走export_litert等）。

Model.export的实现（engine/model.py）会先校验当前模型必须是 PyTorch 模型，然后把imgsz、batch=1、device=None等合并进参数，调用Exporter(...)(model=self.model)。导出相关补充参数：

Track：实时目标跟踪

Track 模式 使用 YOLO 模型对实时视频流进行目标跟踪，适合安防监控、自动驾驶视觉等场景。

from ultralytics import YOLO # Load a model model = YOLO("yolo26n.pt") # load an official detection model model = YOLO("yolo26n-seg.pt") # load an official segmentation model model = YOLO("path/to/best.pt") # load a custom model # Track with the model results = model.track(source="https://youtu.be/LNwODJXcvt4", show=True) results = model.track(source="https://youtu.be/LNwODJXcvt4", show=True, tracker="bytetrack.yaml")

实现细节（engine/model.py）：

• model.track()调用register_tracker(self, persist)注册跟踪回调，并自动把conf降为0.1、batch固定为 1（跟踪器需要低置信度检测作为输入，视频逐帧处理需要 batch=1）。
• 跟踪结果可通过result.boxes.id读取跨帧一致的跟踪 ID。
• persist=True可使跟踪器在多次track()调用之间保持状态。

内置跟踪器配置位于 ultralytics/cfg/trackers：botsort.yaml、bytetrack.yaml、ocsort.yaml、deepocsort.yaml、fasttrack.yaml、tracktrack.yaml（全局默认tracker为tracktrack.yaml）。可通过tracker="bytetrack.yaml"等参数切换，不同跟踪器在遮挡鲁棒性与速度上各有取舍。跟踪相关教程还可见 object_tracking.ipynb 示例。

Benchmark：跨导出格式性能基准

Benchmark 模式 用于剖析 YOLO 在各种导出格式上的速度与精度，帮助你在速度与精度之间选择最优部署格式。

from ultralytics.utils.benchmarks import benchmark # Benchmark benchmark(model="yolo26n.pt", data="coco8.yaml", imgsz=640, device=0)

Benchmark 会针对 ONNX、OpenVINO、TensorRT 等各类导出格式给出：

• 导出产物文件大小；
• 精度指标：检测/分割为mAP50-95，分类为accuracy_top1；
• 单图推理耗时（毫秒）。

除了函数式调用，也可直接在模型上调用model.benchmark(data="coco8.yaml", imgsz=640, device=0, format="onnx", quantize=16)——该方法（engine/model.py）会把mode="benchmark"合并进配置，限制只测指定format，并通过quantize指定 FP16/INT8 精度，返回polars.DataFrame形式的结果表。Benchmark 的核心实现位于 utils/benchmarks.py。

更进一步：直接使用 Trainer / Validator / Predictor 类

YOLO类只是底层 Trainer 类的高层封装：每个 YOLO 任务都有自己的 Trainer，它们都继承自BaseTrainer。这种架构带来更大灵活性，方便自定义任务或做研究型扩展（相关实践可参考 model-training-tips）。

from ultralytics.models.yolo.detect import DetectionPredictor, DetectionTrainer, DetectionValidator # trainer trainer = DetectionTrainer(overrides={}) trainer.train() trained_model = trainer.best # Validator val = DetectionValidator(args=...) val(model=trained_model) # predictor pred = DetectionPredictor(overrides={}) pred(source=SOURCE, model=trained_model) # resume from last weight overrides["resume"] = trainer.last trainer = DetectionTrainer(overrides=overrides)

要点解读：

• DetectionTrainer、DetectionValidator、DetectionPredictor分别对应目标检测的训练、验证与推理（定义在 ultralytics/models/yolo/detect 子包中，其中__init__.py统一导出三者）。其他任务（分割、分类、姿态、obb、depth、semantic）也遵循完全相同的 "Trainer/Validator/Predictor" 三段式命名，分别位于 ultralytics/models/yolo 下对应的segment/、classify/、pose/、obb/、depth/、semantic/目录。
• 训练后trainer.best指向最佳权重文件，trainer.last指向最近一次保存的权重，二者都可用作resume。
• 这种模块化设计让开发者可以方便地自定义 Trainer 以支持全新任务或复现研究思路。YOLO各方法（train/val/predict/track/export）都接受自定义 Trainer/Validator/Predictor 实例作为可选参数。更深入的引擎定制、回调机制参考 usage/engine、usage/callbacks 与 自定义训练器教程。

常见问题（FAQ）速览

如何在 Python 项目中集成 YOLO 做目标检测？

加载预训练模型（或从零训练）后直接对图像调用即可：

from ultralytics import YOLO model = YOLO("yolo26n.pt") results = model("https://ultralytics.com/images/bus.jpg") for result in results: result.show()

更多示例见 Predict 模式。

YOLO 提供哪些工作模式？

Ultralytics YOLO 为不同 ML 工作流提供了成套模式：

• Train：使用自定义数据集训练模型；
• Val：在验证集上评估模型表现；
• Predict：对图像或视频流做预测；
• Export：导出 ONNX、TensorRT 等多种格式；
• Track：视频流实时目标跟踪；
• Benchmark：跨配置评估模型性能。

每种模式对应模型开发与部署链路的不同阶段（参见 model-deployment-options）。

如何用我的数据集训练自定义 YOLO 模型？

指定数据集 YAML 与其他超参数即可：

from ultralytics import YOLO model = YOLO("yolo26n.yaml") model.train(data="path/to/your/dataset.yaml", epochs=10)

数据集 YAML 需按 Ultralytics 格式组织（参考 ultralytics/cfg/datasets/coco8.yaml 的结构），训练细节见 Train 模式。

如何导出模型用于部署？

使用export函数即可，例如导出 ONNX：

from ultralytics import YOLO model = YOLO("yolo26n.pt") model.export(format="onnx")

导出选项见 Export 模式 文档。

能在不同数据集上验证模型吗？

可以。训练结束后用val()并传入另一份数据集的 YAML 路径：

from ultralytics import YOLO model = YOLO("yolo26n.yaml") model.train(data="coco8.yaml", epochs=5) model.val(data="path/to/separate/data.yaml")

小结

Ultralytics YOLO 的 Python 接口遵循"一个YOLO类 + 六大模式（Train/Val/Predict/Export/Track/Benchmark）+ 任务自动映射"的设计哲学：task_map决定底层使用哪套 Trainer/Validator/Predictor，各模式方法则通过统一配置合并规则接收**kwargs。你可以先用几行代码快速验证效果（小型数据集建议从 coco8.yaml 起步），再平滑过渡到完整 COCO 等大型数据集；部署阶段则可通过export()+benchmark()在各类导出格式间挑选精度与速度的平衡点。若需把该接口扩展到自定义任务，沿 usage/engine 提供的模块化架构即可实现。

【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics