rag-blueprint

NVIDIA RAG Blueprint

目的

當需要進行 NVIDIA RAG Blueprint 相關操作時使用此 Skill，包含跨 Docker、Helm 以及函式庫部署模式下的部署、設定、疑難排解、關閉與功能管理。

操作說明

1. 將使用者的需求對照下方意圖路由表進行匹配。
2. 進行任何變更前，先閱讀對應的參考手冊（playbook）。
3. 務必以儲存庫文件與部署設定檔作為權威依據（source of truth）。
4. 完成變更後，驗證受影響的服務或工作流程。

前置需求

• 已取得 NVIDIA RAG Blueprint 儲存庫程式碼。
• 用於部署的 Docker/Compose 或 Kubernetes/Helm 環境。
• 用於函式庫工作流程的 Python 3.11+。
• 用於自建 NIM 服務的 NVIDIA GPU 工具套件。

自主執行原則

• 全自動偵測一切環境資訊：GPU、VRAM、驅動程式、Docker、CUDA、硬碟、作業系統、連接埠、現有服務、NGC 密鑰、儲存庫狀態。
• 只要能透過命令檢查的事項就直接執行檢查，切勿詢問使用者。
• 僅在確實需要使用者操作時才提出詢問：例如提供 API 密鑰、確認刪除資料、或在數個同等可行的選項間做抉擇。
• 分析完成後，立即引導至對應的工作流程並執行。

意圖偵測

判斷使用者的意圖並立即引導：

使用者意圖	執行動作
部署、安裝、建置、啟動 RAG	閱讀並遵照 references/deploy.md
設定、啟用、變更、切換功能	請參考下方的「設定」章節
疑難排解、除錯、修復、錯誤、狀態不健康	閱讀並遵照 references/troubleshoot.md
停止、關閉、拆卸、清理	閱讀並遵照 references/shutdown.md

若意圖不夠明確，請結合上下文推斷（例如：「RAG 無法運作」→ 疑難排解；「把 RAG 跑起來」→ 部署）。只有在真的無法判斷時才向使用者詢問。

---

設定

必須在 RAG 已處於執行狀態下進行。若服務尚未啟動，請先透過 references/deploy.md 進行部署。

將使用者的需求對照下方表格找到對應的參考文件，並閱讀且遵照其內容執行：

功能關鍵字	參考文件
VLM、VLM 嵌入、影像字幕標註 (image captioning)	references/configure/vlm.md
NeMo Guardrails	references/configure/guardrails.md
Agentic RAG、規劃/執行 Agent、Agentic 流式傳輸、階段事件	references/configure/agentic-rag.md
查詢重寫、查詢分解、多輪對話	references/configure/query-and-conversation.md
資料載入（純文字、音訊、Nemotron Parse、OCR、批次 CLI、NV-Ingest、儲存卷掛載、效能）	references/configure/ingestion.md
搜尋、檢索、混合搜尋、多集合、元資料 (metadata)、篩選器、Elasticsearch 篩選器、重排序器 (reranker)、topK、準確度/效能	references/configure/search-and-retrieval.md
LLM/嵌入/排序模型變更、向量資料庫、Milvus/Elasticsearch 認證、服務密鑰、模型設定檔、連接埠/GPU	references/configure/models-and-infrastructure.md
推理、思考模式、reasoning_content、自我反思、提示詞 (prompts)、生成參數 (tokens, temperature, citations)、單次請求 LLM 參數	references/configure/reasoning-and-generation.md
摘要 (Summarization)	references/configure/summarization.md
可觀察性 (tracing, Zipkin, Grafana, Prometheus)	references/configure/observability.md
多模態查詢（圖片 + 文字）	references/configure/multimodal-query.md
資料目錄 (collection/document metadata)	references/configure/data-catalog.md
使用者介面（UI 設定、推理面板、元資料篩選器）	references/configure/user-interface.md
API 參考（端點、結構 Schema）	references/configure/api-reference.md
評估 (RAGAS 指標)	references/configure/evaluation.md（以及 Skill rag-eval）
MCP 伺服器與用戶端、Agent 工具套件	references/configure/mcp.md
版本遷移（版本升級）	references/configure/migration.md
Notebooks（設定與目錄）	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)	任意	自建 (Self-hosted)	deploy/compose/.env
   否	是 (Docker)	NVIDIA 託管 (NVIDIA-hosted)	deploy/compose/nvdev.env
   是 (K8s pods)	任意	自建 (Self-hosted)	values.yaml (NIM 區塊)
   否	是 (K8s pods)	NVIDIA 託管 (NVIDIA-hosted)	values.yaml (envVars)
   —	函式庫程序	函式庫模式 (Library mode)	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, embedding, ranking, VLM, OCR, parse, audio, extraction)	nims.yaml
     guardrails	docker-compose-nemo-guardrails.yaml
     observability (Grafana, Prometheus, Zipkin)	observability.yaml

   • Helm：修改 values.yaml，然後執行升級：helm upgrade rag <chart> -n rag -f values.yaml
   • Library：修改 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
   • Library: 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

摘要說明目前正在執行與已啟用的項目，並詢問使用者想要變更哪一項功能。

---

硬體限制

請閱讀 docs/support-matrix.md 以了解各部署模式當前的 GPU 需求。
請閱讀 docs/service-port-gpu-reference.md 以了解連接埠對應與 GPU 分配資訊。

GPU	功能限制
B200	不支援 VLM、不支援 Guardrails、不支援 Nemotron Parse。可能需要多卡 GPU LLM (LLM_MS_GPU_ID)。
RTX PRO 6000	不支援 Nemotron Parse。在 Helm 環境下不支援音訊 (Audio)。