AI Skills
rag-blueprint

rag-blueprint

热门

NVIDIA RAG Blueprint 运维与管理工具 —— 支持部署、配置、排障及全面管控。覆盖 RAG 全生命周期操作：包含部署、安装、启动、开启、禁用、开关切换、修改、配置、故障排查、调试、修复、关机、停止及销毁任何 RAG 功能或服务（涵盖 Agentic RAG、VLM、护栏 Guardrails、查询重写、模型、检索、数据导入 Ingestion、可观测性、摘要生成、推理等）。

2750Star
320Fork
更新于 2026/8/1
获取 Skill源代码

相关 Skills

agent-reviewer7.1万planning-with-files4.7万planning-and-task-breakdown7.7万
SKILL.md
只读
名称
rag-blueprint
描述

NVIDIA RAG Blueprint 运维与管理工具 —— 支持部署、配置、排障及全面管控。覆盖 RAG 全生命周期操作：包含部署、安装、启动、开启、禁用、开关切换、修改、配置、故障排查、调试、修复、关机、停止及销毁任何 RAG 功能或服务（涵盖 Agentic RAG、VLM、护栏 Guardrails、查询重写、模型、检索、数据导入 Ingestion、可观测性、摘要生成、推理等）。

版本
2.6.0

NVIDIA RAG Blueprint

功能简介

此 Skill 用于处理 NVIDIA RAG Blueprint 的各项运维与管理操作，包括在 Docker、Helm 及 Library（代码库）部署模式下的部署、配置、排障、关机停机以及功能特性管理。

操作指南

  1. 将用户需求对照下方意图路由表进行匹配。
  2. 在动手修改前，先阅读对应的参考手册（Playbook）。
  3. 始终以代码库中的官方文档和部署配置文件为准（Source of Truth）。
  4. 修改完成后，务必验证受影响的服务或工作流是否运行正常。

前置条件

  • 已克隆并检出 NVIDIA RAG Blueprint 代码库。
  • 安装并配置好 Docker/Compose 或 Kubernetes/Helm（用于容器化部署）。
  • Python 3.11+（用于 Library 模式工作流）。
  • 已配置 NVIDIA GPU 相关工具链（用于私有化/自托管 NIM 服务）。

自主运行原则

  • 全自动检测一切环境信息：GPU、显存（VRAM）、驱动、Docker、CUDA、磁盘空间、操作系统、端口占用、已运行服务、NGC 密钥、代码库状态。
  • 能通过命令行自动检查的，直接运行命令检查，不要打扰用户。
  • 仅在必须由用户操作时才提问：如补充 API Key、确认删除数据、或在多个同等可行的方案中做出选择。
  • 完成环境分析后，立即路由到正确的工作流并执行。

用户意图识别与路由

快速判断用户意图并立即路由：

用户意图 执行动作
部署、安装、初始化、启动 RAG 阅读并参考 references/deploy.md
配置、开启、修改、切换某个功能 参考下方的“功能配置”章节
故障排查、调试、修复报错、服务异常 阅读并参考 references/troubleshoot.md
停止、关机、销毁环境、清理资源 阅读并参考 references/shutdown.md

如果意图不够明确，优先根据上下文进行推断（例如：“RAG 连不上了” → 排障；“把 RAG 跑起来” → 部署）。只有在完全无法确定时才向用户询问。

功能配置

前提条件：需要已运行的 RAG 环境。如果服务未运行，请先通过 references/deploy.md 进行部署。

根据用户需求匹配对应的参考文件，阅读并执行相关步骤：

功能关键词 参考文档
VLM、VLM 向量嵌入（Embeddings）、图片描述（Image Captioning） references/configure/vlm.md
NeMo Guardrails 安全护栏 references/configure/guardrails.md
Agentic RAG、规划/执行 Agent、智能体流式输出、阶段事件 references/configure/agentic-rag.md
查询重写（Query Rewriting）、拆解、多轮对话 references/configure/query-and-conversation.md
数据解析与导入 Ingestion（纯文本、音频、Nemotron Parse、OCR、批量 CLI、NV-Ingest、卷挂载、性能优化） references/configure/ingestion.md
检索与搜索 Search/Retrieval（混合检索、多 Collection、元数据过滤、Elasticsearch 筛选、重排器 Reranker、TopK、准确率/性能调优） references/configure/search-and-retrieval.md
LLM / Embedding / Ranking 模型变更、向量数据库、Milvus/Elasticsearch 鉴权、服务 Key、模型 Profile、端口/GPU 配置 references/configure/models-and-infrastructure.md
深度推理（Reasoning）、思考模式（Thinking mode）、reasoning_content、自我反思、Prompt 调优、生成参数（Tokens、Temperature、引用格式）、单次请求 LLM 参数 references/configure/reasoning-and-generation.md
文本摘要（Summarization） references/configure/summarization.md
可观测性 Observability（链路追踪 Tracing、Zipkin、Grafana、Prometheus） references/configure/observability.md
多模态查询 Multimodal query（图文混合） references/configure/multimodal-query.md
数据目录 Data catalog（Collection / 文档元数据管理） references/configure/data-catalog.md
用户界面 UI（UI 设置、推理过程展示面板、元数据过滤器） references/configure/user-interface.md
API 参考文档（Endpoints 接口、Schemas 结构定义） references/configure/api-reference.md
效果评估 Evaluation（RAGAS 评估指标） references/configure/evaluation.md（以及 rag-eval Skill）
MCP 服务端与客户端、Agent 工具包 references/configure/mcp.md
版本迁移 Migration（大版本升级） references/configure/migration.md
Jupyter 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 进程 代码库模式（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

    如果配置文件与在线服务配置不一致，告知用户当前运行服务存在过期配置（stale config），后续需要重启生效。

  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。

使用限制

  • 本 Skill 的操作指南仅适用于当前 NVIDIA RAG Blueprint 代码库。
  • 动态调整部署配置前提是目标环境（Docker、Helm 或 Library 进程）已成功运行。
  • 敏感凭据（如 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。可能需要多卡并行跑 LLM（LLM_MS_GPU_ID）。
RTX PRO 6000 不支持 Nemotron Parse。在 Helm 部署下不支持 Audio。