第18章 故障排查指南
概述故障排查使用 Voicebox 时的常见问题及解决方法本指南涵盖使用或开发 Voicebox 时可能遇到的常见问题及其解决方案。
安装问题
macOS：提示“App 已损坏，无法打开” 这是因为应用没有使用 Apple 开发者证书签名。 解决方法： # 移除隔离属性 xattr -cr /Applications/Voicebox.app
Windows：SmartScreen 警告 Windows SmartScreen 可能提示该应用未被识别。 解决方法：
点击“更多信息” 点击“仍要运行”
未签名的应用出现此提示属正常现象，我们正在为后续版本加入代码签名。
Linux：AppImage 无法运行 解决方法： chmod +x voicebox-*.AppImage ./voicebox-*.AppImage
服务器问题
后端服务器无法启动 症状：
左下角状态指示灯为红色 提示“无法连接到服务器”
解决方法： ▶端口被占用检查 17493 端口是否已被占用：# macOS/Linux lsof -i :17493
# Windows
powershell -Command "Get-NetTCPConnection -LocalPort 17493 -State Listen"结束占用该端口的进程：# macOS/Linux
kill -9
# Windows
taskkill /PID
服务器日志中出现 flash-attn is not installed 警告 症状： Warning: flash-attn is not installed. Will only run the manual PyTorch version. Please install flash-attn for faster inference. 这个警告无害。它由我们基于 Transformer 的引擎（Chatterbox / Qwen）在每次启动时输出。FlashAttention 是一个可选的加速库——未安装时会自动改用 PyTorch 内置的 scaled-dot-product attention（SDPA），在现代 GPU 上吞吐量已接近 FA2。生成功能不受影响。 为什么每个平台都会出现：
Windows：flash-attn 官方不支持 Windows。上游项目（Dao-AILab/flash-attention）至今只表示“可能可以运行”，而且在新版 CUDA/MSVC 组合下源码编译通常失败。 macOS（Apple Silicon）：FlashAttention 仅支持 CUDA，完全不适用。MLX 自带优化过的 attention kernel。 Linux：由于安装过程脆弱且对版本敏感，我们没有将其固定在依赖中；有需要的用户可以自行安装。
解决方法（均可选）： ▶直接忽略（推荐）实际运行模型的就是 PyTorch SDPA，在 Ampere/Ada/Hopper GPU 上，我们的工作负载下它和 FA2 的性能差距只有几个百分点，速度上不会有明显感知。▶在 Linux 上安装 flash-attnpip install flash-attn --no-build-isolation需要匹配的 CUDA toolkit，编译可能耗时 20 分钟以上。▶在 Windows 上安装 flash-attn（社区 wheel）没有官方构建，但社区维护者提供了预编译 wheel： kingbri1/flash-attention releases bdashore3/flash-attention releases 选择与你所用 CUDA + PyTorch + Python 组合完全匹配的 wheel。示例：pip install https://github.com/kingbri1/flash-attention/releases/download/v2.8.3/flash_attn-2.8.3+cu128torch2.8.0cxx11abiFALSE-cp312-cp312-win_amd64.whl也可以在 WSL2 中运行 Voicebox 后端，使用标准 Linux wheel。
连接超时 症状：
加载时间很长 提示“连接超时”
解决方法：
重启应用 检查防火墙设置 确保 localhost 可访问
生成问题
首次生成非常慢 症状：
首次生成需要 2-5 分钟 进度条卡在“正在加载模型……”
说明： 这是正常现象。首次生成时需要下载所选 TTS 引擎的模型并完成初始化。模型大小从 350 MB（Kokoro）到 8 GB（TADA 3B）不等。 解决方法：
等待首次下载完成（进度显示在 Settings → Models 中） 后续生成会复用已缓存的模型，速度会快很多 检查网络连接 带宽有限的话，可以先从 Kokoro（约 350 MB）或 LuxTTS（约 300 MB）入手
音质不佳 症状：
声音机械、不自然 缺少情感或韵律 发音错误
解决方法：
使用 10-30 秒的清晰音频 避免背景噪音 确保说话语气一致 添加同一说话人的多个样本 生成的声音会模仿样本的语气和风格。样本如果平淡单调，生成结果也会如此。 正确使用标点 用逗号制造自然停顿 专有名词注意大写
生成时报"Out of Memory" 症状：
生成过程中崩溃 报"CUDA out of memory"或"RuntimeError: out of memory"
解决方法： ▶释放显存关闭其他占用 GPU 的应用： 游戏 视频编辑软件 多个开启 WebGL 的浏览器标签页 然后重启 Voicebox。▶使用 CPU 模式如果显存不足（需要 6GB 以上），改用 CPU 模式：Settings → Generation → Use CPU instead of GPUCPU 生成慢 5-10 倍，但使用的是系统内存而非显存。▶减小批次长度对于长文本，拆分成较小的片段分批生成，而不是一次性生成。
MLX 报"Failed to load the default metallib"（Apple Silicon） 症状：
生成失败，报"library not found"或"metallib"错误 服务器日志提示缺少 Metal shader 库
解决方法： ▶重新构建服务器二进制just build-server在 Apple Silicon 上，构建脚本会自动打包 MLX Metal shader 库。▶重装 MLX 依赖pip install -r backend/requirements-mlx.txt▶确认后端检测结果查看 Settings → Server Status。Apple Silicon 上应显示 Backend: MLX。如果显示 Backend: PYTORCH，说明 MLX 没有正确安装。
音频问题
无法播放音频 症状：
生成的音频无法播放 播放按钮无响应
解决方法：
检查系统音频设置 确保音频输出设备已连接 尝试导出后用媒体播放器播放
音频有杂音或失真 症状：
音频有静电噪声或失真 出现削波声
解决方法：
检查输入样本本身是否有失真 降低播放音量 用更干净的语音样本重新生成
开发问题
开发模式下后端无法启动 症状：
just dev-backend 或 just dev 失败 报 import 错误或找不到模块
解决方法： ▶Python 版本确保使用 Python 3.12：python3.12 --version # macOS/Linux py -3.12 --version # WindowsVoicebox 将 venv 固定在 Python 3.12，因为部分依赖还没有 3.13 版本。just setup 会重建版本不对的 venv，所以重新运行一次通常就能解决。如果 just setup 找不到可用的 3.12，可以安装一个：任何平台都可以用 uv python install 3.12；macOS 用 brew install [email protected]；Debian/Ubuntu 用 sudo apt install python3.12 python3.12-venv；Windows 则从 python.org 下载或 winget install -e --id Python.Python.3.12， 然后用 py -3.12 启动器。▶虚拟环境确保 venv 已激活：# macOS/Linux source backend/venv/bin/activate
# Windows backend\venv\Scripts\activate终端提示符中应显示 (venv)。▶依赖重新安装依赖——最简单的方式是用 just：just setup或手动执行：cd backend pip install -r requirements.txt pip install --no-deps chatterbox-tts pip install --no-deps hume-tada pip install git+https://github.com/QwenLM/Qwen3-TTS.git
Tauri 构建失败 症状：
bun run tauri build 失败 Rust 编译错误
解决方法： # 清理构建产物 cd tauri/src-tauri cargo clean
# 更新 Rust rustup update
# 重新构建 cd ../.. bun run tauri build
OpenAPI 客户端生成失败 症状：
./scripts/generate-api.sh 失败 报"Failed to fetch schema"错误
解决方法： curl http://localhost:17493/openapi.json应返回 JSON。如果没有，先启动后端。确保没有其他程序占用 17493 端口cd backend source venv/bin/activate uvicorn main:app --reload --port 17493
# 另开一个终端 ./scripts/generate-api.sh
数据库问题
报"Database is locked"错误 症状：
配置或生成操作失败 SQLite 锁错误
解决方法：
关闭所有 Voicebox 实例 删除锁文件： # macOS rm ~/Library/Application\ Support/sh.voicebox.app/data/voicebox.db-shm rm ~/Library/Application\ Support/sh.voicebox.app/data/voicebox.db-wal
数据库损坏 症状：
应用启动时崩溃 数据丢失或损坏
解决方法： 此操作会删除所有声音配置和生成历史，请先导出重要的配置。 # macOS rm ~/Library/Application\ Support/sh.voicebox.app/data/voicebox.db*
# Windows del %APPDATA%\sh.voicebox.app\data\voicebox.db* 通配符会同时删除 SQLite 在 WAL 模式下保存在数据库旁边的 voicebox.db-wal 和 voicebox.db-shm 附属文件，确保重置后完全干净。 重启应用即可创建新的数据库。
模型问题
模型下载失败 症状：
报"Failed to download model"错误 一直卡在“正在下载……”
解决方法：
检查网络连接
查看 HuggingFace Hub 状态
如果所在地区无法访问 HuggingFace，尝试使用 VPN
用 HuggingFace CLI 手动下载并放入缓存目录： pip install huggingface_hub huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base
模型版本错误 症状：
生成质量突然下降 输出的声音不同
解决方法： 清除模型缓存后重新下载。对其他引擎，把 Qwen* 通配符换成对应引擎的组织前缀即可（Chatterbox 用 ResembleAI*，TADA 用 HumeAI*，Kokoro 用 hexgrad* 等），或者通过 API 调用 DELETE /models/{name}。 # macOS / Linux rm -rf ~/.cache/huggingface/hub/models--Qwen*
# Windows rmdir /s %USERPROFILE%\.cache\huggingface\hub\models--Qwen*
性能问题
GPU 生成速度慢 症状：
生成速度低于预期 GPU 未被使用
解决方法： ▶检查 CUDA 安装nvidia-smi应能显示你的 GPU。如果没有，请安装 CUDA 驱动。▶检查 GPU 选择如果有多块 GPU，确保 Voicebox 使用的是正确的设备。Settings → Generation → GPU Device▶更新 GPU 驱动过时的驱动可能导致性能问题，请更新到最新的 NVIDIA 驱动。▶Apple Silicon：确认 MLX 后端查看 Settings → Server Status。Apple Silicon 上应显示 Backend: MLX——此处 MLX 比 PyTorch 快 4-5 倍。如果显示 Backend: PYTORCH，请重装 MLX：pip install -r backend/requirements-mlx.txtGPU 可用性应显示为"Metal (Apple Silicon via MLX)"。
内存占用过高 症状：
应用占用内存过多 系统变卡
解决方法：
关闭不用的声音配置 清除生成历史 定期重启应用
更新问题
报"Update Check Failed" 解决方法：
确认网络连接——更新信息从 GitHub releases 获取。 确保 github.com 可访问，未被防火墙或代理拦截。 作为备选方案，从 GitHub 下载最新版本并手动安装。
报"Invalid Signature"错误 解决方法：
重新下载安装包——签名可能在传输过程中损坏。 校验 .sig 文件与安装包是否匹配；不匹配的话请提交 issue。
远程模式问题
无法连接远程服务器 症状：
报"Connection refused"错误 找不到远程服务器
解决方法：
确保远程服务器正在运行：curl http://
仍然有问题？ 如果问题仍未解决：
查看 GitHub Issues：github.com/jamiepine/voicebox/issues 提交新 Issue，提供以下信息：
操作系统及版本 Voicebox 版本 复现步骤 错误信息或日志
加入 Discord：discord.gg/voicebox（即将上线）
诊断信息 报告问题时请附上以下信息： # Voicebox 版本 # 在应用中查看 Help → About
# 操作系统 uname -a # macOS/Linux systeminfo # Windows
# Python 版本（开发问题） python --version
# GPU 信息（生成问题时） nvidia-smi # NVIDIA GPU在 GitHub 上编辑构建故事使用 Stories 编辑器创建多声部叙事根目录根端点。
