nemotron-retrieval-recipes

Nemotron Retrieval Recipes

呼び出し方法：$nemotron-retrieval-recipes。

目的

このスキルは、ソースのチェックアウトまたはインストール済みパッケージで、公開されている Nemotron の埋め込みおよび再ランキングの検索レシピを扱うために使用します。レシピ CLI、設定、コンテナ、出力パスは頻繁に変更されているため、記憶よりも現在のチェックアウトを優先してください。レシピディレクトリと対応する CLI ファイルが存在する場合に限り、そのレシピファミリーを利用可能とみなしてください。

これは一般公開向けの製品スキルであり、コントリビューター専用のガイダンスではありません。静的なドキュメントと比べて、検索の失敗を適切なレシピファミリーに振り分け、ドキュメントと現在のチェックアウトとの食い違いを解消し、意図しない長時間の処理の起動を避け、シークレットを保護し、具体的なプレビュー、実行、実行レポート用のコマンドを提示できることが、このスキルの価値です。

公開されている Nemotron の embed または rerank のレシピフローに関係するタスクに限って使用してください。検索理論全般、汎用的なベクトルデータベースの選定、汎用的なベンチマークのアドバイス、レシピ以外の Docker／Slurm／NIM のトラブルシューティングに関する依頼の場合は、対象範囲について簡潔に伝えて、そのターンではレシピファイルを確認しないでください。

セキュリティに関する注意事項

リポジトリの範囲内での確認、ヘルプの表示、ドライラン、ユーザーが承認した実行コマンドには Bash を使用してください。ユーザーから明示的な依頼がない限り、API、GPU、Docker、Slurm、NIM、その他の長時間処理を実行しないでください。どちらのファミリーでもステージ 0 の SDG を実行する前に、コーパスの内容を設定済みの推論エンドポイントに送信することが、ユーザーのデータガバナンスポリシーで許可されているか確認してください。許可されていない場合は、承認済みのプライベートまたはエアギャップ環境のパスを使用してください。広範な環境情報のダンプや、シークレット値が露出するコマンドは決して実行しないでください。レシピのデフォルトを編集するより、dotlist によるオーバーライドと設定の確認を優先してください。

情報源の優先順位

競合がある場合は、次の順で優先してください。

1. 現在のチェックアウトにあるレシピ、CLI、設定、ソースファイル。
2. このスキルに同梱されているリファレンス。
3. ユーザーが提供したドキュメントまたは保存済みのスニペット。
4. 記憶。

実行可能なコマンドについては、現在のチェックアウトを信頼できる情報源としてください。必要なレシピディレクトリ、CLI コマンド、設定、または環境プロファイルが存在しない場合は、推測せずに阻害要因として報告してください。

前提条件

• リポジトリ環境：uv sync --all-extras、またはチェックアウトで説明されている関連最小限のエクストラ。
• ステージ 0 の SDG：NVIDIA_API_KEY。シークレット値を貼り付けるようユーザーに求めてはいけません。
• ステージ 1～3 の GPU 処理：CUDA／NVIDIA ドライバーが利用可能であること、および十分な VRAM。
• ステージ 4 のエクスポート：TensorRT を使用する場合は NeMo Export-Deploy コンテナが必要です。デフォルトの Nemotron 3 Embed プロファイルでは、意図的にエクスポートをスキップします。
• ステージ 5 のデプロイ：Docker。デフォルトの Nemotron 3 Embed では、backend=vllm を使用したチェックイン済みの vLLM パス、または backend=nim を使用した互換性のある NEMOTRON3_EMBED_NIM_IMAGE を利用できます。Llama Embed と rerank のデプロイでは、NGC アクセスと NGC_API_KEY が必要になる場合があります。
• リモート実行：--run または --batch にはルートの env.toml プロファイルが必要です。リモートスケジューリング、ログ、GPU の割り当てが関係する場合は、references/remote.md を読み込んでください。

手順

1. レシピファミリーを特定します。
   • 埋め込み、embed、バイエンコーダー、ベクトル検索、第 1 段階の検索、低い Recall@k、関連文書の欠落、NIM embeddings、または nemotron embed の場合は、references/embed.md を使用します。
   • リランク、リランカー、クロスエンコーダー、第 2 段階の検索、再現率は許容範囲だが上位の順位付けが悪い場合、Recall は良好だが nDCG が低い場合、または nemotron rerank の場合は、references/rerank.md を使用します。
   • ユーザーが両方のファミリーについて尋ねている場合、またはどちらのファミリーを選ぶべきか尋ねている場合に限り、両方のリファレンスを使用します。
2. embed では、ステージコマンドを作成する前にモデルプロファイルを 1 つ選択します。
   • 要求されたモデルが不明な場合は、uv run nemotron embed info を実行します。
   • nvidia/Nemotron-3-Embed-1B-BF16 には -c default を使用します。
   • nvidia/llama-nemotron-embed-1b-v2 とそのエクスポートパスには -c llama を使用します。
   • 選択したプロファイルと artifact_root をすべてのステージで引き継ぎます。2 つのプロファイルのアーティファクトを決して組み合わせないでください。
3. 検索の失敗モードに基づいて、調整するモデルファミリーを選択します。
   • 関連文書が候補セットに含まれていない場合は、埋め込みのファインチューニングを優先します。
   • 関連文書は検索されているものの、上位の順位付けが悪い場合は、リランカーのファインチューニングを優先します。
   • 本番環境の検索スタックでは、これらは相互補完的であることを念頭に置きます。まず埋め込みを行い、次に候補をリランクします。
4. 目的を特定します。実行計画の作成、ステージの実行、失敗のデバッグ、ハイパーパラメーターの調整、メトリクスの解釈、モデルのエクスポート／デプロイ、設定の確認、またはドットリストによるオーバーライドの提案です。
5. 対応する前に、現在の公開インターフェイスを確認します。
   • レシピファイル：src/nemotron/recipes/<embed|rerank>/
   • CLI ファイル：src/nemotron/cli/commands/<embed|rerank>/
   • 設定ファイル：src/nemotron/recipes/<family>/stage*/config/<profile>.yaml
   • ヘルプとドライラン：uv run nemotron <family> --help、uv run nemotron <family> <stage> -c <profile> -d

安全なワークフロー

1. タスクに関連するコンテキストのみを収集します。レシピの種類、選択したプロファイル、コーパスのパス、既存の SDG／トレーニング／評価データ、対象ステージの範囲、アーティファクトのルート、チェックポイントのパス、実行モード、GPU ID、必要なシークレットが設定済みかどうかを確認します。シークレットの値を貼り付けるようユーザーに求めてはいけません。
2. コストの低い確認から始めて、コストの高い作業は後にします。
   • uv run nemotron <family> --help
   • uv run nemotron <family> <stage> --help
   • uv run nemotron <family> <stage> -c <profile> -d
   • uv run nemotron <family> run -c <profile> -d --from <stage> --to <stage>
   • run --help では、継承された -c および -d オプションが表示されないことがありますが、run -c default -d ... は動作します。不明な場合は、ドライランを実行して確認してください。
   • すでに準備済みのチェックアウトでは、読み取り専用の確認中に予期しない依存関係の同期を避けるため、uv run --no-sync ... --help または uv run --no-sync ... -d を使用できます。
3. 要求されたステージの前提条件を確認します。
   • リポジトリ環境：uv sync --all-extras、またはリポジトリのドキュメントに記載があれば、関連する最小限のエクストラを使用します。
   • ステージ 0 の SDG：NVIDIA_API_KEY。
   • ステージ 1〜3 の GPU 作業：CUDA／NVIDIA ドライバーが利用可能であることと、十分な VRAM があること。
   • ステージ 4 のエクスポート：TensorRT を使用する場合は、NeMo Export-Deploy コンテナが必要です。Nemotron 3 Embed のデフォルト設定では、このステージはスキップされます。
   • ステージ 5 のデプロイ：Docker に加え、選択したバックエンドのイメージとアーティファクトの契約が必要です。Nemotron 3 のデフォルト設定では、NGC 認証情報なしでチェックイン済みの vLLM イメージを使用できます。NGC 認証情報を必須とする前に、対象ファミリーのリファレンスを読み込んでください。
   • リモート実行：--run または --batch では、ルートの env.toml プロファイルが必要です。リモートのスケジューリング、ログ、GPU の割り当てが関係する場合は、references/remote.md を読み込んでください。
4. ユーザーが再利用可能な設定変更を求めていない限り、デフォルト設定を編集する代わりにドットリストのオーバーライドを使用します。選択したプロファイル、アーティファクトのルート、シーケンス長、プレフィックス、プーリング／正規化、プロンプトテンプレート、ハードネガティブの件数が、全ステージで一貫するようにします。
5. ユーザーから明示的に実行を依頼されていない限り、API、GPU、Docker、Slurm、NIM、または長時間実行されるジョブを開始しないでください。まず、ドライラン、設定のレビュー、小規模なパイロットを提案するか、実行します。
6. ローカル実行では、CUDA_VISIBLE_DEVICES=<ids> を指定して、要求された GPU ID の使用範囲を限定します。--run または --batch では、選択した env.toml プロファイルで gpus_per_node などのスケジューラーリソースを設定し、スケジューラーにデバイスを割り当てさせます。送信シェルの CUDA_VISIBLE_DEVICES がリモートにも引き継がれると想定してはいけません。
7. 複数ステージのローカル実行では、uv run nemotron <family> run -c <profile> --from <stage> --to <stage> を優先します。rerank には default を使用します。デフォルトの run ターゲットは eval で終了します。export と deploy はオプトインです。
8. 品質を評価する際は、デプロイを推奨する前に、固定したホールドアウト評価セットでベースモデルと比較します。レシピ独自のステージ 3 の評価を、単独の公開ベンチマーク評価で代用してはいけません。
9. 長時間実行される SDG、prep、finetune、または eval の作業では、セッションが切れても安全な方法でプロセスを開始し、人間が確認しやすい間隔でポーリングします。小規模なパイロットではおよそ 60 秒、大規模な実行では 120〜300 秒を目安にします。
10. 失敗が発生した場合は、まず失敗したステージを特定し、そのステージの設定、想定される入力、出力ディレクトリ、対応する CLI ラッパーまたは run_uv.py を確認します。

リファレンス

• references/embed.md：埋め込みレシピのステージ、コマンド、デフォルト設定、出力パス、運用パターン。
• references/rerank.md：rerank レシピのステージ、コマンド、デフォルト設定、出力パス、運用パターン。
• references/evaluation.md：指標の解釈、比較時の注意点、デプロイ準備状況の確認。
• references/remote.md：リモート実行プロファイル、バッチ／実行モード、GPU の範囲指定、ログ、ポーリング。

例

ユーザーの依頼：「Recall はまずまずですが、nDCG が低く、適切なパッセージは 40 位あたりです。embed と rerank のどちらを調整すべきでしょうか？」

references/rerank.md と references/evaluation.md を読み込み、Recall は許容できる一方で上位の順位付けが良くない場合は、リランカーの調整が適していると説明してから、トレーニング前に低コストのプレビューを提案します。

uv run nemotron rerank run -c default -d --from prep --to eval

トラブルシューティング

失敗したステージを特定し、そのステージの設定、想定される入力、出力ディレクトリ、対応する CLI ラッパーまたは run_uv.py を確認してください。

制限事項

• 同梱されている参照資料は要約されたスナップショットです。実行前に、アクティブなチェックアウトでコマンド、フラグ、デフォルト値、出力パスを確認してください。
• このスキルは、データセット、チェックポイント、認証情報、GPU リソース、Docker イメージ、NIM サービスを提供しません。

出力スタイル

計画やデバッグの推奨事項では、必要に応じて次の形式を使用してください：Decision、Why、Required inputs、Preview command、Execution command、Avoid、Next step。短い回答に関係のない項目は省略してください。

具体的なコマンドとファイルパスを示してください。前提条件、想定される入力、想定される出力、および次の作業を開始できる状態だと確認するための最も手軽な検証手順を明記してください。実行時間の長いステージでは、プレビュー用コマンドと実行用コマンドを分け、ユーザーが意図をもって選択できるようにしてください。

ドライランまたは実際の実行を報告する際は、簡潔な実行レポートを含めてください。レポートには、コマンド、モード、設定、dotlist オーバーライド、入力パス、出力パス、検証シグナルまたはメトリックファイル、次に実行する最も手軽な確認手順を記載してください。チェックアウトのコミットが確認できる場合は、それも含めてください。