ai-robot-core/spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/design.md

feature_id	title	status	version	last_updated
AISVC-RES	检索与嵌入策略化改造 - 技术设计	draft	0.1.0	2026-03-10

检索与嵌入策略化改造 - 技术设计

1. 目标与原则

• 默认策略保持线上行为不变（旧逻辑保留）。
• 增强策略通过配置启用，可灰度、可回退。
• 元数据驱动检索保持一致并与新策略兼容。
• 同时支持 ReAct / 非 ReAct 两种执行路径。
• 在性能与复杂度之间可调节（轻量优先，重型可选）。

2. 架构总览

2.1 分层结构

• 策略层（Strategy Layer）
  • 策略配置加载、灰度与回退控制
  • 路由到默认策略或增强策略
  • 统一入口处理 ReAct/非 ReAct 流程
• 检索层（Retrieval Layer）
  • 元数据推断与过滤
  • Dense/Keyword/Hybrid 检索与 RRF 融合
  • 可选重排
• 嵌入层（Embedding Layer）
  • 前缀策略（document/query）
  • Matryoshka 向量缩放与兼容

2.2 关键组件

• StrategyRouter：根据配置与灰度规则选择策略。
• ModeRouter：根据 rag_runtime_mode 与自动路由规则选择 direct/react。
• DefaultPipeline：复用现有检索/嵌入逻辑。
• EnhancedPipeline：新端到端方案（文档预处理、切块、元数据、嵌入、检索、重排）。
• MetadataInference：统一的元数据推断入口（策略无关）。
• RetrievalComposer：执行 Dense/Keyword/RRF。
• RollbackManager：策略回退与审计记录。

3. 端到端流程（新旧对照基线）

3.1 旧逻辑默认策略（Baseline）

1. 文档入库前处理：保持现有清洗流程。
2. 切块策略：沿用既有切块规则与阈值。
3. 元数据生成与挂载：保持当前字段与结构。
4. 嵌入策略：保持现有前缀与 Matryoshka 设置。
5. 元数据推断与过滤：使用现有推断体系。
6. 检索策略：保持当前 dense / keyword / hybrid 组合。
7. 重排与输出：保持现有规则（可选）。
8. 回退与灰度控制：默认不开启增强策略。

3.2 新增强策略（End-to-End）

1. 文档入库前处理（清洗/规范化）
   • 统一编码、去噪、Markdown 结构修正。
   • 表格/列表标准化与 FAQ 一问一答拆解。
   • 术语归一化（同义词映射）。
2. 切块策略（结构切块 + 长度切块 + 特殊结构处理）
   • Markdown 标题切分 → 长度切分（chunk_size=500, overlap=100）。
   • 表格行独立 chunk；FAQ 一问一答一块；规则/条件句不跨 chunk。
3. 元数据生成与挂载（title_path、section_type、keywords、doc_type 等）
   • doc_id/source_path/title_path/section_type/lang/doc_type/chunk_index/chunk_char_count/keywords。
   • metadata_confidence 用于 soft/hard filter。
4. 嵌入策略（document/query 前缀、Matryoshka）
   • 索引：search_document 前缀。
   • 查询：search_query 前缀。
   • Matryoshka 256/512/768。
5. 元数据推断与过滤（智能体推断 -> hard/soft filter）
   • 置信度高：硬过滤。
   • 置信度低：软过滤/加权。
   • 置信度不足：回退无过滤。
6. 检索策略（dense + keyword/hybrid + RRF）
   • Dense 向量检索 + 轻量关键词检索。
   • RRF 融合。
   • 可选重排。
7. 重排与输出（可选）
   • 输出包含 title_path/section_type 作为引用解释。
   • 低置信度触发二次检索。
8. 回退与灰度控制（策略配置切换）
   • 策略层支持按比例/白名单灰度。
   • 失败或指标退化时回退默认策略。

4. 运行时策略切换与灰度流程

1. StrategyRouter 读取配置（默认策略=旧逻辑）。
2. 根据灰度规则（percentage/allowlist）选择默认或增强。
3. ModeRouter 根据 rag_runtime_mode 选择 direct/react/auto。
4. auto 模式下结合复杂度/置信度规则自动路由。
5. ReAct 模式：多步检索与策略链路复用。
6. direct 模式：走低延迟通用检索路径。
7. 发生异常或性能超阈值 → RollbackManager 切回默认策略。
8. 变更记录写入审计日志，支持回放与排障。

5. 元数据推断与过滤的位置

• 进入检索前统一调用 MetadataInference。
• 输出结构化字段用于 hard/soft filter。
• 新旧策略均消费同一元数据结果。
• 过滤策略配置与日志保持一致，确保可解释性。

6. 性能与复杂度权衡

• 轻量 Hybrid 作为默认增强策略路径（Dense + 关键词 + RRF）。
• 重型 Hybrid（ES/OS + BM25 + 重排）为可选配置，需性能预算验证。
• Matryoshka 维度裁剪用于平衡延迟与召回。
• direct/react/auto 模式按复杂度分流，减少不必要的高成本推理。
• 通过策略验证接口检查性能预算与回退条件。

7. 模式路由策略（效率控制）

7.1 模式开关

• rag_runtime_mode: direct | react | auto
  • direct：走通用检索 API（低延迟）
  • react：走 ReAct 多步检索（高准确）
  • auto：根据规则自动判断

7.2 自动路由规则（rag_runtime_mode=auto）

• direct 条件：
  • 问句短、意图明确
  • 元数据推断置信度高
  • 无跨域/多条件
• react 条件：
  • 多条件/多约束
  • 元数据置信度低
  • 需要二次确认或多轮推理

7.3 配套参数

• react_trigger_confidence_threshold
• react_trigger_complexity_score
• react_max_steps
• direct_fallback_on_low_confidence

8. 回滚与降级方案

• 回滚触发：策略异常、监控指标退化超过阈值、人工触发。
• 回滚路径：增强策略 → 默认策略（旧逻辑）。
• 降级选项：关闭重排、减少 keyword 检索、降低 topK。

9. 风险与缓解

• 风险：增强策略引入复杂度导致延迟升高。
  • 缓解：灰度发布 + 性能预算验证。
• 风险：元数据不一致导致过滤偏差。
  • 缓解：统一推断入口 + 一致性校验。

10. 端到端流程图（步骤链路）

flowchart TD
  A[文档入库前处理] --> B[结构切块]
  B --> C[长度切块/特殊结构处理]
  C --> D[元数据生成与挂载]
  D --> E[嵌入策略: document/query 前缀 + Matryoshka]
  E --> F[元数据推断与过滤]
  F --> G[检索策略: Dense + Keyword/Hybrid + RRF]
  G --> H[模式路由: direct/react/auto]
  H --> I[重排与输出]
  I --> J[回退与灰度控制]