RAG-F：给知识焦虑开一剂解药的本地 RAG 系统

你有没有过这种经历：企业内部的私域知识库越积越多——产品文档、客服话术、内部规范、项目周报——每次想查个东西，要么在无数个文件夹里翻找，要么直接问同事被已读不回。AI 助手来了，但直接把数据喂给它又不放心。大模型的幻觉问题，让它在回答业务问题时常常一本正经地胡说八道。

RAG-F（KnowledgeRAG-GZHU） 正是为解决这个痛点而生的：它让 AI 只能在你的文档范围内回答问题，答案可以溯源到具体段落，彻底告别幻觉满天飞的困扰。这个项目来自广东财经大学，是一个完整的生产级 RAG 系统，前端、后端、移动端、部署脚本一应俱全。

图1：RAG-F 智能问答界面，答案附来源可溯

---

一、项目起源：为什么需要一个本地 RAG 系统？

检索增强生成（Retrieval-Augmented Generation，RAG）的核心思想很简单：不要让大模型凭空编造，先从你的知识库中检索相关段落，再让模型基于这些真实内容生成答案。这个范式在 2023-2024 年迅速成为企业级 AI 落地的主流方案，原因有三：

1. 解决幻觉问题 —— 模型不知道你公司的具体情况，但它可以先从你的文档里找到相关段落，然后照着念，幻觉率大幅下降。

2. 数据安全合规 —— 很多企业不允许将内部数据发送到第三方 API，本地部署的 RAG 系统数据完全留在本地，满足合规要求。

3. 成本可控 —— 不需要 fine-tuning（微调）的昂贵成本，只需要在推理时多一步检索步骤，成本约为纯 API 调用的 1.5-2 倍。

RAG-F 的设计目标就是做一个开箱即用的私有知识库 RAG 平台，让用户零配置（或低配置）就能跑起来。不同于那些只提供核心算法的研究代码，RAG-F 提供了完整的产品形态：Web 前端、移动 App、用户管理、权限控制、审计日志——俨然是一个可以上生产的小型 SaaS 系统。

---

二、技术架构：三层分离的全栈设计

RAG-F 采用了经典的三层分离架构，每一层都可以独立部署和扩展：

┌──────────────────────────────────────────────────────────────┐
│                      客户端层                                │
│   Web 前端 (Vue3 + Vite + TDesign)                          │
│   移动端 App (React Native + Expo)                          │
└──────────────────────────┬───────────────────────────────────┘
                           │ HTTP / SSE
┌──────────────────────────▼───────────────────────────────────┐
│                      服务层（FastAPI）                       │
│   用户认证 │ 知识库管理 │ RAG 问答 │ Agent 任务 │ 文档创作   │
│   多模型适配 │ 检索策略配置 │ 语音交互 │ 联网搜索           │
└──────────────────────────┬───────────────────────────────────┘
                           │
┌──────────────────────────▼───────────────────────────────────┐
│                      数据层                                   │
│   MySQL（用户/权限/审计） │ Redis Stream（任务队列）          │
│   FAISS（向量索引） │ Ollama / 公共 LLM API（推理）           │
│   本地文件系统（文档存储）                                    │
└──────────────────────────────────────────────────────────────┘

前端基于 Vue3 + TypeScript，使用 TDesign 组件库，提供类似 Notion 的现代化交互体验。前端目录中包含大量扩展功能（外观主题、动画效果、置顶功能等），表明开发团队对用户体验有较高的追求。

后端基于 FastAPI，这是一个以性能著称的现代 Python Web 框架，支持异步 I/O 和自动 API 文档生成（Swagger UI）。后端模块按功能划分清晰：

• chat_units/ — 聊天相关原子单元
• document_processing/ — 文档解析和向量化
• data_sources/ — 多数据源接入（支持 URL、飞书、钉钉、GitHub 等）
• agent_tools/ — Agent 任务模式实现
• creation/ — 文档创作（SSE 流式生成）
• evaluation/ — RAG 评测模块
• enterprise/ — 企业级功能（审计日志、计费等）

---

三、AI 核心技术：LangChain 全家桶 + 多模型适配

RAG-F 的 AI 能力构建在 LangChain 之上，这是一个广受欢迎的 LLM 应用开发框架。项目的 requirements.txt 中可以看到完整的 LangChain 生态：

langchain==0.3.27
langchain_community==0.3.27
langchain_huggingface==0.3.1
langchain_ollama==0.3.6
sentence-transformers>=5.1.0
faiss-cpu>=1.12.0

LangChain 将 RAG 流程封装为标准化的 Chain（链），开发者不需要自己手写检索→组装→生成的流程，直接复用 RetrievalQA 等现成组件即可。RAG-F 同时支持：

• 本地 Ollama 模型：通过 langchain_ollama，支持 qwen2、llama3 等开源模型，完全离线运行，数据不外流。
• 公共 LLM API：通过 docker-compose.lite.yml 的环境变量配置，切换到 DeepSeek（推荐）、阿里云百炼（qwen-plus）或 OpenAI。
• HuggingFace embedding：使用 sentence-transformers 生成文本向量，存入 FAISS 向量数据库进行高效相似度检索。

图2：RAG-F 完整系统架构展示

多模型适配层的存在是这个项目的一个亮点。很多 RAG 教程只演示单个模型的接法，RAG-F 则通过配置化管理支持多种 LLM 后端的自由切换，这在企业实际生产环境中非常有价值——可以在不同阶段、不同预算下选择性价比最优的模型。

---

四、文档解析与向量化：多格式支持的生产级 pipeline

RAG-F 的文档处理 pipeline 覆盖了日常办公中最常见的数据格式：

格式	解析工具	说明
PDF	pdfplumber / PyPDF2 / pdf2image	文本和图片类 PDF
Word	python-docx / docx2txt	.docx 文档
表格	camelot-py	支持从 PDF 中提取表格
图片	Pillow + pytesseract	OCR 文字识别
网页	beautifulsoup4	URL 批量抓取
Markdown	Jinja2	通用文档格式

解析完成后，文本通过 sentence-transformers 转为 768 维或 1024 维向量，存入 FAISS（Facebook AI Similarity Search）向量数据库。FAISS 支持亿级向量的近似最近邻检索（ANN），在消费级 CPU 上也能保持毫秒级查询速度，是目前 RAG 场景下最主流的向量数据库选择之一。

Redis Stream 的任务队列设计是后端架构的一个值得关注的细节：完整版 docker-compose.yml 中包含 Redis 服务，作为异步任务总线。前端上传文档后，后端立即返回排队中，由独立的 Worker 进程完成解析→切分→向量化→入库的全链路处理。这个设计有两个好处：

1. 上传接口不阻塞：文档处理耗时可能很长（几十 MB 的大 PDF），如果同步处理，前端会长时间无响应甚至超时。
2. 资源隔离：Worker 进程的内存爆炸不会影响后端 API 的稳定性。

---

五、部署体验：两条路线，总有一条适合你

RAG-F 提供了两套部署方案，覆盖了不同的使用场景：

方案 A：完整版（docker-compose.yml）

包含 MySQL、Redis、Ollama（本地模型）、Worker 服务，一行命令即可启动：

docker compose up -d

Ollama 容器会自动拉取默认模型（qwen2:0.5b），硬件需求约 2GB 内存。如果有 NVIDIA GPU，取消注释 docker-compose.yml 中的 GPU 配置段落，即可启用 CUDA 加速推理。

方案 B：轻量版（docker-compose.lite.yml）

不包含 Ollama 容器，依赖外部公共 LLM API（DeepSeek / 阿里云百炼 / OpenAI），同时用 SQLite 替代 MySQL，资源占用更低：

docker compose -f docker-compose.lite.yml up -d

这套方案适合：

• 没有 GPU 但想用强模型的场景（DeepSeek-chat 等 API 模型能力远强于 qwen2:0.5b）
• 快速演示/POC 阶段，不需要自己运维 Ollama
• 不想折腾 MySQL 配置的轻量用户

部署难度评估：非常简单。start.sh 脚本内置了端口检测和旧容器清理逻辑，双击即启动，对非技术用户也比较友好。

---

六、功能全景：不只是 RAG 问答

RAG-F 的野心显然不只是问答这一件事。它的功能模块覆盖了知识管理的完整生命周期：

RAG 问答 — 基于检索结果的带来源答案生成，支持流式 SSE 输出。

Agent 任务模式 — 基于 ReAct 框架（Reasoning + Acting），让 AI 能够执行多步骤任务，例如先查 A 文档，再查 B 文档，最后汇总成报告。

文档创作 — 内置 5 种创作模式（SSE 流式）：报告、摘要、大纲、博客、论文，AI 边写你边看。

多数据源接入 — 不仅可以上传本地文件，还支持：Obsidian 笔记同步、飞书文档、钉钉群、企微、Notion、GitHub 仓库、通用 URL 抓取。

RAG 评测 — 内置评测模块，可以量化评估 RAG 系统的检索质量和生成质量。

RBAC 权限管理 — 企业级用户角色权限控制，不同部门/成员访问不同知识库。

审计日志 — 记录所有操作行为，满足合规要求。

---

七、局限与挑战

任何项目都有其局限性，RAG-F 也不例外：

1. License 信息缺失 — 项目根目录没有 LICENSE 文件，GitHub API 返回 license: null。虽然 README badge 显示 MIT License，但实际法律效力存疑，企业使用前需确认。

2. 本地模型能力有限 — 完整版默认使用的 qwen2:0.5b（5 亿参数）属于小型模型，在复杂推理场景下能力不足。切换到更强模型需要更多 GPU 显存。

3. 向量数据库选型较轻量 — FAISS 作为单节点向量库，在超大规模知识库（亿级文档）场景下扩展性有限，生产级部署可能需要升级到 Milvus、Pinecone 等分布式方案。

4. 中文场景优化有限 — sentence-transformers 的默认模型对中文的语义理解能力取决于具体模型选择，需要根据实际效果调优 chunk_size 和 overlap 参数。

---

八、行业意义

RAG-F 代表的趋势是 RAG 从算法研究走向产品落地。2023 年主流的 RAG 项目（如 langchain 官方 examples）还停留在 Jupyter Notebook 里的演示代码；2024-2025 年，像 RAG-F 这样提供完整前后端、移动 App、部署脚本的全栈 RAG 产品开始批量出现，降低了企业 AI 落地的技术门槛。

从 GitHub 数据看，该项目获得了 141 star 和 11 fork，说明在 RAG 赛道中已有一定的社区关注度。其多模型适配 + 多部署路线的设计思路，值得其他 RAG 项目参考。

如果你正在寻找一个开箱即用的私有知识库 RAG 解决方案，RAG-F 是一个值得尝试的选择——尤其是其 lite 版本，零配置接入 DeepSeek API，数据不外流，体验接近云服务但保留本地部署的安全感。