yolo-training

トレーニングとファインチューニング

最速のルート: Platform でトレーニングする

ローカルの GPU を設定せずに数クリックで始めたい場合は、Platform クラウドトレーニングを使用してください:

1. プロジェクトページで New Model をクリックするか、データセットページでクリックしてそのデータセットを事前選択します。
2. 互換性のある事前学習済みモデル、準備済みデータセット、GPU、エポック数、画像サイズ、バッチサイズを選択します。
3. Start Training をクリックし、ライブチャート、コンソールログ、システムメトリクスを確認します。
4. 完了したモデルを開いて検証プロットを確認し、その Predict、Export、Deploy タブを使用します。Platform は best.pt を自動的に保持します。

クラウドジョブには、少なくとも 1 つの train 画像、1 つの val/test 画像、1 つのラベル付き画像が必要です。すでにコンピュートがある場合や、より細かい制御が必要な場合は、Platform のデータセットと実験トラッキングを活用しながら、ローカル/Colab トレーニングを使用してください:

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

Python 3.11 以降で ultralytics>=8.4.120 を使用すると、ul:// URI が Platform データセットをダウンロードし、API キーが利用可能な間（ULTRALYTICS_API_KEY または api_key 設定）、任意の project= 値 — ローカルフォルダであっても — がメトリクスをストリーミングし、重みを Platform にアップロードします。実行をローカルに保つには project を省略します。リスト形式の data= は内部的にこれを設定するため、そのような実行ではキーを未設定にしてください。

クイックスタート（検出）

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)

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

クラス数の変更は自動です — 80 クラスの事前学習済みモデルで 3 クラスの data.yaml がそのまま機能します（ヘッドが再初期化され、バックボーンが転送されます。cls_remap=True は名前が一致するクラスについてヘッドの行も再マッピングします）。

設定する価値のある基本引数（タスクトレーナーはこれらを上書きできます）

引数	デフォルト	備考
epochs	100	ファインチューニングには 100～300。推測に頼らず、早期停止を利用してください
patience	100	早期停止までの val 改善がないエポック数。素早い反復には ~20～50
imgsz	task/model	グローバルフォールバックは 640。classify は未設定時に 224 を使用。明示的な値が優先されます
batch	16	-1 は VRAM の約 60% を自動適合（単一 GPU）。0.8 のような float は VRAM の割合。それ以外は整数
device	None	0、[0,1]（DDP）、cpu、mps、-1 はアイドル状態の GPU を選択
cache	False	I/O バウンドのトレーニングには True（RAM）または "disk"
workers	8	RAM／共有メモリのエラーが出る場合は下げてください
freeze	None	小規模データセット向けに最初の N 層を凍結（freeze=10 ≈ バックボーン）
optimizer	auto	auto のままにしてください（10k イテレーション超では MuSGD、それ以外は AdamW）。depth ファインチューニングでは以下で上書きされます
lr0 / lrf	0.01 / 0.01	lr0 は optimizer=auto では無視されます。使用するには明示的なオプティマイザを設定してください（depth レシピを参照）
fraction	1.0	サブセットトレーニング — スモークテストには fraction=0.1
resume	False	中断された実行を継続します（レシピを参照）
project/name	None	出力フォルダ: 相対 project → runs/<task>/<project>/<name>、絶対 → <project>/<name>。Python 3.11+ で API キーが利用可能な場合、任意の project は Platform にアップロードされます
seed	0	deterministic=True（デフォルト）で再現可能
compile	False	torch.compile。"max-autotune-no-cudagraphs" なども可
time	None	最大トレーニング時間 — epochs を上書きします
引数、拡張、損失重みの完全な表: training-args.md（このフォルダー内）— 上記に記載されていないものを変更する前に必ずお読みください。yolo cfg は基本スキーマとデフォルト値を表示します。タスクトレーナー、チェックポイント、明示的な引数が実際の有効値を決定します。

レシピ

• 中断した実行の再開: YOLO("runs/detect/train/weights/last.pt").train(resume=True)。再開は元の epochs を完了させます。完了後にさらに長く学習するには、best.pt から新規に学習を開始してください（再開は完了済みの実行を延長できません）。
• マルチ GPU: 整数の batch とともに device=[0,1] を使用します（AutoBatch はシングル GPU 専用です）。DDP ワーカーは、トレーナー、モデル、コールバックを cloudpickle する生成スクリプトから再構築されます。公式の Windows 向け PyTorch>=2.4 ホイールは DDP を起動できないため、Linux または WSL2 を使用してください。
• 小規模な detect 形式のデータセット（約 1k 枚未満）: 事前学習済み + freeze=10、n/s モデル、デフォルトの拡張、val 曲線を注視します。
• depth のファインチューニング: -depth.pt から開始し、optimizer=AdamW lr0=1e-4 warmup_bias_lr=1e-4 を使用します。
• 小さなオブジェクト: imgsz=1280 を試してください（計算量/VRAM が増えるため、必要に応じて batch を減らします）。またはデータセットレベルで大きな画像をタイル分割します。
• 実験の衛生管理: 自己記述的な実行名（name=0811_yolo26s_helmets_e100）、1 回の実行につき 1 つの変数。各実行の完全な設定は runs/<task>/<name>/args.yaml に保存されます — これらを diff して実行を比較してください。
• ロギング連携: yolo settings tensorboard=True（同様に wandb）、その後は通常どおり学習します。mlflow、comet、clearml はデフォルトで有効で、パッケージをインストールするとアクティブになります。
• 知識蒸留: distill_model=yolo26l.pt dis=6.0 は、より大きな教師モデルで生徒モデルを学習します。

検証

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

タスクごとの主要指標: detect/obb は mAP50-95(B)、segment は (M)、pose は (P)、semantic は mIoU、depth は delta1、classify は accuracy_top1。Val の基本デフォルトは conf=0.001（OBB は 0.01）、iou=0.7、nms=None（one-to-many ヘッド + NMS）です。nms=False は YOLO26 の NMS フリーヘッドを検証し、この場合 iou は無効です。テストセットには split=test を、COCO 形式の評価には save_json=True を使用してください。

完了した実行の読み方（runs/<task>/<name>/）

• weights/best.pt — 最高の val fitness。これを使用してください。last.pt — 再開用です。
• results.csv / results.png — エポックごとの損失と val 指標。解釈: train 損失が ↓ なのに val mAP が頭打ちになった後 ↓ = 過学習（データ/拡張を増やし、より小さなモデルに — best.pt はすでに良いチェックポイントを保持しています）。両方とも横ばいで低い = 過少学習（より大きなモデル、より多くのエポック、より高い imgsz、ラベルを確認）。mAP50 は良好だが mAP50-95 が悪い = ずさんな位置特定（より高い imgsz、より良いボックス）。
• train_batch*.jpg — ラベルが描画された拡張画像。プロジェクトごとに一度は目を通してください: 誤ったラベルはここで即座に分かります。
• confusion_matrix.png — 2 つのクラス間の非対角のクラスター = 一貫性のないラベル、または本質的に類似したクラス。軸は予測（y）× 真値（x）: background の行が大きい = 検出漏れ（そのクラスにはより多く/より良い例が必要）; background の列が大きい = 誤検出（背景画像を追加するか、推論時に conf を上げる）。

トラブルシューティング

症状	対処法（順番どおりに）
CUDA のメモリ不足	batch を下げる（または batch=-1）、imgsz を下げる、より小さいモデルを使う。VRAM を占有しているゾンビの 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 を受け入れてください
Dataloader が遅い / GPU がアイドル状態	cache=True/"disk"、workers を増やす、データを SSD に置く
実行途中で val メトリクスがゼロになる	val スプリットからクラスが欠落しています

アンチパターン：「きちんと学習させるため」に pretrained=False を使う（約 100 倍のデータが必要です）。50 枚の画像でモデルサイズをベンチマークする。30 個の引数が並んだコマンドをコピーする（デフォルトから始めてください）。混同行列がラベルノイズを訴えているのにハイパーパラメータをチューニングする。

関連ページ

• training-args.md — train／augmentation／loss-weight 引数の完全な表。上記の表にない引数を設定する前に読んでください。

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