如何 10 分钟跑通 RAG 知识库问答:mini-rag 快速上手与本地部署指南

原创2026-10-28 15:10:141,640 阅读

如何 10 分钟跑通 RAG 知识库问答:mini-rag 快速上手与本地部署指南

想用 10 分钟拥有一个能真正跑起来、具备生产级架构的 RAG(检索增强生成)知识库问答系统吗?mini-rag 就是这么一个教学型开源项目:它用 FastAPI 做 API 服务,用 Celery 处理文档切片与向量入库,用 Postgres/pgvector 或 Qdrant 做向量检索,并接入 OpenAI、Cohere 等大模型完成问答,全程通过 Docker Compose 一键拉起。本文带你从零完成 mini-rag 本地部署,并走通「上传文档 → 切片处理 → 向量索引 → 语义问答」的完整 RAG 流程。

一、mini-rag 是什么?为什么值得上手

mini-rag 是一个"手把手"教学项目(配套 26 节分步视频课程),目标不只是让你跑一个 RAG Demo,而是演示如何一步一步构建生产就绪(production-ready)的 RAG 应用:

  • 🧩 模块化架构:路由层(routes/)、控制器层(controllers/)、模型层(models/)、LLM 工厂(stores/llm/)、向量库工厂(stores/vectordb/)职责清晰,换模型、换向量库都只需改配置;
  • ⚙️ 生产级组件:Celery + RabbitMQ 异步任务队列、Redis 结果后端、Flower 监控、Prometheus + Grafana 指标面板一应俱全;
  • 🐳 一键 Docker 部署:所有服务(FastAPI、Nginx、pgvector、Qdrant、RabbitMQ、Redis、监控栈)由一份 docker-compose.yml 统一编排。

想深入了解项目设计与课程对照表,可查阅 README.md;部署细节见 docker/README.md。

二、快速环境准备:Docker 一键本地部署

mini-rag 官方推荐用 Docker Compose 部署(开发模式需要 Python 3.10,Docker 方式可免去本地环境配置的麻烦)。

第 1 步:获取代码并进入部署目录

git clone https://gitcode.com/gh_mirrors/mi/mini-rag
cd mini-rag/docker

第 2 步:准备环境变量文件(应用配置中填写你的 OPENAI_API_KEY、COHERE_API_KEY):

cd env
cp .env.example.app .env.app
cp .env.example.postgres .env.postgres
cp .env.example.grafana .env.grafana
cp .env.example.postgres-exporter .env.postgres-exporter
cd ../minirag
cp alembic.example.ini alembic.ini

💡 默认配置:生成模型用 OpenAI 的 gpt-4o-mini,嵌入模型用 Cohere 的 embed-multilingual-v3.0,向量库默认 PGVECTOR。完整配置项可参考 .env.example.app。

第 3 步:启动全部服务

cd ../docker
docker compose up --build -d

如果遇到数据库连接超时,可以先启动数据库并等待就绪:docker compose up -d pgvector qdrant,约 30 秒后再启动其余服务(详见 docker/README.md 的 Troubleshooting 章节)。

三、验证服务:FastAPI、Qdrant 与监控面板

服务启动后,浏览器打开对应地址即可验证:

服务 访问地址 用途
FastAPI 接口 http://localhost:8000 核心 API
FastAPI 交互文档 http://localhost:8000/docs Swagger 文档
Nginx 网关 http://localhost 反向代理 FastAPI
Qdrant UI http://localhost:6333/dashboard 向量集合可视化
Flower 任务面板 http://localhost:5555 Celery 任务监控
Grafana / Prometheus http://localhost:3000 / :9090 指标监控

先用一条最简单的请求验证应用存活:

curl http://localhost:8000/api/v1/

正常会返回 {"app_name": "mini-RAG", "app_version": "0.1"},说明部署成功。该欢迎接口定义在 routes/base.py,项目还附带了一份 Postman 集合可直接导入体验:mini-rag-app.postman_collection.json。

四、RAG 核心流程:从上传文档到知识库问答

mini-rag 的 API 统一挂载在 /api/v1 前缀下(见 src/main.py),一条完整的 RAG 链路分为三步:

1️⃣ 上传文档 — POST /api/v1/data/upload/{project_id}

支持纯文本与 PDF(FILE_ALLOWED_TYPES=["text/plain", "application/pdf"],单文件上限 10MB),上传成功后返回 file_id。

2️⃣ 切片处理 + 向量入库(一条命令完成) — POST /api/v1/data/process-and-push/{project_id}

请求体示例:

{
    "file_id": "上传返回的file_id",
    "chunk_size": 100,
    "overlap_size": 20,
    "do_reset": 0
}

后端会用 Celery chain 串联「文件切片」与「向量索引」两个任务依次执行(见 tasks/process_workflow.py),返回 workflow_task_id 可去 Flower 面板跟踪进度。

3️⃣ 提问与问答 — 两个接口,按需选用:

  • POST /api/v1/nlp/index/search/{project_id}:纯向量语义检索,返回最相关的文档片段;
  • POST /api/v1/nlp/index/answer/{project_id}:完整 RAG 问答,请求体 {"text": "你的问题", "limit": 5}。

问答的实现逻辑在 controllers/NLPController.py:先检索 Top-N 相关片段,再按 rag 提示词模板 拼装 System Prompt + 文档片段 + 用户问题,最后交给 LLM 生成"只基于所提供文档"的回答——这正是 RAG 降低模型幻觉的关键。接口细节与请求格式可全部在 http://localhost:8000/docs 中交互调试。

五、灵活切换 LLM 与向量数据库

mini-rag 用"工厂 + 配置"的方式隔离外部依赖,换模型、换向量库只改 .env 不动代码:

  • LLM 工厂(stores/llm/LLMProviderFactory.py):内置 OpenAI、Cohere 两个 Provider,GENERATION_BACKEND(生成)与 EMBEDDING_BACKEND(嵌入)可分别指定;
  • 向量库工厂(stores/vectordb/VectorDBProviderFactory.py):VECTOR_DB_BACKEND 可在 QDRANT 与 PGVECTOR 间切换,距离方法由 VECTOR_DB_DISTANCE_METHOD(默认 cosine)控制;
  • 应用启动时按配置创建生成客户端、嵌入客户端与向量库连接,整个初始化过程见 main.py。

想用本地模型?教程系列中包含 Ollama 本地 LLM 服务章节,把 OPENAI_API_URL 指向本地 Ollama 地址即可复用 OpenAI Provider,适合零成本离线体验。

六、常见问题速查

现象 原因与解决
Connection refused 数据库容器还没就绪,先启动 pgvector、qdrant 并等待健康检查通过,再 docker compose restart fastapi
问答返回 VECTORDB_SEARCH_ERROR 集合为空,先确认 process-and-push 工作流已执行完(Flower 面板查看),再查看 docker compose logs --tail=100 celery-worker
迁移报错 确认已执行 cp alembic.example.ini alembic.ini;容器启动时 entrypoint.sh 会自动执行 alembic upgrade head
想彻底重置环境 docker compose down -v --remove-orphans 后重新 up

数据库表结构变更由 Alembic 管理,迁移脚本位于 models/db_schemes/minirag/alembic/versions/。

七、总结:你得到了什么

不到 10 分钟,你已经在本地跑通了一个完整的 RAG 知识库问答系统,并顺手拥有了 Flower 任务监控、Grafana 指标面板、Qdrant 集合可视化这一整套生产化配套设施。mini-rag 的价值不止于"跑起来":

  • ✅ 一条 curl 验证服务存活,/docs 里完成交互式 API 调试;
  • ✅ 三步 API 走通「上传 → 切片索引 → RAG 问答」全链路;
  • ✅ 改几行 .env 即可切换 LLM 与向量数据库后端。

建议下一步对照 README.md 中的 26 节课程分支(tut-001 ~ tut-017)逐课精读源码,从 FastAPI 入门一路学到 Celery 异步任务编排,把这套生产级 RAG 架构真正吃透。

登录后查看全文
mini-rag