0.9444 是怎么来的
这是 2026 年 9 月 7 日的本地检索记录，用的是固定的 50 个案例，这次整理没重跑，先把它当成这套测试数据上的结果。
我当时给检索补了语义模型的接入方式，也检查了原来的关键词加哈希向量方案有没有受影响。默认方案仍是 BM25 + Hashing。
下面这张表来自项目自带评测脚本的报告。Recall@5 看前五条结果找回了多少相关资料，MRR 看正确资料排得够不够靠前，后面的几项分别记录引用、拒答、输出格式和工具调用。
| 指标 | 实测 |
|---|---|
| 固定 case | 50/50 可运行 |
| Recall@5 | 0.9444 |
| MRR | 0.8278 |
| citation_hit_rate | 0.9778 |
| refusal_accuracy | 1.0000 |
| structured_output_success_rate | 1.0000 |
| tool_call_success_rate | 1.0000 |
| 连续演示成功 | 50 |
| 平均检索延迟 / P95 | 1.50 / 1.61 ms |
这轮报告里的目标检查都通过了。旧报告里拒答准确率曾是 0.0，后来用评测脚本重跑更新了结果。50 条查询的前五个文档 ID，以及保留六位的分数，都和修改前一致。
为了接入语义检索，我改了哪些地方
我把模型选择、缓存和线程数做成可配置，再把它们接进原来的检索流程。不同方式的结果用加权排名融合，代码里叫 weighted RRF；查询和文档各自生成向量，再检查向量格式是否有效。
| 文件 | 这轮改了什么 |
|---|---|
src/bomboo1/config.py | 加入检索方式、模型、缓存、CPU 线程数、只用本地模型等配置和检查 |
src/bomboo1/rag/retriever.py | 缓存文档向量，分开处理查询和文档，检查向量，明确加权排名融合的命名和配置入口 |
src/bomboo1/rag/pipeline.py | 接入配置，显示实际检索方式，只更新元数据时也保存变化 |
src/bomboo1/demo/controller.py | 按实际使用的方式显示检索说明 |
src/bomboo1/agent/registry.py | 用 Draft 2020-12 Schema 检查工具参数，出错时清理执行器 |
tests/test_demo.py | 更新加权排名融合相关的测试 |
pyproject.toml | 补上开发环境的 AnyIO 兼容约束和 jsonschema 依赖，保留可选语义检索依赖与 httpx2 |
.env.example | 增加检索方式、模型和缓存的配置例子 |
scripts/verify_e2e.py | 记录客户端文件哈希、调用过程、HTTP 请求与响应，以及失败场景 |
新增的代码放在哪里
接下来我把模型适配、评测和回归检查分开，方便以后换模型或重跑对照。需要找具体实现的话，可以从这些文件开始：
src/bomboo1/rag/embeddings.py：接入 FastEmbed 的 CPU 运行方式，提供提前下载模型的入口。src/bomboo1/evaluation/retrieval.py：分别启动独立进程，对照五种检索方案。src/bomboo1/evaluation/semantic_cases.json：补了 12 个诊断案例。tests/test_retrieval_backends.py：检查原方案逐条结果、缓存、故障处理、配置、指标和真实模型。tests/test_schema_guards.py：检查数组元素、组合规则、本地引用、非法格式和出错记录。scripts/verify_project.py：统一跑验证，保存命令、退出码和日志。docs/retrieval-design.md：整理融合公式、模型配置、运行步骤和适用范围。
运行记录也一起留下
我把评测结果和运行日志一起保存了，后面看到一个数字时还能找回生成它的过程。完整命令和退出码在 verification.json，设计与运行步骤在 docs/retrieval-design.md。
这一轮更新了 evaluation-report.json、eval_rag/index.json 和 e2e-server.log，另外生成了这些记录：
e2e-report.json、e2e_rag/index.json：端到端检查结果。retrieval-report.json和五份retrieval-{strategy}.json/.log：检索对照结果与日志。coverage.json、verification.json和各验证日志：覆盖情况与运行过程。dependencies.log、start-hashes.json、baseline-rankings.json：依赖、起始文件状态和原方案排名。
模型缓存放在项目的 data/models，依赖装在项目自己的 .venv。
顺手核对了类型检查
整理旧问题时，我先跑了一遍类型检查：40 个源文件，0 个错误。旧报告提到的六个错误在这时已经处理好了，这轮继续沿用已有的类型设计。
具体包括给检索器创建函数标返回类型、给配置明确默认值、避开方法名遮蔽，以及给健康检查和算术工具补齐类型。相关代码引用分别是 Retriever、builtins.list、TypedDict 和 Callable。