---
feature_id: "AISVC-RES"
title: "检索与嵌入策略化改造"
status: "draft"
version: "0.1.0"
owners:
  - "product"
  - "backend"
  - "search"
  - "ml"
last_updated: "2026-03-10"
source:
  type: "conversation"
  ref: ""
---

# 检索与嵌入策略化改造（AISVC-RES）

## 1. 背景与目标
- 背景：当前检索与嵌入流程为单一路径，缺少可配置策略切换与灰度控制。
- 目标：在不破坏默认线上逻辑的前提下，引入“策略层”实现可配置的端到端检索与嵌入增强方案，并支持 ReAct / 非 ReAct 两种模式。
- 非目标（Out of Scope）：
  - 新增或替换底层向量数据库/搜索引擎
  - 大规模重构现有元数据推断体系

## 2. 模块边界（Scope）
- 覆盖：
  - 策略配置管理（默认策略与增强策略）
  - 检索与嵌入端到端流程的策略化封装
  - 元数据推断与过滤在策略中的统一位置
  - 运行时灰度切换与回退
- 不覆盖：
  - 上游文档采集系统
  - 对外 API 的业务语义变更

## 3. 依赖盘点（Dependencies）
- 依赖模块/第三方：
  - 知识库索引与检索服务（向量检索/关键词检索）
  - 现有元数据推断智能体/规则引擎
  - 配置中心或本地配置存储

## 4. 用户故事（User Stories）
- [US-AISVC-RES-01] 作为平台运维，我希望能在不影响线上默认逻辑的情况下启用增强策略，以便进行灰度验证。
- [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 保持现有检索与嵌入逻辑不变。
- [AC-AISVC-RES-02] WHEN 配置启用增强策略 THEN 系统 SHALL 按新端到端流程执行并保留可回退能力。
- [AC-AISVC-RES-03] WHEN 运行时切换策略 THEN 系统 SHALL 不影响正在运行的默认策略请求，并支持灰度比例配置。
- [AC-AISVC-RES-04] WHEN 进入检索流程 THEN 系统 SHALL 在策略层统一执行元数据推断与过滤，并与现有元数据驱动检索保持一致。
- [AC-AISVC-RES-05] WHEN 选择 ReAct 模式 THEN 系统 SHALL 采用多步检索链路并保留非 ReAct 的直接检索路径。
- [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）

| AC ID | Endpoint | 方法 | operationId（可选） | 备注 |
|------|----------|------|---------------------|------|
| AC-AISVC-RES-01 | /strategy/retrieval/current | GET | getCurrentRetrievalStrategy | 读取当前策略 |
| AC-AISVC-RES-02 | /strategy/retrieval/switch | POST | switchRetrievalStrategy | 切换策略 |
| AC-AISVC-RES-03 | /strategy/retrieval/switch | POST | switchRetrievalStrategy | 灰度配置 |
| AC-AISVC-RES-04 | /strategy/retrieval/validate | POST | validateRetrievalStrategy | 一致性校验 |
| AC-AISVC-RES-05 | /strategy/retrieval/switch | POST | switchRetrievalStrategy | ReAct/非 ReAct |
| 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 | 路由参数 |