本地 PDF 问答 RAG：文档解析、分块、向量化、混合检索、重排序到 LLM 生成

方案简介

Local PDF Chat RAG 是一套透明、可运行的本地文档问答 RAG 参考实现，面向希望理解检索增强生成完整链路的开发者。它覆盖从文档解析、文本分块、向量化、FAISS 向量检索、BM25 关键词检索、混合检索、重排序到 LLM 回答生成的全流程，每个环节都拆分为可独立阅读、测试和替换的模块。

方案同时提供 Gradio Web UI 和 FastAPI REST API 双入口，支持本地 Ollama、SiliconFlow 以及 OpenAI-compatible API 多种模型后端。适合用于学习 RAG 原理、做教学实验和二次开发参考。项目明确说明是教学与实验用途的参考实现，不是开箱即用的生产级知识库服务。

亮点与能力

• 链路透明：核心步骤按 RAG 执行顺序拆分，便于学习和调试。
• 混合检索：结合 FAISS 向量检索和 BM25 关键词检索。
• 可选重排序：支持 CrossEncoder 或基于模型的相关性评分。
• 多模型后端：支持本地 Ollama、SiliconFlow 以及 OpenAI-compatible API。
• 多种文档格式：支持 PDF、TXT、Markdown、DOCX、XLS/XLSX 和 PPTX。
• 双入口：提供 Gradio Web UI 和 FastAPI REST API。
• 可验证维护：包含自动化测试、GitHub Actions CI、贡献指南和安全报告流程。

组成与分工

• Gradio：提供 Web UI 交互界面（rag_demo.py）。
• FastAPI：提供 REST API 接口（api_router.py）。
• FAISS：向量索引与向量检索（core/vector_store.py）。
• BM25：关键词检索索引（core/bm25_index.py）。
• CrossEncoder：可选的重排序方式，对混合检索结果做相关性重排（core/reranker.py）。
• Ollama / SiliconFlow / OpenAI-compatible API：LLM 生成与向量化后端，通过 .env 配置。
• core/ 模块：document_loader（文档解析）、text_splitter（文本分块）、embeddings（向量化）、retriever（混合与递归检索）、generator（上下文和回答生成）。

前置要求

• Python 3.10 环境
• 依赖安装：

bash
git clone https://github.com/weiwill88/Local_Pdf_Chat_RAG.git
cd Local_Pdf_Chat_RAG

python3.10 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip
pip install -r requirements.txt

• 模型后端至少配置一种：SiliconFlow API Key、OpenAI-compatible 服务密钥，或本地启动 Ollama 并拉取模型。

实施步骤

1. 创建环境

克隆仓库并创建虚拟环境，安装依赖：

bash
git clone https://github.com/weiwill88/Local_Pdf_Chat_RAG.git
cd Local_Pdf_Chat_RAG

python3.10 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip
pip install -r requirements.txt

2. 配置一个模型后端

bash
cp example.env .env

编辑 .env，至少完成下面一种配置：

• 设置 SILICONFLOW_API_KEY；
• 设置 MAGICK_API_KEY、服务地址和模型名称；
• 本地启动 Ollama，并拉取 .env 中配置的模型。

3. 启动 Web UI

bash
python rag_demo.py

4. 启动 REST API

bash
python api_router.py

主要接口：

• GET /api/status：运行状态与后端配置状态；
• POST /api/upload：上传并处理文档；
• POST /api/ask：基于已处理文档提问。

使用与配置要点

• 配置文件为 .env，从 example.env 复制而来，常用变量包括：
• SILICONFLOW_API_KEY / SILICONFLOW_MODEL_NAME：SiliconFlow API 密钥与模型 ID；
• MAGICK_API_KEY / MAGICK_API_URL / MAGICK_MODEL_NAME：OpenAI-compatible 服务配置；
• OLLAMA_MODEL_NAME：本地 Ollama 模型名称；
• SERPAPI_KEY：可选联网搜索密钥；
• RERANK_METHOD：cross_encoder 或 llm。
• Web UI 默认地址 http://127.0.0.1:17995，端口被占用时会依次尝试 17996–17999。
• 验证成功：通过 GET /api/status 查看运行状态与后端配置状态。

注意事项与常见问题

• PDF 采用文本层提取，不包含通用 OCR；扫描件需要先做 OCR。
• Excel 与 PPT 的解析以文本提取为主，不保留完整视觉布局。
• 索引当前保存在进程内存中，服务重启后需要重新处理文档。
• 首次使用向量或重排序模型时可能需要下载模型文件。
• 联网搜索和云端模型会把相应查询发送到第三方服务，请先确认数据边界。
• 密钥只保存在本地 .env 中，请勿提交真实密钥。
• 本仓库是教学与实验用途的参考实现，用于真实业务前需补充身份鉴权、租户隔离、持久化、评测、安全审计和部署治理。

优缺点

• ✓ 链路透明，便于学习和调试
• ✓ 支持本地 Ollama 离线运行
• ✕ 索引在内存中，重启需重新处理
• ✕ 扫描件 PDF 不含 OCR

出处

本方案挖掘自开源项目 weiwill88/Local_Pdf_Chat_RAG，方案内容与实施命令均来自其 README 原文。