Ultralytics YOLO 视觉工具

Ultralytics YOLO 是一款先进的计算机视觉框架，支持多种任务，包括目标检测、实例分割、图像分类、姿态估计和定向边界框（OBB）检测。本技能提供关于如何高效使用 YOLO 的全面指导。

最新模型：YOLO26（2026 年 1 月发布）具备端到端无 NMS 推理能力，并针对边缘部署进行了优化。对于稳定的生产工作负载，推荐同时使用 YOLO26 和 YOLO11。

快速入门

1. 安装与环境检查

# 安装或更新 Ultralytics
pip install -U ultralytics

# 验证安装并检查运行环境
yolo checks

yolo checks 命令会验证 Python 版本、PyTorch、CUDA、GPU 可用性以及所有依赖项。如需详细的环境问题排查，请参阅《环境检查》文档，或使用提供的环境检查脚本：python scripts/check_environment.py。

2. 基础用法示例

Python 接口

from ultralytics import YOLO

# 加载模型（YOLO 会自动根据模型文件推断对应任务）
model = YOLO("yolo26n.pt")  # 或你自定义的模型路径

# 在多种输入源上执行预测
# 默认情况下，输出将保存至 workspace/yolo-vision 目录
results = model("image.jpg")                     # 图像文件 → 保存至 yolo-vision/outputs/images/
results = model("video.mp4", stream=True)        # 视频流式处理 → 保存至 yolo-vision/outputs/videos/
results = model("https://example.com/image.jpg") # 网络 URL → 保存至 yolo-vision/outputs/images/
results = model(0, show=True)                   # 调用默认摄像头并实时显示 → 保存至 yolo-vision/outputs/videos/

# 自定义输出目录（可选）
results = model("image.jpg", project="/custom/path")  # 保存至指定路径

CLI 接口

# 基本语法：yolo TASK MODE ARGS
# 默认情况下，输出将保存至 workspace/yolo-vision 目录
yolo predict model=yolo26n.pt source="image.jpg"  # → 保存至 yolo-vision/runs/detect/predict/

# 按任务区分的示例
yolo detect predict model=yolo26n.pt source="video.mp4"  # → 保存至 yolo-vision/runs/detect/predict/
yolo segment predict model=yolo26n-seg.pt source="image.jpg"  # → 保存至 yolo-vision/runs/segment/predict/
yolo pose predict model=yolo26n-pose.pt source="image.jpg"  # → 保存至 yolo-vision/runs/pose/predict/

# 自定义输出目录（可选）
yolo predict model=yolo26n.pt source="image.jpg" project="/custom/path"  # 保存至指定路径

3. 模型选择

为快速开始，请使用以下默认模型：

• 检测：yolo26n.pt（nano）、yolo26s.pt（small）、yolo26m.pt（medium）
• 分割：yolo26n-seg.pt、yolo26s-seg.pt、yolo26m-seg.pt
• 分类：yolo26n-cls.pt、yolo26s-cls.pt、yolo26m-cls.pt
• 姿态估计：yolo26n-pose.pt、yolo26s-pose.pt、yolo26m-pose.pt
• 定向检测：yolo26n-obb.pt、yolo26s-obb.pt、yolo26m-obb.pt

完整模型列表及选型建议请参阅：Model Names | Model Selection

核心工作流程

步骤 1：理解 YOLO 支持的任务类型

YOLO 支持五种主要的计算机视觉任务，请根据你的应用场景选择合适的任务：

• 检测：识别并定位目标，输出标准轴对齐边界框
• 分割：为目标生成像素级掩码
• 分类：对整张图像进行类别判定
• 姿态估计：检测关键点以支持姿态分析
• 定向检测：检测带旋转角度参数的目标（即 OBB）

详细对比请参阅：Task Types

步骤 2：选择合适模型

选择模型时需考虑以下因素：

• 速度 vs. 准确率：nano（最快）→ X（最准）
• 硬件约束：GPU 显存、CPU 性能等
• 应用需求：实时处理 vs. 批量处理

选型指南请参阅：Model Selection

步骤 3：配置参数

常用配置参数如下：

• conf：置信度阈值（默认值：0.25）
• iou：NMS 的 IoU 阈值（默认值：0.7）
• imgsz：输入图像尺寸（默认值：640）
• device：设备 ID（0 表示第一块 GPU，cpu 表示 CPU 模式）
• save：是否将结果保存至磁盘
• show：是否实时显示结果

完整配置示例请参阅：Configuration Samples

步骤 4：处理预测结果

YOLO 返回 Results 对象，其中包含以下字段：

• boxes：边界框坐标、置信度分数、类别标签
• masks：分割掩码（仅用于分割任务）
• keypoints：姿态关键点（仅用于姿态估计任务）
• probs：分类概率（仅用于分类任务）
• obb：定向边界框（仅用于 OBB 任务）

进阶主题

训练自定义模型

from ultralytics import YOLO

# 加载模型
model = YOLO("yolo26n.pt")

# 在自定义数据集上训练
results = model.train(data="dataset.yaml", epochs=100, imgsz=640)

训练指南请参阅：Training Basics | Dataset Preparation

安装方式

支持多种安装方式：

• pip：pip install -U ultralytics
• Conda：conda install -c conda-forge ultralytics
• Docker：提供预构建的 GPU/CPU 环境镜像
• 源码安装：适用于开发与深度定制场景

详细说明请参阅：Installation Guide

性能优化

• 流式模式：对视频或长序列使用 stream=True，以降低内存占用
• 批量处理：一次性处理多张图像以提升效率
• 硬件加速：配置 CUDA、TensorRT 或 OpenVINO 以实现最优性能

参考文档

实用脚本

为节省 token 使用量并提供开箱即用的工具，scripts/ 目录中提供了以下 Python 脚本：

使用脚本的优势：

• 节省 token：大段代码从文档中分离提取
• 开箱即用：无需从文档中复制粘贴代码
• 模块化设计：按需导入所需功能
• 易于维护：脚本可独立更新升级

常见问题排查

常见问题

Q：安装后执行 yolo 命令提示“未找到”？
A：尝试使用 python -m ultralytics yolo，或检查当前 Python 环境的 PATH 设置。

Q：如何指定特定 GPU 运行？
A：设置 device=0（使用第一块 GPU），或设为 device=cpu 强制使用 CPU。

Q：模型下载速度慢？
A：设置 ULTRALYTICS_HOME 环境变量，以控制模型缓存路径。

Q：如何只检测特定类别？
A：使用 classes 参数，例如：classes=[0, 2, 5]（传入类别索引列表）。

Q：处理长视频时内存不足？
A：启用 stream=True，以生成器方式逐帧处理视频。

Q：是否支持实时摄像头？
A：支持，使用 source=0（默认摄像头）并配合 show=True 即可实现实时画面显示。

获取帮助

• 运行 yolo checks 快速诊断环境问题
• 查阅官方文档：https://docs.ultralytics.com
• 查看参数配置参考：https://docs.ultralytics.com/usage/cfg/

输出目录规范

默认输出位置

当使用 YOLO 处理图像或视频且用户未显式指定输出目录时，所有生成文件将统一保存至工作区（workspace）下的 yolo-vision 文件夹中。

文件组织结构

yolo-vision 文件夹将按如下结构组织：

yolo-vision/
├── inputs/            # 原始输入文件（为便于参考而复制）
├── outputs/           # 包含检测结果的处理后文件
│   ├── images/        # 检测后的图像
│   ├── videos/        # 检测后的视频  
│   └── previews/      # 预览图
├── reports/           # 分析报告与统计信息
│   ├── json/          # JSON 格式报告
│   ├── markdown/      # Markdown 格式报告
│   └── csv/           # CSV 格式数据
├── models/            # 下载的 YOLO 模型
│   ├── yolo26/        # YOLO26 模型
│   ├── yolo11/        # YOLO11 模型
│   └── custom/        # 自定义训练模型
└── logs/              # 处理日志与调试信息

自动创建目录

该技能将自动完成以下操作：

1. 若 yolo-vision 文件夹不存在，则自动创建
2. 按需创建所有子目录
3. 按日期与任务类型自动归类文件
4. 生成带时间戳的文件名，便于追踪与管理

使用示例

# 不指定输出目录 —— 使用默认 yolo-vision 文件夹
results = model("image.jpg")  # 输出保存至 yolo-vision/outputs/images/

# 指定自定义输出目录
results = model("image.jpg", save_dir="/custom/path")  # 使用指定路径

优势

1. 一致性：所有 YOLO 输出集中存放于一个可预期的位置
2. 条理性：文件按类型自动分类
3. 可追溯性：原始输入文件被保留供后续参考
4. 可复现性：便于查找与比对历史分析结果
5. 工作区整洁：避免主工作目录杂乱

用户覆盖机制

用户仍可在需要时指定自定义输出目录：

• 在 Python 代码中通过 save_dir 参数传入
• 在 CLI 命令中使用 --project 标志
• 通过设置 ULTRALYTICS_PROJECT 环境变量

许可说明：Ultralytics YOLO 对开源用途采用 AGPL-3.0 许可协议，商业用途需购买企业许可证。许可详情请访问：https://ultralytics.com/license。