基于 FastAPI 的知识库问答后端

这是一个我用 FastAPI 做的知识库问答后端项目。
除了基础的文档入库和问答功能，我还补充了引用返回、拒答逻辑、日志记录、统计接口和检索快照，尽量让它更像一个可以分析和迭代的后端系统。

这个项目目前主要关注知识库问答的后端链路，包括：文档入库、文本切分、embedding 检索、基于上下文回答、引用返回、日志与统计。

---

项目特点

• 支持文档入库和 .txt / .md 文件上传
• 支持文本切分与 overlap
• 支持 embedding 检索与 top_k 排序
• 支持 grounded / no_evidence 两类问答结果
• 支持 citation 返回
• 支持日志记录、helpful 反馈和统计接口
• 支持保存检索证据快照，便于后续回放与分析

---

技术栈

• Python
• FastAPI
• SQLAlchemy
• Pydantic
• SQLite
• Gemini API

---

主要功能

1. 文档管理

• 创建文档
• 上传 txt / md 文件入库
• 查看文档列表
• 查看单个文档详情
• 删除文档

2. 检索问答

• 文档入库后自动切分为多个 chunk
• 为 chunk 生成 embedding
• 使用余弦相似度进行检索
• 取 top_k 结果作为候选上下文
• 当最高分低于阈值时主动拒答

3. 引用与拒答

• grounded 时返回引用片段
• no_evidence 时不返回伪依据
• 返回 top_score、threshold_used、used_chunks 等信息，方便调试和分析

4. 日志与统计

• 记录 question、answer、status、mode、top_score、retrieved_chunk_ids
• 支持 helpful / unhelpful 反馈
• 统计接口支持查看：
  • 文档数、chunk 数、日志数
  • grounded / no_evidence / error 次数
  • helpful / unhelpful 次数
  • 平均 top_score
  • grounded / no_evidence / helpful 比例
  • 各种 mode 的次数

5. 检索快照

• 在日志中保存当时检索到的 chunk 快照
• 后续即使文档被删除，日志中仍然可以回放当时的检索证据

---

项目结构

.
├── main.py
├── config.py
├── database.py
├── models.py
├── schemas.py
├── routers/
│   ├── documents.py
│   ├── ask.py
│   └── log.py
└── services/
    └── retrieval.py

主要接口

文档相关

• POST /documents/
• POST /documents/upload
• GET /documents/
• GET /documents/{document_id}
• DELETE /documents/{document_id}

问答相关

• POST /ask

日志相关

• GET /logs/
• GET /logs/{log_id}
• PATCH /logs/{log_id}/feedback
• GET /logs/stats

项目截图

问答接口（grounded）

问答接口（no_evidence）

日志统计

测试示例

可以先上传一个测试文档，再提下面这些问题：

有依据问题

• FastAPI是什么？
• 默认阈值是多少？
• chunk_size 和 overlap 分别是多少？

无依据问题

• 最新款苹果手机是什么？

正常情况下：

• 前几个问题会返回 grounded
• 最后一个问题会返回 no_evidence

这个项目里我自己实现的部分

这个项目没有一开始就直接套现成知识库框架，而是先自己把几个核心环节走了一遍：

• 文本切分
• overlap 策略
• embedding 序列化与反序列化
• 余弦相似度检索
• top_k 排序
• 阈值拒答
• citation 返回
• 日志记录与统计
• 检索快照保存与回放

这样做的原因是，我更想把整个知识库问答后端的链路真正理解清楚，而不是只把框架接起来。

本地运行

1. 安装依赖

pip install -r requirements.txt

2. 配置 .env

DATABASE_URL=sqlite:///./test.db GEMINI_API_KEY=your_api_key RETRIEVAL_SCORE_THRESHOLD=0.72 CHUNK_SIZE=500 CHUNK_OVERLAP=100

3. 启动项目

python -m uvicorn main:app --reload