yolo-training

训练与微调

最快捷方式：在 Platform 中训练

如果你想只需点击几下即可开始，而无需配置本地 GPU，请使用 Platform 云训练：

1. 在项目页面点击 New Model，或在数据集页面点击以预选该数据集。
2. 选择兼容的预训练模型、就绪数据集、GPU、轮数、图像尺寸和批次大小。
3. 点击 Start Training，并查看实时图表、控制台日志和系统指标。
4. 打开已完成的模型，检查验证图表，并使用其 Predict、Export 或 Deploy 选项卡。Platform 会自动保留 best.pt。

云端任务至少需要一张训练图像、一张验证/测试图像，以及一张带标签的图像。如果你已有计算资源或需要更多控制，同时希望继续使用 Platform 数据集和实验跟踪，请使用本地/Colab 训练：

export ULTRALYTICS_API_KEY="YOUR_API_KEY"
yolo train model=yolo26n.pt data=ul://username/datasets/dataset-slug \
  epochs=100 project=username/project-slug name=experiment-1

在 Python 3.11+ 环境中使用 ultralytics>=8.4.120 时，ul:// URI 会下载 Platform 数据集；只要 API 密钥可用（ULTRALYTICS_API_KEY 或 api_key 设置），任何 project= 值（即使是本地文件夹）都会向 Platform 流式传输指标并上传权重。省略 project 可将运行保留在本地；列表形式的 data= 会在内部设置该值，因此运行这些任务时请取消设置密钥。

快速入门（检测）

from ultralytics import YOLO

model = YOLO("yolo26n.pt")  # ALWAYS start from pretrained weights
results = model.train(data="data.yaml", epochs=100, imgsz=640, batch=16, device=0)

yolo detect train data=data.yaml model=yolo26n.pt epochs=100 imgsz=640 batch=16 device=0

类别数量变更会自动处理——在 80 类预训练模型上使用 3 类的 data.yaml 即可正常运行（检测头会重新初始化，骨干网络会迁移；cls_remap=True 还会为名称匹配的类别重新映射检测头行）。

值得设置的基础参数（任务训练器可覆盖这些参数）

参数	默认值	说明
epochs	100	微调时设为 100–300；依靠提前停止，而非猜测
patience	100	验证集指标未提升时，等待多少个 epoch 后提前停止；快速迭代时约为 20–50
imgsz	task/model	全局回退值为 640；未设置时，分类任务使用 224；显式设置的值优先
batch	16	-1 自动适配约 60% 的显存（单 GPU）；浮点数（如 0.8）表示显存占比；否则为整数
device	None	0、[0,1]（DDP）、cpu、mps、-1（选择空闲 GPU）
cache	False	True（RAM）或 "disk"，用于受 I/O 限制的训练
workers	8	如果出现 RAM／共享内存错误，请调低此值
freeze	None	冻结前 N 层（freeze=10 ≈ 主干网络），适用于小型数据集
optimizer	auto	保持 auto（迭代次数超过 10k 时使用 MuSGD，否则使用 AdamW）；深度微调会覆盖此设置
lr0 / lrf	0.01 / 0.01	optimizer=auto 时会忽略 lr0；如需使用，请指定优化器（参见深度微调方案）
fraction	1.0	子集训练——冒烟测试时设为 fraction=0.1
resume	False	继续中断的运行（参见方案）
project/name	None	输出文件夹：相对路径 project → runs/<task>/<project>/<name>，绝对路径 → <project>/<name>。在 Python 3.11 及更高版本中，若有可用的 API 密钥，任何 project 都会上传到 Platform
seed	0	设置 deterministic=True（默认值）即可复现
compile	False	torch.compile；也可以是 "max-autotune-no-cudagraphs" 等
time	None	最大训练时长（小时）——会覆盖 epochs
完整的参数、数据增强和损失权重表：training-args.md（此文件夹）——更改以上未列出的内容前请先阅读。yolo cfg 显示基础架构和默认值；任务训练器、检查点和显式参数决定实际生效的值。

训练方案

• 恢复中断的训练：YOLO("runs/detect/train/weights/last.pt").train(resume=True)。恢复训练会完成原定的 epochs；训练完成后若要继续训练，请从 best.pt 开始新的训练（恢复训练无法延长已完成的训练）。
• 多 GPU：使用整数 batch 配合 device=[0,1]（AutoBatch 仅支持单 GPU）。DDP 工作进程会从生成的脚本重建，该脚本会通过 cloudpickle 序列化训练器、模型和回调；官方 Windows PyTorch>=2.4 轮子无法启动 DDP，因此请使用 Linux 或 WSL2。
• 小型检测风格数据集（<~1k 张图像）：使用预训练模型 + freeze=10，选择 n/s 模型，采用默认数据增强，并关注验证曲线。
• 深度微调：从 -depth.pt 开始，并使用 optimizer=AdamW lr0=1e-4 warmup_bias_lr=1e-4。
• 小目标：尝试 imgsz=1280（需要更多计算资源/VRAM；必要时减小 batch），或在数据集层面切分大图像。
• 实验规范：使用能说明实验内容的名称（name=0811_yolo26s_helmets_e100），每次训练只改一个变量；每次训练的完整配置都会保存在 runs/<task>/<name>/args.yaml 中——对比这些文件即可比较不同训练。
• 日志集成：运行 yolo settings tensorboard=True（wandb 也同理），然后按常规方式训练。mlflow、comet 和 clearml 默认启用，安装相应软件包后便会激活。
• 知识蒸馏：使用 distill_model=yolo26l.pt dis=6.0，以更大的教师模型训练学生模型。

验证

yolo val model=runs/detect/train/weights/best.pt data=data.yaml # split=val by default

各任务的主要指标：检测/OBB 为 mAP50-95(B)，分割为 (M)，姿态为 (P)，语义分割为 mIoU，深度为 delta1，分类为 accuracy_top1。验证基础默认值为 conf=0.001（OBB 为 0.01）、iou=0.7 和 nms=None（一对多检测头 + NMS）；nms=False 则验证 YOLO26 的免 NMS 检测头，此时 iou 不起作用。使用 split=test 评估测试集，使用 save_json=True 进行 COCO 格式评估。

查看已完成的训练（runs/<task>/<name>/）

• weights/best.pt——验证适应度最高的检查点；使用这个。last.pt——用于恢复训练。
• results.csv / results.png——每个轮次的损失和验证指标。解读：训练损失 ↓，而验证 mAP 先趋于平稳后下降 = 过拟合（增加数据/数据增强，使用更小的模型——best.pt 已保留效果良好的检查点）。两者都低且持平 = 欠拟合（使用更大的模型、增加训练轮数、提高 imgsz，并检查标签）。mAP50 良好但 mAP50-95 较差 = 定位不够精确（提高 imgsz，改进边界框）。
• train_batch*.jpg——绘有标签的增强图像。每个项目至少检查一次：错误标签在这里一目了然。
• confusion_matrix.png——两个类别之间出现非对角线聚集，说明标签不一致或类别本身相似。坐标轴为预测类别（y）× 真实类别（x）：背景行较重 = 漏检（该类别需要更多/更好的样本）；背景列较重 = 误报（添加背景图像，或在推理时提高 conf）。

故障排除

症状	依次尝试的解决方法
CUDA 显存不足	降低 batch（或设为 batch=-1），降低 imgsz，使用更小的模型；结束占用显存的僵尸 Python 进程
NaN / 损失爆炸	设置 optimizer=AdamW lr0=0.001（auto 会忽略 lr0）；检查标签；尝试 amp=False
mAP 接近 0	95% 的情况下都是数据集问题——参见 yolo-datasets，检查 train_batch*.jpg
mAP 停滞在较低水平	首先增加或改进数据；然后提高 imgsz、使用更大的模型、增加训练轮数；参见 yolo-tuning playbook
比预期更早停止	这是 patience 的作用——调高它，或接受 best.pt
数据加载器速度慢 / GPU 空闲	使用 cache=True/"disk"，增加 workers，将数据放在 SSD 上
运行中验证指标为 0	验证集划分中缺少类别

反模式：设置 pretrained=False 来“正确训练”（需要约 100× 更多数据）；仅用 50 张图像对比模型大小；复制包含 30 个参数的命令（从默认值开始）；混淆矩阵明显显示标签噪声时仍调整超参数。

相关页面

• training-args.md — 完整的训练/数据增强/损失权重参数表。设置上述表格中未列出的任何参数前，请先阅读。

如果已安装的版本不接受某个参数（yolo checks 会显示版本），请以错误文本和 yolo cfg 为准，而不是本文档。