155 lines
4.8 KiB
Markdown
155 lines
4.8 KiB
Markdown
# 微信公众号AI助手服务技术文档
|
||
|
||
## 1. 概述
|
||
本服务是一个基于Flask的微信公众号后端服务，实现了与Dify AI平台的集成。主要功能包括：
|
||
- 验证微信服务器请求的合法性
|
||
- 接收用户消息并调用Dify AI服务获取智能回复
|
||
- 通过微信客服消息接口异步返回AI回复
|
||
- 维护用户会话状态，支持多轮对话
|
||
|
||
## 2. 功能描述
|
||
| 功能模块 | 描述 | 实现方式 |
|
||
|---------|------|---------|
|
||
| 微信服务器验证 | 验证微信服务器请求的合法性 | SHA1签名验证 |
|
||
| 消息接收与路由 | 接收并处理用户消息 | XML解析与路由 |
|
||
| AI服务调用 | 调用Dify AI服务获取智能回复 | HTTP POST请求 |
|
||
| 会话管理 | 维护用户对话上下文 | 内存映射(conv_map) |
|
||
| 客服消息发送 | 异步发送AI回复给用户 | 微信客服消息接口 |
|
||
| 被动回复 | 即时返回"正在查询"提示 | XML格式响应 |
|
||
|
||
## 3. 环境要求
|
||
- Python 3.7+
|
||
- Flask 2.0+
|
||
- Requests库
|
||
- 微信公众号（服务号或订阅号）
|
||
- Dify AI服务（本地或云端）
|
||
|
||
## 4. 配置说明
|
||
在代码全局配置区设置以下参数：
|
||
|
||
```python
|
||
# 微信相关配置
|
||
TOKEN = "your_wechat_token" # 与微信公众号后台配置一致
|
||
APPID = "your_appid" # 微信公众号APPID
|
||
APPSECRET = "your_appsecret" # 微信公众号APPSECRET
|
||
|
||
# Dify AI服务配置
|
||
DIFY_API_BASE = "http://your-dify-server/api" # Dify API地址
|
||
DIFY_API_KEY = "your_dify_api_key" # Dify API密钥（可选）
|
||
```
|
||
|
||
## 5. 核心模块说明
|
||
|
||
### 5.1 微信服务器验证 (`/wx` GET请求)
|
||
- 验证流程：
|
||
1. 获取请求参数：signature, timestamp, nonce, echostr
|
||
2. 对token、timestamp、nonce进行字典序排序
|
||
3. 拼接字符串并进行SHA1加密
|
||
4. 比较加密结果与signature是否一致
|
||
- 成功：返回echostr
|
||
- 失败：返回403错误
|
||
|
||
### 5.2 消息处理 (`/wx` POST请求)
|
||
- 支持的消息类型：文本消息(MsgType=text)
|
||
- 处理流程：
|
||
1. 解析XML消息体
|
||
2. 提取用户OpenID、公众号ID和消息内容
|
||
3. 启动后台线程调用AI服务
|
||
4. 立即返回"正在查询"的被动回复
|
||
|
||
### 5.3 Dify AI服务调用 (`async_reply`函数)
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant W as 微信用户
|
||
participant S as 本服务
|
||
participant D as Dify AI服务
|
||
W->>S: 发送文本消息
|
||
S->>S: 启动后台线程
|
||
S->>W: 返回"正在查询"提示
|
||
S->>D: 发送用户消息和会话ID
|
||
D->>S: 返回AI回复和会话ID
|
||
S->>S: 更新会话映射(conv_map)
|
||
S->>W: 通过客服消息发送AI回复
|
||
```
|
||
|
||
### 5.4 客服消息发送 (`send_wechat_customer_message`函数)
|
||
- 使用微信客服消息接口发送文本消息
|
||
- 前提条件：
|
||
- 公众号已完成认证
|
||
- 用户在48小时内与公众号有过交互
|
||
- 消息格式：
|
||
```json
|
||
{
|
||
"touser": "OPENID",
|
||
"msgtype": "text",
|
||
"text": {"content": "消息内容"}
|
||
}
|
||
```
|
||
|
||
### 5.5 会话管理
|
||
- 使用全局字典`conv_map`存储会话状态
|
||
- 数据结构：`{user_openid: conversation_id}`
|
||
- 会话保持：每次调用Dify时带上conversation_id
|
||
- 新会话：当用户首次交互时自动创建新会话
|
||
|
||
## 6. 部署与运行
|
||
|
||
### 6.1 安装依赖
|
||
```bash
|
||
pip install flask requests
|
||
```
|
||
|
||
### 6.2 运行服务
|
||
```bash
|
||
python wechat_kefu.py
|
||
```
|
||
|
||
### 6.3 微信公众号配置
|
||
1. 服务器地址(URL): `http://your-domain/wx`
|
||
2. Token: 与代码中TOKEN一致
|
||
3. 消息加解密方式: 明文模式
|
||
|
||
## 7. 注意事项
|
||
|
||
### 7.1 安全性
|
||
1. 验证所有来自微信服务器的请求
|
||
2. 保护APP_SECRET和API_KEY不被泄露
|
||
3. 生产环境禁用DEBUG模式
|
||
4. 使用HTTPS加密传输
|
||
|
||
### 7.2 性能优化
|
||
1. 实现access_token缓存（有效期7200秒）
|
||
2. 限制用户请求频率
|
||
3. 使用连接池管理HTTP连接
|
||
4. 监控conv_map内存使用情况
|
||
|
||
### 7.3 异常处理
|
||
1. Dify服务不可用：返回用户友好提示
|
||
2. 客服消息发送失败：记录日志并重试
|
||
3. 会话丢失：自动创建新会话
|
||
4. 非文本消息：忽略并返回success
|
||
|
||
### 7.4 扩展性
|
||
1. 支持其他消息类型（如图片、语音）
|
||
2. 添加用户身份验证
|
||
3. 集成多个AI服务提供商
|
||
4. 实现消息队列处理异步任务
|
||
|
||
## 8. 常见问题排查
|
||
|
||
| 问题现象 | 可能原因 | 解决方案 |
|
||
|----------|---------|----------|
|
||
| 微信验证失败 | TOKEN配置不一致 | 检查公众号后台配置 |
|
||
| 无法接收消息 | 服务器网络问题 | 检查服务器防火墙设置 |
|
||
| 客服消息发送失败 | access_token过期 | 实现token缓存机制 |
|
||
| AI回复乱码 | 编码问题 | 检查Unicode解码逻辑 |
|
||
| 会话不连续 | conv_map未持久化 | 使用数据库存储会话 |
|
||
|
||
## 9. 版本信息
|
||
- 初始版本：1.0
|
||
- 最后更新：2025-06-05
|
||
- 依赖版本：
|
||
- Flask 2.1.2
|
||
- Requests 2.28.1
|
||
|
||
> 注意：本服务需要微信公众号具备客服消息接口权限，开发前请确认公众号类型和权限设置。 |