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

示例：

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

2.2.2 rag - 定向知识库检索

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

适用场景：

• 产品咨询 → 路由到产品知识库
• 售后问题 → 路由到售后知识库
• 政策查询 → 路由到政策知识库

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

示例：

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

2.2.3 flow - 启动话术流程

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

适用场景：

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

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

示例：

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

2.2.4 transfer - 转人工

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

适用场景：

• 投诉建议
• 复杂问题
• 明确要求人工服务

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

示例：

{
  "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 列表中任意一个关键词匹配即成功

示例：

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

3.3 正则表达式匹配规则

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

示例：

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

3.4 优先级机制

规则排序：

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：

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

4.2 创建意图规则

接口：POST /admin/intent-rules

请求示例 1：固定回复

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：定向知识库检索

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：启动话术流程

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：转人工

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 中台对接文档
• Prompt 模板管理分析