ai-robot-core/spec/ai-service/iterations/v0.8.0-intent-hybrid-routing/scope.md

---
iteration_id: "v0.8.0-intent-hybrid-routing"
title: "意图识别混合路由优化 - 模块边界与依赖盘点"
status: "draft"
version: "0.8.0"
created_at: "2026-03-08"
parent_spec: "spec/ai-service/requirements.md"
---

# 意图识别混合路由优化 - Scope & Dependencies

## 1. 模块边界说明（Module Scope）

### 1.1 本次覆盖范围

本次迭代仅聚焦于 **意图识别子域** 的混合路由优化，具体包括：

| 覆盖项 | 说明 |
|--------|------|
| RuleMatcher | 保留现有 IntentRouter 关键词/正则匹配逻辑，增加 score 输出 |
| SemanticMatcher | 新增：基于 Embedding 的意图向量语义匹配 |
| LlmJudge | 新增：冲突/低置信场景的 LLM 仲裁 |
| FusionPolicy | 新增：三路打分融合决策策略 |
| IntentRouter 升级 | 改造：新增 `match_hybrid()` 方法，调用三路 Matcher + FusionPolicy |
| IntentRule 实体扩展 | 新增：`intent_vector`、`semantic_examples` 字段 |
| 路由追踪日志 | 新增：`route_trace` 字段支持监控 API |
| 融合配置 API | 新增：融合权重与阈值的配置管理 |

### 1.2 本次不覆盖范围

| 不覆盖项 | 原因 | 所属模块 |
|----------|------|----------|
| Orchestrator 主流程 | 仅在 Step 3 插入混合路由，不改主链路 | orchestrator.py |
| RAG 检索模块 | 本次仅意图识别，不涉及知识库检索逻辑 | retrieval/* |
| Flow 流程引擎 | 意图路由结果驱动流程，流程逻辑不变 | flow/* |
| Guardrail 护栏 | 输出过滤逻辑不变 | guardrail/* |
| Prompt 模板系统 | 模板渲染逻辑不变 | prompt/* |
| Memory 记忆层 | 会话管理不变 | memory/* |
| LLM Adapter | LLM 调用逻辑不变 | llm/* |
| /ai/chat API | 对外响应语义不变 | api/chat.py |
| 多知识库管理 | 知识库路由逻辑不变 | kb/* |
| Query 改写 | Query 增强逻辑不变 | retrieval/query_rewriter.py |

### 1.3 边界约束

```
┌─────────────────────────────────────────────────────────────────────┐
│                        Orchestrator Pipeline                         │
│                                                                      │
│  Step 1    Step 2    Step 3 [改造]    Step 4    Step 5-12           │
│  Input     Flow      Intent          Query     RAG/LLM/...          │
│  Scanner   Engine    Router          Rewriter                       │
│                      │                                               │
│                      ▼                                               │
│            ┌─────────────────────┐                                   │
│            │  Hybrid Routing     │  ← 本次改造范围                    │
│            │  (Rule+Semantic+LLM)│                                   │
│            └─────────────────────┘                                   │
│                      │                                               │
│                      ▼                                               │
│              response_type 路由（不变）                               │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘
```

---

## 2. 依赖清单（Dependencies）

### 2.1 内部依赖

| 依赖模块 | 依赖方式 | 用途说明 |
|----------|----------|----------|
| EmbeddingProvider | 复用 | SemanticMatcher 使用现有 Embedding 提供者生成向量 |
| QdrantClient | 复用 | SemanticMatcher 使用现有向量数据库进行相似度检索 |
| LLMClient | 复用 | LlmJudge 使用现有 LLM 客户端进行仲裁 |
| IntentRuleService | 复用 | 规则 CRUD、缓存管理、命中统计 |
| RuleCache | 复用 | 规则内存缓存（TTL=60s） |
| GenerationContext | 扩展 | 新增 `route_trace` 字段 |

### 2.2 外部依赖

| 依赖项 | 类型 | 说明 |
|--------|------|------|
| PostgreSQL | 数据库 | IntentRule 实体存储（扩展字段） |
| Qdrant | 向量库 | 意图向量索引（复用现有 Collection 或新建） |
| LLM API | 外部服务 | LlmJudge 仲裁调用 |

### 2.3 依赖接口清单

#### 2.3.1 EmbeddingProvider 接口（复用）

```python
class EmbeddingProvider(ABC):
    async def embed(self, text: str) -> list[float]:
        """生成单个文本的向量"""
        pass
    
    async def embed_batch(self, texts: list[str]) -> list[list[float]]:
        """批量生成向量"""
        pass
    
    def get_dimension(self) -> int:
        """获取向量维度"""
        pass
```

#### 2.3.2 QdrantClient 接口（复用）

```python
class QdrantClient:
    async def search(
        self,
        collection_name: str,
        query_vector: list[float],
        limit: int = 10,
        score_threshold: float | None = None,
        query_filter: dict | None = None
    ) -> list[ScoredPoint]:
        """向量相似度搜索"""
        pass
```

#### 2.3.3 LLMClient 接口（复用）

```python
class LLMClient:
    async def generate(
        self,
        messages: list[dict],
        max_tokens: int = 1000,
        temperature: float = 0.7
    ) -> LLMResponse:
        """生成回复"""
        pass
```

#### 2.3.4 IntentRuleService 接口（复用）

```python
class IntentRuleService:
    async def get_enabled_rules_for_matching(self, tenant_id: str) -> list[IntentRule]:
        """获取启用的规则列表（按优先级降序）"""
        pass
    
    async def increment_hit_count(self, tenant_id: str, rule_id: uuid.UUID) -> bool:
        """更新命中统计"""
        pass
```

---

## 3. 对外提供能力（Provider Contracts）

### 3.1 新增接口

| 接口 | 类型 | 说明 |
|------|------|------|
| `IntentRouter.match_hybrid()` | 内部方法 | 混合路由入口，返回融合结果 |
| `GET /admin/intent-rules/fusion-config` | Admin API | 获取融合配置 |
| `PUT /admin/intent-rules/fusion-config` | Admin API | 更新融合配置 |
| `POST /admin/intent-rules/{id}/generate-vector` | Admin API | 生成意图向量 |

### 3.2 扩展接口

| 接口 | 变更说明 |
|------|----------|
| `IntentRule` 实体 | 新增 `intent_vector`、`semantic_examples` 字段 |
| `POST /admin/intent-rules` | 支持 `intent_vector`、`semantic_examples` 参数 |
| `PUT /admin/intent-rules/{id}` | 支持 `intent_vector`、`semantic_examples` 参数 |
| `GET /admin/monitoring/conversations/{id}` | 响应新增 `route_trace` 字段 |

### 3.3 不变的对外契约

| 契约 | 说明 |
|------|------|
| `/ai/chat` 响应 | `reply`、`confidence`、`shouldTransfer` 字段语义不变 |
| `IntentRouter.match()` | 保留原有方法，向后兼容 |
| 意图规则响应类型 | `fixed`/`rag`/`flow`/`transfer` 路由逻辑不变 |

---

## 4. 数据模型变更

### 4.1 IntentRule 实体扩展

```sql
ALTER TABLE intent_rules ADD COLUMN intent_vector JSONB;
ALTER TABLE intent_rules ADD COLUMN semantic_examples JSONB;

COMMENT ON COLUMN intent_rules.intent_vector IS '意图向量（预计算）';
COMMENT ON COLUMN intent_rules.semantic_examples IS '语义示例句列表（动态计算）';
```

### 4.2 ChatMessage 实体扩展

```sql
ALTER TABLE chat_messages ADD COLUMN route_trace JSONB;

COMMENT ON COLUMN chat_messages.route_trace IS '意图路由追踪日志';
```

### 4.3 新增配置模型

```python
class FusionConfig:
    w_rule: float = 0.5
    w_semantic: float = 0.3
    w_llm: float = 0.2
    semantic_threshold: float = 0.7
    conflict_threshold: float = 0.2
    gray_zone_threshold: float = 0.6
    min_trigger_threshold: float = 0.3
    clarify_threshold: float = 0.4
    multi_intent_threshold: float = 0.15
```

---

## 5. 风险评估

| 风险项 | 等级 | 缓解措施 |
|--------|------|----------|
| Embedding 调用增加延迟 | 中 | SemanticMatcher 设置超时（100ms），超时跳过 |
| LLM Judge 频繁触发增加成本 | 中 | 配置合理的触发阈值，默认仅在冲突/灰区触发 |
| 语义向量配置复杂度高 | 低 | 提供自动生成 API，支持示例句模式降低门槛 |
| 多路匹配结果不一致 | 中 | FusionPolicy 明确优先级规则，记录决策原因 |
| 向后兼容性 | 低 | 保留 `match()` 方法，新增 `match_hybrid()` 方法 |

---

## 6. 准入条件检查

- [x] 能明确回答"这是哪个模块的需求？" → **意图识别子域**
- [x] 能明确回答"本模块对外提供什么能力？" → **混合路由匹配能力**
- [x] 能明确回答"本模块依赖谁？依赖哪些接口？" → **EmbeddingProvider、QdrantClient、LLMClient、IntentRuleService**
- [x] 依赖接口已存在或已有实现计划 → **全部为复用现有接口**

---

## 7. 文件变更清单

### 7.1 新增文件

| 文件路径 | 说明 |
|----------|------|
| `app/services/intent/semantic_matcher.py` | 语义匹配器 |
| `app/services/intent/llm_judge.py` | LLM 仲裁器 |
| `app/services/intent/fusion_policy.py` | 融合决策策略 |
| `app/services/intent/models.py` | 数据模型定义 |
| `tests/test_semantic_matcher.py` | 语义匹配单元测试 |
| `tests/test_llm_judge.py` | LLM 仲裁单元测试 |
| `tests/test_fusion_policy.py` | 融合决策单元测试 |
| `tests/test_intent_router_hybrid.py` | 混合路由集成测试 |

### 7.2 修改文件

| 文件路径 | 变更说明 |
|----------|----------|
| `app/models/entities.py` | 扩展 IntentRule、ChatMessage 实体 |
| `app/services/intent/router.py` | 新增 `match_hybrid()` 方法 |
| `app/services/orchestrator.py` | Step 3 调用 `match_hybrid()` |
| `app/api/admin/intent_rules.py` | 新增融合配置 API |
| `app/api/admin/monitoring.py` | 返回 `route_trace` 字段 |

### 7.3 数据库迁移

| 迁移文件 | 说明 |
|----------|------|
| `alembic/versions/xxx_add_intent_vector_fields.py` | 新增 intent_vector、semantic_examples 字段 |
| `alembic/versions/xxx_add_route_trace_field.py` | 新增 route_trace 字段 |