zhuyongxin
7ae9707a3b
Persist provider reasoning and assistant text separately on agent_reasoning_audit (DeepSeekAssistantMessage path), extract diagnosis_run.conclusion, enrich RAG tool audit (step_id/query/qualityScore), gate empty mysql tools, drop devtools, and align MVP docs after live E2E verification.
4.6 KiB
4.6 KiB
Change: Unify RAG quality score (dense/hybrid labels) and stop keyword boost re-rank
Why
BM25 hybrid 已在库内完成 dense + BM25 + RRF 融合，但后处理仍：
- 把 hybrid 结果伪装成 L2 再
normalizeL2（含bm25_only_no_dense弱分占位）； - 用 L0 domain/entity/keyword contains 加分改主序。
这导致：排序信号与质量闸门分裂；词面信号被 BM25 与后处理双重计分；「词面热、语义冷」的片段可能被抬到前面；hybrid 的 RRF 序被冲掉。
需要统一：检索负责序，后处理只做 quality 归一化 + 裁剪装配。
What Changes
检索层（MilvusHybridKnowledgeStore / VectorSearchService）
- 一级
scoreLabel仅两种：dense|hybrid（与retrieval.search.mode对齐）。 - 废弃正式一级 label：
l2_distance/rrf_fused/bm25_only_no_dense（可读兼容映射到 dense/hybrid）。 mode=dense：score= L2 距离，label=dense，originalRank= ANN 序。mode=hybrid：label=hybrid；不再用 dense L2 覆盖主score；不再对 BM25-only 伪造 maxL2；originalRank= RRF 返回序；rawScore可保留引擎融合分。mode=dense|hybrid保留：hybrid 为线上主路径；dense 为同库对照/评测（已写入架构 §6.0）。
归一化（新）
- 新增唯一转换点
RetrievalScoreNormalizer.toQualityScore(label, score, rank, batchSize, maxL2)→qualityScore ∈ [0,1]（越大越好）。dense：1 - clamp(L2)/maxL2Distancehybrid：按 rank 映射（本轮 batch 线性），不把 RRF 原分当 L2 套公式。
- Label 差异只在此消化。
后处理（KnowledgeEvidencePostProcessor）
- 统一流程，只消费
qualityScore+originalRank（label-agnostic）。 - 排序主序 =
originalRank升序（保检索序）；去掉 domain/entity/keyword/source_type 加分改序。 - L0 contains 匹配若保留，仅写入
hitReasons/ trace 解释，不参与 sort key、不加 finalScore。 relevance_level/isLowQuality/ category unfiltered retry：只看 topqualityScore与既有阈值；不再要求hasHintSupport才能 PRECISE。- 保留：evidenceKey 去重、
max-chunks-per-document、return-n、excerpt 截断、EvidenceBlock 装配。
文档 / 测试
- 更新
mvp/architecture/RAG知识检索架构.md§6 分数与后处理约定。 - 单测：dense 路径 quality 与现 L2 归一化一致；hybrid 保序且不被 keyword 打乱；无
bm25_only一级 label；旧 label 别名可 canonicalize。
Non-goals
- Cross-encoder / listwise 精排、query rewrite、邻块扩展。
- 删除
mode=dense对照开关。 - 改变 Agent 可见 ACI 字段结构（
evidence[]/relevance_level枚举名可不变；分布会变）。 - 修改 Milvus schema / 强制全量 rebuild（本 change 不改 collection 结构）。
- 上线可配
max(rank, denseSim)混合 quality（可后续迭代；本 change 切片 1 用纯 rank 映射 hybrid）。
Context constraints (from devflow)
- 承接 archived：
rag-chunk-evidence-identity-dedup、rag-bm25-hybrid-drop-sdk、rag-hybrid-search-rrf、modular-rag-pipeline。 - 单一知识后端仍为
MilvusHybridKnowledgeStore（V2）；不得恢复 sdk/spring 主路径路由。 - Agent 投影仍不暴露 raw fused score / 完整 contextPack 作为主契约（内部 LookupResult/trace 可保留调试字段）。
- 历史 decision「Dense L2 enrichment for threshold compatibility」本 change 有意废止，改为 qualityScore 统一闸门。
Impact
- 行为变化（对内检索质量语义）：
- hybrid 下证据顺序更贴近 RRF；
- 词面命中不再被后处理 contains 二次抬序；
relevance_level与 unfiltered retry 触发分布可能变化；- BM25-only 命中不再被标成 quality≈0。
- 接口影响：L2（内部 DTO/注释/scoreLabel 字符串约定）；Agent ACI 字段名不变。
- 风险：hybrid rank→quality 为序数映射，绝对值不跨 query 可比；阈值 0.75/0.5 可能需后续观测再调（本 change 先沿用配置项）。
Scale
- standard（多文件、有意行为变化、需 design + specs + tasks + 测试）。
Depends on
- 已落地 hybrid schema + chunk evidenceKey（archived changes 如上）。
- 对话已确认的设计口径（见 change
decisions.md）。
WIP note
- 工作区可能已有未接线的
RetrievalScoreLabels/RetrievalScoreNormalizer草稿文件；apply 阶段以 Committed OpenSpec 为准接入或改写，不视为已完成实现。