ai-robot-core/docs/intent-rule-usage.md

# 意图规则使用指南

## 1. 概述

意图规则（Intent Rule）是 AI 中台的智能路由系统，用于识别用户意图并自动路由到最合适的处理方式。它在 12 步生成流程的第 3 步执行，优先级高于默认的 RAG 检索。

### 1.1 核心特性

- ✅ **关键词匹配**：支持多个关键词的模糊匹配（不区分大小写）
- ✅ **正则表达式匹配**：支持复杂的模式匹配
- ✅ **优先级排序**：按优先级从高到低匹配，命中第一个即停止
- ✅ **四种响应类型**：固定回复、RAG 检索、话术流程、转人工
- ✅ **租户隔离**：不同租户的规则完全独立
- ✅ **缓存优化**：60 秒 TTL 内存缓存，减少数据库查询
- ✅ **命中统计**：自动记录规则命中次数

### 1.2 在生成流程中的位置

```
用户消息 → Step 1: 输入扫描 → Step 2: 流程检查 → Step 3: 意图匹配 → Step 4-12: 后续处理
```

**意图匹配的作用**：
- 如果匹配成功 → 根据 response_type 路由到对应处理方式
- 如果匹配失败 → 继续执行默认的 RAG 检索流程

---

## 2. 数据模型

### 2.1 IntentRule 实体

| 字段 | 类型 | 必填 | 说明 |
|-----|------|------|------|
| `id` | UUID | 自动生成 | 规则唯一标识 |
| `tenant_id` | string | ✅ | 租户 ID（格式：name@ash@year） |
| `name` | string | ✅ | 规则名称（如"退货意图"） |
| `keywords` | string[] | ❌ | 关键词列表（如 ["退货", "退款"]） |
| `patterns` | string[] | ❌ | 正则表达式列表（如 ["退.*货", "如何退货"]） |
| `priority` | int | ❌ | 优先级（默认 0，数值越大优先级越高） |
| `response_type` | string | ✅ | 响应类型：fixed/rag/flow/transfer |
| `target_kb_ids` | string[] | ❌ | 目标知识库 ID 列表（rag 类型必填） |
| `flow_id` | UUID | ❌ | 话术流程 ID（flow 类型必填） |
| `fixed_reply` | string | ❌ | 固定回复内容（fixed 类型必填） |
| `transfer_message` | string | ❌ | 转人工提示语（transfer 类型必填） |
| `is_enabled` | bool | ✅ | 是否启用（默认 true） |
| `hit_count` | int | 自动 | 命中次数统计 |
| `created_at` | datetime | 自动 | 创建时间 |
| `updated_at` | datetime | 自动 | 更新时间 |

### 2.2 响应类型详解

#### 2.2.1 fixed - 固定回复

**用途**：对于明确的问题，直接返回预设的固定回复，跳过 LLM 生成。

**适用场景**：
- 常见问候语（"你好"、"在吗"）
- 简单查询（"营业时间"、"联系方式"）
- 标准流程说明（"如何下单"、"支付方式"）

**必填字段**：`fixed_reply`

**示例**：
```json
{
  "name": "营业时间查询",
  "keywords": ["营业时间", "几点开门", "几点关门"],
  "response_type": "fixed",
  "fixed_reply": "我们的营业时间是周一至周日 9:00-21:00，节假日正常营业。"
}
```

#### 2.2.2 rag - 定向知识库检索

**用途**：将用户问题路由到特定的知识库进行检索，而不是搜索所有知识库。

**适用场景**：
- 产品咨询 → 路由到产品知识库
- 售后问题 → 路由到售后知识库
- 政策查询 → 路由到政策知识库

**必填字段**：`target_kb_ids`（知识库 ID 列表）

**示例**：
```json
{
  "name": "产品咨询意图",
  "keywords": ["产品", "功能", "参数", "配置"],
  "patterns": [".*产品.*", "有什么功能"],
  "response_type": "rag",
  "target_kb_ids": ["kb_product_001", "kb_product_002"]
}
```

#### 2.2.3 flow - 启动话术流程

**用途**：触发预定义的多轮对话流程（话术脚本）。

**适用场景**：
- 订单处理流程（收集地址、确认信息）
- 问题诊断流程（逐步排查问题）
- 信息采集流程（收集用户需求）

**必填字段**：`flow_id`（话术流程 ID）

**示例**：
```json
{
  "name": "退货流程意图",
  "keywords": ["退货", "退款", "不想要了"],
  "response_type": "flow",
  "flow_id": "flow_return_process_001"
}
```

#### 2.2.4 transfer - 转人工

**用途**：直接转接到人工客服。

**适用场景**：
- 投诉建议
- 复杂问题
- 明确要求人工服务

**必填字段**：`transfer_message`（转人工提示语）

**示例**：
```json
{
  "name": "转人工意图",
  "keywords": ["人工", "客服", "投诉"],
  "patterns": ["转.*人工", "找.*客服"],
  "response_type": "transfer",
  "transfer_message": "正在为您转接人工客服，请稍候..."
}
```

---

## 3. 匹配算法

### 3.1 匹配流程

```
1. 加载启用的规则（is_enabled=true），按 priority DESC 排序
2. 遍历规则列表（从高优先级到低优先级）
3. 对每个规则：
   a. 先尝试关键词匹配（keywords）
   b. 如果关键词未匹配，尝试正则表达式匹配（patterns）
4. 命中第一个规则后立即返回，不再继续匹配
5. 如果所有规则都未匹配，返回 None（继续默认 RAG 流程）
```

### 3.2 关键词匹配规则

- **不区分大小写**：用户输入和关键词都转为小写后匹配
- **子串匹配**：只要用户消息包含关键词即可（如 "我想退货" 包含 "退货"）
- **任意匹配**：keywords 列表中任意一个关键词匹配即成功

**示例**：
```python
keywords = ["退货", "退款", "不想要"]
user_message = "我想退货"  # ✅ 匹配成功（包含"退货"）
user_message = "能退款吗"  # ✅ 匹配成功（包含"退款"）
user_message = "发货了吗"  # ❌ 匹配失败
```

### 3.3 正则表达式匹配规则

- **不区分大小写**：使用 `re.IGNORECASE` 标志
- **全文匹配**：使用 `re.search()`，匹配消息中的任意位置
- **任意匹配**：patterns 列表中任意一个模式匹配即成功
- **错误处理**：如果正则表达式语法错误，记录警告并跳过该模式

**示例**：
```python
patterns = ["退.*货", "如何.*退货", "^退货.*"]
user_message = "我想退货"      # ✅ 匹配 "退.*货"
user_message = "如何申请退货"  # ✅ 匹配 "如何.*退货"
user_message = "退货流程"      # ✅ 匹配 "^退货.*"
```

### 3.4 优先级机制

**规则排序**：
```sql
ORDER BY priority DESC, created_at DESC
```

**优先级策略**：
- 高优先级规则优先匹配
- 相同优先级按创建时间倒序（新规则优先）
- 建议为重要规则设置更高的优先级（如 100、200）

**示例场景**：
```
规则 A: priority=100, keywords=["退货"]        → 精确退货流程
规则 B: priority=50,  keywords=["退", "货"]   → 通用退货咨询
规则 C: priority=0,   keywords=["产品"]       → 产品咨询

用户输入 "我想退货"：
1. 先匹配规则 A（priority=100）→ 命中，返回
2. 不再匹配规则 B 和 C
```

---

## 4. API 使用

### 4.1 认证与租户隔离

所有接口必须携带以下 HTTP Headers：

```http
X-API-Key: <your_api_key>
X-Tenant-Id: <tenant_id>
```

### 4.2 创建意图规则

**接口**：`POST /admin/intent-rules`

**请求示例 1：固定回复**
```bash
curl -X POST http://ai-service:8080/admin/intent-rules \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-Tenant-Id: szmp@ash@2026" \
  -d '{
    "name": "营业时间查询",
    "keywords": ["营业时间", "几点开门", "几点关门", "什么时候营业"],
    "priority": 50,
    "response_type": "fixed",
    "fixed_reply": "我们的营业时间是周一至周日 9:00-21:00，节假日正常营业。如有特殊情况会提前通知。"
  }'
```

**请求示例 2：定向知识库检索**
```bash
curl -X POST http://ai-service:8080/admin/intent-rules \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-Tenant-Id: szmp@ash@2026" \
  -d '{
    "name": "产品咨询意图",
    "keywords": ["产品", "功能", "参数", "配置", "型号"],
    "patterns": [".*产品.*", "有什么功能", "支持.*吗"],
    "priority": 80,
    "response_type": "rag",
    "target_kb_ids": ["kb_product_001", "kb_product_faq_002"]
  }'
```

**请求示例 3：启动话术流程**
```bash
curl -X POST http://ai-service:8080/admin/intent-rules \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-Tenant-Id: szmp@ash@2026" \
  -d '{
    "name": "退货流程意图",
    "keywords": ["退货", "退款", "不想要了", "申请退货"],
    "patterns": ["退.*货", "如何.*退", "想.*退"],
    "priority": 100,
    "response_type": "flow",
    "flow_id": "550e8400-e29b-41d4-a716-446655440000"
  }'
```

**请求示例 4：转人工**
```bash
curl -X POST http://ai-service:8080/admin/intent-rules \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-Tenant-Id: szmp@ash@2026" \
  -d '{
    "name": "转人工意图",
    "keywords": ["人工", "客服", "投诉", "找人"],
    "patterns": ["转.*人工", "找.*客服", "我要.*投诉"],
    "priority": 200,
    "response_type": "transfer",
    "transfer_message": "正在为您转接人工客服，请稍候..."
  }'
```

---

## 5. 总结

意图规则（Intent Rule）是 AI 中台的智能路由系统，在 12 步生成流程的第 3 步执行。

### 5.1 核心流程

创建规则 → 设置关键词/正则 → 配置响应类型 → 启用规则 → 用户对话 → 意图匹配 → 路由处理

### 5.2 关键特性

- **智能路由**: 根据用户意图自动选择最佳处理方式
- **优先级控制**: 灵活的优先级机制避免冲突
- **四种响应**: 固定回复、RAG 检索、话术流程、转人工
- **高性能**: 60 秒缓存 + 优化的匹配算法
- **租户隔离**: 多租户数据完全独立
- **命中统计**: 自动记录规则使用情况

### 5.3 最佳实践

1. **关键词设计**: 2-6 个字，使用完整词组
2. **正则表达式**: 简单明了，避免过于复杂
3. **优先级分配**: 200+ 紧急、100-199 重要、50-99 常规、0-49 兜底
4. **响应类型**: 根据场景选择最合适的类型
5. **测试验证**: 先低优先级测试，再调整为正式优先级
6. **监控优化**: 定期检查命中率，优化关键词

---

**文档版本**: v1.0
**生成时间**: 2026-02-27
**维护状态**: ✅ 活跃维护
**相关文档**:
- [AI 中台对接文档](../AI中台对接文档.md)
- [Prompt 模板管理分析](./prompt-template-analysis.md)