feat: add bounded rag embedding optimization

[xjx-star]

变更范围

阶段十四：CodeSense:knowledge-rag:stage14。新增离线优先的嵌入 provider registry、请求级调用/成本预算和质量对比报告；默认仍使用 cjk_ngram，只有显式设置 KNOWLEDGE_RAG_EMBEDDER=token 才切换。新增 KNOWLEDGE_RAG_EMBEDDING_MAX_COST 成本上限，预算超限沿用 answer-only 回退。

同时修复阶段十三主线回归中发现的公共状态投影缺口：timeout 和 rate_limited 不再被错误投影成 unknown，保留明确回退码和 HTTP 200 answer-only 行为。

不改数据库结构、权限、部署、生产凭据、外部 embedding 服务、持久化向量库或核心 JSON/SSE 既有字段。

验证命令及结果

隔离 worktree，使用共享 student-eval Python，未使用生产数据库、生产 Redis、外部 AI 或生产凭据。

• python -m pytest tests/test_knowledge_evidence.py tests/test_knowledge_reliability.py tests/test_knowledge_rag.py tests/test_knowledge_optimization.py tests/test_knowledge_eval.py -q --disable-warnings
  • 46 passed，退出码 0。
• python -m pytest -q --disable-warnings
  • 748 passed，退出码 0，约 16 分 49 秒。
• python -m services.knowledge_optimization_eval
  • cjk_ngram recall_at_k=0.875，181 calls，estimated_cost=0.0，质量/成本门禁通过。
  • token recall_at_k=0.875，181 calls，estimated_cost=0.0，质量/成本门禁通过；默认仍选择 cjk_ngram。
• python -c "from pathlib import Path; [compile(p.read_text(encoding='utf-8'), str(p), 'exec') for p in [Path('services/knowledge_optimization.py'), Path('services/knowledge_optimization_eval.py'), Path('services/knowledge_eval.py'), Path('services/knowledge_rag.py'), Path('services/knowledge_evidence.py'), Path('routes/api.py')]]"
  • 通过。
• git diff --check
  • 通过。

提交：e4cd81e。

事实与推断边界

已确认事实：默认 provider 未改变；显式 provider 切换可用；两个离线 provider 在当前固定集上 recall_at_k 均为 0.875；调用数、成本和预算拒绝以有界指标记录；timeout/rate_limited 公共投影回归通过。

推断边界：固定集只有 5 个查询，不能代表生产模型效果；本地零成本不代表外部模型零成本；本地延迟不代表生产 SLA；当前 registry 不等于已接入生产模型。

未解决问题与后续建议

尚未接入真实 embedding 模型、生产账单、多实例全局配额或管理端质量趋势页面。后续应先提供脱敏且规模更大的评估集和真实成本口径，再单独评审外部模型、Redis 配额、权限和部署方案。当前实现可直接回滚，无需数据库或部署回滚。

详细系统地图、观察、假设、指标、回滚和学习总结见 KNOWLEDGE_RAG_STAGE14.md。

[XiaoCow666]

CodeSense 自动评审

核心目标已完成：默认嵌入器保持 cjk_ngram，token 仅在显式配置时启用，请求级调用和成本预算会在超限时回退为 answer-only；timeout 与 rate_limited 的公共状态投影也已修复。未发现会导致安全风险、数据损坏、明显回归、无法运行或任务未完成的阻塞问题。

合并后可以继续改进的地方

• services/knowledge_optimization_eval.py 的固定评估集规模较小，当前质量门禁只能证明该固定集上的一致性，不能代表生产检索质量；PR 描述已明确这一边界。
• 公共指标中的 embedding_estimated_cost 目前仅做非负值清洗，后续如接入外部 provider，可考虑像调用次数一样设置公共展示上限，进一步强化指标边界。

已有验证信息

• PR 提供的定向测试证据：tests/test_knowledge_evidence.py tests/test_knowledge_reliability.py tests/test_knowledge_rag.py tests/test_knowledge_optimization.py tests/test_knowledge_eval.py 共 46 passed，退出码 0。
• PR 提供的全量测试证据：python -m pytest -q --disable-warnings 共 748 passed，退出码 0。
• PR 提供的离线评估证据：cjk_ngram 与 token 均为 recall_at_k=0.875、181 calls、estimated_cost=0.0，质量与成本门禁通过，默认选择 cjk_ngram。
• PR 提供的静态检查证据：相关模块编译检查及 git diff --check 通过。

评审事件：34c0f5a0-b3f0-11f1-8481-eb4529fb040f

[XiaoCow666]

结论：需要修改 1 项功能正确性问题。

1. 嵌入调用上限与实际切片数量不一致，会让合法检索直接进入 unavailable 回退。

证据：services/knowledge_rag.py::_request_embedder() 把 max_calls 固定为 MAX_INDEX_DOCUMENTS + 1；retrieve_assignment_knowledge() 随后对最多 64 个 document 执行 knowledge_pipeline.chunker.split(document)，并把产生的全部 chunk 交给 VersionedKnowledgeIndex。一个 document 可以产生多个 chunk，因此索引数量可能超过 64。构建索引时，第 66 次嵌入调用会触发 EmbeddingBudgetExceeded，整个请求随即返回 unavailable。这与文档声明的“最多 64 个索引切片加 1 次查询调用”不一致，也会使包含较长知识点的现有作业失去全部检索结果。

请打开 services/knowledge_rag.py 的 retrieve_assignment_knowledge() 和 _request_embedder()，在创建 VersionedKnowledgeIndex 前将实际参与索引的 chunk 明确限制为 64 个，并让调用预算依据同一个切片上限计算，确保最多执行 64 次索引嵌入和 1 次查询嵌入。随后在 tests/test_knowledge_rag.py 增加回归用例：准备能够生成超过 64 个 chunk 的知识内容，验证请求不会返回 unavailable，indexed_chunk_count 不超过 64，embedding_calls 不超过 65，并且查询调用仍有预算。运行：python -m pytest tests/test_knowledge_rag.py tests/test_knowledge_optimization.py tests/test_knowledge_evidence.py -q --disable-warnings。

[XiaoCow666]

CodeSense 自动评审

核心目标已完成：新增请求级嵌入 provider registry、调用/成本预算与离线质量对比，并保留默认 provider 和 answer-only 回退行为。提供的检查证据显示相关测试、全量测试、评估命令、编译检查及 diff 校验均通过，未发现真正阻塞问题。

合并后可以继续改进的地方

• 公共指标中的 MAX_EMBEDDING_CALLS 为 128，而请求实际配置的最大调用次数为 65，虽然当前不会导致功能错误，但上下限定义不完全一致，后续可统一以减少维护歧义。
• 离线评估固定集规模较小，当前结果只能证明实现可复现，不能代表生产 embedding 质量或成本表现。

已有验证信息

• PR 描述提供的目标测试结果为 46 passed，退出码 0。
• PR 描述提供的全量测试结果为 748 passed，退出码 0。
• PR 描述提供的离线 provider 对比中 cjk_ngram 与 token 的 recall_at_k 均为 0.875，质量/成本门禁通过。
• PR 描述提供的 Python 编译检查和 git diff --check 均通过。

评审事件：ec8027c0-ba39-11f1-90da-6b7759c278e5

[XiaoCow666]

根据提供的 diff，未发现能够确认的必要修改项。

已检查范围：

• services/knowledge_optimization.py：预算检查在调用 provider 前执行；调用次数与预计成本在同一个锁内更新，预算拒绝不会继续调用 provider。
• services/knowledge_rag.py::_request_embedder：每次请求创建预算封装，默认继续使用现有 embedder；环境变量支持显式选择 provider。预算异常进入 unavailable 回退路径，并记录使用指标。
• services/knowledge_eval.py、services/knowledge_optimization_eval.py：评估支持注入 embedder，并生成质量、成本和选择结果。
• services/knowledge_evidence.py、routes/api.py 及新增测试：检查了公共指标投影、日志参数对应关系，以及 provider 切换和可靠性状态的测试断言。

本次仅进行了静态审查，没有运行命令；PR 中的测试结果属于贡献者提供的记录。

后续建议（不阻塞合并）：

1. 在 tests/test_knowledge_optimization.py::test_comparison_reports_quality_cost_and_selected_provider 中补充固定集基线断言，例如两个 provider 的 recall_at_k >= 0.875。当前 >= 0.0 与相对质量门槛无法发现两个 provider 同时退化的问题。运行 python -m pytest tests/test_knowledge_optimization.py -q 验证。
2. 为 BudgetedEmbedder 增加使用真实离线 provider 的调用次数上限测试，确认达到 max_calls 后再次调用会抛出 EmbeddingBudgetExceeded，且快照中的调用次数保持不变。现有预算测试主要覆盖成本上限。
3. PR description 中记录的提交 e4cd81e 与元数据中的当前提交 fc5fbe708a050299f09ebe06c59ca5a389b73f90 不同。建议注明验证结果对应的提交；提交更新后，运行文中五个测试文件的 pytest 命令，并记录命令、退出码和通过数量，方便维护者核对。