yolo-tuning

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Improving models & hyperparameter tuning

模型改进与超参数调优

The improvement playbook (follow in order — tuning is the LAST step)

改进指南（按顺序执行——调优是最后一步）

Hyperparameter tuning is expensive and usually not the bottleneck. Escalate in this order, re-validating after each step:

Fix the data — check
```
confusion_matrix.png
```
and
```
train_batch*.jpg
```
for label noise; review the top false-negative/false-positive val images; add examples of failing classes and true-background images. Data quality beats every other lever.
Train longer — if val mAP was still rising at the end: more
```
epochs
```
, higher
```
patience
```
.
Bigger input — small objects or mAP50 ≫ mAP50-95: raise
```
imgsz
```
(640 → 960/1280).
Bigger model — underfitting (train and val both mediocre): n → s → m → l.
Domain-matched augmentation — aerial
```
degrees=180 flipud=0.5
```
, crowded scenes
```
copy_paste=0.3
```
/
```
mixup=0.1
```
, color-critical classes lower
```
hsv_h
```
(see yolo-training's
```
training-args.md
```
).
Only now: hyperparameter tuning — worth ~0.5–2 mAP when everything above is exhausted.

Decision signals: overfitting (val drops while train improves) → more data/aug or smaller model, NOT tuning. Underfitting → bigger model/longer, NOT tuning. Label noise in the confusion matrix → nothing else matters until fixed.

超参数调优成本高昂，通常并非性能瓶颈。请按以下顺序逐步优化，每一步后重新验证效果：

修复数据问题 — 查看
```
confusion_matrix.png
```
和
```
train_batch*.jpg
```
检查标签噪声；回顾验证集里排名靠前的假阴性/假阳性图像；添加识别失败类别的样本和真实背景图像。数据质量优于其他所有优化手段。
延长训练时长 — 如果验证集mAP在训练结束时仍呈上升趋势：增加
```
epochs
```
，提高
```
patience
```
值。
增大输入尺寸 — 存在小目标或mAP50远大于mAP50-95时：提升
```
imgsz
```
（从640调整为960/1280）。
更换更大模型 — 出现欠拟合（训练集和验证集表现均不佳）：从n模型切换到s→m→l模型。
匹配领域的增强策略 — 航拍数据设置
```
degrees=180 flipud=0.5
```
，密集场景设置
```
copy_paste=0.3
```
/
```
mixup=0.1
```
，对颜色敏感的类别降低
```
hsv_h
```
值（详见yolo-training的
```
training-args.md
```
）。
最后才进行：超参数调优 — 当以上所有步骤都完成后，调优能带来约0.5–2的mAP提升。

判断信号：过拟合（训练集性能提升但验证集下降）→ 增加数据/增强或更换更小模型，而非调优。欠拟合→更换更大模型/延长训练时长，而非调优。混淆矩阵中存在标签噪声→在修复前其他优化都无效。

Compare experiments in Platform

在平台中对比实验

Keep candidates in one Platform project. Train from the New Model dialog, or stream local runs by setting

project=username/project-slug

and a unique

name

. Select models together in the project charts, or use Table > Diff to compare training arguments and final metrics.

Platform is the experiment owner and visualization layer; the built-in genetic tuner and Ray Tune below remain Python workflows. Use a completed Platform model as the next base checkpoint, or download its

.pt

file, after the comparison identifies a winner.

将候选模型放在同一个平台项目中。通过「新建模型」对话框进行训练，或通过设置

project=username/project-slug

和唯一的

name

来同步本地运行记录。在项目图表中选择多个模型进行对比，或使用「表格 > 差异」功能对比训练参数和最终指标。

平台是实验的管理和可视化层；以下内置遗传调优器和Ray Tune仍为Python工作流。对比确定最优模型后，可将已完成的平台模型作为下一个基准检查点，或下载其

.pt

文件。

Built-in genetic tuner

内置遗传调优器

python

from ultralytics import YOLO

model = YOLO("yolo26n.pt")
model.tune(data="data.yaml", epochs=30, iterations=300, plots=False, save=False, val=False)

Tuning is Python-only — there is no

yolo tune

CLI mode (MODES are train/val/predict/export/track/benchmark).

Each iteration = one full (short) training with mutated hyperparameters; fitness is read from the run's val metrics.

Default search space: 26 keys —

lr0

lrf

momentum

weight_decay

warmup_epochs

warmup_momentum

, loss weights (

box

cls

cls_pw

dfl

), all augmentation knobs (

hsv_*

degrees

translate

scale

shear

perspective

flipud

fliplr

bgr

mosaic

mixup

cutmix

copy_paste

close_mosaic

Custom space (subset + ranges as

(min, max)

python

model.tune(data="data.yaml", epochs=30, iterations=100, space={"lr0": (1e-5, 1e-1), "mosaic": (0.5, 1.0)})

Results:
```
runs/<task>/tune/
```
—
```
best_hyperparameters.yaml
```
,
```
tune_results.ndjson
```
, fitness plots. Load the yaml and retrain fully with it.
Distributed tuning across machines: pass
```
mongodb_uri=
```
(+ optional
```
mongodb_db=
```
,
```
mongodb_collection=
```
) — workers share one result pool via MongoDB.

python

from ultralytics import YOLO

model = YOLO("yolo26n.pt")
model.tune(data="data.yaml", epochs=30, iterations=300, plots=False, save=False, val=False)

调优仅支持Python方式——没有

yolo tune

命令行模式（命令行模式包括train/val/predict/export/track/benchmark）。

每次迭代 = 使用变异超参数完成一次（短时长）完整训练；适应度从运行的验证指标中读取。

默认搜索空间：26个参数——

lr0

、

lrf

、

momentum

、

weight_decay

、

warmup_epochs

、

warmup_momentum

、损失权重（

box

、

cls

、

cls_pw

、

dfl

）、所有数据增强参数（

hsv_*

、

degrees

、

translate

、

scale

、

shear

、

perspective

、

flipud

、

fliplr

、

bgr

、

mosaic

、

mixup

、

cutmix

、

copy_paste

）、

close_mosaic

。

自定义空间（子集+范围设置为

(min, max)

）：

python

model.tune(data="data.yaml", epochs=30, iterations=100, space={"lr0": (1e-5, 1e-1), "mosaic": (0.5, 1.0)})

结果存储在
```
runs/<task>/tune/
```
目录下——包含
```
best_hyperparameters.yaml
```
、
```
tune_results.ndjson
```
、适应度图表。加载该yaml文件并使用其配置进行完整训练。
跨机器分布式调优：传入
```
mongodb_uri=
```
（可选
```
mongodb_db=
```
、
```
mongodb_collection=
```
）——工作节点通过MongoDB共享同一个结果池。

Ray Tune (advanced search algorithms, parallel trials)

Ray Tune（高级搜索算法，并行试验）

python

model = YOLO("yolo26n.pt")
result_grid = model.tune(use_ray=True, data="data.yaml", iterations=20, epochs=30, gpu_per_trial=1)

Requires
```
pip install "ray[tune]"
```
. Default scheduler is ASHA (early-kills bad trials after
```
grace_period
```
epochs, default 10).
```
search_alg=
```
accepts Ax, BOHB, Nevergrad, ZOOpt, Optuna, HyperOpt, HEBO, BayesOpt, or
```
"random"
```
(string, or an object for Ax/BOHB/ZOOpt) instead of random search.
Optional W&B logging if
```
wandb
```
is installed. Use Ray when you have multiple GPUs to parallelize trials or want smarter-than-genetic search; the built-in tuner is simpler and has no extra dependency.

python

model = YOLO("yolo26n.pt")
result_grid = model.tune(use_ray=True, data="data.yaml", iterations=20, epochs=30, gpu_per_trial=1)

需要安装
```
pip install "ray[tune]"
```
。默认调度器为ASHA（在
```
grace_period
```
轮次（默认10轮）后提前终止表现不佳的试验）。
```
search_alg=
```
参数可接受Ax、BOHB、Nevergrad、ZOOpt、Optuna、HyperOpt、HEBO、BayesOpt，或
```
"random"
```
（字符串，或Ax/BOHB/ZOOpt的对象）来替代随机搜索。
如果安装了
```
wandb
```
，可选择进行W&B日志记录。当你有多块GPU用于并行试验，或需要比遗传算法更智能的搜索时使用Ray；内置调优器更简单且无额外依赖。

Evolution best practices ("autotraining" recipe)

进化调优最佳实践（「自动训练」方案）

Search cheap, retrain expensive: tune with a small model (
```
n
```
/
```
s
```
), reduced
```
epochs
```
(~30),
```
plots=False save=False val=False
```
; then retrain the best config at full size/epochs.
Budget: iterations × epochs × time-per-epoch. 100–300 iterations is a realistic minimum for the genetic tuner to beat defaults.
Keep
```
data
```
fixed during the search — changing data invalidates all prior fitness.
One fitness target: the tuner optimizes the task's default metric (e.g. mAP50-95(B)); confirm that matches what you actually care about before burning GPU days.
Sanity-check the winner on the val AND test split — tuned configs can overfit the val split when iterations are high.

If the installed version rejects an argument (

yolo checks

shows the version), trust the error text and

yolo cfg

over this file.

低成本搜索，高成本重训：使用小型模型（
```
n
```
/
```
s
```
）、减少
```
epochs
```
（约30轮）、设置
```
plots=False save=False val=False
```
进行调优；然后使用最优配置以全尺寸/全轮次重新训练。
预算：迭代次数 × 轮次 × 每轮耗时。遗传调优器要优于默认配置，100–300次迭代是现实的最低要求。
搜索过程中保持
```
data
```
固定——更改数据会使之前所有的适应度结果失效。
单一适应度目标：调优器会优化任务的默认指标（例如mAP50-95(B)）；在消耗GPU资源前，请确认该指标与你实际关注的指标一致。
在验证集和测试集上 sanity-check 最优配置——当迭代次数较多时，调优后的配置可能会过拟合验证集。

如果已安装的版本不支持某个参数（

yolo checks

可查看版本），请以错误提示和

yolo cfg

为准，而非本文档。