kplam
51dc8dc4f6
- FastAPI + Qdrant + Redis + Ollama 技术栈 - L1→L2→L3→chunk 四层分层检索（dense + sparse RRF 融合） - 文档三级总结与 2.5 级回退 - query 解析路由与分类 - /admin 管理页面
2.7 KiB
2.7 KiB
Checklist
配置与模型
- config 含 taxonomy 路径、分类置信度阈值、各层 top-k（l1/l2/l3）、sparse 开关、缓存 TTL，.env.example 同步更新
- taxonomy 默认配置文件存在且含 uncategorized 兜底类，加载校验函数可用
- CategoryResult（主类+多标签+置信度）、ChunkModel、SearchRequest/SearchResponse/SearchHit 模型齐备且有类型注解
入库链路
- L2 大纲优先使用文档原生标题树，无结构文本回退 LLM 生成，2.5 级回退逻辑不受影响
- 分类器输出主类+多标签+置信度，低置信文档归入 uncategorized，不再硬编码 default
- chunk 按标题树切分并记录 section_path，超长 section 二次切分，短文本单 chunk
- 入库后 Qdrant 四层集合均有数据：doc_l1/doc_l2/doc_l3/chunks，payload 含 doc_id/category/tags/section_path
- chunks 与 doc_l1 同时携带 dense 与 sparse 向量，sparse 由本地分词+BM25 生成、无外部模型依赖
- 入库失败时返回明确错误码，已生成总结不丢失（可重试）
检索链路
- query 解析以 JSON 约束输出意图类目+置信度+rewrite+关键词，解析失败自动降级全库检索
- 分类路由：高置信按主类硬过滤，多标签软召回生效，低置信/超类目上限走全库兜底
- 三级文档检索沿 L1→L2→L3→chunk 逐层收敛，chunk 候选仅来自 L3 命中范围
- 2.5 级文档 L1 命中后直进 L3/chunk 层
- L2/L3 空召回时回退上一层范围直搜 chunk，不返回空结果
- chunk 层 dense+sparse 双路召回经 RRF 融合，返回 final_k 个结果
- 检索结果 text 字段为原文 chunk，摘要仅以 doc_summary 上下文标注出现
- Redis 缓存命中时重复 query 不重复调用 Ollama/Qdrant；Redis 宕机检索仍可用
API
- POST /api/v1/documents 入库成功返回 document_id、分类结果、总结层级
- POST /api/v1/search 返回统一格式 {"code":0,"data":...,"message":"ok"}
- GET /api/v1/knowledge/categories 返回 taxonomy 类目列表
- 错误码符合 0=成功、1xxx=客户端错误、2xxx=服务端错误规范
评测
- 回归集样例 ≥5 篇文档，每篇含应检出/不应检出 query 及 golden 标注
- 评测脚本输出 Entity Recall（L1/L3）、Hallucination Rate、Routing F1、Pruning Loss、Precision@5/Recall@10
- 报告含平铺 chunk baseline 对比，未达门槛项显式标出
端到端
- docker compose 环境下 入库→检索→评测 全链路跑通（本机以内存 Qdrant 集成测试 + 真实 Ollama 冒烟等效验证，NAS docker 部署待用户侧执行）
uv run pytest全部通过