ドキュメントASR-LLM-TTS 音声対話アシスタント バックエンド
🏗️ アーキテクチャの概要
本プロジェクトのバックエンドは、FastAPI + WebSocket で構築したモダンな非同期音声対話システムです。自動音声認識（ASR）、大規模言語モデル（LLM）、音声合成（TTS）の機能を統合し、音声インタラクションの一連の流れを完結させます。
主な特長
- 🎤 ローカル音声認識：sherpa-onnx ベースのリアルタイム ASR。VAD による発話区間検出に対応
- 🧠 大規模モデルの統合：火山引擎 Doubao シリーズ。Function Calling によるツール呼び出しに対応
- 🔊 ストリーミング音声合成：火山引擎 TTS の双方向ストリーミング合成で、生成しながら再生
- 🌐 リアルタイム通信：WebSocket プロトコルによる低遅延の双方向データ転送
- ⚡ 並行処理：LLM 生成、TTS 合成、音声再生の 3 系統を並列実行
- 🔧 ツール群：豊富な Function Calling ツール。MCP プロトコルによる拡張に対応
技術スタック
| コンポーネント | 採用技術 | 説明 |
|---|---|---|
| Web フレームワーク | FastAPI + Uvicorn | 非同期 Python Web フレームワーク |
| 通信プロトコル | WebSocket | リアルタイム双方向通信 |
| 音声認識 | sherpa-onnx + silero-vad | ローカル ASR + VAD 発話区間検出 |
| 大規模言語モデル | 火山引擎 Doubao | Function Calling に対応 |
| 音声合成 | 火山引擎 TTS | WebSocket 双方向ストリーミング合成 |
| 音声再生 | sounddevice + pygame | リアルタイム音声処理 |
| 並行処理モデル | asyncio + multiprocessing | 非同期 IO + マルチプロセス |
| 設定管理 | YAML + 環境変数 | 柔軟な設定システム |
📁 プロジェクト構成
Backend/
├── server.py # 🚀 FastAPI主入口，WebSocket服务器
├── config.yaml # ⚙️ 全局配置文件
├── requirements.txt # 📦 Python依赖列表
├── .env.example # 🔐 API密钥配置模板
│
├── app/ # 🎯 应用核心逻辑
│ ├── turn_manager.py # 对话管理器，协调整个对话流程
│ ├── tts_player.py # TTS播放控制器
│ └── shared_state.py # 全局状态管理
│
├── asr/ # 🎤 语音识别模块
│ └── asr_service.py # 多进程ASR服务
│
├── llm/ # 🧠 大语言模型模块
│ ├── client.py # LLM API客户端
│ └── errors.py # 错误处理与提示
│
├── tts/ # 🔊 文本转语音模块
│ ├── client.py # TTS WebSocket客户端
│ ├── protocols.py # WebSocket协议定义
│ └── errors.py # TTS错误处理
│
├── utils/ # 🔧 工具和辅助模块
│ ├── audio/ # 音频处理模块
│ │ ├── audio_device_manager.py # 音频设备管理器
│ │ └── audio_player.py # 音频播放器
│ ├── config/ # 配置管理模块
│ │ └── config_loader.py # 配置加载器
│ │
│ ├── function_call/ # 🛠️ Function Calling工具系统
│ │ ├── function_call_tools.py # 工具注册与调用框架
│ │ ├── function_schema.py # 工具Schema定义
│ │ └── function_tools_impl.py # 工具具体实现
│ │
│ ├── mcp/ # 🌐 MCP (Model Context Protocol) 支持
│ │ ├── client/ # MCP客户端管理
│ │ │ ├── mcp_client.py # 统一MCP客户端实现
│ │ │ └── __init__.py # 模块初始化
│ │ ├── config/ # MCP配置管理
│ │ │ └── mcp_servers.json # MCP服务器配置文件
│ │ └── __init__.py # MCP模块入口
│ │
│ └── audio_config/ # 🔊 音频设备配置工具
│ ├── setup_audio_devices.py # 交互式音频配置工具
│ ├── check_audio_devices.py # 设备状态检测
│ └── audio_device_config_manager.py # 配置管理器
│
├── model/ # 📊 AI模型文件
│ ├── asr/ # ASR模型目录
│ └── vad/ # VAD模型目录
│
├── resource/ # 🎵 资源文件
│ └── *.mp3, *.wav, *.flac # 音乐文件
│
├── scripts/ # 📜 辅助脚本
│ └── fix_rdkx5_audio.sh # RDKX5音频修复脚本
│
├── test/ # 🧪 测试脚本
│ ├── audio_tests/ # 音频相关测试
│ └── *.py # 各模块测试脚本
│
└── docs/ # 📚 详细文档 (本次新增)
├── architecture.md # 架构设计详解
├── function_call.md # Function Calling系统
├── mcp_integration.md # MCP集成文档
├── audio_system.md # 音频系统文档
├── deployment.md # 部署指南
└── api_reference.md # API参考
🔄 システムアーキテクチャのフロー
┌─────────────┐ WebSocket ┌─────────────────────────────────┐
│ 前端应用 │◄────连接/消息────►│ FastAPI服务器 │
│ (Next.js) │ │ (server.py) │
└─────────────┘ └─────────────┬───────────────────┘
│
▼
┌─────────────────┐
│ 对话管理器 │
│ (turn_manager) │
└─────────┬───────┘
│
┌─────────────────────────┼─────────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ LLM客户端 │ │ Function Call │ │ TTS播放器 │
│ (llm/client.py) │ │ 工具调用 │ │ (tts_player.py) │
└─────────┬───────┘ └─────────────────┘ └─────────┬───────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 火山引擎LLM │ │ 本地工具 + MCP │ │ 火山引擎TTS │
│ HTTP API │ │ 远程工具 │ │ WebSocket API │
└─────────────────┘ └─────────────────┘ └─────────┬───────┘
│
▼
┌─────────────────┐
│ 音频播放器 │
│ (AudioPlayer) │
└─────────────────┘
🚀 クイックスタート
環境の準備
# 1. 安装Python依赖
cd Backend
pip install -r requirements.txt
# 2. 配置API密钥
cp .env.example .env
# 编辑 .env 文件，填入你的火山引擎API密钥
# 3. 配置音频设备 (Linux)
python utils/audio_config/setup_audio_devices.py
# 4. 下载模型文件 (如需ASR功能)
# ASR模型: https://github.com/k2-fsa/sherpa-onnx/releases
# VAD模型: https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/silero_vad.onnx
サービスの起動
# 方法1: 使用uvicorn
uvicorn server:app --host 0.0.0.0 --port 8000
# 方法2: 直接运行
python server.py
# 方法3: 使用项目根目录的一键脚本
cd ..
./run.sh
サービス起動後：
- バックエンド API：http://localhost:8000
- WebSocket：ws://localhost:8000/ws/chat
- ヘルスチェック：http://localhost:8000/
📖 詳細ドキュメント
| ドキュメント | 内容 | 対象読者 |
|---|---|---|
| アーキテクチャ設計 | システムアーキテクチャ、モジュール間の連携、設計原則 | アーキテクト、上級開発者 |
| Function Calling | ツール呼び出しシステム、拡張開発 | 機能開発者 |
| MCP 統合 | MCP プロトコル対応、リモートツール | システムインテグレーター |
| オーディオシステム | 音声処理、デバイス設定 | オーディオ開発者 |
| デプロイガイド | 本番環境へのデプロイ、運用 | DevOps エンジニア |
| API リファレンス | WebSocket プロトコル、メッセージ形式 | フロントエンド開発者 |
⚙️ 主要な設定
主な設定項目（config.yaml）：
app:
input_mode: "keyboard" # 输入模式: "keyboard" | "asr"
llm:
volcengine:
api_url: "https://ark.cn-beijing.volces.com"
model:
name: "doubao-pro-32k-functioncall-241028"
parameters:
temperature: 0.7
max_tokens: 4096
tts:
volcengine:
app_id: "从环境变量读取"
access_token: "从环境变量读取"
voice:
default_speaker: "zh_female_qingxin"
asr: # ASR模式下需要配置
model_dir: "./model/asr/sherpa-onnx-paraformer-zh"
vad_model_path: "./model/vad/silero_vad.onnx"
target_microphone_keyword: "UGREEN"
🔧 開発ガイド
新しいツールの追加
utils/function_call/function_tools_impl.pyでツールクラスを実装します。utils/function_call/function_call_tools.pyでツールを登録します。utils/function_call/function_schema.pyでスキーマを定義します。- ツール呼び出しをテストします。
WebSocket メッセージの拡張
server.pyで新しいメッセージタイプの定数を定義します。- WebSocket 処理関数にメッセージのルーティングを追加します。
- フロントエンドの対応するメッセージ処理ロジックを更新します。
音声関連の問題のデバッグ
# 检查设备状态
python utils/audio_config/check_audio_devices.py
# 诊断音频问题
python test/audio_tests/diagnose_rdkx5_audio.py
# 测试音频播放
python test/audio_tests/test_audio_player_new.py
💡 ヘルプ
問題が発生した場合は 目的に応じて、対応する詳細ドキュメントを参照してください。
- 🏗️ システムアーキテクチャを理解する → アーキテクチャ設計ドキュメント
- 🛠️ ツール機能を開発する → Function Calling ドキュメント
- 🌐 MCP サービスを統合する → MCP 統合ドキュメント
- 🔊 音声関連の問題を解決する → オーディオシステムのドキュメント
- 🚀 本番環境にデプロイする → デプロイガイド
- 📡 フロントエンドと API を連携する → WebSocket API リファレンス