Initial commit: QMDSearch 分层信息检索服务

- FastAPI + Qdrant + Redis + Ollama 技术栈
- L1→L2→L3→chunk 四层分层检索（dense + sparse RRF 融合）
- 文档三级总结与 2.5 级回退
- query 解析路由与分类
- /admin 管理页面

.trae/specs/add-hierarchical-rag-pipeline/checklist.md

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