yolo-tuning

モデルの改善とハイパーパラメーターのチューニング

改善手順（順番に実施してください。チューニングは最後の手段です）

ハイパーパラメーターのチューニングはコストが高く、通常はボトルネックではありません。以下の順に進め、各手順の後に再検証してください。

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 で実験を比較する

候補は 1 つの Platform プロジェクトにまとめます。New Model ダイアログから学習するか、Ask AI に実験の実行と比較を依頼し（AutoTrain）、または project=username/project-slug と一意の name を設定して、認証済みのローカル実行をストリーミングします。プロジェクトのグラフでモデルをまとめて選択するか、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 です）。

• 各イテレーションでは、変異させたハイパーパラメーターで 1 回の短縮学習を行い、実行の検証指標から適合度を読み取ります。イテレーションでは内部的に 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 を介して 1 つの結果プールを共有できます。

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 でチューニングします。その後、最良の設定をフルサイズ/フルエポックで再トレーニングします。
• 予算: イテレーション数 × エポック数 × 1エポックあたりの時間。遺伝的チューナーがデフォルトを上回るには、100〜300イテレーションが現実的な最小値です。
• 探索中は data を固定してください。データを変更すると、それまでのすべての適応度が無効になります。
• 適応度の目標は1つ: チューナーは検証 fitness を最大化します（detect では mAP50-95(B)、segment と pose では box と mask/pose の mAP50-95 を組み合わせます）。GPU を何日も費やす前に、それが本当に重視したい指標と一致しているか確認してください。
• 勝者を val と test の両方の分割でサニティチェックしてください。イテレーション数が多いと、チューニング済みの設定が val 分割に過学習することがあります。

インストールされているバージョンが引数を拒否する場合（yolo checks でバージョンを確認できます）、このファイルよりもエラーメッセージと yolo cfg を信頼してください。