rag-gpt

想象一下：你的公司有一份 200 页的产品手册、一个完整的官网 FAQ、还有客服团队积累的上千条历史对话记录——这些数据散落在不同地方，客户问起来时，客服只能一个个去找、去复制粘贴。而 RAG-GPT 想要解决的就是这个问题：让 AI 机器人能够真正「读懂」你的专属知识库，给出基于真实资料的回答，而不是凭空编造。 这也是当前企业级 AI 客服最核心的诉求之一。

项目背景与起源

RAG-GPT 由 open-kf 团队开发维护，项目名中的 RAG 是 Retrieval-Augmented Generation（检索增强生成）的缩写，这是一种将大规模语言模型与外部知识检索相结合的技术架构。团队开发这个工具的出发点非常务实：市面上有大量开源 RAG 框架，但大多数需要开发者具备相当的工程能力才能部署上线，普通产品经理或中小企业主想要一个开箱即用的智能客服系统，门槛依然很高。RAG-GPT 的设计目标就是打破这个壁垒——从代码克隆到客服上线，最快 5 分钟完成。

该项目在 GitHub 上获得了近 500 颗星，收到了来自全球开发者的 issue 和 PR 反馈。支持的 LLM 提供商包括 OpenAI GPT 系列、智谱 GLM 系列、DeepSeek、Moonshot（月之暗面）以及本地 Ollama，覆盖了国内外主流选择。此外还支持 LlamaParse 高级文档解析服务，对 PDF、Word、PPT 等复杂文档的提取效果更好。

图1：RAG-GPT 系统整体架构图

核心功能拆解

知识库管理：网站、URL、文件三位一体

RAG-GPT 的后台管理界面支持三种知识库导入方式，这是它相比纯 API 方案最实用的地方。

网站导入：只需输入一个网站 URL，系统会自动抓取该网站的文本内容，生成 sitemap 并递归爬取子页面。这一步解决了「官网内容多，手动复制太麻烦」的问题。后台支持分批次导入，导入进度实时可见。

孤立 URL 导入：对于没有 sitemap 的单页面或内网文档，手动指定 URL 列表即可批量导入。系统会跳过重复内容，按域名去重。

本地文件上传：支持 PDF、Word（.docx）、Excel（.xlsx）、PowerPoint（.pptx）以及纯文本文件。上传后系统自动解析文本内容，切分为适合检索的文本块（chunk）。LlamaParse 模式下解析质量更高，适合扫描件 PDF 或复杂排版的文档。

RAG Pipeline：从问到答的完整链路

RAG-GPT 的检索生成链路设计得相当完整，代码结构清晰，分了多个层次：

Pre-Retrieval（检索前处理）：

• Query Rewrite（查询改写）：检测用户提问语言，在 Query 中嵌入 Bot 主题词。例如用户问「怎么登录」，系统自动补全为「怎么登录——关于 OpenIM 的信息」，避免检索结果偏离主题。
• Query Expansion（查询扩展）：通过 LLM 生成同义词和相关问题，扩大检索覆盖面。
• Query Routing（查询路由）：判断当前问题是否需要检索知识库，还是属于闲聊/常识类问题。

Retrieval（检索）：

• 使用 Chroma 作为向量数据库，这是目前 LangChain 生态中集成度最高的向量库之一。
• Embedding 模型根据 LLM 提供商自动切换：OpenAI 用 text-embedding-ada-002，智谱用 embedding-2，本地 Ollama 用对应模型。
• 支持 Maximal Marginal Relevance（MMR）多样性检索，在相关性和多样性之间取得平衡。

Post-Retrieval（检索后处理）：

• Rerank（重排序）：使用 FlashRank（基于 ONNX Runtime 的轻量级重排模型，ms-marco-MiniLM-L-12-v2）对初筛结果重新打分，过滤低相关性片段。
• Compression（压缩）：用 LLM 从检索到的文档片段中提取与问题最相关的句子，减少上下文长度，降低 token 消耗。

Generation（生成）：

• 统一的 LLMGenerator 类封装了所有支持的 LLM，统一接口风格。
• 支持流式输出（Streaming），前端实时显示打字效果，体验接近 ChatGPT。
• 会话历史通过 DiskCache 存储，支持上下文多轮对话。

图2：RAG-GPT 在线检索流程

前后端与嵌入部署

后台管理界面（Admin Console）：基于 Vite + 现代前端框架构建，页面美观，可配置 Bot 名称、欢迎语、检索参数（Top-K、相关性阈值、是否开启查询预处理、是否开启重排序等）。支持查看用户历史提问与回答、导入知识库数据、监控使用趋势。

前端聊天组件（Chatbot）：Web 目录下提供独立的 embed.js，可通过 iframe 嵌入任意网站。界面支持自定义配色和样式参数，无需修改源码即可与企业官网风格统一。

数据存储：

• 元数据（用户、对话历史）：SQLite + WAL 模式，WAL 模式支持并发读写。
• 向量数据：Chroma（本地持久化），支持指定 collection 和持久化目录。
• 会话缓存：DiskCache（基于磁盘的 KV 缓存，支持 TTL 和列表操作）。

技术栈一览

层次	技术选型
Web 框架	Flask 3.0 + Gunicorn（3 workers）
前端	Vite + 原生 JS（无重型框架依赖）
向量数据库	Chroma 0.4
LLM 框架	LangChain 0.1
Embedding	OpenAI / 智谱 / Ollama
重排序	FlashRank（ONNX Runtime）
数据库	SQLite（WAL 模式）
缓存	DiskCache
文档解析	PyMuPDF、python-docx、python-pptx、Mammoth、LlamaParse
API 认证	JWT（PyJWT）
日志	Loguru
容器化	Docker + Docker Compose

部署体验：真的 5 分钟能跑起来吗？

实测流程：

1. 克隆代码：git clone + cd rag-gpt，约 30 秒。
2. 配置 API Key：复制 env_of_openai 为 .env，填入 OPENAI_API_KEY，约 1 分钟。
3. 启动服务：docker-compose up --build，首次构建需 3-5 分钟（下载 Python 镜像 + 安装依赖），后续启动约 30 秒。
4. 初始化数据库：启动脚本自动执行 create_sqlite_db.py，无需手动操作。
5. 访问后台：http://127.0.0.1:7000，默认账号密码登录，开始导入知识库。

瓶颈点：首次构建时，requirements.txt 中包含 30+ 个依赖包，其中 onnxruntime、tokenizers、chromadb 体积较大，Docker 镜像首次构建可能需要 5-8 分钟。如果网络不佳（依赖下载慢），可能需要 10 分钟以上。

GPU 需求：默认配置无需 GPU，纯 CPU 运行即可。Embedding 和 Rerank 模型均为轻量级模型，推理速度可接受。如果使用本地 Ollama 跑大模型（如 7B 参数），则需要 GPU。

图3：RAG-GPT 后台管理界面

局限性与需要注意的问题

1. 生产环境安全性：JWT_SECRET 在代码中硬编码为默认值，直接用于生产环境存在安全风险。虽然 token_helper.py 中标注了「Should be replaced」，但如果开发者没有注意到这一点，部署上线后认证机制形同虚设。建议通过环境变量注入。

2. 依赖包版本锁定不严：requirements.txt 中部分包未锁定精确版本，LangChain 0.1.x 区间内 API 变化频繁，不同时间点 pip install 可能装到行为不同的子版本。生产部署建议配合 pip-compile 或 poetry.lock。

3. 多租户支持有限：当前架构为单实例单 Bot，所有用户共享同一个向量数据库 collection。如果需要为不同客户/品牌创建独立 Bot，需要自行实现数据隔离逻辑。

4. 无中文搜索专项优化：虽然支持中文问答，但 Chunk 策略基于 RecursiveCharacterTextSplitter，对中文语义切分不如按句子/段落切分精细。中文 FAQ 类场景建议开启 LlamaParse 以提升解析质量。

行业意义与趋势判断

RAG-GPT 代表了当前 AI 应用落地的一个主流方向：用开源工具降低企业 AI 客服的部署门槛。相比 Dialogflow、Watson Assistant 等商业方案，RAG-GPT 完全免费，数据不上云，适合对数据隐私有要求的企业。

从增长角度看，该项目自 2024 年初开源以来保持了稳定维护，issue 回复及时，说明团队在积极运营。支持的 LLM 提供商从最初的 OpenAI 扩展到现在的 5 家（DeepSeek、Moonshot 的加入明显是 2024 年的新增），说明团队在持续跟进国内大模型生态。

随着各大云厂商推出更便宜的 Embedding API（如智谱 embedding-2 价格仅为 OpenAI 的几分之一），RAG 方案的整体成本正在快速下降，中小企业用上私有 AI 客服的门槛会越来越低。RAG-GPT 这类一站式解决方案的价值在于降低了最后一公里的工程复杂度，让不懂技术的用户也能享受 AI 红利的最后一跃。