溯知：可追溯 RAG 知识库引擎

溯知是一个基于 FastAPI 的本地 RAG 知识库与中文调试工作台。它把多格式资料解析、OCR、切块、混合检索、来源引用、低相关拒答和自动化评估串成一条可运行、可观察的 AI 应用链路。

当前版本面向本地学习、面试演示和单机开发，不是可直接暴露到公网的多租户知识库服务。

访问 http://127.0.0.1:8000/demo/ 可以使用完整中文工作台；/docs 保留给接口调试。

截图使用本地 mock 模式生成，不包含真实 API Key。

核心能力

• 多格式解析：Markdown、TXT、PDF、DOCX、PNG、JPG、JPEG、WEBP。
• 本地 OCR：文本型 PDF 直接提取；扫描 PDF 和图片回退到 RapidOCR。
• 可追溯切块：优先按标题与句子边界切分，保留文档名、章节和 PDF 页码。
• 混合检索：BGE + FAISS 语义召回与 Jieba + BM25 关键词召回并行执行。
• RRF 融合：按排名融合两路候选，避免直接相加不同量纲的原始分数。
• 可选重排：支持 CrossEncoder；默认关闭，模型不可用时降级为 RRF。
• 拒答与引用：没有满足阈值的候选时拒答；命中时返回来源与各阶段分数。
• 版本化索引：新索引在临时目录构建，完成后切换 ACTIVE；删除时先重建成功再移除源文件。
• Tool Calling：知识库检索作为只读工具接入聊天流程；写入演示工具需要人工确认。
• 中文工作台：聊天问答、知识库管理、检索调试、评估中心。

RAG 数据流

flowchart LR
    A[上传资料] --> B[格式校验与解析]
    B --> C{文本是否足够}
    C -- 否 --> D[RapidOCR]
    C -- 是 --> E[标题与页码感知切块]
    D --> E
    E --> F[BGE Embedding]
    F --> G[FAISS 版本化索引]

    Q[用户问题] --> H[Jieba + BM25]
    Q --> I[BGE + FAISS]
    H --> J[RRF 排名融合]
    I --> J
    J --> K[可选 CrossEncoder 重排]
    K --> L{达到相关性要求}
    L -- 否 --> M[拒答]
    L -- 是 --> N[拼接来源上下文]
    N --> O[Mock 或 DeepSeek]
    O --> P[回答 + 文档/章节/页码引用]

Loading

后端分层

flowchart TD
    UI[中文工作台 / API Client] --> R[routers]
    R --> S[schemas]
    R --> V[services]
    V --> K[rag: ingestion / chunker / index / evaluation]
    V --> T[tools]
    V --> M[memory]
    V --> L[llm_client]
    L --> A[ProviderAdapter]
    A --> P[Mock / OpenAI-compatible API]
    V --> D[data / storage]

Loading

技术栈

模块	技术
API 与校验	FastAPI、Pydantic、httpx
向量检索	BAAI/bge-small-zh-v1.5、sentence-transformers、FAISS、NumPy
关键词检索	Jieba、rank-bm25
文档解析	pypdfium2、python-docx、Pillow
OCR	RapidOCR、ONNX Runtime
模型适配	Mock、DeepSeek / OpenAI-compatible API、ProviderAdapter
前端	原生 HTML、CSS、JavaScript
测试	pytest、FastAPI TestClient

快速开始

推荐 Python 3.11 或 3.12。首次建立索引时会下载 BGE 模型，需要网络和约 100 MB 以上磁盘空间；实际大小取决于模型版本与缓存格式。

git clone https://github.com/DZH166/ai_study_assistant_api.git
cd ai_study_assistant_api
python -m venv .venv

激活虚拟环境：

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate

安装并配置：

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

复制 .env.example 为 .env，默认使用 mock 模型；不要提交 .env。

# Windows PowerShell
Copy-Item .env.example .env

# macOS / Linux
cp .env.example .env

启动：

python -m uvicorn app.main:app --reload --port 8000

访问：

• 中文工作台：http://127.0.0.1:8000/demo/
• OpenAPI 文档：http://127.0.0.1:8000/docs
• 健康检查：http://127.0.0.1:8000/health

前端使用相对 API 路径，必须通过 FastAPI 的 /demo/ 访问，不能直接双击 web_demo/index.html。

配置

主要配置见 .env.example：

USE_MOCK_LLM=true
RAG_STORAGE_DIR=storage/knowledge_bases
RAG_UPLOAD_DIR=storage/uploads
RAG_MODEL_CACHE_DIR=
JIEBA_CACHE_DIR=
RAG_EMBEDDING_MODEL=BAAI/bge-small-zh-v1.5
RAG_ENABLE_RERANKER=false
RAG_ENABLE_OCR=true

模型和 Jieba 缓存默认使用：

• ~/.cache/huggingface
• ~/.cache/jieba

可以通过 RAG_MODEL_CACHE_DIR 和 JIEBA_CACHE_DIR 指向其他磁盘。Windows 用户也可以把缓存放到非系统盘。

切换 DeepSeek 时，只在本机 .env 中设置：

USE_MOCK_LLM=false
ENABLE_MOCK_FALLBACK=false
LLM_PROVIDER=deepseek
LLM_API_KEY=your-api-key
LLM_BASE_URL=https://api.deepseek.com/v1
LLM_MODEL_NAME=deepseek-chat

四个工作区

1. 聊天问答：多场景聊天、多轮摘要记忆、Tool Calling、来源引用。
2. 知识库管理：上传、去重、删除、重建和 OCR 状态。
3. 检索调试：分别查看 BM25、向量、RRF 与重排候选。
4. 评估中心：运行固定 JSONL 样例集，查看 Recall@K、MRR、来源命中率和拒答准确率。

API 概览

Method	Path	作用
GET	/health	服务与知识库状态
GET	/knowledge-base/documents	查看公开文档信息
POST	/knowledge-base/documents/upload	上传、解析并重建索引
DELETE	/knowledge-base/documents/{id}	重建成功后删除上传资料
POST	/knowledge-base/search/debug	查看检索阶段候选
POST	/knowledge-base/evaluation/run	运行内置评估集
POST	/knowledge-base/ask	基于资料问答与拒答
POST	/chat	多轮聊天与 Tool Calling
POST	/chat/stream	应用层 SSE 事件链路
POST	/extract/study-note	学习笔记结构化提取
POST	/tools/confirm	写入演示工具的人工确认

评估

内置数据集位于 data/evaluation/rag_eval_v1.jsonl，当前只有 6 条回归样例：5 条有相关来源的问题和 1 条无答案拒答问题。

python -m pytest -q tests
python scripts/verify_document_formats.py

指标口径：

• Recall@K、MRR、来源命中率只对有 relevant_paths 的正样本计算。
• 拒答样本单独计入拒答准确率，不会抬高检索指标。
• 该评估用于检查本仓库示例知识库是否回归，不代表大规模公开 Benchmark。

安全与隐私

• .env、会话 JSON、上传资料、FAISS 索引和模型缓存均不应提交。
• 公开文档接口不返回本机绝对路径和文件 checksum。
• 上传限制扩展名、文件魔数、大小、PDF 页数和图片像素。
• 模型只能提出工具调用；后端负责白名单、Pydantic 参数校验和写入确认。
• 当前没有账号、认证、租户隔离、服务端速率限制或配额，不要直接部署到公网。
• 删除上传资料时会先构建新索引；成功后删除源文件，并清理包含旧文本的历史索引版本。

当前限制

• Reranker 默认关闭；仓库只保证未启用时的 BM25 + 向量 + RRF 链路。
• OCR 质量受清晰度、字体、版面和复杂表格影响。
• .docx 已支持，旧 .doc 需要先转换。
• /chat/stream 当前在完整回答生成后按应用层事件分段，不是真实模型 token streaming。
• OpenAI-compatible 客户端目前是同步 HTTP 调用，尚未实现 async 并发优化。
• save_review_tasks 是工具权限与确认流程演示，没有写入真实业务数据库。
• 索引适合单进程本地演示；多进程部署需要共享存储、任务队列和并发控制。

项目结构

app/
  core/                  配置
  routers/               Chat、知识库、提取与工具确认接口
  schemas/               请求与响应契约
  services/              业务编排、记忆和知识库问答
  rag/                   解析、切块、Embedding、混合索引、评估
  llm_client/            Mock 与 OpenAI-compatible 适配
  tools/                 工具白名单、参数与权限
  data/                  会话与确认状态
web_demo/                中文工作台
scripts/                 集成演示和多格式验证
data/raw/                内置示例资料
data/evaluation/         版本化评估样例
tests/                   单元和端到端测试
docs/history/            早期 Module 学习演进记录

许可证与第三方说明

项目源码使用 MIT License。第三方依赖和模型仍遵循各自许可证：

• pypdfium2：BSD-3-Clause / Apache-2.0；其 PDFium 二进制包含独立第三方许可。
• BAAI/bge-small-zh-v1.5 与可选 reranker：使用前请核对对应模型卡与许可证。
• RapidOCR：Apache-2.0；其 ONNX 模型和依赖遵循各自许可。

本仓库不重新分发 Hugging Face 模型文件、PDFium 外部资源或用户上传资料。

历史

项目从聊天 API 逐步演进为当前 RAG 引擎。早期学习过程和旧项目包装稿保留在 docs/history，仅作为演进记录，不代表当前功能边界。