kplam
51dc8dc4f6
- FastAPI + Qdrant + Redis + Ollama 技术栈 - L1→L2→L3→chunk 四层分层检索（dense + sparse RRF 融合） - 文档三级总结与 2.5 级回退 - query 解析路由与分类 - /admin 管理页面
1.8 KiB
1.8 KiB
Checklist
配置与任务管理器
- config 含 ingest_max_concurrency(默认 2)/ingest_task_ttl_done(默认 86400)/ingest_task_ttl_failed(默认 604800)，.env.example 同步
- submit 返回 task_id 且状态初始 pending；后台任务按信号量限流（超额保持 pending）
- 状态机按流水线阶段推进：pending→summarizing→classifying→embedding→writing→done
- 成功后 result 为完整 IngestionResult；失败 error 含 stage 与 message，partial_summary（已产出总结）保留
- 状态写 Redis：done TTL 24h、failed TTL 7 天；Redis 故障降级内存字典且接口不报错
API
- POST /api/v1/documents 合法请求返回 HTTP 202 + {task_id, status:"pending"}，不再同步等待流水线
- POST 空文本等校验失败仍同步返回 code=1001（不进任务队列）
- GET /api/v1/documents/tasks/{task_id} 返回状态/时间戳；done 附 result；failed 附 error.stage/message
- 查询不存在 task_id 返回 code=1004
- 既有入库相关测试全部适配新契约且通过
管理页面
- 入库提交后展示 task_id 与状态，2s 轮询直至 done/failed
- done 展示 category/置信度/tags/总结层级/chunks_count；failed 展示 stage 与 message
- 轮询期间禁止重复提交；5 分钟超时停止轮询并提示
- 页面测试覆盖 tasks 轮询路径与新交互标记
集成与文档
- 内存闭环：提交→轮询 done→GET /documents/{doc_id} 可查→检索命中→删除 全通
- 失败路径：FakeOllama 抛错 → 任务 failed、stage 正确、failed TTL=7 天
- CLAUDE.md API 清单反映 POST /documents 202 异步与任务查询端点
uv run pytest全部通过；uv run ruff check app tests scripts无错误