rag-blueprint

NVIDIA RAG Blueprint

用途

将此技能用于 NVIDIA RAG Blueprint 操作：通过 Docker、Helm 和库部署进行部署、配置、 故障排除、关闭和功能管理。

说明

1. 将用户请求与下方的意图路由表匹配。
2. 做出更改前，阅读相应的操作手册。
3. 以代码库文档和部署配置文件为准。
4. 更改后，验证受影响的服务或工作流。

前提条件

• NVIDIA RAG Blueprint 代码库检出。
• 用于部署的 Docker/Compose 或 Kubernetes/Helm。
• 用于库工作流的 Python 3.11+。
• 用于可自托管 NIM 服务的 NVIDIA GPU 工具。

自主执行原则

• 自动检测所有信息：GPU、显存、驱动程序、Docker、CUDA、磁盘、操作系统、端口、现有服务、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、规划/执行 Agent、Agentic 流式传输、阶段事件	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 服务和客户端、Agent 工具包	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 Pod）	任意	可自托管	values.yaml（NIM 部分）
   否	是（K8s Pod）	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
     guardrails	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

总结当前正在运行和已启用的内容，然后询问要更改哪项功能。

---

硬件限制

阅读 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 不支持音频。