yolo-training

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Training & fine-tuning

训练与微调

Fastest route: train in Platform

最快路径：在Platform中训练

Use Platform cloud training when you want to start in a few clicks without configuring a local GPU:

Create a project and click New Model (or start from a dataset's Train action).
Select a compatible pretrained model, ready dataset, GPU, epochs, image size, and batch size.
Click Start Training and watch live charts, console logs, and system metrics.
Open the completed model to inspect validation plots and use its Predict, Export, or Deploy tab. Platform preserves
```
best.pt
```
automatically.

Cloud jobs require at least one train image, one val/test image, and one labeled image. Use local/Colab training when you already have compute or need more control, while keeping Platform datasets and experiment tracking:

bash

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

With

ultralytics>=8.4.104

, the

ul://

URI downloads the Platform dataset and the

username/project-slug

target streams metrics back to that Platform project.

当您希望通过几次点击即可开始训练，无需配置本地GPU时，请使用Platform云端训练：

创建项目并点击新建模型（或从数据集的训练操作开始）。
选择兼容的预训练模型、就绪数据集、GPU、epochs（轮次）、图像尺寸和批次大小。
点击开始训练，查看实时图表、控制台日志和系统指标。
打开已完成的模型，检查验证图表，并使用其预测、导出或部署标签页。Platform会自动保存
```
best.pt
```
文件。

云端任务至少需要1张训练图像、1张验证/测试图像和1张带标注的图像。如果您已有计算资源或需要更多控制，同时希望保留Platform的数据集和实验追踪功能，请使用本地/Colab训练：

bash

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

当

ultralytics>=8.4.104

时，

ul://

URI会下载Platform数据集，

username/project-slug

目标会将指标流回该Platform项目。

Quickstart (detection)

快速入门（检测任务）

python

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)

bash

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

Class-count changes are automatic — a 3-class data.yaml on an 80-class pretrained model just works (head re-initializes, backbone transfers;

cls_remap=True

even re-maps head rows for classes whose names match).

python

from ultralytics import YOLO

model = YOLO("yolo26n.pt")  # 始终从预训练权重开始
results = model.train(data="data.yaml", epochs=100, imgsz=640, batch=16, device=0)

bash

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

类别数量变化会自动处理——在80类预训练模型上使用3类的data.yaml即可正常运行（头部会重新初始化，骨干网络进行迁移；

cls_remap=True

甚至会为名称匹配的类别重新映射头部行）。

Base arguments worth setting (task trainers can override them)

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

Arg	Default	Notes
`epochs`	100	100–300 for fine-tuning; rely on early stopping, not guesses
`patience`	100	epochs without val improvement before early stop; ~20–50 for quick iterations
`imgsz`	task/model	global fallback 640; classify uses 224 when unset; explicit values win
`batch`	16	`-1` auto-fits ~60% VRAM; float like `0.8` = VRAM fraction; else integer
`device`	None	`0` , `[0,1]` (DDP), `cpu` , `mps` , `-1` picks an idle GPU
`cache`	False	`True` (RAM) or `"disk"` for I/O-bound training
`workers`	8	lower if RAM/shared-memory errors
`freeze`	None	freeze first N layers ( `freeze=10` ≈ backbone) for small datasets
`optimizer`	auto	leave on auto (YOLO26 adds MuSGD); depth fine-tuning overrides it below
`lr0` / `lrf`	0.01 / 0.01	base values; depth fine-tuning uses a lower `lr0` below
`fraction`	1.0	subset training — `fraction=0.1` for smoke tests
`resume`	False	continue an interrupted run (see recipes)
`project` / `name`	None	local output naming; authenticated `username/project-slug` also streams to Platform
`seed`	0	reproducible with `deterministic=True` (default)
`compile`	False	torch.compile; also `"max-autotune-no-cudagraphs"` etc.
`time`	None	max training hours — overrides epochs

Full argument, augmentation, and loss-weight tables:

training-args.md

(this folder) — read before changing anything not listed above.

yolo cfg

shows the base schema and defaults; task trainers, checkpoints, and explicit arguments determine effective values.

参数	默认值	说明
`epochs`	100	微调时设置为100–300；依赖早停机制，而非主观猜测
`patience`	100	验证集性能无提升时触发早停的轮次；快速迭代时可设置为20–50
`imgsz`	任务/模型	全局默认值为640；分类任务未设置时使用224；显式设置的值优先级最高
`batch`	16	`-1` 会自动适配约60%的显存；设置为浮点数如 `0.8` 表示显存占比；否则为整数
`device`	None	`0` 、 `[0,1]` （DDP分布式训练）、 `cpu` 、 `mps` 、 `-1` 会选择空闲GPU
`cache`	False	`True` （内存缓存）或 `"disk"` （磁盘缓存）适用于I/O受限的训练场景
`workers`	8	若出现内存/共享内存错误，可降低该值
`freeze`	None	冻结前N层（ `freeze=10` ≈冻结骨干网络）适用于小型数据集
`optimizer`	auto	保持默认auto（YOLO26新增MuSGD）；深度微调会覆盖此设置
`lr0` / `lrf`	0.01 / 0.01	基础值；深度微调需使用更低的 `lr0`
`fraction`	1.0	训练子集—— `fraction=0.1` 可用于快速测试
`resume`	False	恢复中断的训练（请参阅下方方案）
`project` / `name`	None	本地输出命名；已认证的 `username/project-slug` 也会将指标流回Platform
`seed`	0	设置 `deterministic=True` （默认）可保证训练可复现
`compile`	False	torch.compile；也可设置为 `"max-autotune-no-cudagraphs"` 等
`time`	None	最大训练时长——会覆盖epochs设置

完整的参数、数据增强和损失权重表格请查看

training-args.md

（本文件夹下）——在修改上述未列出的任何参数前，请先阅读该文档。

yolo cfg

会显示基础配置和默认值；任务训练器、检查点和显式参数会决定最终生效的值。

Recipes

训练方案

Resume interrupted run:
```
YOLO("runs/detect/train/weights/last.pt").train(resume=True)
```
. Resume finishes the original
```
epochs
```
; to train longer after completion, start a NEW training from
```
best.pt
```
(resume can't extend a finished run).
Multi-GPU:
```
device=[0,1]
```
. Run as a script — DDP spawns processes and breaks in notebooks (and on Windows, guard with
```
if __name__ == "__main__":
```
).
Small detect-style dataset (<~1k images): pretrained +
```
freeze=10
```
,
```
n
```
/
```
s
```
model, default augmentation, watch val curves.

Depth fine-tuning: start from

-depth.pt

and use

optimizer=AdamW lr0=1e-4 warmup_bias_lr=1e-4

Small objects: try
```
imgsz=1280
```
(more compute/VRAM; reduce batch if needed), or tile large images at dataset level.
Experiment hygiene: self-describing run names (
```
name=0811_yolo26s_helmets_e100
```
), one variable per run; each run's full config is saved in
```
runs/<task>/<name>/args.yaml
```
— diff those to compare runs.
Logging integrations:
```
yolo settings tensorboard=True
```
(likewise
```
wandb
```
,
```
mlflow
```
,
```
comet
```
,
```
clearml
```
) — then train normally.
Knowledge distillation:
```
distill_model=yolo26l.pt dis=6.0
```
trains the student with a larger teacher.

恢复中断的训练：
```
YOLO("runs/detect/train/weights/last.pt").train(resume=True)
```
。恢复训练会完成原设定的
```
epochs
```
；若训练完成后想继续训练更久，请从
```
best.pt
```
开始新的训练（恢复无法延长已完成的训练）。
多GPU训练：
```
device=[0,1]
```
。需以脚本形式运行——DDP会生成进程，在笔记本中会失效（Windows系统下需用
```
if __name__ == "__main__":
```
包裹）。
小型检测类数据集（<~1k张图像）：使用预训练模型 +
```
freeze=10
```
、
```
n
```
/
```
s
```
规模模型、默认数据增强，关注验证曲线。

深度微调：从

-depth.pt

模型开始，使用

optimizer=AdamW lr0=1e-4 warmup_bias_lr=1e-4

。

小目标检测：尝试设置
```
imgsz=1280
```
（会增加计算量/显存占用；必要时降低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
```
会用更大的教师模型训练学生模型。

Validation

验证

bash

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

Per-task headline metrics: detect/obb

mAP50-95(B)

, segment

(M)

, pose

(P)

, semantic

mIoU

, depth

delta1

, classify

accuracy_top1

. Val base defaults are

conf=0.001

(

0.01

for OBB) and

iou=0.7

;

iou

is inactive for default end-to-end YOLO26. Use

split=test

for the test set and

save_json=True

for COCO-format eval.

bash

yolo val model=runs/detect/train/weights/best.pt data=data.yaml # 默认使用val拆分数据集

各任务的核心指标：检测/定向边界框（OBB）为

mAP50-95(B)

，分割为

(M)

，姿态估计为

(P)

，语义分割为

mIoU

，深度估计为

delta1

，分类为

accuracy_top1

。验证的基础默认值为

conf=0.001

（OBB为

0.01

）和

iou=0.7

；默认端到端的YOLO26中

iou

无效。使用

split=test

可测试测试集，

save_json=True

可生成COCO格式的评估结果。

Reading a finished run (

runs/<task>/<name>/

)

解读已完成的训练（

runs/<task>/<name>/

目录）

```
weights/best.pt
```
— highest val fitness; use this one.
```
last.pt
```
— for resuming.
```
results.csv
```
/
```
results.png
```
— per-epoch losses and val metrics. Interpretation: train loss ↓ while val mAP plateaus-then-drops = overfitting (more data/aug, smaller model —
```
best.pt
```
already kept the good checkpoint). Both flat and low = underfitting (bigger model, more epochs, higher imgsz, check labels). mAP50 good but mAP50-95 poor = sloppy localization (higher imgsz, better boxes).
```
train_batch*.jpg
```
— augmented images with labels drawn. Look once per project: wrong labels are instantly visible here.
```
confusion_matrix.png
```
— off-diagonal cluster between two classes = inconsistent labels or genuinely similar classes. Axes are predicted (y) × true (x): heavy background row = missed detections (that class needs more/better examples); heavy background column = false positives (add background images or raise
```
conf
```
at inference).

```
weights/best.pt
```
——验证集性能最优的权重；请使用该文件。
```
last.pt
```
——用于恢复训练。
```
results.csv
```
/
```
results.png
```
——每轮的损失值和验证指标。解读：训练损失↓但验证mAP趋于平稳后下降 = 过拟合（需更多数据/增强、更小模型——
```
best.pt
```
已保留最优检查点）。两者均平稳且数值低 = 欠拟合（更大模型、更多轮次、更大图像尺寸、检查标注）。mAP50良好但mAP50-95较差 = 定位精度不足（更大图像尺寸、更优边界框）。
```
train_batch*.jpg
```
——带标注的增强图像。每个项目至少查看一次：错误标注会立即显现。
```
confusion_matrix.png
```
——两类之间的对角线外聚类 = 标注不一致或类别本身相似。坐标轴为预测类别（y轴）×真实类别（x轴）：背景行权重高 = 漏检（该类别需要更多/更好的样本）；背景列权重高 = 误检（添加背景图像或提高推理时的
```
conf
```
阈值）。

Troubleshooting

故障排查

Symptom	Fix, in order
CUDA out of memory	lower `batch` (or `batch=-1` ), lower `imgsz` , smaller model; kill zombie python processes holding VRAM
NaN / exploding loss	set `optimizer=AdamW lr0=0.001` ( `auto` ignores `lr0` ); check labels; try `amp=False`
mAP near 0	dataset problem 95% of the time — see yolo-datasets, check `train_batch*.jpg`
mAP plateaus low	more/better data first; then imgsz ↑, bigger model, more epochs; see yolo-tuning playbook
Stopped earlier than expected	that's `patience` — raise it or accept `best.pt`
Dataloader slow / GPU idle	`cache=True` / `"disk"` , raise `workers` , data on SSD
Val metrics zero mid-run	classes missing from the val split

Anti-patterns:

pretrained=False

"to train properly" (needs ~100× more data); benchmarking model sizes on 50 images; copying 30-argument commands (start from defaults); tuning hyperparameters while the confusion matrix screams label noise.

症状	解决步骤（按优先级）
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指南
训练提前终止	这是 `patience` 早停机制导致的——可提高该值或接受 `best.pt`
数据加载缓慢 / GPU闲置	设置 `cache=True` / `"disk"` 、提高 `workers` 、将数据存储在SSD上
训练中途验证指标为0	验证拆分数据集中缺少对应类别

反模式：设置

pretrained=False

“以进行正确训练”（需要约100倍更多数据）；用50张图像测试模型规模；复制30个参数的命令（从默认值开始）；当混淆矩阵显示标注噪声时仍调整超参数。

yolo-training

Original

Translation

Training & fine-tuning

训练与微调

Fastest route: train in Platform

最快路径：在Platform中训练

Quickstart (detection)

快速入门（检测任务）

Base arguments worth setting (task trainers can override them)

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

Recipes

训练方案

Validation

验证

Reading a finished run (
`runs/<task>/<name>/`
)

解读已完成的训练（
`runs/<task>/<name>/`
目录）

Troubleshooting

故障排查

Related pages

相关页面

yolo-training

Original

Translation

Training & fine-tuning

训练与微调

Fastest route: train in Platform

最快路径：在Platform中训练

Quickstart (detection)

快速入门（检测任务）

Base arguments worth setting (task trainers can override them)

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

Recipes

训练方案

Validation

验证

Reading a finished run (runs/<task>/<name>/)

解读已完成的训练（runs/<task>/<name>/目录）

Troubleshooting

故障排查

Related pages

相关页面

Reading a finished run (
`runs/<task>/<name>/`
)

解读已完成的训练（
`runs/<task>/<name>/`
目录）