[AC-AISVC-RES-01~15] docs(spec): 新增检索策略路由规范文档

- 新增 design.md 设计文档
- 新增 tasks.md 任务分解文档
- 更新 requirements.md 需求文档
- 更新 openapi.provider.yaml API 定义

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

@@ -0,0 +1,155 @@
+---
+feature_id: "AISVC-RES"
+title: "检索与嵌入策略化改造 - 技术设计"
+status: "draft"
+version: "0.1.0"
+last_updated: "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. 端到端流程图（步骤链路）
+
+```mermaid
+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[回退与灰度控制]
+```

spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/openapi.provider.yaml

@@ -193,4 +193,3 @@ components:
           $ref: "#/components/schemas/RetrievalStrategyStatus"
         rollback_to:
           $ref: "#/components/schemas/RetrievalStrategyStatus"
-

spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/requirements.md

@@ -44,6 +44,7 @@ source:
 - [US-AISVC-RES-02] 作为检索工程师，我希望能在配置中切换 ReAct 与非 ReAct 模式的检索流程，以便适配不同调用场景。
 - [US-AISVC-RES-03] 作为业务方，我希望元数据驱动检索在新旧策略中保持一致，以便结果可解释且向后兼容。
 - [US-AISVC-RES-04] 作为系统维护者，我希望能验证策略配置的完整性与一致性，以便避免错误配置上线。
+- [US-AISVC-RES-05] 作为检索工程师，我希望系统在 direct/react/auto 模式下自动选择合适路径，以便平衡延迟与准确性。
 
 ## 5. 验收标准（Acceptance Criteria, EARS）
 - [AC-AISVC-RES-01] WHEN 系统未启用增强策略 THEN 系统 SHALL 保持现有检索与嵌入逻辑不变。
@@ -54,6 +55,13 @@ source:
 - [AC-AISVC-RES-06] WHEN 执行策略验证接口 THEN 系统 SHALL 返回策略配置完整性与一致性校验结果。
 - [AC-AISVC-RES-07] WHEN 检索与嵌入策略发生异常 THEN 系统 SHALL 支持回退到默认策略并记录审计信息。
 - [AC-AISVC-RES-08] WHEN 启用增强策略 THEN 系统 SHALL 保证关键指标性能退化不超过可配置阈值并提供降级选项。
+- [AC-AISVC-RES-09] WHEN 配置 rag_runtime_mode 为 direct THEN 系统 SHALL 走低延迟通用检索路径。
+- [AC-AISVC-RES-10] WHEN 配置 rag_runtime_mode 为 react THEN 系统 SHALL 强制走 ReAct 多步检索路径。
+- [AC-AISVC-RES-11] WHEN 配置 rag_runtime_mode 为 auto THEN 系统 SHALL 根据复杂度与置信度规则自动选择 direct 或 react 路由。
+- [AC-AISVC-RES-12] WHEN 问句短且元数据推断置信度高 THEN 系统 SHALL 选择 direct 路由。
+- [AC-AISVC-RES-13] WHEN 问句多条件或元数据置信度低 THEN 系统 SHALL 选择 react 路由。
+- [AC-AISVC-RES-14] WHEN direct 路由检索置信度低 THEN 系统 SHALL 按配置触发 react 回退。
+- [AC-AISVC-RES-15] WHEN 调整 react_trigger_confidence_threshold 等路由参数 THEN 系统 SHALL 立即应用到自动路由逻辑。
 
 ## 6. 追踪映射（Traceability）
 
@@ -67,3 +75,10 @@ source:
 | AC-AISVC-RES-06 | /strategy/retrieval/validate | POST | validateRetrievalStrategy | 校验结果 |
 | AC-AISVC-RES-07 | /strategy/retrieval/rollback | POST | rollbackRetrievalStrategy | 回退 |
 | AC-AISVC-RES-08 | /strategy/retrieval/validate | POST | validateRetrievalStrategy | 性能阈值 |
+| AC-AISVC-RES-09 | /strategy/retrieval/switch | POST | switchRetrievalStrategy | 模式 direct |
+| AC-AISVC-RES-10 | /strategy/retrieval/switch | POST | switchRetrievalStrategy | 模式 react |
+| AC-AISVC-RES-11 | /strategy/retrieval/switch | POST | switchRetrievalStrategy | 模式 auto |
+| AC-AISVC-RES-12 | /strategy/retrieval/validate | POST | validateRetrievalStrategy | 路由规则 |
+| AC-AISVC-RES-13 | /strategy/retrieval/validate | POST | validateRetrievalStrategy | 路由规则 |
+| AC-AISVC-RES-14 | /strategy/retrieval/validate | POST | validateRetrievalStrategy | 路由回退 |
+| AC-AISVC-RES-15 | /strategy/retrieval/switch | POST | switchRetrievalStrategy | 路由参数 |

spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/tasks.md

@@ -0,0 +1,39 @@
+---
+feature_id: "AISVC-RES"
+title: "检索与嵌入策略化改造 - 任务拆解"
+status: "draft"
+version: "0.1.0"
+last_updated: "2026-03-10"
+---
+
+# 检索与嵌入策略化改造 - 任务拆解
+
+## 策略层与配置
+- [ ] 设计并实现 StrategyRouter（默认策略/增强策略路由）【AC-AISVC-RES-01】【AC-AISVC-RES-02】
+- [ ] 实现 ModeRouter 与 rag_runtime_mode 配置开关（direct/react/auto）【AC-AISVC-RES-09】【AC-AISVC-RES-10】【AC-AISVC-RES-11】
+- [ ] 增加灰度发布配置模型（percentage/allowlist）【AC-AISVC-RES-03】
+- [ ] 实现策略回退与审计记录【AC-AISVC-RES-07】
+
+## 检索与嵌入策略
+- [ ] 封装默认策略 Pipeline（复用现有逻辑）【AC-AISVC-RES-01】
+- [ ] 实现增强策略 Pipeline（端到端新流程）【AC-AISVC-RES-02】
+- [ ] 支持 ReAct / 非 ReAct 两种执行路径【AC-AISVC-RES-05】
+- [ ] 实现自动路由规则（复杂度/置信度判定）【AC-AISVC-RES-11】【AC-AISVC-RES-12】【AC-AISVC-RES-13】
+- [ ] 实现 direct 低置信度回退到 react 的机制【AC-AISVC-RES-14】
+- [ ] 实现元数据推断统一入口与 hard/soft filter【AC-AISVC-RES-04】
+
+## 检索组合与性能
+- [ ] 实现 Dense + Keyword + RRF 组合检索【AC-AISVC-RES-02】
+- [ ] 可选重排模块与降级开关【AC-AISVC-RES-08】
+- [ ] 性能预算与阈值配置校验【AC-AISVC-RES-08】
+- [ ] 路由参数配置与热更新（阈值/复杂度/最大步数）【AC-AISVC-RES-15】
+
+## API 与校验
+- [ ] 实现策略查询接口（/strategy/retrieval/current）【AC-AISVC-RES-01】
+- [ ] 实现策略切换接口（/strategy/retrieval/switch）【AC-AISVC-RES-02】【AC-AISVC-RES-03】
+- [ ] 实现策略校验接口（/strategy/retrieval/validate）【AC-AISVC-RES-06】
+- [ ] 实现策略回退接口（/strategy/retrieval/rollback）【AC-AISVC-RES-07】
+
+## 观测与灰度验证
+- [ ] 增强策略指标埋点与监控面板【AC-AISVC-RES-03】【AC-AISVC-RES-08】
+- [ ] 灰度验证与回滚演练【AC-AISVC-RES-07】