nemo-automodel-recipe-development

NeMo AutoModel レシピの開発

手順

レシピに関する質問には、実行に必要な最小限の手順をすべて含めて回答してください。

1. 該当するレシピファイルまたは YAML セクションを示します。
2. 関連するビルダー関数または設定キーを列挙します。
3. 設定方法について尋ねられた場合は、最小限の YAML またはコマンドの例を含めます。
4. ローカルでの検証コマンド、または CPU で実行可能な小さなテストで締めくくります。

概念的なレシピに関する質問には、ファイルの編集を求められない限り、このスキルだけを参照して回答してください。リポジトリを調べたり、ほかの AutoModel スキルを読み込んだりしないでください。回答は、レシピの YAML、ビルダー、CLI のルーティング、テスト、ローカルでの検証に絞ってください。

よくある質問には、次の簡潔な回答パターンを使用してください。

• 新しいファインチューニングレシピのバリエーション：nemo_automodel/recipes/ の下にある最も近いファイルを基に、モデル、データセットまたはデータローダー、オプティマイザー、損失、LR スケジューラー、ステップスケジューラー、チェックポイントビルダーを更新します。新しいレシピクラスを追加する場合に限り、レシピの別名を登録します。examples/ の下に YAML の例を追加し、CPU で実行可能な小さな単体テストを追加してから、automodel <config.yaml> を実行します。
• _target_ フィールド：_target_ は完全修飾された Python 呼び出し可能オブジェクトであると説明し、同じ階層にあるキーがキーワード引数になることを説明します。オプティマイザーとデータセットの例を示し、--optimizer.lr のようなネストされた CLI オーバーライドに触れます。
• 検証とチェックポイント：step_scheduler.val_check_interval、step_scheduler.checkpoint_interval、validation_dataset、restore_from.path、統合された safetensors を挙げ、このスキルにある最小限の YAML スニペットを含めます。

検証とチェックポイントについては、必ず次の項目を挙げてください。

• 検証の間隔には step_scheduler.val_check_interval を使用します。
• 保存の間隔には step_scheduler.checkpoint_interval を使用します。
• 検証データローダーのソースとして validation_dataset を使用します。
• 再開には restore_from.path を使用します。
• HF エコシステムとの互換性のため、統合された safetensors がデフォルトのチェックポイント形式です。

適用範囲

このスキルは、レシピの構築と実行フローに関する質問に使用してください。対象には、YAML 構造、_target_ 呼び出し可能オブジェクト、ビルダー関数、検証データセット、チェックポイント設定、CLI ルートの登録、レシピ固有のテストが含まれます。

分散ストラテジーの単独での選択、クラスターランチャーの設定、モデルアーキテクチャの導入には、このスキルを使用しないでください。ただし、ユーザーがそれらの選択肢を AutoModel レシピの YAML 内でどう指定するかを尋ねている場合は除きます。

レシピのアーキテクチャ

実行フロー

CLI (automodel config.yaml)
  -> app.py resolves the config's recipe target
    -> recipe script (e.g. train_ft.py) main(config_path)
      -> Recipe class .setup() builds all components
        -> .run_train_validation_loop() executes training

レシピクラス

レシピは BaseRecipe を継承し、次の 2 つのメソッドを実装します。

• setup() — ビルダー関数を使用して、モデル、オプティマイザー、データローダー、損失、LR スケジューラー、ステップスケジューラー、チェックポイント設定を構築します。
• run_train_validation_loop() — 学習と検証のループを実行します。

ビルダーパターン

すべてのコンポーネントは、専用のビルダー関数を使用して構築されます。

• build_model() — 設定からモデルをインスタンス化します
• build_optimizer() — オプティマイザー（AdamW など）を作成します
• build_dataloader() — 学習用および検証用のデータローダーをセットアップします
• build_loss_module() — 損失関数を作成します
• build_lr_scheduler() — 学習率スケジューラーを作成します
• build_step_scheduler() — 学習の進行を制御するステップスケジューラーを作成します
• CheckpointingConfig — チェックポイントを設定します（YAML の checkpoint: ブロックから RecipeConfig.checkpoint を介して直接構築されます）

インフラストラクチャの適用順序

構築後、コンポーネントは次の厳密な順序で適用されます。

1. PEFT（LoRA など）
2. FP8 量子化
3. QAT（量子化を考慮した学習）
4. チェックポイントの読み込み／復元
5. パラメーターの凍結
6. シャーディング（FSDP2、Megatron-FSDP、DDP）
7. デバイスへの配置
8. torch.compile
9. コンテキスト並列処理のフック

YAML 設定の構成

完全なレシピ設定は次の構造になります。

step_scheduler:
  max_steps: 1000
  num_epochs: 1
  grad_accumulation_steps: 4
  val_check_interval: 100
  checkpoint_interval: 500
  log_interval: 10

dist_env:
  master_addr: localhost
  master_port: 29500

rng:
  seed: 42

model:
  _target_: nemo_automodel.NeMoAutoModelForCausalLM.from_pretrained
  pretrained_model_name_or_path: meta-llama/Llama-3.2-1B
  dtype: float32
  # additional model kwargs passed to the constructor

compile:
  enabled: false
  backend: inductor

clip_grad_norm:
  max_norm: 1.0

distributed:
  strategy: fsdp2       # fsdp2 | megatron_fsdp | ddp
  dp_size: auto
  tp_size: 1
  cp_size: 1

loss_fn:
  _target_: torch.nn.CrossEntropyLoss

dataset:
  _target_: nemo_automodel.datasets.squad.SquadDataset
  tokenizer_name_or_path: meta-llama/Llama-3.2-1B
  max_seq_length: 2048

validation_dataset:
  _target_: nemo_automodel.datasets.squad.SquadDataset
  split: validation

packed_sequence:
  enabled: false

dataloader:
  batch_size: 4
  num_workers: 4
  pin_memory: true

optimizer:
  _target_: torch.optim.AdamW
  lr: 2.0e-5
  weight_decay: 0.01

lr_scheduler:
  _target_: nemo_automodel.schedulers.CosineAnnealingWarmup
  warmup_steps: 50
  min_lr: 1.0e-6

全パラメーター学習の精度

torch.optim.Adam／AdamWを使用した新規の全パラメーター学習では、fp32 のマスタ重みと Adam のモーメントを使用するため、NeMoAutoModelローダーでmodel.dtype: float32を明示的に設定してください。計算精度は別途設定します（FSDP2：distributed.mp_policy）。

PEFT、TE FusedAdam、拡散モデルでは、それぞれ別の精度設定が必要です。混合精度ガイドを参照してください。既存の設定を移行する場合は、メモリ、学習動作、チェックポイントからの再開を検証してください。

_target_パターン

_target_キーでは、完全修飾された Python 呼び出し可能オブジェクトを指定します。そのセクションの残りのキーはすべて、キーワード引数として渡されます。

optimizer:
  _target_: torch.optim.AdamW   # callable
  lr: 2.0e-5                    # kwarg
  weight_decay: 0.01            # kwarg

これはtorch.optim.AdamW(lr=2e-5, weight_decay=0.01)と同等です。

CLI オーバーライド

設定値はすべてコマンドラインからオーバーライドできます。

automodel config.yaml \
  --optimizer.lr 1e-4 \
  --step_scheduler.max_steps 500 \
  --distributed.tp_size 2

例

検証とチェックポイント保存：

step_scheduler:
  val_check_interval: 100
  checkpoint_interval: 500

validation_dataset:
  _target_: nemo_automodel.datasets.squad.SquadDataset
  split: validation

restore_from:
  path: /checkpoints/step-500

ドメイン固有の注意事項

LLM

• nemo_automodel/recipes/llm/train_ft.pyは、ファインチューニングと事前学習の両方を処理します。両者の違いは設定（データセット、学習率など）で決まります。
• nemo_automodel/recipes/llm/kd.pyは、教師モデルと生徒モデルを使った知識蒸留を実装します。
• nemo_automodel/recipes/llm/benchmark.pyは、スループットとレイテンシのベンチマークを実行します。

VLM

• 因果 LM クラスの代わりにNeMoAutoModelForImageTextToTextを使用します。
• 設定には、単独のトークナイザーではなくprocessorセクションが含まれます。
• レシピはnemo_automodel/recipes/vlm/finetune.pyにあります。

拡散モデル

• NeMoAutoDiffusionPipelineを使用します。
• 並列化を定義するため、設定にparallel_scheme辞書が必要です。
• DDP と FSDP2 のストラテジーのみをサポートします（Megatron-FSDP はサポートしません）。
• レシピはnemo_automodel/recipes/diffusion/train.pyにあります。

検索

• エンコーダーのパターンは2種類あります。
  • バイエンコーダー（nemo_automodel/recipes/retrieval/train_bi_encoder.py）：クエリと文書に別々のエンコーダーを使い、対照損失を適用します。
  • クロスエンコーダー（nemo_automodel/recipes/retrieval/train_cross_encoder.py）：結合してエンコードし、分類ヘッドを使用します。
• ハードネガティブマイニング：nemo_automodel/recipes/retrieval/mine_hard_negatives.py。

学習ループの詳細

学習ループは、各エポックで次の構造に従います。

for epoch in range(num_epochs):
    for batch_idx in range(batches_per_epoch):
        # --- gradient accumulation inner loop ---
        for micro_batch in micro_batches:
            if pipeline_parallel:
                schedule.step(micro_batch)    # PP schedule
            else:
                loss = model(micro_batch)     # direct forward
                loss.backward()

        # --- optimizer step ---
        scale_grads_and_clip_grad_norm(model, max_norm)
        optimizer.step()
        lr_scheduler.step()
        optimizer.zero_grad()

        # --- logging ---
        MetricsSample(step, epoch, loss, grad_norm, lr, mem, tps, mfu)

        # --- validation (at configured intervals) ---
        if step % val_check_interval == 0:
            run_validation()

        # --- checkpoint (at configured intervals) ---
        if step % checkpoint_interval == 0:
            save_checkpoint()

StepScheduler

学習の進行全体を制御します。エポック数、ステップ数、勾配蓄積ステップ数、検証間隔、チェックポイント間隔、ログ出力間隔を管理します。

勾配クリッピング

バックワードパスの後、オプティマイザーステップの前にscale_grads_and_clip_grad_norm()を使って適用します。設定ではclip_grad_norm.max_normで制御します。

コンテキスト並列化

cp_size > 1の場合、make_cp_batch_and_ctx()を使ってバッチをコンテキスト並列グループ間で分割します。これはフォワードパスの前に行う必要があります。

MetricsSample

各学習ステップでは、次のフィールドを持つMetricsSampleが生成されます。

• step -- グローバルステップ数
• epoch -- 現在のエポック
• loss -- 学習損失
• grad_norm -- クリッピング後の勾配ノルム
• lr -- 現在の学習率
• mem -- GPU メモリ使用量
• tps -- 1秒あたりのトークン数
• mfu -- モデル FLOPS 使用率

検証とチェックポイント保存

検証

• step_scheduler.val_check_intervalで定義された間隔で実行します。
• validation_dataset設定から構築された検証データローダーを使用します。
• モデルを評価モードに設定し、勾配を無効にします。

チェックポイント保存

• デフォルトの形式は、HF エコシステムへのデプロイを容易にする統合済み safetensors です（DCP より常にこちらを優先してください）。
• チェックポイントの保存間隔はstep_scheduler.checkpoint_intervalで制御します。
• チェックポイントディレクトリを指すrestore_from設定キーを使って、学習を再開します。

restore_from:
  path: /checkpoints/step-500

よくある問題

問題	原因	対処方法
設定エラーが通知されない	_target_ の値の入力ミス	クラスパスが、有効でインポート可能な Python 呼び出し可能オブジェクトである必要があります。モジュールパスとクラス名を再確認してください。
トレーニングの最初のステップでクラッシュする	global_batch_size が local_batch_size * dp_size * grad_accumulation_steps で割り切れない	すべての次元でバッチサイズの計算に整合性があることを確認してください。
新しいレシピを CLI から利用できない	設定に解決可能な recipe ターゲットがない	設定の recipe キーに、検出可能なレシピのクラス名または完全なドット区切りの _target_ パスを設定してください。
順伝播時に形状が一致しない	データセットの照合関数の出力がモデルの入力シグネチャと一致しない	照合関数が、モデルの想定するキーと形状を持つテンソルを返すことを確認してください。
検証中に OOM が発生する	検証バッチサイズが大きすぎる、または勾配が無効化されていない	検証を torch.no_grad() で囲み、検証バッチサイズを小さくすることを検討してください。
チェックポイントの復元に失敗する	チェックポイントと設定でモデルアーキテクチャが一致しない	モデル設定がチェックポイントと完全に一致することを確認してください（レイヤー数、隠れ層の次元、語彙サイズ）。