rag-blueprint

NVIDIA RAG Blueprint

目的

Docker、Helm、ライブラリの各デプロイ方法における NVIDIA RAG Blueprint の運用（デプロイ、設定、トラブルシューティング、シャットダウン、機能管理）には、このスキルを使用します。

手順

1. ユーザーのリクエストを、以下のインテント振り分けテーブルに照らし合わせます。
2. 変更を加える前に、参照先のプレイブックを読みます。
3. リポジトリのドキュメントとデプロイ設定ファイルを信頼できる情報源として使用します。
4. 変更後、影響を受けるサービスまたはワークフローを検証します。

前提条件

• NVIDIA RAG Blueprint リポジトリのチェックアウト。
• デプロイ用の Docker/Compose または Kubernetes/Helm。
• ライブラリのワークフロー用の Python 3.11 以降。
• セルフホスト型 NIM サービス用の NVIDIA GPU ツール。

自律性の原則

• あらゆる情報を自動検出します。GPU、VRAM、ドライバー、Docker、CUDA、ディスク、OS、ポート、既存のサービス、NGC キー、リポジトリの状態を確認します。
• コマンドで確認できることは、ユーザーに尋ねずに確認します。
• ユーザーの操作が必要な場合に限り、質問します。API キーの提供、データ削除の確認、または同等に妥当な選択肢からの選択が該当します。
• 分析が完了したら、適切なワークフローに振り分けて実行します。

インテントの検出

ユーザーの目的を判断し、直ちに振り分けます。

ユーザーのインテント	アクション
RAG のデプロイ、インストール、セットアップ、起動	references/deploy.md を読み、手順に従います
機能の設定、有効化、変更、切り替え	以下の「設定」セクションを使用します
トラブルシューティング、デバッグ、修正、エラー、異常	references/troubleshoot.md を読み、手順に従います
停止、シャットダウン、削除、クリーンアップ	references/shutdown.md を読み、手順に従います

インテントが曖昧な場合は、文脈から判断します（例：「RAG が動作しない」→トラブルシューティング、「RAG を使えるようにする」→デプロイ）。本当に不明な場合に限り、質問します。

---

設定

実行中の RAG デプロイが必要です。サービスが実行されていない場合は、まず references/deploy.md に従ってデプロイします。

ユーザーのリクエストを参照ファイルに照らし合わせてから、そのファイルを読み、手順に従います。

機能のキーワード	参照先
VLM、VLM 埋め込み、画像キャプション生成	references/configure/vlm.md
NeMo Guardrails	references/configure/guardrails.md
Agentic RAG、計画／実行エージェント、エージェント型ストリーミング、ステージイベント	references/configure/agentic-rag.md
クエリ書き換え、分解、マルチターン	references/configure/query-and-conversation.md
インジェスト（テキストのみ、音声、Nemotron Parse、OCR、バッチ CLI、NV-Ingest、ボリュームマウント、パフォーマンス）	references/configure/ingestion.md
検索、検索拡張、ハイブリッド検索、複数コレクション、メタデータ、フィルター、Elasticsearch フィルター、再ランキング、topK、精度／パフォーマンス	references/configure/search-and-retrieval.md
LLM／埋め込み／ランキングモデルの変更、ベクターデータベース、Milvus／Elasticsearch 認証、サービスキー、モデルプロファイル、ポート／GPU	references/configure/models-and-infrastructure.md
推論、思考モード、reasoning_content、自己省察、プロンプト、生成パラメーター（トークン、温度、引用）、リクエストごとの LLM パラメーター	references/configure/reasoning-and-generation.md
要約	references/configure/summarization.md
可観測性（トレーシング、Zipkin、Grafana、Prometheus）	references/configure/observability.md
マルチモーダルクエリ（画像＋テキスト）	references/configure/multimodal-query.md
データカタログ（コレクション／ドキュメントのメタデータ）	references/configure/data-catalog.md
ユーザーインターフェイス（UI 設定、推論パネル、メタデータフィルター）	references/configure/user-interface.md
API リファレンス（エンドポイント、スキーマ）	references/configure/api-reference.md
評価（RAGAS メトリクス）	references/configure/evaluation.md（およびスキル rag-eval）
MCP サーバーとクライアント、エージェントツールキット	references/configure/mcp.md
移行（バージョンアップグレード）	references/configure/migration.md
ノートブック（セットアップとカタログ）	references/configure/notebooks.md

フローの設定

1. ユーザーのリクエストに対応する、上記の表のリファレンスファイルを照合します。

2. 稼働中のものを検出します：

   echo "=== NIM ===" && docker ps --format '{{.Names}}' 2>/dev/null | grep -iE '(nim-llm|nemotron-(vlm-)?embedding|nemotron-ranking|nemotron-vlm|nemotron-3-nano-omni|page-elements|graphic-elements|table-structure|nemotron-ocr)' || echo "NO_LOCAL_NIMS"; echo "=== RAG ===" && docker ps --format '{{.Names}}' 2>/dev/null | grep -iE '(rag-server|ingestor-server|elasticsearch|milvus|seaweedfs|lancedb)' || echo "NO_DOCKER_RAG"; echo "=== K8S ===" && kubectl get pods -n rag 2>/dev/null | head -5 || echo "NO_K8S"; echo "=== LIBRARY ===" && ps aux 2>/dev/null | grep -E '(nvidia_rag|uvicorn.*rag)' | grep -v grep || echo "NO_LIBRARY"
   

3. この表を使って、プラットフォーム、デプロイタイプ、設定の保存場所を特定します：

   ローカル NIM の稼働状況	RAG サービスの稼働状況	デプロイタイプ	設定の保存場所
   はい（Docker）	任意	セルフホスト	deploy/compose/.env
   いいえ	はい（Docker）	NVIDIA ホスト型	deploy/compose/nvdev.env
   はい（K8s ポッド）	任意	セルフホスト	values.yaml（NIM セクション）
   いいえ	はい（K8s ポッド）	NVIDIA ホスト型	values.yaml（envVars）
   —	ライブラリプロセス	ライブラリモード	notebooks/config.yaml
   いいえ	いいえ	稼働していません	references/deploy.md を使って先にデプロイ

   検出した内容をユーザーに伝え、確認を求めます。例：「ローカルの NIM コンテナ（nim-llm-ms、nemotron-vlm-embedding-ms）が稼働しています。これはセルフホスト型のデプロイです。設定ファイルは deploy/compose/.env です。よろしいですか？」

4. 変更を加える前に、現在の機能の状態を確認します。手順 3 の設定の保存場所を読み込み、稼働中のサービスと照合します：

   • Docker：docker exec rag-server env 2>/dev/null | grep -E "<VAR_NAME>"
   • Helm：kubectl get pod -n rag -l app=rag-server -o jsonpath='{.items[0].spec.containers[0].env}' 2>/dev/null

   設定ファイルと稼働中のサービスの内容が一致しない場合、サービスの設定が古く、再起動が必要であることをユーザーに伝えます。

5. 機能に追加 GPU が必要な場合は、ハードウェアの制約（下記を参照）に照らして空き状況を確認します：

   nvidia-smi --query-gpu=index,name,memory.total,memory.used --format=csv,noheader 2>/dev/null || echo "NO_GPU"
   

6. リファレンスファイルを読み、変更を適用します：

   • Docker：env ファイルを編集し（有効化するにはコメントを解除し、無効化するには再度コメントアウトします。env ファイルが信頼できる唯一の情報源です）、影響を受けるサービスを再起動します：

     source <env-file> && docker compose -f deploy/compose/<compose-file> up -d
     

     サービス	Compose ファイル
     rag-server	docker-compose-rag-server.yaml
     ingestor-server	docker-compose-ingestor-server.yaml
     Elasticsearch、Milvus、etcd、SeaweedFS	vectordb.yaml
     NIM コンテナ（LLM、埋め込み、ランキング、VLM、OCR、解析、音声、抽出）	nims.yaml
     ガードレール	docker-compose-nemo-guardrails.yaml
     オブザーバビリティ（Grafana、Prometheus、Zipkin）	observability.yaml

   • Helm：values.yaml を編集し、次にアップグレードします：helm upgrade rag <chart> -n rag -f values.yaml
   • ライブラリ：notebooks/config.yaml を編集し、Python プロセスを再起動します

7. 検証します：

   • Docker：docker ps --format "table {{.Names}}\t{{.Status}}" | head -20; curl -s http://localhost:8081/v1/health?check_dependencies=true 2>/dev/null | head -1
   • Helm：kubectl get pods -n rag; kubectl rollout status deployment/rag-server -n rag --timeout=120s
   • ライブラリ：curl -s http://localhost:8081/v1/health 2>/dev/null | head -1

8. 再起動に失敗した場合は、references/troubleshoot.md を読みます。複数の機能をリクエストされた場合は、機能ごとに手順 1 から繰り返します。

例

• 「RAG をデプロイ」-> references/deploy.md を案内します。
• 「VLM を有効化」-> references/configure/vlm.md を案内します。
• 「RAG が正常に動作しない」-> references/troubleshoot.md を案内します。
• 「RAG を停止」-> references/shutdown.md を案内します。

制限事項

• 運用ガイダンスの対象は、この RAG Blueprint リポジトリのみです。
• 稼働環境への変更には、Docker、Helm、またはライブラリの実行環境が稼働している必要があります。
• NGC_API_KEY などのシークレットは、ユーザー環境から提供する必要があります。

トラブルシューティング

エラー／兆候	対応
サービスが稼働していません	機能を設定する前に、references/deploy.md に従ってください。
再起動またはヘルスチェックに失敗します	references/troubleshoot.md に従ってください。
ユーザーが環境の削除をリクエストしています	references/shutdown.md に従い、破壊的なクリーンアップであることを確認してください。

ユーザーが具体的な指定なしで「設定」と言った場合

上記のステップ 2～3 を実行し、特定した設定ファイルを読み取って、現在有効になっているものを一覧表示します：

grep -E "^(export )?(ENABLE_|APP_)" <config-file> 2>/dev/null | sort

実行中および有効になっているものを要約し、どの機能を変更するかを尋ねます。

---

ハードウェア制限

デプロイモードごとの現在の GPU 要件については、docs/support-matrix.md を参照してください。 ポートマッピングと GPU の割り当てについては、docs/service-port-gpu-reference.md を参照してください。

GPU	機能の制限
B200	VLM なし、Guardrails なし、Nemotron Parse なし。マルチ GPU LLM（LLM_MS_GPU_ID）が必要になる場合があります。
RTX PRO 6000	Nemotron Parse なし。Helm での音声なし。