rag-chatbot
基于本地文档的 RAG 问答机器人，结合 Chroma 向量检索与 llama.cpp 本地 LLM 推理，实现完全私有化的智能问答系统
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
基于本地文档的 RAG 问答机器人，结合 Chroma 向量检索与 llama.cpp 本地 LLM 推理，实现完全私有化的智能问答系统
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
你有没有过这样的经历——把一份厚厚的 Markdown 文档丢给 ChatGPT 问问题，得到的答案却驴唇不对马嘴？原因很简单：LLM 并没有真正"读"过你的文档，它只是在海量互联网语料上训练出来的通用模型，对于特定领域、特定私有文档的理解能力非常有限。
RAG（检索增强生成） 正是解决这个问题的核心技术路线。简单来说，RAG 的工作流程是：当用户提问时，先从你的文档库中检索出最相关的片段，再把这些片段作为上下文喂给 LLM，让它"就着这些材料回答"。这样，LLM 的回答就有了事实依据，不再是凭空编造。
本文要介绍的 RAG Chatbot 项目（umbertogriffo/rag-chatbot，424★），就是这样一款开源 RAG 系统——它以 Markdown 文件集合作为知识库，通过 Chroma 向量数据库实现语义检索，再结合 llama.cpp 驱动的本地 LLM 提供精准问答。
图1：RAG Chatbot 系统架构概览
RAG Chatbot 由开发者 Umberto Griffo 创建并维护，采用了 Apache-2.0 开源许可证。项目充分利用了当前开源 AI 生态中最活跃的几项技术：llama.cpp（高性能 LLM 推理）、Chroma（轻量向量数据库）、Sentence Transformers（语义嵌入）以及 FastAPI（现代 Python Web 框架）。
从 GitHub Topics 来看，项目覆盖了 chatbot、rag、llm、llama3、qwen3-5、chromadb、gpu 等多个标签，表明其定位是面向开发者的、可本地部署的 RAG 解决方案，而非云端 API 调用类应用。
RAG Chatbot 的核心之一是 scripts/memory_builder.py 脚本。它负责将 docs/ 目录下的所有 Markdown 文件分块、向量化，然后存入 Chroma 向量数据库。分块策略支持自定义 chunk_size 和 chunk_overlap，并且实现了增量构建——对于已索引过的文档，只在内容变化时才重新计算向量，避免了重复计算。
项目还从 LangChain 中移植了 RecursiveCharacterTextSplitter，针对 Markdown 文件做了专门优化，能够按标题层级自然分块，保留文档结构信息。分块后调用 Sentence Transformers（默认使用 Jina Embeddings V5）将文本转为 768 维稠密向量，存入 Chroma 的持久化存储。
当用户提问时，系统通过向量相似度搜索（余弦距离）从 Chroma 中检索 Top-K 相关文档块（默认 K=2）。检索结果经过 tree-summarization 策略进行摘要融合，最终生成高质量的上下文 prompt，喂给 LLM 回答。
项目的一大亮点是不依赖 OpenAI 等云端 API，LLM 推理完全在本地运行。通过 llama.cpp 的 llama-server 组件（以 Docker 容器方式部署在 GPU 机器上），可以在本地高效运行 GGUF 格式的量化模型。默认支持 Qwen3-5、Llama3 等开源模型，支持配置推理参数（temperature、top_p、top_k 等）。
前端基于 React 19 + TypeScript + TailwindCSS 构建，提供了完整的对话界面，支持流式输出（WebSocket）、Markdown 渲染、多轮对话上下文记忆。Web UI 本身也是一个对话式 AI 助手，区别于传统文档问答——它能够记住之前的对话历史，提供连贯的多轮交互体验。
图2：检索与上下文构建流程
RAG Chatbot 的后端采用了经典的 FastAPI + SQLModel + SQLite 架构，模块划分清晰：
| 模块 | 职责 |
|---|---|
api/ | REST API 路由：chat、documents、health、chat_stream |
memory/ | 向量数据库封装、嵌入器、分块器 |
llm_providers/ | LLM 客户端（llama.cpp HTTP API 封装） |
services/ | 文档处理流水线（加载、分块、注册） |
models/ + schemas/ | Pydantic 数据模型 |
database.py | SQLModel + SQLite，WAL 模式 |
代码质量方面，项目使用 Poetry 管理依赖，Ruff 进行代码风格检查和格式化，pytest 全覆盖测试，预提交钩子（pre-commit）规范化 Git 工作流，整体工程化程度相当高。
值得特别一提的是，项目通过 alembic 管理数据库迁移，使用 sqlmodel 提供类型安全的 ORM 支持，文档索引元数据（文档ID、版本哈希）单独存储在 SQLite 中，与向量数据分离——这是一个务实的设计选择，兼顾了查询效率和可维护性。
部署 RAG Chatbot 需要具备以下条件：
部署步骤（借助 Makefile 和 docker-compose）：
# 1. 安装 Poetry 依赖
make install_dependencies
# 2. 初始化数据库
make migrate_db
# 3. 启动 llama.cpp 服务（GPU 模式）
make start_llama_server_cuda
# 4. 启动前后端
make start
docker-compose.yml 中配置了 llama.cpp:server-cuda-b9501 镜像，带有健康检查（/health 端点），自动挂载 models/ 目录加载 GGUF 模型文件。后端 FastAPI 通过环境变量 LLAMA_SERVER_BASE_URL 指向该服务。
快速启动的局限：llama.cpp 镜像只提供推理服务，不包含模型文件本身——用户需要自行下载 GGUF 模型（约 4-20GB 不等），放入 models/ 目录后 llama-server 才能启动。这是本地 LLM 部署的普遍门槛，RAG Chatbot 也不例外。
RAG Chatbot 并不是一个"开箱即用"的产品，部署和使用中有几个需要特别注意的点：
1. 模型文件需要自行下载
项目仓库中不包含 LLM 模型文件，用户需要从 HuggingFace 等渠道手动下载对应格式的 GGUF 文件（如 Qwen3-5、Llama3 等），这是本地 LLM 部署的基本门槛。
2. 文档格式目前仅限于 Markdown
ALLOWED_UPLOAD_EXTENSIONS = [".md"]，系统只接受 Markdown 文件，不支持 PDF、Word、HTML 等其他常见文档格式。虽然依赖链中有 unstructured 和 docling 库（支持多格式解析），但上传接口目前限制了只接受 Markdown。
3. GPU 依赖限制了部署灵活性
llama.cpp 的 GPU 推理需要 NVIDIA 显卡 + CUDA 环境，在没有 GPU 的机器上只能运行 CPU 模式，推理速度会大幅下降。
4. LLM 幻觉问题
README 明确警告：LLM 有时会生成幻觉或错误信息。RAG 只能减少幻觉（通过检索真实文档作为上下文），但无法完全消除。项目通过 tree-summarization 策略改善上下文质量，但用户仍需对 AI 输出保持审慎。
RAG 是 2024-2025 年企业 AI 落地最热门的架构模式之一。相比直接调用 GPT-4 API，RAG 系统将私有知识融入模型推理过程，具有数据隐私可控、领域知识精准、无 API 成本等优势。
RAG Chatbot 作为这一领域的代表性开源项目，展示了从文档处理→向量检索→LLM 推理→前端交互的完整工程实现。其模块化设计使其既可以作为学习 RAG 原理的参考项目，也可以作为二次开发的基础框架——比如替换向量数据库（Chroma → Qdrant/Weaviate）、替换 LLM（llama.cpp → vLLM/Ollama）、扩展文档格式支持等。
RAG Chatbot 是一款面向开发者和技术团队的本地 RAG 问答系统，具有以下核心优势：
主要门槛在于：需要 GPU 环境 + 手动下载模型文件 + 文档需转换为 Markdown 格式。对于有技术能力的团队而言，这是一个值得投入学习成本的高质量开源项目。