30分钟部署企业级RAG系统:NVIDIA RAG Blueprint Docker Compose快速上手教程
30分钟部署企业级RAG系统:NVIDIA RAG Blueprint Docker Compose快速上手教程
NVIDIA RAG Blueprint 是 NVIDIA 推出的企业级检索增强生成(RAG)参考方案,用 Docker Compose 即可在单机上快速部署一套完整的 RAG 系统:涵盖文档摄取、向量检索、混合搜索、重排序、答案生成与可视化界面,让大模型基于你自己的企业数据回答问题。本教程面向新手,带你按 4 个步骤完成 NVIDIA RAG Blueprint 的 Docker Compose 部署。
一、NVIDIA RAG Blueprint 是什么?
一句话概括:把"文档摄取 → 向量检索 → LLM 生成"整条 RAG 流水线,用一组可拆分的 NVIDIA NIM 微服务 + Docker 容器打包好的蓝图。
它的核心能力包括:
- 📥 多模态数据摄取:支持 PDF、Word、图片、音频、视频等,内置 OCR、表格结构识别
- 🔍 混合搜索与重排序:稠密 + 稀疏检索,Reranking 进一步提升准确性
- 🤖 可选 Agentic RAG:面向多跳、跨文档复杂问题的规划-执行流水线
- 🧭 内容护栏(Guardrails):可选的内容安全与主题控制
- 🖥️ 开箱即用的 Web UI:上传文档、提问、查看引用来源
下面是 RAG Blueprint 的完整 RAG 流水线架构(查询管道 + 摄取管道):
二、部署前检查:硬件、磁盘与软件要求
⚠️ 最容易被忽略的是磁盘空间:模型下载与缓存约占 100–150GB,请务必先确认磁盘余量。
| 检查项 | 最低要求 | 说明 |
|---|---|---|
| 磁盘空间 | ≥ 200GB | 模型缓存 + 容器镜像 + 向量库数据 |
| 操作系统 | Ubuntu 22.04 | 自托管 Docker 部署的推荐系统 |
| GPU 硬件 | 3× H100 / 3× B200 / 3× RTX PRO 6000 | 默认 LLM 为 FP8 TP2,需 2 张 GPU |
| GPU 驱动 / CUDA | 驱动 560+ / CUDA 12.9+ | 满足 NIM 运行要求 |
| Docker | Engine 24.0+(29.5.x 不支持) | 需安装 Compose 插件 2.29.1+ |
| NVIDIA Container Toolkit | 必须 | GPU 加速容器的前置依赖 |
💡 没有 GPU ?可以改用 NVIDIA Hosted 端点部署或无容器的 Lite 模式(纯 Python,调用云端 API)。详细硬件标准见 docs/support-matrix.md。
三、克隆仓库并登录镜像仓库
RAG Blueprint 的预构建容器托管在 NVIDIA NGC,需要先创建一个 NGC API Key 用于登录:
git clone https://gitcode.com/gh_mirrors/rag1/rag
cd rag
export NGC_API_KEY="nvapi-你的API-Key"
echo "${NGC_API_KEY}" | docker login nvcr.io -u '$oauthtoken' --password-stdin
四、四步启动全部服务(核心流程)
完整步骤参考 docs/deploy-docker-self-hosted.md,所有 compose 文件都放在 deploy/compose/ 目录。
1️⃣ 准备模型缓存目录与环境变量
mkdir -p ~/.cache/model-cache
export MODEL_DIRECTORY=~/.cache/model-cache
source deploy/compose/.env
deploy/compose/.env 中预置了自托管模型所需的全部变量,确认其中"云 NIM 端点"部分是注释状态即可。
2️⃣ 启动 NIM 微服务(GPU 密集部分)
USERID=$(id -u) docker compose -f deploy/compose/nims.yaml up -d
这一步会拉起 LLM、Embedding、Reranking、OCR、表格/图形检测等 NIM 容器。用以下命令观察状态,等待 nim-llm-ms、nemotron-ranking-ms、nemotron-vlm-embedding-ms 变为 healthy 再继续:
watch -n 2 'docker ps --format "table {{.Names}}\t{{.Status}}"'
3️⃣ 启动向量数据库
默认使用 Elasticsearch(CPU 即可),也可选 GPU 加速的 Milvus:
# 默认:Elasticsearch
docker compose -f deploy/compose/vectordb.yaml up -d
# 可选:Milvus(GPU 加速)
docker compose -f deploy/compose/vectordb.yaml --profile milvus up -d
4️⃣ 启动 Ingestor Server 与 RAG Server
docker compose -f deploy/compose/docker-compose-ingestor-server.yaml up -d
docker compose -f deploy/compose/docker-compose-rag-server.yaml up -d
两个 Server 分别对应文档摄取 API 与 RAG 查询 API,定义文件为 docker-compose-ingestor-server.yaml 和 docker-compose-rag-server.yaml。
📌 持久化数据(Elasticsearch、SeaweedFS、Milvus/etcd 等)自动存放在 rag-vol-* 命名卷中,首次启动时由 Docker Compose 创建,无需手动配置。
五、健康检查:确认服务真的跑起来了
服务健康状态可以用自带的 /v1/health 端点验证:
# RAG Server 健康检查
curl 'http://localhost:8081/v1/health?check_dependencies=true'
# Ingestor Server 健康检查
curl 'http://localhost:8082/v1/health?check_dependencies=true'
返回 "message": "Service is up." 且各依赖项为 healthy 即代表部署成功。常用端口速查:
| 服务 | 端口 | 作用 |
|---|---|---|
| RAG Frontend(Web UI) | 8090 | 浏览器访问入口 |
| RAG Server | 8081 | RAG 查询/生成 API |
| Ingestor Server | 8082 | 文档摄取 API |
| LLM NIM | 8999 | 主语言模型推理 |
| Elasticsearch | 9200 | 默认向量数据库 |
完整端口与 GPU 分配表见 docs/service-port-gpu-reference.md。
六、打开 Web UI:上传文档、提问、看引用
浏览器访问 http://localhost:8090,RAG UI 即刻可用(界面细节见 docs/user-interface.md)。
- 点击左下角 New Collection 创建文档集合并上传文件,支持 PDF、DOCX、图片、音频、视频等(单批最多 100 个文件):
- 在 Ask a question about your documents 输入框中提问,勾选一个或多个 Collection 作为检索范围:
- 点击 Sources 可查看答案引用的文档片段与评分,点击 Settings 可调整检索/生成参数,观察不同配置对答案质量的影响。
七、进阶玩法与日常运维命令
按需裁剪部署:只启动 RAG 或只启动摄取相关服务时,加上 profile 参数:
USERID=$(id -u) docker compose -f deploy/compose/nims.yaml --profile rag up -d
精度/性能调优预设:
source deploy/compose/accuracy_profile.env # 精度优先
source deploy/compose/perf_profile.env # 性能优先
更多模型组合见 docs/model-profiles.md。
可观测性:部署后可通过 OpenTelemetry + Grafana 追踪每次查询的耗时与检索链路,配置位于 deploy/config/ 目录,链路追踪界面示例:
停止与清理全部服务:
docker compose -f deploy/compose/docker-compose-rag-server.yaml down
docker compose -f deploy/compose/docker-compose-ingestor-server.yaml down
docker compose -f deploy/compose/nims.yaml down
docker compose -f deploy/compose/vectordb.yaml down
八、常见问题速查
| 问题 | 解决办法 |
|---|---|
| 磁盘不足导致拉取/下载失败 | 清理 Docker 镜像缓存,确保 ≥200GB 空闲空间 |
| 端口冲突(如 8081 被占用) | 修改对应 compose YAML 中的端口映射,并同步更新引用该端口的环境变量 |
docker compose 报错拉不到 NGC 镜像 |
重新执行 NGC 登录;注意 Docker Engine 29.5.x 不受支持 |
| 服务起不来、日志混乱 | 参考 docs/troubleshooting.md 排查,含持久化卷管理方法 |
到这里,一套完整的企业级 RAG 系统已经在你的机器上跑起来了 🎉。接下来可以继续探索多轮对话、自定义提示词与 MCP 集成,让这套蓝图真正融入你的业务场景。



