Tolan/backend

Tolan 语音助手 - 后端

这是Tolan语音助手的后端服务，使用FastAPI + WebSocket构建。

功能特性

• ✅ WebSocket实时通信
• ✅ 豆包API连接池（预热机制）
• ✅ 流式音频处理（实时转发）
• ✅ 低延迟优化（<300ms）
• ✅ 完整的错误处理和日志
• ✅ 健康检查和性能监控

技术栈

• 框架: FastAPI 0.110+
• WebSocket: FastAPI WebSocket
• 异步: asyncio
• 日志: loguru
• 配置: pydantic-settings + python-dotenv

快速开始

1. 安装依赖

cd /Users/wuzilong/work/00code/Tolan/backend

# 使用本机Python环境
pip install -r requirements.txt

2. 配置环境变量

创建 .env 文件：

# 豆包API配置（必需）
DOUBAO_API_KEY=your_api_key_here
DOUBAO_APP_ID=your_app_id_here

# 豆包API地址（可选，默认使用官方地址）
DOUBAO_API_URL=wss://openspeech.bytedance.com/api/v3/realtime/dialogue

# 输出音频格式（可选，默认ogg_opus）
DOUBAO_OUTPUT_FORMAT=ogg_opus

# 服务器配置
HOST=0.0.0.0
PORT=8000
DEBUG=False

# 连接池配置
CONNECTION_POOL_SIZE=10

重要说明:

• 如果没有豆包API密钥，系统会自动使用模拟API，可以测试前后端通信
• 完整配置说明请参考 ENV_CONFIG.md

3. 启动服务器

开发环境:

python main.py

生产环境（使用SSL）:

python -m uvicorn main:app --host 0.0.0.0 --port 8443 \
  --ssl-keyfile=../ssl/key.pem \
  --ssl-certfile=../ssl/cert.pem

4. 访问服务

• 根路径: http://localhost:8000
• API文档: http://localhost:8000/docs
• 健康检查: http://localhost:8000/health
• WebSocket: ws://localhost:8000/ws/realtime

项目结构

backend/
├── main.py                  # FastAPI主应用
├── config.py                # 配置管理
├── connection_pool.py       # 豆包API连接池
├── websocket_handler.py     # WebSocket处理器
├── doubao_api/             # 豆包API模块
│   ├── __init__.py
│   └── realtime_dialog_client.py
├── logs/                    # 日志目录（自动创建）
├── requirements.txt         # Python依赖
└── README.md

核心模块说明

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

实现豆包API连接池，提供：

• 预创建连接（消除连接建立延迟）
• 连接复用（获取/归还机制）
• 健康检查（定期检查连接状态）
• 自动重建（不健康连接自动替换）

from connection_pool import connection_pool

# 初始化连接池
await connection_pool.initialize()

# 获取连接
client = await connection_pool.acquire()

# 使用连接
await client.send_audio(audio_data)

# 归还连接
await connection_pool.release(client)

2. WebSocket处理器 (websocket_handler.py)

实现流式会话处理，包括：

• 控制消息处理（JSON格式）
• 音频数据转发（二进制格式）
• 状态同步
• 性能指标追踪

from websocket_handler import connection_manager

# 建立连接
session = await connection_manager.connect(websocket, session_id)

# 启动会话
await session.start()

# 处理流式数据
await session.process_stream()

3. FastAPI应用 (main.py)

主应用入口，提供：

• WebSocket端点
• 健康检查端点
• 全局异常处理
• 生命周期管理

API端点

HTTP端点

GET /

根路径，返回应用信息

GET /health

健康检查，返回：

• 应用状态
• 连接池状态
• 活跃会话数

{
  "status": "healthy",
  "timestamp": 1696752000000,
  "connection_pool": {
    "initialized": true,
    "pool_size": 10,
    "idle": 8,
    "active": 2
  },
  "active_sessions": 2
}

WebSocket端点

WS /ws/realtime

实时语音交互端点

消息格式:

1. 控制消息（文本/JSON）:

   {
    "type": "init",
    "payload": {
      "version": "1.0",
      "capabilities": ["pcm", "opus"]
    }
   }
   

   1. 音频数据（二进制）:
   2. 上行：PCM (16kHz, 16bit, 单声道)
   3. 下行：OGG/Opus

   消息类型:

   客户端 → 服务端：

   • init - 初始化
   • start_recording - 开始录音
   • stop_recording - 停止录音
   • ping - 心跳
   • close - 关闭连接

   服务端 → 客户端：

   • init_ack - 初始化确认
   • recording_started - 录音已开始
   • recording_stopped - 录音已停止
   • ai_response_start - AI开始回复
   • ai_response_end - AI回复结束
   • state_change - 状态变更
   • error - 错误消息
   • metrics - 性能指标
   • pong - 心跳响应

   配置说明

   环境变量

   变量名	说明	默认值
   DOUBAO_API_KEY	豆包API密钥	-
   DOUBAO_APP_ID	豆包APP ID	-
   HOST	服务器地址	0.0.0.0
   PORT	服务器端口	8000
   CONNECTION_POOL_SIZE	连接池大小	10
   LOG_LEVEL	日志级别	INFO

   连接池配置

   # config.py
   CONNECTION_POOL_SIZE = 10              # 连接池大小
   CONNECTION_MAX_IDLE_TIME = 300         # 最大空闲时间（秒）
   CONNECTION_HEALTH_CHECK_INTERVAL = 60  # 健康检查间隔（秒）
   

性能优化

1. 连接池预热

• 应用启动时预创建所有连接
• 消除连接建立延迟（100-200ms → 0ms）

2. 流式处理

• 使用asyncio并发处理
• 边接收边转发，无等待
• 零拷贝设计

3. 异步架构

• 所有IO操作使用async/await
• asyncio.Queue缓冲音频块
• 并发处理多个任务

日志

日志文件位于 logs/ 目录：

• 自动轮转（500MB）
• 保留10天
• 格式：YYYY-MM-DD HH:mm:ss | LEVEL | message

日志级别:

• DEBUG: 详细调试信息
• INFO: 常规信息
• WARNING: 警告信息
• ERROR: 错误信息

错误处理

错误码

错误码	说明	可恢复
CONNECTION_POOL_EXHAUSTED	连接池已耗尽	是
DOUBAO_API_ERROR	豆包API错误	是
INTERNAL_ERROR	内部错误	否

错误消息格式

{
  "type": "error",
  "payload": {
    "code": "CONNECTION_POOL_EXHAUSTED",
    "message": "服务繁忙，请稍后重试",
    "severity": "error",
    "recoverable": true
  }
}

监控指标

性能指标

应用会追踪并返回以下指标：

• 端到端延迟（ms）
• 网络延迟（ms）
• 处理延迟（ms）
• AI处理延迟（ms）
• 音频接收/发送字节数

系统指标

• 活跃连接数
• 连接池状态
• 活跃会话数

故障排查

问题1: 连接池初始化失败

症状: 启动时报错"连接池初始化失败"

解决方案:

1. 检查豆包API配置是否正确
2. 检查网络连接
3. 查看详细日志

问题2: WebSocket连接失败

症状: 前端无法连接WebSocket

解决方案:

1. 确认后端服务已启动
2. 检查CORS配置
3. 检查防火墙设置

问题3: 音频延迟过高

症状: 端到端延迟 > 500ms

解决方案:

1. 检查连接池是否正常工作
2. 查看性能指标，定位瓶颈
3. 检查网络状况

开发命令

# 安装依赖
pip install -r requirements.txt

# 启动开发服务器（自动重载）
python main.py

# 或使用uvicorn
python -m uvicorn main:app --reload

# 查看日志
tail -f logs/app_*.log

# 健康检查
curl http://localhost:8000/health

部署建议

1. 生产环境配置

# 使用HTTPS
python -m uvicorn main:app \
  --host 0.0.0.0 \
  --port 8443 \
  --ssl-keyfile=../ssl/key.pem \
  --ssl-certfile=../ssl/cert.pem \
  --workers 4

2. 使用进程管理器

Supervisor:

[program:tolan-backend]
directory=/Users/wuzilong/work/00code/Tolan/backend
command=python -m uvicorn main:app --host 0.0.0.0 --port 8000
autostart=true
autorestart=true

systemd:

[Unit]
Description=Tolan Backend Service
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/Users/wuzilong/work/00code/Tolan/backend
ExecStart=python -m uvicorn main:app --host 0.0.0.0 --port 8000
Restart=always

[Install]
WantedBy=multi-user.target

3. 使用Nginx反向代理

upstream tolan_backend {
    server localhost:8000;
}

server {
    listen 443 ssl http2;
    server_name api.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location /ws {
        proxy_pass http://tolan_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 86400;
    }

    location / {
        proxy_pass http://tolan_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

TODO

• 集成实际的豆包API客户端
• 添加用户认证
• 实现会话持久化
• 添加限流机制
• 优化音频处理逻辑

许可证

MIT