feat: add reproducible keyword retrieval baseline #6

2026-10-15T22:30:34+08:00

Kronecker commented

2026-10-15 22:30:34 +08:00

知识管理已有审核状态，但缺少可独立调用、可复核的关键词检索基线。本改动新增已核验知识的中文关键词检索，返回原文片段、出处、记录版本、排序分数和耗时，并保留当时的结果与配置。

关联任务与边界

T06：关键词检索基线；阶段 2 后端已通过普通分支 PR #4 合入 dev，本分支从最新 dev 开始。
只实现 keyword 模式。持久化 chunks、倒排/向量索引、Embedding、RRF、RAG 与模型 API 保持后续阶段边界。
独立任务 Issue 仍待补齐；本 PR 保留任务编号、实现、实际验证和交接材料供追踪。
请按项目既定审阅权限审阅，本请求不自动合并。

API 与排序

POST /api/retrieval，输入 query、top_k（1–20）、可选 category 和 keyword 模式。
固定 jieba 0.42.1 搜索分词，关闭 HMM，加入项目词并采用固定中文停用词表；标题权重 2、正文权重 1 的 BM25 正值平滑变体，k1=1.2/b=0.75。同分按知识 ID 升序。
pending/rejected/软删除及审核元数据缺失的资料不参与语料统计；关联来源和文档须仍有效。没有命中如实返回 no_evidence，不生成模型答案。
命中提供知识、文档、来源 ID 和版本、HTTP(S) 来源、原文片段与偏移、命中词和排序分数。分数不是置信度或事实正确率。
GET /api/retrieval/runs 和 /api/retrieval/runs/{run_id} 支持分页及当时结果复核；依据失效后重新检索会排除该知识，但不会改写历史。
OpenAPI 与前端 src/api.ts 类型和调用同步；页面交互留给前端接入。

数据库与容量

新增 0003_retrieval_runs 迁移及检索记录表，保存实际语料指纹、算法参数、原始结果和耗时。
先安装更新依赖并执行 alembic upgrade head，再启动应用。新后端会明确拒绝旧 Schema。
基线按请求计算，最多 5000 条且标题/正文合计不超过 200 万字符；容量超限明确 503，不静默截断或伪造空结果。
真实检索耗时不包含记录写入和网络时间；这些是功能验证结果，不是论文对照实验。

实际验证

后端 ruff check .、ruff format --check . 均通过。
pytest -q：42 passed，真实隔离 PostgreSQL 16 + pgvector，包含手算 BM25、标题权重、排序复现、审核与父记录边界、零命中、历史、容量拒绝、旧库迁移及服务重启后的检索记录。
前端 npm run build：通过，包含新增检索调用类型检查。
测试资料与审核人均为占位数据，隐私检查通过；新增提交使用 feat: 与项目通用作者身份。

风险、待验收与回滚

当前主机 Docker 服务尚未启动，容器及真实浏览器端联调仍未验收，临时 PostgreSQL 测试不替代这两项。
服务仍限本机开发，鉴权、限流、生产部署和检索记录保留策略留待后续工程阶段。
撤回代码可回退本功能提交；备份后可使用 alembic downgrade 0002_catalog 仅删除检索记录表，保留阶段 2 知识、审核和历史。降级须配合旧版后端，恢复检索记录须使用备份。

知识管理已有审核状态，但缺少可独立调用、可复核的关键词检索基线。本改动新增已核验知识的中文关键词检索，返回原文片段、出处、记录版本、排序分数和耗时，并保留当时的结果与配置。 ## 关联任务与边界 - T06：关键词检索基线；阶段 2 后端已通过普通分支 PR #4 合入 dev，本分支从最新 dev 开始。 - 只实现 keyword 模式。持久化 chunks、倒排/向量索引、Embedding、RRF、RAG 与模型 API 保持后续阶段边界。 - 独立任务 Issue 仍待补齐；本 PR 保留任务编号、实现、实际验证和交接材料供追踪。 - 请按项目既定审阅权限审阅，本请求不自动合并。 ## API 与排序 - POST /api/retrieval，输入 query、top_k（1–20）、可选 category 和 keyword 模式。 - 固定 jieba 0.42.1 搜索分词，关闭 HMM，加入项目词并采用固定中文停用词表；标题权重 2、正文权重 1 的 BM25 正值平滑变体，k1=1.2/b=0.75。同分按知识 ID 升序。 - pending/rejected/软删除及审核元数据缺失的资料不参与语料统计；关联来源和文档须仍有效。没有命中如实返回 no_evidence，不生成模型答案。 - 命中提供知识、文档、来源 ID 和版本、HTTP(S) 来源、原文片段与偏移、命中词和排序分数。分数不是置信度或事实正确率。 - GET /api/retrieval/runs 和 /api/retrieval/runs/{run_id} 支持分页及当时结果复核；依据失效后重新检索会排除该知识，但不会改写历史。 - OpenAPI 与前端 src/api.ts 类型和调用同步；页面交互留给前端接入。 ## 数据库与容量 - 新增 0003_retrieval_runs 迁移及检索记录表，保存实际语料指纹、算法参数、原始结果和耗时。 - 先安装更新依赖并执行 alembic upgrade head，再启动应用。新后端会明确拒绝旧 Schema。 - 基线按请求计算，最多 5000 条且标题/正文合计不超过 200 万字符；容量超限明确 503，不静默截断或伪造空结果。 - 真实检索耗时不包含记录写入和网络时间；这些是功能验证结果，不是论文对照实验。 ## 实际验证 - 后端 ruff check .、ruff format --check . 均通过。 - pytest -q：42 passed，真实隔离 PostgreSQL 16 + pgvector，包含手算 BM25、标题权重、排序复现、审核与父记录边界、零命中、历史、容量拒绝、旧库迁移及服务重启后的检索记录。 - 前端 npm run build：通过，包含新增检索调用类型检查。 - 测试资料与审核人均为占位数据，隐私检查通过；新增提交使用 feat: 与项目通用作者身份。 ## 风险、待验收与回滚 - 当前主机 Docker 服务尚未启动，容器及真实浏览器端联调仍未验收，临时 PostgreSQL 测试不替代这两项。 - 服务仍限本机开发，鉴权、限流、生产部署和检索记录保留策略留待后续工程阶段。 - 撤回代码可回退本功能提交；备份后可使用 alembic downgrade 0002_catalog 仅删除检索记录表，保留阶段 2 知识、审核和历史。降级须配合旧版后端，恢复检索记录须使用备份。

Kronecker added 1 commit 2026-10-15 22:30:34 +08:00

feat: add reproducible keyword retrieval baseline 8ac9dcaacb

Kronecker referenced this pull request

2026-10-16 07:52:28 +08:00

feat: implement authentication and backend role permissions #7

saint merged commit 18a80ad7f4 into dev

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

Kronecker referenced this issue from a commit

2026-10-16 13:42:12 +08:00

Merge pull request 'feat: add reproducible keyword retrieval baseline' (#6) from kronecker/feat/backend-keyword-retrieval into dev

Sign in to join this conversation.