YOLO26文档参考指南：官方仓库README使用说明-开发者社区

YOLO26文档参考指南：官方仓库README使用说明

最新 YOLO26 官方版训练与推理镜像，专为快速落地目标检测与姿态估计任务设计。它不是简单封装的运行环境，而是一套经过完整验证、开箱即用的工程化解决方案——从模型加载、数据准备、本地推理到全流程训练，所有环节都已预置适配，省去你反复踩坑、调试依赖、核对版本的繁琐过程。

本镜像基于YOLO26 官方代码库构建，预装了完整的深度学习开发环境，集成了训练、推理及评估所需的所有依赖，开箱即用。

1. 镜像环境说明

这套镜像不是“能跑就行”的临时环境，而是严格对齐YOLO26官方推荐配置的生产级基础。所有组件版本均经实测兼容，避免常见冲突（如CUDA与PyTorch版本错配、OpenCV编译异常等），让你把时间花在调模型上，而不是修环境上。

核心框架:pytorch == 1.10.0
CUDA版本:12.1
Python版本:3.9.5
主要依赖:torchvision==0.11.0,torchaudio==0.10.0,cudatoolkit=11.3,numpy,opencv-python,pandas,matplotlib,tqdm,seaborn等。

注意：镜像中默认激活的是torch25环境，但YOLO26实际运行需切换至yolo环境。这是新手最容易忽略的一步，切记执行conda activate yolo后再操作，否则会提示模块找不到或版本不匹配。

2. 快速上手

启动镜像后，你会看到一个干净的终端界面和Jupyter Lab入口。别急着写代码——先理清工作流：环境 → 代码位置 → 推理 → 训练 → 结果导出。下面每一步都对应真实操作场景，不是理论罗列。

2.1 激活环境与切换工作目录

镜像启动后，默认进入/root目录，但官方代码存放在系统盘（不可写区域）。直接修改会失败，必须先复制到可写路径。

第一步，激活专用环境：

conda activate yolo

第二步，将代码复制到工作区（数据盘）：

cp -r /root/ultralytics-8.4.2 /root/workspace/

第三步，进入工作目录：

cd /root/workspace/ultralytics-8.4.2

这三步是后续所有操作的前提。复制动作看似简单，实则解决了两个关键问题：一是避免系统盘写入权限限制，二是防止镜像重置时丢失你的修改。

2.2 模型推理：5分钟跑通第一张图

YOLO26支持图像、视频、摄像头多种输入源。我们以最典型的单图推理为例，带你走通完整链路。

新建或编辑detect.py文件，内容如下：

# -*- coding: utf-8 -*- from ultralytics import YOLO if __name__ == '__main__': # 加载YOLO26轻量级姿态模型 model = YOLO(model=r'yolo26n-pose.pt') # 对示例图进行推理，结果自动保存到 runs/detect/ model.predict(source=r'./ultralytics/assets/zidane.jpg', save=True, show=False)

参数含义直白解释：

model：填模型文件名或绝对路径，镜像已预置yolo26n-pose.pt和yolo26n.pt，直接用即可
source：可以是图片路径（如zidane.jpg）、视频路径（如test.mp4）、摄像头编号（如0表示默认摄像头）
save=True：必须加！否则结果只在内存里一闪而过，不会生成带框图
show=False：设为False可避免在无GUI环境下报错；若需实时预览，改为True即可

运行命令：

python detect.py

几秒后，终端会输出类似Results saved to runs/detect/predict/的提示。打开该路径，你就能看到带关键点和边界框的zidane.jpg—— 这就是YOLO26的原始输出效果。

小技巧：如果想快速测试多张图，把source改成文件夹路径（如./my_images/），YOLO26会自动批量处理。

2.3 模型训练：从配置到启动只需改3处

训练不是黑盒。YOLO26沿用Ultralytics一贯清晰的配置逻辑：数据定义 → 模型结构 → 训练参数。你只需动3个地方，就能跑通自己的数据集。

第一步：准备并配置 data.yaml

YOLO26要求数据集为标准YOLO格式（images/+labels/+data.yaml）。上传后，在data.yaml中修改两处路径：

train: ../my_dataset/images/train # 训练图路径 val: ../my_dataset/images/val # 验证图路径 nc: 1 # 类别数 names: ['person'] # 类别名列表

注意：路径是相对于data.yaml文件自身的相对路径，不是绝对路径。写错会导致FileNotFoundError。

第二步：编写 train.py

无需从头写，复用以下精简模板（已去除冗余注释，保留关键可调项）：

from ultralytics import YOLO if __name__ == '__main__': # 指定模型配置文件（非权重！） model = YOLO('/root/workspace/ultralytics-8.4.2/ultralytics/cfg/models/26/yolo26.yaml') # 加载预训练权重（可选，新任务建议跳过） # model.load('yolo26n.pt') model.train( data='data.yaml', # 数据配置 imgsz=640, # 输入尺寸（YOLO26默认支持640） epochs=200, # 训练轮数 batch=128, # 批次大小（根据显存调整） workers=8, # 数据加载进程数 device='0', # GPU编号 project='runs/train', # 输出根目录 name='my_exp' # 实验名称（生成 runs/train/my_exp/） )

第三步：启动训练

python train.py

训练开始后，终端会实时打印 loss、mAP、precision 等指标。训练完成后，模型权重保存在runs/train/my_exp/weights/best.pt，日志和可视化图表在同目录下的results.csv和results.png中。

关键提醒：YOLO26的yolo26.yaml是模型结构定义，yolo26n.pt是预训练权重。训练时先加载.yaml，再用.pt初始化参数（model.load()）。若做迁移学习，务必确保两者结构一致。

2.4 下载训练成果：高效导出不卡顿

训练好的模型、日志、可视化图表都在服务器上。下载时请避开两个误区：一是直接拖拽整个runs/文件夹（体积大、易中断），二是用浏览器下载（不支持大文件）。

推荐做法：

将best.pt和last.pt单独压缩：

zip -r best_model.zip runs/train/my_exp/weights/best.pt

用 Xftp 连接后，从右侧服务器窗口拖拽压缩包到左侧本地窗口，双击传输任务可实时查看进度。
若需下载完整实验目录，先打包再传：
```
zip -r my_exp_all.zip runs/train/my_exp/
```

这样既节省时间，又避免传输中断后重来。

3. 已包含权重文件

镜像已内置YOLO26官方发布的全部轻量级权重，位于代码根目录，开箱即用：

yolo26n.pt：YOLO26基础检测模型（nano级）
yolo26n-pose.pt：YOLO26姿态估计模型（nano级）
yolo26s.pt/yolo26s-pose.pt：小尺寸版本（如需更高精度可选用）

这些文件无需额外下载，直接在model=参数中引用即可。例如：

model = YOLO('yolo26s-pose.pt') # 切换为小尺寸姿态模型

提示：不同权重适用于不同场景。n版本适合边缘设备或高帧率需求；s版本在精度和速度间更均衡。实测在RTX 4090上，yolo26n-pose.pt推理速度可达 120+ FPS。

4. 常见问题

Q：为什么运行python detect.py报错ModuleNotFoundError: No module named 'ultralytics'？
A：未激活yolo环境。务必先执行conda activate yolo，再运行脚本。
Q：训练时提示AssertionError: Dataset not found，但data.yaml路径明明是对的？
A：检查data.yaml中的路径是否为相对路径，且相对于该文件所在位置。例如data.yaml在/root/workspace/ultralytics-8.4.2/，则train: ../my_dataset/images/train表示上层目录的my_dataset。
Q：model.train()报 CUDA out of memory，怎么调？
A：优先降低batch值（如从128→64→32），其次减小imgsz（如640→320），最后考虑用device='cpu'调试流程（仅限验证）。
Q：如何查看训练过程中的 mAP 曲线？
A：训练结束后，打开runs/train/my_exp/results.png，其中第3行第2列即为mAP50-95(B)曲线；也可用 Excel 打开results.csv查看每轮详细数值。