# 豆包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密钥

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

### 配置环境变量

在 `backend/.env` 文件中配置：

```bash
# 必需配置
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. 连接建立

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

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

### 2. 音频发送

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

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

### 3. 音频接收

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

### 4. 连接关闭

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

## 测试验证

### 1. 测试模拟API

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

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

### 2. 测试真实API

```bash
# 配置.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. 端到端测试

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

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

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

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

## 性能监控

### 查看连接池状态

```bash
curl http://localhost:8000/health
```

输出：
```json
{
  "connection_pool": {
    "initialized": true,
    "pool_size": 10,
    "idle": 8,
    "active": 2
  }
}
```

### 查看实时日志

```bash
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文档

### 自动降级

系统具有自动降级机制：

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

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

## 性能优化

### 连接池配置建议

```bash
# 开发环境
CONNECTION_POOL_SIZE=5

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

### 音频格式选择

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

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

## 下一步

### 1. 验证集成

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

### 2. 优化配置

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

### 3. 生产部署

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

## 相关文档

- [环境变量配置说明](./ENV_CONFIG.md)
- [后端README](./README.md)
- [API文档](../项目文档/API文档.md)
- [豆包官方demo](../doubao-api/)

## 技术支持

遇到问题？

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

---

**祝集成顺利！** 🚀