Accueil Explorer Aide
S'inscrire Connexion
wuzilong
/
Tolan
1
0
Fork 0
Fichiers Tickets 0 Pull Requests 0 Wiki
Aborescence: c7d86c63fa
Branches Tags
Tolan
/
INTEGRATION_GUIDE.md

INTEGRATION_GUIDE.md 5.1 KB
Historique Raw

豆包实时API集成指南

概览

本项目已完成豆包实时语音对话API的集成，实现了完整的录音 → 豆包API → 音频回复流程。

架构说明

后端架构

前端录音 → WebSocket服务器 → 豆包实时服务 → 豆包API
                   ↓                      ↓
前端播放 ← WebSocket服务器 ← 豆包实时服务 ← 豆包响应音频

核心组件

  1. DoubaoRealtimeService (backend/src/services/doubao_realtime_service.py)

    • 豆包实时对话服务管理器
    • 处理WebSocket连接到豆包API
    • 管理会话生命周期

  2. DoubaoRealtimeSession

    • 单个豆包对话会话
    • 处理音频发送和响应接收
    • 实现豆包协议解析

  3. WebSocketServer (backend/src/services/websocket_server.py)

    • 修改了音频处理流程
    • 集成豆包实时服务
    • 实现流式音频响应

  4. 前端App (frontend/src/App.tsx)

    • 完整的录音-播放流程
    • 实时状态显示
    • 音频数据处理

配置要求

1. 豆包API凭据

注意：API凭据已在代码中配置，可直接使用！

如需自定义，可设置环境变量：

# 豆包API配置（可选，已有默认值）
export DOUBAO_APP_ID="9775523795"
export DOUBAO_ACCESS_KEY="70G0Dky0P24Ai2VsizJQ5bDLHIkKzLNt"

# 其他可选配置
export DOUBAO_TTS_SPEAKER="zh_male_yunzhou_jupiter_bigtts"
export DOUBAO_BASE_URL="wss://openspeech.bytedance.com/api/v3/realtime/dialogue"

2. 豆包API配置说明

当前已针对Tolan英语学习应用进行优化配置：

认证信息：

  • App ID: 9775523795 (已配置)
  • Access Key: 70G0Dky0P24Ai2VsizJQ5bDLHIkKzLNt (已配置)

英语学习配置：

  • 机器人名称: "Tolan" (英语对话伙伴)
  • 系统角色: 友善的英语对话伙伴，帮助用户练习英语
  • 说话风格: 清晰发音，适合英语学习者的语速，鼓励性语调
  • 位置设置: "Global" (国际化英语学习环境)
  • 音色: zh_male_yunzhou_jupiter_bigtts (注：如有英文音色可替换)

可用模式：

  • english_conversation: Tolan英语对话学习 (默认)
  • english_tutor: 英语口语陪练加强模式
  • casual_english: 轻松英语聊天模式

如需自定义配置，可访问 豆包开放平台 获取新的API凭据。

使用流程

1. 启动后端服务

cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
python run.py

2. 启动前端应用

cd frontend
npm install
npm start

3. 使用步骤

  1. 打开浏览器访问前端应用
  2. 允许麦克风权限
  3. 等待WebSocket连接和会话建立
  4. 点击录音按钮开始录音
  5. 再次点击停止录音并发送到豆包API
  6. 等待豆包生成语音回复
  7. 自动播放AI回复的音频

核心功能特性

实时音频流处理

  • 支持实时音频数据传输
  • 流式响应音频播放
  • 音频格式自动转换

状态管理

  • 连接状态实时显示
  • 录音状态可视化
  • AI响应状态跟踪

错误处理

  • 网络错误自动重连
  • 音频处理错误恢复
  • 用户友好的错误提示

技术细节

音频格式处理

  • 前端录音：WebM/WAV格式
  • 发送到豆包：PCM 16kHz 单声道
  • 豆包返回：PCM 24kHz 单声道
  • 前端播放：通过Web Audio API

协议实现

  • 完整的豆包WebSocket协议实现
  • 支持会话管理和音频传输
  • 正确的消息格式和压缩处理

会话管理

  • 自动会话创建和清理
  • 会话状态同步
  • 连接断开自动恢复

调试功能

前端调试面板

  • WebSocket连接状态
  • 会话建立状态
  • 录音和播放状态
  • 音频设备支持状态

后端日志

  • 详细的API调用日志
  • 音频数据传输日志
  • 错误和异常日志

常见问题

1. 连接失败

  • 检查豆包API凭据是否正确
  • 确认网络连接正常
  • 查看后端日志获取详细错误信息

2. 录音问题

  • 确保浏览器允许麦克风权限
  • 检查音频设备是否正常工作
  • 尝试使用不同的浏览器

3. 播放问题

  • 检查浏览器音频权限
  • 确认扬声器/耳机工作正常
  • 查看浏览器控制台错误信息

扩展开发

添加新功能

  1. 多语言支持：修改会话配置
  2. 自定义音色：更改TTS配置
  3. 语音识别文本：处理ASR结果

性能优化

  1. 音频压缩：在发送前压缩音频
  2. 缓存管理：优化音频缓冲区
  3. 连接池：复用WebSocket连接

部署说明

开发环境

按照上述配置要求本地运行

生产环境

  1. 使用环境变量管理配置
  2. 启用HTTPS（WebSocket over TLS）
  3. 配置负载均衡和监控
  4. 设置日志收集和分析

更新日志

v1.0.0 (当前版本)

  • ✅ 完成豆包实时API集成
  • ✅ 实现录音到AI回复完整流程
  • ✅ 添加实时状态显示
  • ✅ 完善错误处理和调试功能
  • ✅ 支持流式音频播放

技术支持

如遇到问题：

  1. 查看本文档的常见问题部分
  2. 检查浏览器和后端控制台日志
  3. 确认豆包API配置和权限
  4. 验证网络连接和防火墙设置