998211c483
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
435 lines
11 KiB
Markdown
435 lines
11 KiB
Markdown
# Coze API 使用文档
|
||
|
||
## 一、概述
|
||
|
||
Coze是字节跳动推出的AI对话平台，提供强大的Bot开发和对话管理能力。本文档整理了考培练系统陪练功能需要使用的核心API。
|
||
|
||
### 官方资源
|
||
- **官方文档**: https://www.coze.cn/open/docs/developer_guides/chat_v3
|
||
- **Python SDK**: https://github.com/coze-dev/coze-py
|
||
- **API域名**: https://api.coze.cn (中国区)
|
||
|
||
### 重要提示
|
||
⚠️ **从GitHub获取的源码和示例默认使用 `COZE_COM_BASE_URL`，使用前必须改为 `COZE_CN_BASE_URL`**
|
||
|
||
## 二、认证方式
|
||
|
||
### 2.1 个人访问令牌 (Personal Access Token - 推荐)
|
||
|
||
**获取方式**：
|
||
1. 访问 https://www.coze.cn/open/oauth/pats
|
||
2. 创建新的个人访问令牌
|
||
3. 设置名称、有效期和权限
|
||
4. 保存令牌（仅显示一次）
|
||
|
||
**使用示例**：
|
||
```python
|
||
from cozepy import Coze, TokenAuth, COZE_CN_BASE_URL
|
||
|
||
coze = Coze(
|
||
auth=TokenAuth(token="pat_Sa5OiuUl0gDflnKstQTToIz0sSMshBV06diX0owOeuI1ZK1xDLH5YZH9fSeuKLIi"),
|
||
base_url=COZE_CN_BASE_URL # 重要：使用中国区域名
|
||
)
|
||
```
|
||
|
||
### 2.2 OAuth JWT认证 (生产环境推荐)
|
||
|
||
```python
|
||
from cozepy import Coze, JWTAuth, COZE_CN_BASE_URL
|
||
from pathlib import Path
|
||
|
||
coze = Coze(
|
||
auth=JWTAuth(
|
||
client_id="your_client_id",
|
||
private_key=Path("private_key.pem").read_text(),
|
||
public_key_id="your_public_key_id",
|
||
ttl=900 # Token有效期（秒）
|
||
),
|
||
base_url=COZE_CN_BASE_URL
|
||
)
|
||
```
|
||
|
||
## 三、核心API功能
|
||
|
||
### 3.1 Bot对话 (Chat API)
|
||
|
||
#### 流式对话 (推荐)
|
||
|
||
**功能说明**：实时流式返回AI响应，适合陪练对话场景
|
||
|
||
**示例代码**：
|
||
```python
|
||
from cozepy import Coze, TokenAuth, Message, ChatEventType, COZE_CN_BASE_URL
|
||
|
||
coze = Coze(auth=TokenAuth(token="your_token"), base_url=COZE_CN_BASE_URL)
|
||
|
||
# 创建流式对话
|
||
stream = coze.chat.stream(
|
||
bot_id='7560643598174683145', # 陪练Bot ID
|
||
user_id='user_123', # 用户ID（业务系统的用户标识）
|
||
additional_messages=[
|
||
Message.build_user_question_text("你好，我想练习轻医美产品咨询"),
|
||
],
|
||
conversation_id='conv_abc', # 可选：关联对话ID
|
||
)
|
||
|
||
# 处理流式事件
|
||
for event in stream:
|
||
if event.event == ChatEventType.CONVERSATION_MESSAGE_DELTA:
|
||
# 消息增量（实时打字效果）
|
||
print(event.message.content, end="", flush=True)
|
||
|
||
elif event.event == ChatEventType.CONVERSATION_MESSAGE_COMPLETED:
|
||
# 消息完成
|
||
print("\n消息完成")
|
||
|
||
elif event.event == ChatEventType.CONVERSATION_CHAT_COMPLETED:
|
||
# 对话完成
|
||
print("Token用量:", event.chat.usage.token_count)
|
||
break
|
||
|
||
elif event.event == ChatEventType.CONVERSATION_CHAT_FAILED:
|
||
# 对话失败
|
||
print("对话失败:", event.chat.last_error)
|
||
break
|
||
```
|
||
|
||
#### 非流式对话
|
||
|
||
```python
|
||
chat = coze.chat.create(
|
||
bot_id='bot_id',
|
||
user_id='user_id',
|
||
additional_messages=[
|
||
Message.build_user_question_text('你好')
|
||
]
|
||
)
|
||
print(chat.content)
|
||
```
|
||
|
||
### 3.2 对话管理 (Conversation API)
|
||
|
||
#### 创建对话
|
||
|
||
```python
|
||
# 创建新对话
|
||
conversation = coze.conversations.create()
|
||
print("对话ID:", conversation.id)
|
||
```
|
||
|
||
#### 获取对话列表
|
||
|
||
```python
|
||
# 获取Bot的对话列表
|
||
conversations = coze.conversations.list(
|
||
bot_id='bot_id',
|
||
page_num=1,
|
||
page_size=20
|
||
)
|
||
|
||
for conv in conversations.items:
|
||
print(f"对话ID: {conv.id}, 创建时间: {conv.created_at}")
|
||
```
|
||
|
||
#### 删除对话
|
||
|
||
```python
|
||
# 删除指定对话
|
||
coze.conversations.delete(conversation_id='conversation_id')
|
||
```
|
||
|
||
### 3.3 消息历史
|
||
|
||
#### 获取对话消息
|
||
|
||
```python
|
||
# 获取指定对话的消息列表
|
||
messages = coze.conversations.messages.list(
|
||
conversation_id='conversation_id',
|
||
page_num=1,
|
||
page_size=50
|
||
)
|
||
|
||
for msg in messages.items:
|
||
print(f"{msg.role}: {msg.content}")
|
||
```
|
||
|
||
### 3.4 中断对话
|
||
|
||
```python
|
||
# 中断正在进行的对话
|
||
result = coze.chat.cancel(
|
||
conversation_id='conversation_id',
|
||
chat_id='chat_id'
|
||
)
|
||
```
|
||
|
||
### 3.5 文件上传 (可选)
|
||
|
||
```python
|
||
from pathlib import Path
|
||
|
||
# 上传文件（如音频文件）
|
||
uploaded_file = coze.files.upload(file=Path('audio.wav'))
|
||
print("文件ID:", uploaded_file.id)
|
||
|
||
# 在消息中使用文件
|
||
from cozepy import MessageObjectString
|
||
|
||
message = Message.build_user_question_objects([
|
||
MessageObjectString.build_audio(file_id=uploaded_file.id)
|
||
])
|
||
```
|
||
|
||
## 四、事件类型说明
|
||
|
||
### 4.1 ChatEventType枚举
|
||
|
||
| 事件类型 | 说明 | 用途 |
|
||
|---------|------|------|
|
||
| `CONVERSATION_CHAT_CREATED` | 对话创建 | 获取chat_id和conversation_id |
|
||
| `CONVERSATION_MESSAGE_DELTA` | 消息增量 | 实时显示打字效果 |
|
||
| `CONVERSATION_MESSAGE_COMPLETED` | 消息完成 | 显示完整消息 |
|
||
| `CONVERSATION_CHAT_COMPLETED` | 对话完成 | 统计Token用量、清理状态 |
|
||
| `CONVERSATION_CHAT_FAILED` | 对话失败 | 错误处理、用户提示 |
|
||
| `CONVERSATION_AUDIO_DELTA` | 音频增量 | 实时语音播放（语音对话） |
|
||
|
||
### 4.2 事件对象结构
|
||
|
||
```python
|
||
# 消息增量事件
|
||
event.event == ChatEventType.CONVERSATION_MESSAGE_DELTA
|
||
event.message.content # 消息内容增量
|
||
event.message.role # 消息角色：user/assistant
|
||
|
||
# 对话完成事件
|
||
event.event == ChatEventType.CONVERSATION_CHAT_COMPLETED
|
||
event.chat.id # 对话ID
|
||
event.chat.conversation_id # 会话ID
|
||
event.chat.usage.token_count # Token用量
|
||
event.chat.usage.input_count # 输入Token数
|
||
event.chat.usage.output_count # 输出Token数
|
||
|
||
# 对话失败事件
|
||
event.event == ChatEventType.CONVERSATION_CHAT_FAILED
|
||
event.chat.last_error # 错误信息
|
||
```
|
||
|
||
## 五、消息构建方法
|
||
|
||
### 5.1 文本消息
|
||
|
||
```python
|
||
from cozepy import Message
|
||
|
||
# 用户问题
|
||
user_msg = Message.build_user_question_text("你好，我想了解产品")
|
||
|
||
# 助手回答
|
||
assistant_msg = Message.build_assistant_answer("好的，我来为您介绍")
|
||
```
|
||
|
||
### 5.2 多轮对话
|
||
|
||
```python
|
||
# 构建对话历史
|
||
messages = [
|
||
Message.build_user_question_text("第一个问题"),
|
||
Message.build_assistant_answer("第一个回答"),
|
||
Message.build_user_question_text("第二个问题"),
|
||
]
|
||
|
||
stream = coze.chat.stream(
|
||
bot_id='bot_id',
|
||
user_id='user_id',
|
||
additional_messages=messages
|
||
)
|
||
```
|
||
|
||
## 六、错误处理
|
||
|
||
### 6.1 常见错误
|
||
|
||
```python
|
||
from cozepy.exception import CozePyError
|
||
|
||
try:
|
||
chat = coze.chat.create(bot_id='bot_id', user_id='user_id')
|
||
except CozePyError as e:
|
||
print(f"Coze API错误: {e}")
|
||
# 处理错误
|
||
```
|
||
|
||
### 6.2 超时配置
|
||
|
||
```python
|
||
import httpx
|
||
from cozepy import Coze, TokenAuth, SyncHTTPClient
|
||
|
||
# 自定义超时设置
|
||
http_client = SyncHTTPClient(timeout=httpx.Timeout(
|
||
timeout=180.0, # 总超时
|
||
connect=5.0 # 连接超时
|
||
))
|
||
|
||
coze = Coze(
|
||
auth=TokenAuth(token="your_token"),
|
||
base_url=COZE_CN_BASE_URL,
|
||
http_client=http_client
|
||
)
|
||
```
|
||
|
||
## 七、调试技巧
|
||
|
||
### 7.1 日志配置
|
||
|
||
```python
|
||
import logging
|
||
from cozepy import setup_logging
|
||
|
||
# 启用DEBUG日志
|
||
setup_logging(level=logging.DEBUG)
|
||
```
|
||
|
||
### 7.2 获取LogID
|
||
|
||
```python
|
||
# 每个请求都有唯一的logid用于排查问题
|
||
bot = coze.bots.retrieve(bot_id='bot_id')
|
||
print("LogID:", bot.response.logid)
|
||
|
||
stream = coze.chat.stream(bot_id='bot_id', user_id='user_id')
|
||
print("LogID:", stream.response.logid)
|
||
```
|
||
|
||
## 八、最佳实践
|
||
|
||
### 8.1 陪练对话场景建议
|
||
|
||
1. **使用流式响应**：提供更好的用户体验
|
||
2. **传递对话上下文**：使用`conversation_id`保持多轮对话
|
||
3. **合理设置超时**：陪练对话建议180秒超时
|
||
4. **错误重试机制**：网络波动时自动重试
|
||
5. **Token计数统计**：监控API使用成本
|
||
|
||
### 8.2 用户ID设计
|
||
|
||
```python
|
||
# 推荐：使用业务系统的用户ID
|
||
user_id = f"trainee_{user.id}" # trainee_123
|
||
|
||
# 对话ID可包含场景信息
|
||
conversation_id = f"practice_{scene_id}_{user_id}_{timestamp}"
|
||
```
|
||
|
||
### 8.3 场景参数传递
|
||
|
||
可以通过Bot的系统提示词（Prompt）或参数传递场景信息：
|
||
|
||
```python
|
||
# 方式1：在用户消息中包含场景背景
|
||
scene_context = """
|
||
场景：轻医美产品咨询
|
||
背景：客户是30岁女性，关注面部抗衰
|
||
AI角色：扮演挑剔的客户，对价格敏感
|
||
"""
|
||
|
||
stream = coze.chat.stream(
|
||
bot_id='bot_id',
|
||
user_id='user_id',
|
||
additional_messages=[
|
||
Message.build_user_question_text(scene_context + "\n\n开始陪练")
|
||
]
|
||
)
|
||
```
|
||
|
||
## 九、性能优化
|
||
|
||
### 9.1 连接复用
|
||
|
||
```python
|
||
# 全局初始化一次Coze客户端
|
||
coze = Coze(auth=TokenAuth(token="your_token"), base_url=COZE_CN_BASE_URL)
|
||
|
||
# 多次调用复用连接
|
||
def handle_chat(user_id, message):
|
||
stream = coze.chat.stream(bot_id='bot_id', user_id=user_id, ...)
|
||
return stream
|
||
```
|
||
|
||
### 9.2 异步并发
|
||
|
||
```python
|
||
from cozepy import AsyncCoze, AsyncTokenAuth
|
||
import asyncio
|
||
|
||
async_coze = AsyncCoze(
|
||
auth=AsyncTokenAuth(token="your_token"),
|
||
base_url=COZE_CN_BASE_URL
|
||
)
|
||
|
||
async def concurrent_chats():
|
||
tasks = [
|
||
async_coze.chat.create(bot_id='bot_id', user_id=f'user_{i}')
|
||
for i in range(10)
|
||
]
|
||
results = await asyncio.gather(*tasks)
|
||
return results
|
||
```
|
||
|
||
## 十、陪练系统专用配置
|
||
|
||
### 10.1 配置信息
|
||
|
||
```python
|
||
# 考培练系统陪练Bot配置
|
||
COZE_API_BASE = "https://api.coze.cn"
|
||
COZE_API_TOKEN = "pat_Sa5OiuUl0gDflnKstQTToIz0sSMshBV06diX0owOeuI1ZK1xDLH5YZH9fSeuKLIi"
|
||
COZE_PRACTICE_BOT_ID = "7560643598174683145"
|
||
```
|
||
|
||
### 10.2 FastAPI集成示例
|
||
|
||
```python
|
||
from fastapi import FastAPI
|
||
from fastapi.responses import StreamingResponse
|
||
from cozepy import Coze, TokenAuth, Message, ChatEventType, COZE_CN_BASE_URL
|
||
import json
|
||
|
||
app = FastAPI()
|
||
coze = Coze(auth=TokenAuth(token="your_token"), base_url=COZE_CN_BASE_URL)
|
||
|
||
@app.post("/api/v1/practice/start")
|
||
async def start_practice(user_id: str, message: str):
|
||
"""开始陪练对话（SSE流式返回）"""
|
||
def generate_stream():
|
||
stream = coze.chat.stream(
|
||
bot_id=COZE_PRACTICE_BOT_ID,
|
||
user_id=user_id,
|
||
additional_messages=[Message.build_user_question_text(message)]
|
||
)
|
||
|
||
for event in stream:
|
||
if event.event == ChatEventType.CONVERSATION_MESSAGE_DELTA:
|
||
yield f"event: message.delta\ndata: {json.dumps({'content': event.message.content})}\n\n"
|
||
elif event.event == ChatEventType.CONVERSATION_CHAT_COMPLETED:
|
||
yield f"event: done\ndata: [DONE]\n\n"
|
||
|
||
return StreamingResponse(
|
||
generate_stream(),
|
||
media_type="text/event-stream"
|
||
)
|
||
```
|
||
|
||
## 十一、参考资料
|
||
|
||
- **Coze Python SDK GitHub**: https://github.com/coze-dev/coze-py
|
||
- **示例代码目录**: `参考代码/coze-py-main/examples/`
|
||
- **后端参考实现**: `参考代码/coze-chat-backend/main.py`
|
||
- **官方文档**: https://www.coze.cn/open/docs
|
||
|
||
---
|
||
|
||
**文档维护**：本文档基于 Coze Python SDK v0.19.0 编写，最后更新时间：2025-10-13
|
||
|