323 lines
10 KiB
Markdown
323 lines
10 KiB
Markdown
# 意图规则使用指南
|
||
|
||
## 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)
|