第20章 架构
开发者架构理解 Voicebox 的技术架构
系统概览
Voicebox 采用客户端-服务器架构：React 前端 + Python 后端。桌面应用基于 Tauri 构建，包含两个主要层次：
- 前端层：React 应用，负责 UI 组件、Zustand 状态管理和 React Query（TanStack Query）数据请求。
- 后端层：Python FastAPI 服务器，提供 REST API，运行可插拔的 TTS/STT 引擎注册表，管理 SQLite 数据库，并处理音频。
两层通过 localhost:17493 上的 HTTP 通信，前端向后端发起 API 请求。生产环境中后端用 PyInstaller 打包，作为 Tauri sidecar 启动；开发环境下则手动通过 uvicorn 运行。
前端架构
技术栈
- 框架：React 18 + TypeScript
- 状态管理：Zustand stores
- 数据请求：React Query（TanStack Query）
- 样式：Tailwind CSS
- 音频：WaveSurfer.js
- 桌面端：Tauri（Rust）
组件结构
后端架构
技术栈
- 框架：FastAPI（Python 3.12）
- TTS 引擎：Qwen3-TTS、Qwen CustomVoice、LuxTTS、Chatterbox、Chatterbox Turbo、TADA、Kokoro
- 语音识别：Whisper（PyTorch 或 MLX-Whisper）
- 推理后端：MLX（Apple Silicon）、PyTorch（CUDA / ROCm / XPU / DirectML / CPU）
- 数据库：SQLite（通过 SQLAlchemy）
- 音频：librosa、soundfile、Pedalboard
目录结构
app.pymain.pyconfig.pymodels.pyserver.pybuild_binary.py
请求流程
HTTP 请求进入路由处理器，由其校验输入并委托给 service 函数。service 通过注册表调用相应的引擎后端执行实际推理，音频后处理（裁剪、重采样、效果器）则由 utils 完成。
路由处理器刻意保持精简——只做输入校验、委托 service、格式化响应。所有业务逻辑都放在 services/ 目录。
多引擎注册表
后端的设计让新增 TTS 引擎只需修改 backends/ 目录和中央注册表，路由和 service 中没有任何针对特定引擎的分支逻辑。
- TTSBackend Protocol（backends/__init__.py）——定义每个引擎需实现的接口：load_model、create_voice_prompt、combine_voice_prompts、generate、unload_model、is_loaded、_get_model_path。
- ModelConfig dataclass——每个模型变体的中央元数据记录：model_name、display_name、engine、hf_repo_id、size_mb、needs_trim、languages、supports_instruct 等。
- TTS_ENGINES dict——将引擎名（"qwen"、"kokoro" 等）映射到显示名。
- get_tts_backend_for_engine(engine)——线程安全的工厂函数，通过双重检查锁延迟实例化并缓存引擎后端。
已内置的引擎：
引擎标识显示名称Profile 类型qwenQwen TTSClonedqwen_custom_voiceQwen CustomVoicePresetluxttsLuxTTSClonedchatterboxChatterbox TTSClonedchatterbox_turboChatterbox TurboClonedtadaTADAClonedkokoroKokoroPreset
完整接口规范和集成阶段请参见 TTS Engines，候选评估中的引擎见 PROJECT_STATUS.md。
关键模块
- app.py——FastAPI 应用工厂、CORS、生命周期事件
- main.py——入口（导入 app，运行 uvicorn）
- server.py——Tauri sidecar 启动器、父进程 PID 看门狗、frozen 构建环境设置
- services/generation.py——单个函数处理所有生成模式（generate、retry、regenerate）
- services/task_queue.py——GPU 推理的串行生成队列
- backends/__init__.py——Protocol 定义、ModelConfig 注册表和引擎工厂
- backends/base.py——所有引擎实现共享的工具（设备选择、进度跟踪、输出裁剪）
推理后端选择
服务器在启动时检测最佳推理后端，所有支持它的引擎都会使用：
平台后端加速方式macOS（Apple Silicon）MLXMetal / Neural EngineWindows / Linux（NVIDIA）PyTorchCUDA（cu128）Linux（AMD）PyTorchROCmWindows / Linux（Intel Arc）PyTorchXPU（IPEX）Windows（其他 GPU）PyTorchDirectML任意平台PyTorchCPU 回退
各平台的说明和手动覆盖方法见 GPU Acceleration。
数据模型
核心表（见 backend/database/models.py）：
- profiles——音色档案，通过 voice_type 区分（cloned | preset | designed），包含 preset_engine、preset_voice_id 和 default_engine。
- profile_samples——cloned 档案的参考音频片段和转写文本，preset 档案为空。
- generations——生成的音频，记录文本、引擎、模型、语言、seed 和时长。
- generation_versions——同一次生成的不同效果器链处理版本。
- audio_channels + channel_device_mappings + profile_channel_mappings——多输出路由。
详见 Voice Profiles 和 Effects Pipeline。
桌面应用（Tauri）
Rust 后端
Cargo.tomltauri.conf.jsonsrc/
职责
- 以 sidecar 进程启动 Python 后端
- 原生文件对话框
- 系统托盘集成
- 自动更新（Tauri updater + 自定义 CUDA 后端替换）
- 父进程 PID 看门狗，应用崩溃时后端随之退出
构建流程
开发
just dev # 启动后端 + Tauri 应用 just dev-web # 启动后端 + Web 应用（无 Tauri） just dev-backend # 仅后端 just dev-frontend # 仅 Tauri 应用（后端需已在运行）
生产
just build # CPU 服务器二进制 + Tauri 安装包 just build-local # CPU + CUDA 二进制 + Tauri 安装包（Windows） just build-server # 仅服务器二进制 just build-tauri # 仅 Tauri 应用
PyInstaller 的具体工作方式，以及 CUDA 二进制如何拆分打包，参见 Building。
数据流
生成流程
- 用户输入——在 React 组件中输入文本，选择引擎和档案
- 状态更新——Zustand 生成表单 store 记录请求
- API 请求——React Query mutation 调用 POST /generate
- 路由——routes/generate.py 校验输入，分发给 services/generation.py
- 音色提示——service 通过引擎后端创建或读取缓存的 voice prompt
- 队列——services/task_queue.py 串行化生成任务，避免 GPU 争抢
- 推理——引擎后端执行 generate()，返回音频和采样率
- 后处理——可选裁剪（部分引擎需要），按 generation 版本应用效果器链
- 存储——音频写入 generations 目录，元数据保存到 SQLite
- 响应——后端返回生成记录；前端更新 React Query 缓存并播放音频
性能考量
前端
- 代码分割——路由懒加载
- 记忆化——重型组件使用 React.memo
- 虚拟滚动——用于长列表
- 防抖——搜索和输入处理
后端
- 异步 I/O——所有 I/O 均为异步；推理通过 asyncio.to_thread 运行
- 串行任务队列——避免多个引擎争抢 GPU
- Voice prompt 缓存——按引擎区分，以音频哈希 + 参考文本为键
- 模型固定——每个引擎同时只加载一个模型，切换时卸载前一个
- 引擎后端缓存——每个引擎在每个进程中只实例化一次
安全性
现状
- 默认仅限本机（绑定 127.0.0.1:17493）
- 无身份验证（信任 localhost）
- 通过 Tauri 实现文件系统沙箱
规划中
- 远程模式的 API key 认证
- 用户账户
- 速率限制
- HTTPS 支持
部署模式
本地模式
- 后端以 sidecar 方式运行
- 所有数据保留在本机
- 无需联网
远程模式
- 后端运行在另一台机器上（Docker 或裸机）
- 前端（桌面端或 Web）通过 HTTP 连接
- 详见 Remote Mode 和 Docker
下一步
开发环境搭建配置你的开发环境TTS Engines如何添加新引擎Contributing参与 Voicebox 开发在 GitHub 上编辑开发环境搭建配置 Voicebox 的本地开发环境Contributing如何为 Voicebox 做贡献
