diff --git a/spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/design.md b/spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/design.md new file mode 100644 index 0000000..3f9d351 --- /dev/null +++ b/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[回退与灰度控制] +``` diff --git a/spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/openapi.provider.yaml b/spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/openapi.provider.yaml index 36cb31e..78f5354 100644 --- a/spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/openapi.provider.yaml +++ b/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" - diff --git a/spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/requirements.md b/spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/requirements.md index 1e3724d..9301efc 100644 --- a/spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/requirements.md +++ b/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 | 路由参数 | diff --git a/spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/tasks.md b/spec/ai-service/iterations/v0.9.0-retrieval-embedding-strategy/tasks.md new file mode 100644 index 0000000..9f087ee --- /dev/null +++ b/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】