Repository navigation
版本
v6.27.0 (LockFairness) → v6.28.0 (LoadShedding) — 检索性能总纲（19 个提交合并发布）
成果
| 指标 | 基线 | v6.28.0 | 改善 |
|---|---|---|---|
| 检索中位（稳态） | 15.40s | 1.6~3.0s | 5~9x |
| 重启后首条 | 12.7s | ~2.5s | 5x |
| 超时率（稳态） | ~11% | 0% | 归零 |
| 并发 8 超时 | 8/8 | 0/8 | 归零 |
| 并发 12 超时 | 12/12 | 0/12 | 归零 |
| 503 峰值 | 78/h | 0 | 归零 |
并发场景下所有请求返回完整 20 条结果（不再退化为 9–10 条兜底）。
关键改动
- 社区成员 sidecar 索引 — 取成员 7,719ms → 3ms（2,166x）；构建 1,449s → 16.4s（88x）
（目标侧分批 + keyset 游标分页，绕开引擎 1 万行上限与 max_skip 限制） - 社区索引 100% 覆盖 + 按社区门控 — 社区扩展熔断误触 55% → 0
- reranker 长度分桶 — 2.08x，排序逐位一致（bit 级等价）；
max_length保持 512 - 本体同步前移到启动期 — 首条 6.87s → 2.51s
（根因：路由层 lazy sync 是预热盲区，预热直连QueryRouter.retrieve绕过api/routes/） - reranker 进程级并发闸门 — Semaphore + 有界 acquire + 优雅降级，无死锁
- 高并发显式卸载 — in-flight ≥ 4 时跳过社区扩展，超载请求快速返回未扩展的完整结果
（严格优于原「超时 6s → Cypher 兜底只给 9–10 条」）；低并发逐字节不变 - 社区相关性 TF-IDF 拟合缓存 — bit 级等价，固定语料 89x
关键依赖（版本要求 / 下载地址）
| 依赖 | 版本要求 | 说明 |
|---|---|---|
| Python | 3.11+ | |
| overgraph | >=0.17.0 | 存储引擎（纯 Rust 嵌入式图数据库，v6.0.0 起唯一后端）· https://overgraph.io |
| torch | 2.12.1+cpu（实测） | CPU 构建即可（本机无 GPU；CUDA 可选） |
| sentence-transformers | >=2.2.0（实测 2.7.0） | 重排模型加载 |
| scikit-learn | >=1.3.0 | 社区相关性 / BM25 |
| mcp | >=2.0.0 | MCP 协议支持 |
| 嵌入模型 | EmbeddedLLM/bge-m3-onnx-o2-cpu |
ONNX，MRL 截断 512 保 HNSW 契约；国内镜像 https://hf-mirror.com |
| 重排模型 | BAAI/bge-reranker-base |
CPU 推理（需本地 HF 缓存，离线加载） |
⚠️ graphlite_sdk不在 PyPI（仅迁移旧库时需要源码构建）；v6.0.0 起后端已是 OverGraph。
验证
- 全量测试 1783 passed / 1 skipped / 0 failed
- 生产实测（重启后）：稳态 0 超时、0 503；并发 4/8/12 全部 0 超时且返回完整 20 条
- 等价性：长度分桶排序逐位一致；缓存与原实现差
0.000e+00；卸载在低并发逐字节不变
已知结构性成本（未消除，已由卸载兜住）
- 每请求社区相关性 char-ngram 向量化 ~530ms（摘要集随查询变化，553–1509 条）
- reranker 单次 ~0.94s（CPU 串行）
方法论
本轮用 py-spy 抓栈替代猜测定位瓶颈；3 个假设被实测证伪（ONNX 加速 1.04x /
后台任务抢 CPU / 「93% 是词表拟合」），1 个方案被实测否决（全局词表：1.0x 且语义偏离 84.4%）。
过程与数字均有记录。