nemotron-retrieval-recipes

Nemotron Retrieval Recipes

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

目的

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

これは一般公開されている製品スキルであり、コントリビューター専用のガイダンスではありません。静的なドキュメントに対するこのスキルの利点は、ユーザーの検索失敗を適切なレシピファミリーに振り分け、ドキュメントと現在のチェックアウトの内容を照合し、意図せず長時間実行される処理を避け、シークレットを保護し、具体的なプレビュー、実行、実行レポートのコマンドを提示できることです。

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

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

リポジトリ内の調査、ヘルプの表示、ドライラン、ユーザーが承認した実行コマンドには Bash を使用してください。ユーザーから明示的に依頼されない限り、API、GPU、Docker、Slurm、NIM、その他の長時間実行される処理を実行しないでください。環境全体を広範囲にダンプするコマンドや、シークレットの値を露出させるコマンドは絶対に実行しないでください。レシピのデフォルト設定を編集するより、ドットリスト形式のオーバーライドと設定の確認を優先してください。

情報源の優先順位

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

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

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

前提条件

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

手順

1. レシピファミリーを特定します。
   • 埋め込み、embed、バイエンコーダー、ベクトル検索、初段の検索、低い Recall@k、関連ドキュメントの欠落、NIM embeddings、または nemotron embed については、references/embed.md を使用してください。
   • rerank、リランカー、クロスエンコーダー、二段目の検索、再現率は許容範囲でも上位の順位付けが不適切な場合、Recall は良好でも nDCG が低い場合、または nemotron rerank については、references/rerank.md を使用してください。
   • ユーザーが両方のファミリーについて尋ねている場合、またはどちらのファミリーを選ぶべきか尋ねている場合にのみ、両方のリファレンスを使用してください。
2. 検索失敗のパターンから、調整するモデルを選びます。
   • 関連ドキュメントが候補セットに含まれていない場合は、埋め込みのファインチューニングを優先してください。
   • 関連ドキュメントは検索されるものの、上位の順位付けが適切でない場合は、リランカーのファインチューニングを優先してください。
   • 本番環境の検索スタックでは、両者は相互補完的であることを忘れないでください。まず埋め込みを行い、次に候補をリランキングします。
3. 意図を特定します。実行の計画、ステージの実行、失敗のデバッグ、ハイパーパラメーターの調整、メトリクスの解釈、モデルのエクスポート／デプロイ、設定の確認、またはドットリスト形式のオーバーライドの提案のいずれかです。
4. 実行する前に、現在公開されているインターフェイスを確認します。
   • レシピファイル：src/nemotron/recipes/<embed|rerank>/
   • CLI ファイル：src/nemotron/cli/commands/<embed|rerank>/
   • デフォルト設定：src/nemotron/recipes/<family>/stage*/config/default.yaml
   • ヘルプとドライラン：uv run nemotron <family> --help、uv run nemotron <family> <stage> -c default -d

安全なワークフロー

1. タスクに関連するコンテキストのみを収集します。コーパスのパス、既存の SDG／トレーニング／評価データ、対象ステージの範囲、出力ディレクトリ、チェックポイントのパス、実行モード、GPU ID、必要なシークレットが設定済みかどうかを確認します。シークレットの値を貼り付けるようユーザーに求めないでください。
2. 費用のかかる作業の前に、負荷の小さいチェックを行います。
   • uv run nemotron <family> --help
   • uv run nemotron <family> <stage> --help
   • uv run nemotron <family> <stage> -c default -d
   • uv run nemotron <family> run -c default -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～4 の GPU 作業：CUDA／NVIDIA ドライバーが利用可能で、十分な VRAM があること。
   • ステージ 4 のエクスポート：TensorRT を使用する場合は NeMo Export-Deploy コンテナー。
   • ステージ 5 のデプロイ：Docker、NGC へのアクセス、NGC_API_KEY。
   • リモート実行：--run または --batch 用のルート env.toml プロファイル。リモートスケジューリング、ログ、GPU の割り当てが関係する場合は、references/remote.md を読み込みます。
4. ユーザーが再利用可能な設定変更を求めない限り、デフォルト設定を編集せず、ドットリスト形式のオーバーライドを使います。シーケンス長、プレフィックス、プーリング／正規化、プロンプトテンプレート、ハードネガティブ数を全ステージで一貫させます。
5. ユーザーから明示的に実行を依頼されない限り、API、GPU、Docker、Slurm、NIM、または長時間実行されるジョブを起動しないでください。まず、ドライラン、設定レビュー、小規模なパイロットを提案するか、実行します。
6. ユーザーが GPU ID を指定した場合は、すべてのステージコマンドを CUDA_VISIBLE_DEVICES=<ids> で指定した GPU のみに制限します。
7. 複数ステージにわたるローカル実行では、uv run nemotron <family> run -c default --from <stage> --to <stage> を優先します。run のデフォルトの対象は eval までです。export と deploy はオプトインです。
8. 品質を評価する際は、デプロイを推奨する前に、固定のホールドアウト評価セットでベースモデルと比較します。レシピ独自のステージ 3 評価を、単独の公開ベンチマーク評価で代用しないでください。
9. SDG、prep、finetune、eval を長時間実行する場合は、セッションが切れても実行を継続できる方法でプロセスを開始し、人間にとって確認しやすい間隔で状態を確認します。小規模なパイロットではおよそ 60 秒、大規模な実行では 120～300 秒を目安にします。
10. 失敗が発生した場合は、まず PITFALLS.md を読み込み、失敗したステージを特定します。その後、ステージ設定、想定される入力、出力ディレクトリ、対応する CLI ラッパーまたは run_uv.py を確認します。

参考資料

• references/embed.md：埋め込みレシピのステージ、コマンド、デフォルト、出力パス、運用パターン。
• references/rerank.md：リランキングレシピのステージ、コマンド、デフォルト、出力パス、運用パターン。
• references/evaluation.md：指標の解釈、比較時の注意点、デプロイ準備状況の確認。
• references/remote.md：リモート実行プロファイル、バッチ／実行モード、GPU の指定、ログ、状態確認。
• PITFALLS.md：SDG、prep、トレーニング、評価、エクスポート、デプロイ、CLI の設定に関するよくある失敗と復旧方法。

例

ユーザーの質問：「Recall はまずまずですが、nDCG は低く、正解のパッセージは 40 位あたりにあります。embed と rerank のどちらを調整すべきですか？」

references/rerank.md と references/evaluation.md を読み込み、Recall は許容範囲でも上位の順位付けが不十分であることから、reranker の調整が適切だと説明します。その後、トレーニングの前に手軽なプレビューを提案します。

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

トラブルシューティング

失敗が発生した場合は、まず PITFALLS.md を読み込みます。失敗したステージを特定してから、ステージ設定、想定される入力、出力ディレクトリ、対応する CLI ラッパーまたは run_uv.py を確認します。

制限事項

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

出力スタイル

計画やデバッグに関する推奨事項では、役立つ場合、次の形式を使用してください。Decision、Why、Required inputs、Preview command、Execution command、Avoid、Next step。短い回答に不要な項目は省略してください。

具体的なコマンドとファイルパスを示してください。前提条件、想定される入力、想定される出力、および次のアクションを実行できる状態だと証明するための最も低コストな検証手順を明記してください。時間のかかるステージでは、ユーザーが慎重に選択できるように、プレビューコマンドと実行コマンドを分けてください。

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