Ultralytics YOLO 超参数调优指南#

Ultralytics YOLO 中的超参数调优是一种自动化的迭代搜索，通过优化学习率、损失权重和增强强度等设置，最大化机器学习模型的准确率、精确率和召回率等性能指标。Ultralytics YOLO 不会手动逐一测试这些值，而是使用遗传算法探索超参数空间，在多次短时训练运行中变异并评估候选配置。

什么是超参数？#

超参数是算法的高级结构设置。它们在训练阶段开始前设定，并在训练过程中保持不变。以下是 Ultralytics YOLO 中一些常见的可调超参数：

• 学习率 lr0：确定沿着损失函数趋近最小值时每次迭代的步长。
• 批量大小 batch：一次前向传播中同时处理的图像数量。
• 轮数 epochs：一个 epoch 是对所有训练样本进行一次完整的前向传播和反向传播。
• 架构细节：例如通道数、层数、激活函数类型等。这些内容位于模型 YAML 配置中，而不是训练参数中。

这四项中，只有学习率位于默认搜索空间中：batch、epochs 和架构保持不变。调优器还会变异下方列出的调度策略、损失增益和增强参数。

有关 YOLO26 中使用的完整增强超参数列表，请参阅配置页面。

遗传进化与变异#

Ultralytics YOLO 使用遗传算法优化超参数。遗传算法的灵感来源于自然选择和遗传机制。

• 选择：每次迭代根据适应度加权，从最多九个适应度最高的配置中选择一个。获得 30 个结果后，所有结果中排名前 20% 的配置（最多 30 个）还会估计参数协方差，其影响力会随着精英样本证据的累积而增强。
• 变异：每次迭代使用根据搜索范围归一化的高斯步长，变异大约一半的参数。协方差启用后，最多 40% 的变异会根据置信度加权使用相关步长，并通过反射将这些步长保持在边界内，而不会累积被截断的值。当试验不断累积但没有改进时，步长会在 25 次试验内线性缩小最多 20%，发现新的最佳结果后则重置。第 1 次迭代没有父代，并使用默认训练超参数作为基线。

准备超参数调优#

开始调优过程前，请务必：

1. 确定指标：内置调优器（use_ray=False）根据任务的 fitness 分数对试验进行排名，而 use_ray=True 使用任务指标。确定要检查哪些次要指标，例如 AP50 或 F1 分数。
2. 设置调优预算：确定你愿意分配多少计算资源。超参数调优可能需要大量计算资源。

调优循环的工作方式#

对于每次迭代，内置调优器都会重复以下循环：

1. 初始化超参数 — 从合理的基线开始，可以是 Ultralytics YOLO 设置的默认超参数，也可以是基于你的领域知识或以往实验得出的值。
2. 变异超参数 — Tuner 类会自动使用其 _mutate 方法，根据现有超参数集生成一组新的超参数。
3. 训练模型 — 使用变异后的超参数进行训练，然后使用你选择的指标评估训练性能。
4. 评估模型 — 评估过程会生成本次迭代的适应度分数，并将其与之前的迭代进行比较，以确定当前超参数是否有所改进。
5. 记录结果 — 记录性能指标及其对应的超参数，以供日后参考。Ultralytics YOLO 会自动将这些结果保存为 NDJSON 格式。
6. 重复 — 持续执行，直到达到设定的迭代次数，每次迭代都会基于之前运行获得的知识继续优化。内置调优器会运行全部 iterations；Ray Tune 会在每个拟合 epoch 后报告指标，使 ASHA 能够在宽限期后停止表现较弱的试验。

迭代次数与种群大小#

使用内置调优器（use_ray=False）时，iterations 控制顺序试验的总数，默认值为 300。每个试验使用一组超参数配置训练一个模型——例如，iterations=40 配合 epochs=50 会安排 40 次相互独立的 50-epoch 训练运行，而不是进行一次包含 40 个独立候选配置的 50-epoch 运行。

内置遗传算法没有显式的种群大小参数。存在先前试验后，它会从最多九个适应度最高的配置中进行选择，并在每次迭代中变异一个候选配置。

如需并行试验或更高级的搜索策略，请将 use_ray=True 设置为使用 Ray Tune；Ray Tune 使用相同的 300 次试验默认值，并接收 iterations 作为 num_samples。详情请参阅 Ray Tune 集成指南。

默认搜索空间#

下表列出了 YOLO26 超参数调优的默认搜索空间参数。每个参数都有由元组 (min, max) 定义的特定取值范围。

自定义搜索空间示例#

下面介绍如何定义搜索空间，并使用 model.tune() 方法调用 Tuner 类，对 COCO8 上的 YOLO26n 进行 30 个 epoch 的超参数调优，使用 AdamW 优化器，并跳过绘图、检查点保存以及除最终 epoch 外的验证，以加快调优速度。

from ultralytics import YOLO

# Initialize the YOLO model
model = YOLO("yolo26n.pt")

# Define search space
search_space = {
    "lr0": (1e-5, 1e-2),
    "degrees": (0.0, 45.0),
}

# Tune hyperparameters on COCO8 for 30 epochs
model.tune(
    data="coco8.yaml",
    epochs=30,
    iterations=300,
    optimizer="AdamW",
    space=search_space,
    plots=False,
    save=False,
    val=False,
)

恢复中断的超参数调优会话#

你可以通过传入 resume=True 来恢复中断的超参数调优会话。你还可以选择传入在 runs/{task} 下使用的目录 name 以恢复会话。如果没有传入 name，程序会恢复字面名称为 tune 的目录；这是默认名称，而不是最近运行的会话名称，因此对于使用自定义名称启动的运行，请传入 name。你还需要提供所有之前的训练参数，包括 data、epochs、iterations 和 space。

from ultralytics import YOLO

# Define a YOLO model
model = YOLO("yolo26n.pt")

# Define search space
search_space = {
    "lr0": (1e-5, 1e-2),
    "degrees": (0.0, 45.0),
}

# Resume previous run
results = model.tune(data="coco8.yaml", epochs=50, iterations=300, space=search_space, resume=True)

# Resume tuning run with name 'tune_exp'
results = model.tune(data="coco8.yaml", epochs=50, iterations=300, space=search_space, name="tune_exp", resume=True)

结果#

成功完成超参数调优过程后，你将获得若干封装调优结果的文件和目录。下面介绍每一项：

文件结构#

下面是结果目录结构的示例。train/ 和 train-2/ 等训练目录包含各次独立的调优迭代，即使用一组超参数训练的一个模型。tune/ 目录包含所有单独模型训练的调优结果：

runs/
└── detect/
    ├── train/
    ├── train-2/
    ├── ...
    └── tune/
        ├── best_hyperparameters.yaml
        ├── tune_fitness.png
        ├── tune_results.ndjson
        ├── tune_scatter_plots.png
        └── weights/
            ├── last.pt
            └── best.pt

文件说明#

best_hyperparameters.yaml#

此 YAML 文件包含调优过程中找到的性能最佳超参数。你可以使用此文件，利用这些优化后的设置初始化后续训练。

• 格式：YAML

• 用途：超参数结果

• 示例：

  # 558/900 iterations complete ✅ (45536.81s)
  # Results saved to /usr/src/ultralytics/runs/detect/tune
  # Best fitness=0.64297 observed at iteration 498
  # Best fitness metrics are {'metrics/precision(B)': 0.87247, 'metrics/recall(B)': 0.71387, 'metrics/mAP50(B)': 0.79106, 'metrics/mAP50-95(B)': 0.62651, 'val/box_loss': 2.79884, 'val/cls_loss': 2.72386, 'val/l1_loss': 0.68503, 'fitness': 0.64297}
  # Best fitness model is /usr/src/ultralytics/runs/detect/tune/weights
  # Best fitness hyperparameters are printed below.
  
  lr0: 0.00269
  lrf: 0.00288
  momentum: 0.73375
  weight_decay: 0.00015
  warmup_epochs: 1.22935
  warmup_momentum: 0.1525
  box: 18.27875
  cls: 1.32899
  dfl: 0.56016
  hsv_h: 0.01148
  hsv_s: 0.53554
  hsv_v: 0.13636
  degrees: 0.0
  translate: 0.12431
  scale: 0.07643
  shear: 0.0
  perspective: 0.0
  flipud: 0.0
  fliplr: 0.08631
  mosaic: 0.42551
  mixup: 0.0
  copy_paste: 0.0

tune_fitness.png#

此图显示适应度与迭代次数之间的关系。它可以帮助你直观了解遗传算法随时间的表现。

• 格式：PNG
• 用途：性能可视化

图中包含：

• 每个数据集的每次迭代各有一个标记，因此单数据集运行会在每次迭代显示一个点，多数据集运行则会在每次迭代为每个数据集显示一个点。
• 一条点状的“平滑均值”线，该线是对每次迭代的顶层适应度值进行高斯平滑（sigma=3）后计算得到的。

tune_results.ndjson#

一个包含每次调优迭代详细结果的 NDJSON 文件。每行都是一个 JSON 对象，包含汇总适应度、调优后的超参数和每个数据集的指标。单数据集和多数据集调优使用相同的文件格式。

• 格式：NDJSON
• 用途：跟踪每次迭代的结果。
• 示例：

下面提供一个格式化示例以便阅读；在实际的 .ndjson 文件中，每个对象都存储在单独一行中。

{
    "iteration": 1,
    "fitness": 0.48628,
    "hyperparameters": {
        "lr0": 0.01,
        "lrf": 0.01,
        "momentum": 0.937,
        "weight_decay": 0.0005
    },
    "datasets": {
        "coco8": {
            "metrics/precision(B)": 0.65666,
            "metrics/recall(B)": 0.85,
            "metrics/mAP50(B)": 0.85086,
            "metrics/mAP50-95(B)": 0.64104,
            "val/box_loss": 1.57958,
            "val/cls_loss": 1.04986,
            "val/l1_loss": 1.32641,
            "fitness": 0.64104
        },
        "coco8-grayscale": {
            "metrics/precision(B)": 0.6582,
            "metrics/recall(B)": 0.51667,
            "metrics/mAP50(B)": 0.59106,
            "metrics/mAP50-95(B)": 0.33152,
            "val/box_loss": 1.95424,
            "val/cls_loss": 1.64059,
            "val/l1_loss": 1.70226,
            "fitness": 0.33152
        }
    },
    "save_dirs": {
        "coco8": "runs/detect/coco8",
        "coco8-grayscale": "runs/detect/coco8-grayscale"
    }
}

顶层的 fitness 是各数据集 fitness 值的算术平均值。对于单数据集调优，datasets 字典包含一个条目，其中 fitness 等于顶层的 fitness。每次完成的迭代都会记录一个 JSON 对象。实际的 save_dirs 路径是绝对路径；为便于阅读，上方对其进行了缩写。

tune_scatter_plots.png#

此文件包含根据 tune_results.ndjson 生成的散点图，帮助你直观了解不同超参数与性能指标之间的关系。变异使用每个超参数配置的范围，因此取值可以从 degrees 和 shear 等零值默认值开始变化。

• 格式：PNG
• 用途：探索性数据分析

weights/#

此目录包含调优运行中适应度最佳迭代所保存的 PyTorch 模型。这两个文件都来自同一次迭代：

• last.pt：last.pt 是训练最后一个 epoch 的权重。
• best.pt：best.pt 是达到最佳适应度分数的迭代所对应的权重。

利用这些结果，你可以为未来的模型训练和分析做出更明智的决策。

结论#

Ultralytics YOLO 中的超参数调优启动简单且功能强大，其底层使用基于适应度加权的选择机制和基于范围归一化的遗传算法变异。按照本指南介绍的循环操作，你可以系统地调优模型以获得更好的性能，然后重复使用生成的 best_hyperparameters.yaml 初始化后续训练运行。如需通过并行试验和更高级的搜索算法扩展调优，请继续阅读 Ray Tune 集成指南，或者通过 Ultralytics Platform 的云训练运行可配置超参数并实时跟踪指标的托管任务。

对于没有任何参数提供的设置，例如逐层学习率或自定义适应度指标，请改为继承 trainer。如需深入了解，请查看 Tuner 类的源代码。如果你有问题或功能请求，请通过 GitHub 或 Discord 联系我们。

常见问题#