nemo-automodel-recipe-development

NeMo AutoModel のレシピ開発

手順

レシピに関する質問には、実行に必要な最小限の完全な手順で回答します。

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

概念的なレシピに関する質問には、ファイルの編集を依頼された場合を除き、リポジトリを調査したり、ほかの AutoModel スキルを読み込んだりせず、このスキルに基づいて回答します。レシピ YAML、ビルダー、CLI のルーティング、テスト、ローカルでの検証に焦点を絞ります。

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

• 新しいファインチューニングレシピのバリエーション：nemo_automodel/recipes/ の下にある最も近いファイルをベースにし、モデル、データセットまたはデータローダー、オプティマイザー、損失関数、LR スケジューラー、ステップスケジューラー、チェックポイントビルダーを更新します。コマンドまたはドメインエイリアスを追加する場合に限り CLI ルートを登録し、examples/ に YAML の例を追加してから、CPU で実行できる小さな単体テストを追加し、automodel finetune llm -c <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 finetune llm -c config.yaml)
  -> app.py parses command + domain + config
    -> 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_fn() -- 損失関数を作成します
• build_lr_scheduler() -- 学習率スケジューラーを作成します
• build_step_scheduler() -- トレーニングの進行を制御するステップスケジューラーを作成します
• build_checkpoint_config() -- チェックポイントを設定します

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

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

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.models.llm.NemotronHForCausalLM
  name_or_path: meta-llama/Llama-3.2-1B
  # 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

_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 Overrides

コマンドラインから任意の設定値を上書きできます。

automodel finetune llm -c 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 にあります。

Diffusion

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

Retrieval

• エンコーダーのパターンは 2 種類あります。
  • Bi-encoder（nemo_automodel/recipes/retrieval/train_bi_encoder.py）：クエリーとドキュメントに別々のエンコーダーを使用し、対照損失を適用します。
  • Cross-encoder（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 から利用できない	CLI コマンドエイリアスの登録漏れ	CLI アプリに新しいルートを登録し、automodel <command> <domain> で正しく解決されるようにしてください。
フォワードパスで形状が一致しない	データセットの collate 関数の出力がモデルの入力シグネチャと一致しない	collate 関数が、モデルの想定するキーと形状のテンソルを返すことを確認してください。
検証中に OOM が発生する	検証バッチサイズが大きすぎる、または勾配が無効になっていない	検証を torch.no_grad() で囲み、検証バッチサイズを小さくすることを検討してください。
チェックポイントの復元に失敗する	チェックポイントと設定の間でモデルアーキテクチャが一致しない	モデル設定がチェックポイントと完全に一致すること（レイヤー数、隠れ次元、語彙サイズ）を確認してください。