feat: add chunk BM25 and reproducible RRF retrieval #14

2026-10-16T13:58:03+08:00

Kronecker commented

2026-10-16 13:58:03 +08:00

当前关键词基线按知识条目排序，向量模式按 chunk 排序，不能直接用来比较或融合。本改动补充 chunk 正文 BM25，并在同一当前文本/向量发布及分类范围内实现 RRF，保留原条目接口。

范围与审阅

T07 检索阶段；从已合入 PR #11/#13 的最新 dev 创建 feat/backend-rrf-retrieval，无待审叠加依赖。Refs #5 的认证后端已合入，本轮检查无新意见；前端/浏览器验收仍待交接。独立 T07 Issue 尚待补建，本 PR 和任务板保留追踪记录。
POST /api/retrieval/chunks 为可独立调用的正文 BM25，不要求本地模型；POST /api/retrieval/hybrid 为等权 RRF，固定 k=60，每路候选默认50、最多200且不小于 top_k。
保存两路完整候选排名/原始分数、最终命中的两路贡献、模型空间、语料指纹、文本/向量发布代数、切分/分词/BM25配置及出处/原文偏移。同分稳定排序；条目与 chunk 口径明确区分。
查询编码在发布锁外，编码后复核审核语料、空间及版本。两路计算和检索历史写入同一受锁事务；模型/竞争/数据库失败不保存部分结果，关键词一路为空时明确记录。
历史支持 keyword/vector/keyword_chunks/hybrid 四种类型；管理历史仍限管理员。同步前端调用与类型，未改页面。完整字段及验收边界见 docs/HYBRID_API.md。

验证

backend/.venv/bin/python -m pytest -q backend/tests：180 passed, 1 skipped。skip 为须显式启用的真实模型专项。
真实固定 BGE small CPU 专项另1 passed：HTTP/pgvector/混合两路排名及后端重启后结果和历史一致。全部资料为合成测试，未声称领域质量或论文分数。
新增27项轻量用例覆盖手算BM25/RRF、候选截断/缺席/同分、相同chunk与分类、出处、历史、权限、锁外编码、版本竞争、损坏快照、失败回滚和容量。
ruff check、ruff format --check、frontend npm run build、git diff --check：通过。

数据库、容量与回滚

无需新迁移，仍为0006_vectors；每份发布最多2000 chunks，同步精确排序会短暂串行化目录写入。模型离线固定空间，不静默截断token，也不以占位推理替代真实向量。

回滚代码即可撤回两个新增接口。旧历史响应模型不认识两个新mode，回滚时须限制旧历史端点或备份保留新模式记录，避免解析失败；无需降级数据库，不应无备份删除记录。Docker容器、前端浏览器、正式模型冻结、核验领域语料/问题集与RAG留待后续验收。请按团队权限审阅；本阶段合入dev后再推进下一阶段。

当前关键词基线按知识条目排序，向量模式按 chunk 排序，不能直接用来比较或融合。本改动补充 chunk 正文 BM25，并在同一当前文本/向量发布及分类范围内实现 RRF，保留原条目接口。 ## 范围与审阅 - T07 检索阶段；从已合入 PR #11/#13 的最新 dev 创建 feat/backend-rrf-retrieval，无待审叠加依赖。Refs #5 的认证后端已合入，本轮检查无新意见；前端/浏览器验收仍待交接。独立 T07 Issue 尚待补建，本 PR 和任务板保留追踪记录。 - POST /api/retrieval/chunks 为可独立调用的正文 BM25，不要求本地模型；POST /api/retrieval/hybrid 为等权 RRF，固定 k=60，每路候选默认50、最多200且不小于 top_k。 - 保存两路完整候选排名/原始分数、最终命中的两路贡献、模型空间、语料指纹、文本/向量发布代数、切分/分词/BM25配置及出处/原文偏移。同分稳定排序；条目与 chunk 口径明确区分。 - 查询编码在发布锁外，编码后复核审核语料、空间及版本。两路计算和检索历史写入同一受锁事务；模型/竞争/数据库失败不保存部分结果，关键词一路为空时明确记录。 - 历史支持 keyword/vector/keyword_chunks/hybrid 四种类型；管理历史仍限管理员。同步前端调用与类型，未改页面。完整字段及验收边界见 docs/HYBRID_API.md。 ## 验证 - backend/.venv/bin/python -m pytest -q backend/tests：180 passed, 1 skipped。skip 为须显式启用的真实模型专项。 - 真实固定 BGE small CPU 专项另1 passed：HTTP/pgvector/混合两路排名及后端重启后结果和历史一致。全部资料为合成测试，未声称领域质量或论文分数。 - 新增27项轻量用例覆盖手算BM25/RRF、候选截断/缺席/同分、相同chunk与分类、出处、历史、权限、锁外编码、版本竞争、损坏快照、失败回滚和容量。 - ruff check、ruff format --check、frontend npm run build、git diff --check：通过。 ## 数据库、容量与回滚无需新迁移，仍为0006_vectors；每份发布最多2000 chunks，同步精确排序会短暂串行化目录写入。模型离线固定空间，不静默截断token，也不以占位推理替代真实向量。回滚代码即可撤回两个新增接口。旧历史响应模型不认识两个新mode，回滚时须限制旧历史端点或备份保留新模式记录，避免解析失败；无需降级数据库，不应无备份删除记录。Docker容器、前端浏览器、正式模型冻结、核验领域语料/问题集与RAG留待后续验收。请按团队权限审阅；本阶段合入dev后再推进下一阶段。

Kronecker added 1 commit 2026-10-16 13:58:03 +08:00

feat: add chunk BM25 and reproducible RRF retrieval bb273ec724

saint merged commit e7518a4fea into dev

2026-10-16 17:24:29 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: saint/border-red-post-nalati#14