豆包API集成指南

概述

本文档说明如何将真实的豆包API集成到Tolan后端服务中。

集成状态

✅ 已完成: 豆包API集成代码已完成，支持真实API和模拟API自动切换

架构说明

客户端音频 → 后端WSS → 连接池 → 豆包API客户端 → 豆包服务器
                                    ↓
客户端播放 ← 后端WSS ← 连接池 ← 豆包API客户端 ← 豆包响应

核心模块

1. 协议模块 (doubao_api/protocol.py)

负责豆包API的消息编码和解码：

generate_header() - 生成协议头
parse_response() - 解析响应消息

2. 客户端模块 (doubao_api/realtime_dialog_client.py)

实现豆包API的完整客户端：

connect() - 建立连接并初始化会话
send_audio() - 发送PCM音频数据
receive_audio() - 接收OGG/Opus音频数据
close() - 优雅关闭连接

3. 连接池模块 (connection_pool.py)

管理豆包API连接的生命周期：

预创建连接（消除延迟）
连接复用
健康检查
自动重建

豆包API配置

获取API密钥

访问豆包开放平台: https://www.volcengine.com/
注册账号并登录
创建应用
获取以下信息：
- API Key (X-Api-Access-Key)
- App ID (X-Api-App-ID)

配置环境变量

在 backend/.env 文件中配置：

# 必需配置
DOUBAO_API_KEY=your_api_key_here
DOUBAO_APP_ID=your_app_id_here

# 可选配置
DOUBAO_API_URL=wss://openspeech.bytedance.com/api/v3/realtime/dialogue
DOUBAO_OUTPUT_FORMAT=ogg_opus

音频格式说明

输入格式（客户端 → 豆包）

格式: PCM
采样率: 16000 Hz
位深: 16 bit (Int16)
声道: 单声道
字节序: 小端序

输出格式（豆包 → 客户端）

格式: OGG封装的Opus音频
采样率: 24000 Hz
压缩: 高效压缩
特点: 浏览器原生支持

豆包API事件类型

发送事件

Event	类型	说明
1	StartConnection	开始连接
2	FinishConnection	结束连接
100	StartSession	开始会话
102	FinishSession	结束会话
200	AudioData	音频数据

接收事件

Event	说明	处理方式
400	音频数据	转发给客户端播放
401	对话结束	停止接收
其他	控制消息	日志记录

集成工作流

1. 连接建立

client = RealtimeDialogClient(
    api_key="your_key",
    app_id="your_app_id"
)

# 连接会自动：
# 1. 建立WebSocket连接
# 2. 发送StartConnection请求
# 3. 发送StartSession请求
await client.connect()

2. 音频发送

# 接收客户端PCM数据
pcm_audio = await websocket.receive_bytes()

# 转发给豆包（会自动压缩）
await client.send_audio(pcm_audio)

3. 音频接收

# 持续接收豆包响应
while True:
    audio_data = await client.receive_audio()
    
    if audio_data:
        # 转发给客户端
        await websocket.send_bytes(audio_data)
    else:
        # 对话结束
        break

4. 连接关闭

# 优雅关闭
await client.close()
# 会自动：
# 1. 发送FinishSession请求
# 2. 发送FinishConnection请求
# 3. 关闭WebSocket

测试验证

1. 测试模拟API

# 不配置豆包API密钥
python main.py

看到日志：

[WARNING] 豆包API密钥未配置，创建模拟连接
[SUCCESS] 连接 #0 创建成功 (模拟)

2. 测试真实API

# 配置.env文件
echo "DOUBAO_API_KEY=your_key" > .env
echo "DOUBAO_APP_ID=your_app_id" >> .env

# 启动服务
python main.py

看到日志：

[INFO] 连接豆包API: wss://openspeech.bytedance.com/...
[SUCCESS] 豆包API连接成功，LogID: xxx
[SUCCESS] 豆包会话已建立: session_xxx
[SUCCESS] 连接 #0 创建成功 (真实API)

3. 端到端测试

# 1. 启动后端
cd backend
python main.py

# 2. 启动前端（新终端）
cd frontend
npm run dev

# 3. 浏览器访问
open http://localhost:5173

# 4. 测试对话
# - 按住录音按钮说话
# - 松开按钮等待回复
# - 查看延迟指标

性能监控

查看连接池状态

curl http://localhost:8000/health

输出：

{
  "connection_pool": {
    "initialized": true,
    "pool_size": 10,
    "idle": 8,
    "active": 2
  }
}

查看实时日志

tail -f logs/app_*.log

关键日志：

[INFO] 连接豆包API: wss://...
[SUCCESS] 豆包会话已建立
[DEBUG] 发送音频到豆包: 1024 bytes
[DEBUG] 收到豆包音频: 2048 bytes

错误处理

常见错误

1. API密钥错误

错误:

[ERROR] 连接 #0 创建失败: 401 Unauthorized

解决:

检查DOUBAO_API_KEY是否正确
检查DOUBAO_APP_ID是否正确
确认密钥未过期

2. 网络连接失败

错误:

[ERROR] 连接豆包API失败: Connection refused

解决:

检查网络连接
确认防火墙设置
检查API URL是否正确

3. 会话建立失败

错误:

[ERROR] StartSession响应错误

解决:

查看详细错误信息
检查会话配置参数
查看豆包API文档

自动降级

系统具有自动降级机制：

try:
    # 尝试创建真实API连接
    client = RealtimeDialogClient(...)
    await client.connect()
except Exception as e:
    # 失败则创建模拟连接
    logger.warning("回退到模拟连接")
    client = MockConnection()

好处：

✅ 开发环境无需API密钥即可测试
✅ API故障时不会中断服务
✅ 便于前端独立开发

性能优化

连接池配置建议

# 开发环境
CONNECTION_POOL_SIZE=5

# 生产环境
CONNECTION_POOL_SIZE=20  # 根据并发量调整

音频格式选择

# 推荐: OGG/Opus（高压缩率，低带宽）
DOUBAO_OUTPUT_FORMAT=ogg_opus

# 备选: PCM（无压缩，高质量，高带宽）
DOUBAO_OUTPUT_FORMAT=pcm

下一步

1. 验证集成

配置豆包API密钥
启动服务，检查连接池初始化
测试音频发送和接收
验证延迟指标

2. 优化配置

调整连接池大小
配置AI提示词（system_role）
选择合适的音色（speaker）
调整超时参数

3. 生产部署

配置SSL证书
配置环境变量
设置进程管理
配置监控告警

技术支持

遇到问题？

查看日志文件 logs/app_*.log
检查 /health 端点
参考豆包官方文档
提交Issue

祝集成顺利！ 🚀

INTEGRATION_GUIDE.md 6.7 KB 文件历史 原始文件