mcpField
Y
yolo-tuning

yolo-tuning

github.com/ultralytics数据与数据库33114 次安装1 天前更新
代码仓库

关于 yolo-tuning

用于改进 Ultralytics YOLO 模型的指导技能，提供分阶段优化流程，并介绍内置遗传调参器和 Ray Tune。适合希望比较实验、并在处理数据与训练问题后再进行调参的从业者。

主要功能

  1. 01分阶段模型改进流程
  2. 02Platform 实验对比
  3. 03内置遗传超参数调节器
  4. 04Ray Tune 搜索与并行试验
  5. 05调参结果与验证指南

适用场景

  1. 01诊断过拟合或欠拟合
  2. 02比较候选训练运行
  3. 03修复数据后搜索超参数
  4. 04使用 Ray Tune 并行运行调参试验

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ultralytics/skills --skill yolo-tuning

安装后在 Claude Code 中输入/yolo-tuning确认已加载。

附带文件agents/openai.yaml

详细介绍

改进模型与超参数调优

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

超参数调优成本高，通常也不是瓶颈。请按以下顺序逐步处理，并在每一步后重新验证：

  1. 修复数据——检查 confusion_matrix.png 和 train_batch*.jpg，查找标签噪声；查看验证集图像中误报率最高的假阴性和假阳性；为效果不佳的类别和真实背景图像补充样本。数据质量比其他任何手段都重要。
  2. 延长训练时间——如果结束时验证集 mAP 仍在上升：增加 epochs，提高 patience。
  3. 增大输入尺寸——小目标较多，或 mAP50 远高于 mAP50-95：增大 imgsz（640 → 960/1280）。
  4. 使用更大的模型——欠拟合（训练集和验证集表现都平平）：n → s → m → l。
  5. 使用匹配领域的增强方式——航拍图像使用 degrees=180 flipud=0.5，拥挤场景使用 mixup=0.1（分割/OBB 还可加上 copy_paste=0.3），对颜色敏感的类别则降低 hsv_h（参见 yolo-training 的 training-args.md）。
  6. 到这时再调超参数——只有上述手段都已用尽时，调优才值得一试，通常可提升约 0.5–2 mAP。

决策信号：过拟合（训练集表现提升，验证集表现下降）→ 增加数据/增强，或使用更小的模型，而不是调优。欠拟合 → 使用更大的模型/延长训练，而不是调优。混淆矩阵中存在标签噪声 → 修复前，其他任何手段都无济于事。

在 Platform 中比较实验

将候选模型保存在同一个 Platform 项目 中。通过 New Model 对话框开始训练，让 Ask AI 运行并比较实验（AutoTrain），或设置 project=username/project-slug 和唯一的 name，将经过身份验证的本地运行记录同步到 Platform。在项目图表中同时选择多个模型，或使用 Table > Diff 比较训练参数和最终指标。

Platform 会跟踪并绘制实验图表；内置遗传调优器和下文的 Ray Tune 仅在 Python 中运行。比较结果确定胜出模型后，可将已完成的 Platform 模型用作下一个基础检查点，或下载其 .pt 文件。

内置遗传调优器

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 CLI 模式（MODES 为 train/val/predict/export/track/benchmark）。

  • 每次迭代 = 使用变异后的超参数进行一次完整的（短时）训练；适应度根据运行的验证指标计算。迭代会在内部设置 project，因此在 Python 3.11+ 中提供 API 密钥时，每次迭代都会上传到 Platform；取消设置密钥即可在本地调优。
  • 默认搜索空间：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) 表示的范围）： 
    model.tune(data="data.yaml", epochs=30, iterations=100, space={"lr0": (1e-5, 1e-2), "mosaic": (0.5, 1.0)})
  • 结果：runs/<task>/tune/——best_hyperparameters.yaml、tune_results.ndjson、适应度图表。使用这些值进行完整重训练，并设置 optimizer=AdamW（调优器的默认值）；optimizer=auto 会忽略调优后的 lr0 和 momentum。
  • 跨机器分布式调优：传入 mongodb_uri=（以及可选的 mongodb_db=、mongodb_collection=）——各工作进程通过 MongoDB 共享同一个结果池。

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

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= 默认值为 "optuna"；其他字符串选项包括 "ax"、"bayesopt"、"bohb"、"hebo"、"hyperopt"、"nevergrad"、"zoopt" 和 "random"，也可传入任意 Ray Tune 搜索器对象（BOHB 会将 ASHA 替换为 HyperBandForBOHB）。
  • 安装并启用 wandb 后（yolo settings wandb=True），W&B 会记录每次试验。如果有多块 GPU，想并行运行试验，或希望使用比遗传算法更智能的搜索方式，请使用 Ray；内置调优器更简单，且无需额外依赖。

演进最佳实践（“自动训练”方案）

  • 低成本搜索，高成本重训练：使用小模型（n/s）进行调优，并减少 epochs（约 30），设置 plots=False save=False val=False；然后使用最佳配置，以完整模型规模和训练轮数重新训练。
  • 预算：迭代次数 × 训练轮数 × 每轮耗时。对于遗传调优器而言，100–300 次迭代是超越默认配置的现实最低值。
  • 搜索期间保持 data 不变——更改数据会使此前所有适应度结果失效。
  • 只设定一个适应度目标：调优器会最大化验证集上的 fitness（检测任务为 mAP50-95(B)；分割和姿态任务会结合边界框与掩码/姿态的 mAP50-95）；在投入数天 GPU 时间前，请确认这与实际关注的指标一致。
  • 在 val 和 test 划分上检查最佳配置——迭代次数较多时，调优后的配置可能会对 val 划分过拟合。

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

评论

支持 Markdown