yexixian0769/rag-knowledge-base

RAG Knowledge Base Assistant

一个基于 FastAPI、ChromaDB 和 OpenAI 兼容 API 的 RAG 知识库问答系统。

项目面向 GitHub 展示、AI 工程师简历和面试演示，重点呈现从文档上传到带引用流式回答的完整、透明、可解释的 RAG 工程链路。

当前状态：文档上传、解析、切片、Embedding、ChromaDB 检索、引用、流式问答和历史会话均已接通。

开发原则

• —MVP 可运行优先，简单实现优先。
• —不为未来需求提前增加抽象层。
• —ChromaDB 直接集成，不建设向量数据库适配器。
• —不提前设计多知识库、多租户、Agent、LangGraph 或插件系统。
• —实现顺序固定为：

上传 -> 解析 -> 切片 -> Embedding -> ChromaDB -> 检索 -> 引用 -> 流式回答

项目特性

• —单知识库模式，启动时自动初始化默认知识库
• —支持 PDF、DOCX、Markdown、TXT
• —支持识别 DOCX 内嵌图片中的中英文文字
• —文档解析、文本切片、Embedding 和 ChromaDB 本地索引
• —向量检索与相关度阈值过滤
• —基于 SSE 的流式回答
• —文档名称、页码或段落位置引用
• —SQLite 持久化文档状态与历史会话
• —本地 Bootstrap 轻量界面，无独立前端工程或 CDN 依赖
• —知识库无依据时拒绝确定性回答
• —失败文档重新索引、文档删除与确认提示
• —Chat、Embedding 和 ChromaDB 配置状态检查

技术栈

RAG 流程

flowchart LR
    A["上传文档"] --> B["解析正文"]
    B --> C["文本切片"]
    C --> D["生成 Embedding"]
    D --> E["写入 ChromaDB"]
    F["用户问题"] --> G["问题 Embedding"]
    G --> H["向量检索"]
    E --> H
    H --> I["可选重排"]
    I --> J["构建上下文"]
    J --> K["流式生成回答"]
    K --> L["展示引用来源"]

项目结构

rag-knowledge-base/
├── app.py                    # FastAPI 入口与页面路由
├── config.py                 # 环境变量配置
├── requirements.txt
├── README.md
├── PRD.md
├── .env.example
├── data/
│   ├── uploads/              # 上传原文件
│   └── chroma_db/            # ChromaDB 持久化数据
├── services/
│   ├── document_loader.py    # 文档解析
│   ├── ocr_service.py        # DOCX 内嵌图片 OCR
│   ├── text_splitter.py      # 文本切片
│   ├── embedding_service.py  # Embedding
│   ├── vector_store.py       # ChromaDB 直接集成
│   ├── conversation_store.py # 会话与消息持久化
│   ├── llm_service.py        # 流式模型调用
│   └── rag_service.py        # RAG 流程编排
├── templates/
│   ├── base.html
│   ├── index.html
│   ├── upload.html
│   ├── chat.html
│   └── documents.html
├── static/
│   ├── style.css
│   └── main.js
└── docs/
    └── database-design.md

快速开始

1. 环境要求

• —Python 3.11 或 3.12
• —同时支持聊天和 Embedding 的 OpenAI 兼容 API

Windows 推荐使用 Python 3.11。项目固定使用 ChromaDB 0.4.24、 NumPy 1.26.4 和 ONNX Runtime 1.16.3，以避免新版原生索引组件的兼容问题。

2. 创建虚拟环境

Windows PowerShell：

python -m venv .venv
.\.venv\Scripts\Activate.ps1

macOS/Linux：

python3 -m venv .venv
source .venv/bin/activate

3. 安装依赖

python -m pip install --upgrade pip
pip install -r requirements.txt

4. 配置环境变量

Windows PowerShell：

Copy-Item .env.example .env

macOS/Linux：

cp .env.example .env

至少配置：

OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://api.siliconflow.cn/v1
CHAT_MODEL=Pro/deepseek-ai/DeepSeek-V3.2
CHAT_FALLBACK_MODEL=Qwen/Qwen2.5-7B-Instruct
EMBEDDING_MODEL=BAAI/bge-m3

5. 启动应用

uvicorn app:app --reload

访问：

• —首页：<http://127.0.0.1:8000>
• —健康检查：<http://127.0.0.1:8000/api/v1/health>
• —API 文档：<http://127.0.0.1:8000/docs>

建议先上传仓库中的 test.txt，等待文档显示“已索引”，再进入问答页提问：

RAG 是什么？
这个项目使用了哪些技术？

模型和 Embedding 连接状态可在设置页检查：

• —设置页：<http://127.0.0.1:8000/settings>

Hugging Face Spaces 部署

项目根目录已包含 Dockerfile，可直接部署到 Docker Space。镜像默认使用 7860 端口并开启公开演示模式。

1. 1.将仓库文件推送到已创建的 Hugging Face Docker Space。
2. 2.在 Space 的 Settings -> Variables and secrets 中添加 Secret：

OPENAI_API_KEY=your-api-key

1. 1.等待 Space 完成构建。首次启动会自动导入 docs/demo-knowledge-base.md 并建立索引。
2. 2.打开 /api/v1/health，确认返回 status: ok。
3. 3.进入问答页，使用首页提供的示例问题验证流式回答和引用来源。

演示模式会隐藏模型设置、保护预置文档，并限制公开上传和问答频率。 Space 重启后本地 SQLite、上传文件和 ChromaDB 数据可能重置，预置文档会自动恢复。

如需覆盖镜像内的公开配置，可在 Space Variables 中设置：

OPENAI_BASE_URL=https://api.siliconflow.cn/v1
CHAT_MODEL=Pro/deepseek-ai/DeepSeek-V3.2
CHAT_FALLBACK_MODEL=Qwen/Qwen2.5-7B-Instruct
EMBEDDING_MODEL=BAAI/bge-m3
DEMO_MODE=true

配置说明

问答检索链路采用查询改写、ChromaDB 多路向量召回、SQLite FTS5 关键词召回、RRF 融合和轻量重排。DOCX 会合并相邻段落，避免标题、 问题和答案被拆成互不相关的短切片。

完整配置见 .env.example。

开发路线

• —[x] 产品需求文档
• —[x] 数据库设计
• —[x] 项目目录骨架
• —[x] 配置与依赖清单
• —[x] SQLite 文档状态存储
• —[x] 文档上传、解析和切片
• —[x] DOCX 内嵌图片 OCR
• —[x] Embedding 与 ChromaDB 索引
• —[x] 向量检索与相关度过滤
• —[x] SSE 流式问答与引用
• —[x] 历史会话保存、继续和删除
• —[x] 模型健康检查与失败索引重试
• —[x] 核心单元测试和演示数据
• —[ ] 可选重排服务
• —[x] Docker 与 Hugging Face Spaces 演示模式
• —[ ] GitHub 演示截图与视频链接

设计文档

• —产品需求文档
• —数据库设计

MVP 边界

MVP 不包含登录、权限、多租户、团队协作、多知识库、Agent、LangGraph、网页抓取、图片语义理解、Excel/CSV、其他向量数据库或向量库抽象层。当前 OCR 仅识别 DOCX 内嵌图片中的文字。

License

建议在首次公开发布前选择并添加开源许可证，例如 MIT License。