Knowledge Base QA: 本地 RAG 知识库问答系统

一个面向学习与工程实践的本地知识库问答系统。项目从基础 RAG Demo 演进为具备文档接入、增量索引、混合检索、证据门控、评估调优、多轮聊天和 Agent API 接入能力的完整原型。

当前定位：本地学习版 / 小规模团队原型 / Agent 知识库工具服务。

核心能力

• 多格式文档接入：支持 PDF、Word、Markdown、图片文件；扫描版 PDF 或图片可通过 OCR 提取文本。
• 工程化索引链路：基于 SQLite 元数据库管理文档、索引任务、索引版本、chunk 状态和查询日志。
• 增量索引与版本化：基于 file_hash、chunk_hash、config_hash 复用未变化内容，索引成功后再切换 active version。
• Chroma 双模式：支持 Chroma Local 与 Chroma Server，推荐使用 Server 模式降低多进程访问 sqlite 文件导致的锁冲突。
• 多用户 / 多知识库隔离：按 user_id + knowledge_base_id + index_version 过滤文件、metadata 和向量检索范围。
• 检索质量优化：支持向量检索、BM25、Hybrid Search、summary 粗筛、父文档合并、句子窗口、上下文选择器和可选 rerank。
• 柔性问题理解：根据问题类型自动选择检索策略，例如事实类走句子窗口，总结/解释类走父文档合并，只检索问题不调用 LLM。
• 证据门控与拒答：结合距离、hybrid 分数、关键词覆盖、实体覆盖、上下文充分性等信号判断是否应回答。
• 多轮聊天：支持 context_only 与 condense_plus_context，可把追问压缩成独立检索问题。
• Agent API 接入：通过 FastAPI 提供 /v1/retrieve、/v1/answer、/v1/chat、/v1/route、/v1/index/status 等接口。
• 评估与调参体系：支持 BEIR、RAGAS、OOD gate、chunk 参数调优、prompt 调优和检索参数调优。

技术栈

• 语言与界面：Python、Streamlit、FastAPI、Pydantic
• 文档处理：PyMuPDF、python-docx、Markdown、OCR.Space、Tesseract OCR
• 向量检索：Chroma、Sentence Transformers
• 关键词检索：BM25、Hybrid Search、RRF / relative score fusion
• 模型接入：Ollama、本地模型、OpenAI 兼容 API、DeepSeek API
• 工程与评估：SQLite、pytest、Docker、BEIR、RAGAS、uv

系统流程

文档上传 / 本地文件
  -> 文本解析 / OCR
  -> 文本清洗
  -> chunk 切分
  -> summary / parent / sentence 索引
  -> embedding
  -> Chroma 向量库
  -> SQLite 元数据库记录状态

用户问题
  -> 柔性问题理解
  -> 聊天追问压缩 / 查询改写
  -> summary 粗筛
  -> vector + BM25 hybrid 检索
  -> 父文档合并 / 句子窗口
  -> context selector
  -> evidence gate
  -> LLM 回答或拒答
  -> 引用来源 + diagnostics + query log

快速开始

1. 安装依赖

推荐使用 uv：

uv sync

如果没有 pyproject.toml 或锁文件，也可以使用：

uv pip install -r requirements.txt

2. 启动 Chroma Server

推荐打开一个单独终端运行：

uv run chroma run --path .\data\chroma_server --host localhost --port 8000

3. 启动 Streamlit 页面

再打开第二个终端运行：

$env:CHROMA_MODE="server"
$env:CHROMA_HOST="localhost"
$env:CHROMA_PORT="8000"
uv run streamlit run app.py

打开 Streamlit 给出的本地地址后：

1. 在侧边栏确认 User ID 和 Knowledge Base ID。
2. 上传 PDF、Word、Markdown 或图片。
3. 点击“保存上传文件”。
4. 点击“提交增量索引任务”或“提交全量重建任务”。
5. 索引完成后开始提问。

模型配置

项目支持两类模型来源：

• Ollama：本地模型，例如 qwen2.5:7b。
• OpenAI 兼容 API：云端或自建模型服务，例如 DeepSeek。

示例 .env：

MODEL_PROVIDER=OpenAI兼容API
MODEL_API_BASE_URL=https://api.deepseek.com
MODEL_API_KEY=你的_API_KEY
OPENAI_COMPATIBLE_MODEL=deepseek-chat

CHROMA_MODE=server
CHROMA_HOST=localhost
CHROMA_PORT=8000

.env 已被 .gitignore 忽略，请不要把真实 API Key 提交到仓库。

Agent API 使用

启动 API 服务：

uv run uvicorn src.api_server:app --host 127.0.0.1 --port 8010

常用接口：

GET  /health
POST /v1/route
POST /v1/retrieve
POST /v1/answer
POST /v1/chat
POST /v1/index/status

示例请求：

curl -X POST http://127.0.0.1:8010/v1/answer `
  -H "Content-Type: application/json" `
  -d "{\"question\":\"这篇文档的核心结论是什么？\",\"user_id\":\"user_xxx\",\"knowledge_base_id\":\"kb_001\"}"

API 会返回：

• answer：答案或拒答。
• sources：引用来源。
• diagnostics：检索查询、候选数量、上下文选择、证据门控、问题理解等调试信息。

评估与调参

运行单元测试：

.\.venv\Scripts\python.exe -m pytest tests -p no:cacheprovider

运行 BEIR 检索评估：

.\.venv\Scripts\python.exe eval\prepare_beir_benchmark.py --dataset scifact
.\.venv\Scripts\python.exe eval\index_beir_benchmark.py --dataset scifact --chroma-mode server --chroma-host localhost --chroma-port 8000
.\.venv\Scripts\python.exe eval\run_beir_eval.py --dataset scifact --configs vector,bm25,hybrid --chroma-mode server --chroma-host localhost --chroma-port 8000

运行 OOD 拒答评估：

.\.venv\Scripts\python.exe eval\run_ood_gate_eval.py --benchmark scifact_cross_beir --configs strict,balanced,loose --chroma-mode server --chroma-host localhost --chroma-port 8000

运行 RAGAS 评估前需要安装可选依赖：

uv pip install -r eval\requirements-ragas.txt

项目结构

app.py                         Streamlit 页面
src/api_server.py              FastAPI 服务层，供 Agent 调用
src/question_understanding.py  柔性问题理解与检索策略路由
src/search_pipeline.py         在线检索 Pipeline
src/retriever.py               Chroma + BM25 + Hybrid 检索
src/context_selector.py        上下文选择器
src/context_expansion.py       父文档合并与句子窗口
src/evidence_gate.py           证据门控与拒答判断
src/index_pipeline.py          离线索引 Pipeline
src/index_tasks.py             索引任务状态与恢复
src/metadata_store.py          SQLite 元数据库
src/summaries.py               文档 summary 索引
src/llm.py                     Ollama / OpenAI 兼容 API 调用
src/prompts.py                 Prompt 模板层
eval/                          检索、RAGAS、OOD、chunk、prompt 调参脚本
tests/                         单元测试与集成测试
docs/                          Agent 接入与 API 文档

当前验证状态

最近一次核心测试：

81 passed

覆盖模块包括：

• API Server
• Chat Engine
• Context Expansion
• Context Selector
• Evidence Gate
• Metadata Store
• Retriever
• Search Pipeline
• Question Understanding
• Prompt Layer
• OCR / Splitter / Summaries

适合展示的项目亮点

• 不是简单调用 LLM，而是完整实现了可索引、可评估、可拒答、可接入 Agent 的 RAG 工程系统。
• 支持从本地 Demo 到 API 服务化的演进路径。
• 通过 BEIR / RAGAS / OOD benchmark 建立检索和拒答评估闭环。
• 使用索引版本、增量索引和 Chroma Server 解决重建中断、文件锁、多进程访问等工程问题。

注意事项

• 当前仍是本地学习版，不包含正式登录鉴权、权限系统和生产级部署。
• OCR.Space 会上传图片到云端 OCR 服务，请勿用于敏感文档。
• Chroma Server 推荐作为默认运行方式；Local 模式更适合单进程本地测试。
• .env、data/、评估输出和个人生成文件不会提交到 GitHub。