peanut
ca42a7d9a4
- 删除分布式架构相关文件和配置 - 将backend-distributed重命名为backend保留分布式代码作为参考 - 优化backend-single单体架构实现 - 添加Coze API集成相关文档和测试 - 清理项目根目录的部署脚本和配置文件 - 更新WebSocket和消息服务实现 - 完善认证服务和密码加密功能
143 lines
3.4 KiB
Markdown
143 lines
3.4 KiB
Markdown
# Coze API 集成说明
|
||
|
||
## 概述
|
||
|
||
本项目已经优化了 AiChatServiceImpl 的 Coze API 接口实现，确保能够正确调用 Coze 的 v3 API。
|
||
|
||
## 配置说明
|
||
|
||
### application.yml 配置
|
||
|
||
```yaml
|
||
emotion:
|
||
coze:
|
||
api:
|
||
token: pat_GCR4qKzqpf90wMCvKsldMrB18KG3QsLDci65bZthssKsbLxu8X70BKYumleDcabO
|
||
base-url: https://api.coze.cn
|
||
chat:
|
||
path: /v3/chat
|
||
talk:
|
||
bot-id: 7523042446285439016
|
||
workflow-id: 7523047462895796287
|
||
summary:
|
||
bot-id: 7529062814150295595
|
||
workflow-id: 7523047462895796287
|
||
timeout: 30000
|
||
retry-count: 3
|
||
retry-delay: 1000
|
||
```
|
||
|
||
### 配置项说明
|
||
|
||
- `token`: Coze API 的访问令牌，格式为 `pat_` 开头
|
||
- `base-url`: Coze API 的基础URL，通常为 `https://api.coze.cn`
|
||
- `chat.path`: 聊天API的路径，固定为 `/v3/chat`
|
||
- `chat.talk.bot-id`: 对话聊天使用的机器人ID
|
||
- `chat.talk.workflow-id`: 对话聊天使用的工作流ID
|
||
- `chat.summary.bot-id`: 聊天记录总结使用的机器人ID
|
||
- `chat.summary.workflow-id`: 聊天记录总结使用的工作流ID
|
||
- `timeout`: API调用超时时间（毫秒）
|
||
- `retry-count`: 重试次数
|
||
- `retry-delay`: 重试延迟（毫秒）
|
||
|
||
## API 调用流程
|
||
|
||
### 1. 发送聊天消息
|
||
|
||
```java
|
||
String response = aiChatService.sendChatMessage(conversationId, message, userId);
|
||
```
|
||
|
||
### 2. 访客聊天
|
||
|
||
```java
|
||
Map<String, Object> response = aiChatService.guestChat(message, clientIp);
|
||
```
|
||
|
||
### 3. 生成对话总结
|
||
|
||
```java
|
||
String summary = aiChatService.generateConversationSummary(conversationId, userId);
|
||
```
|
||
|
||
## 实现特点
|
||
|
||
### 1. 正确的 API 调用流程
|
||
|
||
1. **发送聊天请求**: 调用 `/v3/chat` 接口发送消息
|
||
2. **获取 chat_id**: 从响应中提取 `chat_id` 和 `conversation_id`
|
||
3. **轮询状态**: 使用 `/v3/chat/retrieve` 接口轮询聊天状态
|
||
4. **获取消息**: 当状态为 `completed` 时，调用 `/v3/chat/message/list` 获取AI回复
|
||
|
||
### 2. 请求格式
|
||
|
||
```json
|
||
{
|
||
"bot_id": "7523042446285439016",
|
||
"workflow_id": "7523047462895796287",
|
||
"user_id": "user-123",
|
||
"stream": false,
|
||
"additional_messages": [
|
||
{
|
||
"role": "user",
|
||
"content": "用户消息内容",
|
||
"content_type": "text",
|
||
"type": "question"
|
||
}
|
||
],
|
||
"parameters": {}
|
||
}
|
||
```
|
||
|
||
### 3. 响应处理
|
||
|
||
- 解析初始响应获取 `chat_id` 和 `conversation_id`
|
||
- 轮询聊天状态直到完成（最多30秒，每2秒一次）
|
||
- 从消息列表中提取 AI 回复（role=assistant, type=answer）
|
||
|
||
### 4. 错误处理
|
||
|
||
- 网络异常处理
|
||
- API 错误响应处理
|
||
- 超时处理
|
||
- 重试机制
|
||
|
||
## 测试
|
||
|
||
运行以下命令测试 API 集成：
|
||
|
||
```bash
|
||
mvn test -Dtest=CozeApiTest
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **API Token**: 确保使用有效的 Coze API token
|
||
2. **Bot ID**: 确保 bot_id 和 workflow_id 正确配置
|
||
3. **网络连接**: 确保服务器能够访问 `https://api.coze.cn`
|
||
4. **超时设置**: 根据实际情况调整超时时间
|
||
5. **错误处理**: 生产环境中应该有完善的错误处理和日志记录
|
||
|
||
## 故障排除
|
||
|
||
### 1. 检查配置
|
||
|
||
```bash
|
||
# 检查配置是否正确加载
|
||
curl -X GET http://localhost:19089/api/ai/health
|
||
```
|
||
|
||
### 2. 查看日志
|
||
|
||
```bash
|
||
# 查看详细的API调用日志
|
||
tail -f logs/emotion-single.log | grep -i coze
|
||
```
|
||
|
||
### 3. 常见错误
|
||
|
||
- **401 Unauthorized**: 检查 API token 是否正确
|
||
- **404 Not Found**: 检查 bot_id 是否存在
|
||
- **Timeout**: 增加超时时间或检查网络连接
|
||
- **Rate Limit**: 检查API调用频率限制
|