第5章 GPU 加速
第5章：GPU 加速
概述
Voicebox 在首次启动时会自动检测可用的加速器，并选择最快的后端。对大多数人来说，只需打开应用即可，系统会自动匹配到正确的后端。
本页适用于自动检测失效的情况： * 你有 GPU，但 Voicebox 却在用 CPU 运行 * 你升级了 GPU（尤其是升级到 RTX 50 系列 / Blackwell 架构），导致兼容性中断 * 你想手动切换后端（例如在 Apple Silicon 上强制使用 MLX 而非 PyTorch） * 你在设置中的 GPU 旁看到 [UNSUPPORTED - see logs] 提示
后端矩阵
| 平台 | 自动选择的后端 | 备注 | | :--- | :--- | :--- | | macOS Apple Silicon | MLX (Metal) | 通过 Apple Neural Engine，速度比 PyTorch 快 4-5 倍 | | macOS Intel | PyTorch CPU | 无 GPU 加速；仅支持 PyTorch ≥ 2.2 | | Windows + NVIDIA | PyTorch CUDA (cu128) | 首次使用时自动下载 CUDA 后端二进制文件 | | Windows + Intel Arc | PyTorch XPU (IPEX) | 0.4 版本新增 — 支持 Arc A 系列和 B 系列 | | Windows 通用 GPU | DirectML | 支持通用 Windows GPU；速度比 CUDA 慢 | | Linux + NVIDIA | PyTorch CUDA (cu128) | 使用本地或远程 Python 后端及 CUDA PyTorch | | Linux + AMD | PyTorch ROCm | 自动配置 HSA_OVERRIDE_GFX_VERSION | | Linux + Intel Arc | PyTorch XPU (IPEX) | | | 无 GPU | PyTorch CPU | 通用支持；预计比 GPU 慢 5-50 倍 |
检测到的后端显示在“设置 → GPU”中。启动日志也会打印选定的后端和设备名称。
Apple Silicon — MLX 与 PyTorch
在 M 系列 Mac 上，Voicebox 内置了针对 MLX 优化的后端，利用 Apple Neural Engine。对于支持的引擎，其速度比 PyTorch（CPU/Metal）路径快 4-5 倍。
| 引擎 | MLX 支持 | 备注 | | :--- | :--- | :--- | | Qwen3-TTS | ✅ 原生支持 | 可用时仅使用 MLX | | Chatterbox / Turbo | PyTorch MPS | 回退至通过 PyTorch 使用 Metal | | LuxTTS | PyTorch MPS | | | TADA | PyTorch MPS | | | Kokoro | PyTorch MPS | 需设置 PYTORCH_ENABLE_MPS_FALLBACK=1 | | Qwen CustomVoice | PyTorch MPS | | | Whisper (transcribe) | ✅ 原生支持 | MLX-Whisper 是 Apple Silicon 的默认选择 |
Whisper Turbo 搭配 MLX 的组合，在 M 系列芯片上将转录延迟从约 20 秒降低至约 2-3 秒（参见 v0.1.10 的 CHANGELOG 条目）。
Windows + NVIDIA — CUDA 后端替换
Voicebox 的主安装包不捆绑 CUDA（否则对于没有 NVIDIA GPU 的用户来说，下载体积会膨胀到数 GB）。相反，当你首次需要它时，应用会下载一个独立的 CUDA 后端二进制文件，其中包含 PyTorch + CUDA 运行时。
如果检测到 NVIDIA GPU，你将在 GPU 面板中看到“Install CUDA backend”（安装 CUDA 后端）。应用将分别下载两个归档文件： * 服务器核心 (~200-400 MB) — 随每个 Voicebox 版本更新 * CUDA 库 (~4 GB) — 庞大的 PyTorch + CUDA DLL，独立版本管理
Voicebox 将重启以载入 CUDA 后端。
这种分离归档的设计（v0.4 新增）意味着大多数 Voicebox 升级只需重新下载较小的服务器核心归档。4 GB 的库归档仅在下层 CUDA 工具包或 torch 主版本变化时才会刷新。
自动更新
当新的 Voicebox 版本发布时，GPU 面板会检查捆绑的服务器核心是否与已安装的 CUDA 版本匹配。如果只有核心发生了变化（常见情况），它将在后台拉取新的核心。如果库版本发生了变化（罕见 — 仅发生在 cu126 → cu128 这类版本升级时），系统会提示你确认较大的下载量。
RTX 50 系列 / Blackwell
Voicebox 0.4 增加了对 RTX 50 系列的显式支持：
* CUDA 工具包升级为 cu128（之前的版本使用 cu126，缺乏 Blackwell 内核） * 构建时固定为 TORCH_CUDA_ARCH_LIST=...12.0+PTX 以支持向前兼容
如果你使用的是 RTX 5070 / 5080 / 5090，并看到“no kernel image is available”（没有可用的内核映像）错误：
* 确保你使用的是 Voicebox ≥ 0.4.0（设置 → 关于） * 重新安装 CUDA 后端（设置 → GPU → Reinstall CUDA backend）— 旧安装可能含有过时的 cu126 库 * 如果错误持续，请参阅下方的 GPU 兼容性警告部分
Intel Arc (XPU)
0.4 版本新增。适用于 Arc A 系列（Alchemist：A380, A580, A750, A770）和 B 系列（Battlemage）。
设置
Voicebox 会自动检测 Arc GPU 并通过 Intel 的 PyTorch XPU 后端（由 IPEX — Intel Extension for PyTorch 提供支持）进行路由。除了标准的 Voicebox 安装外，无需额外安装步骤。
验证是否正常工作： * 设置 → GPU 应显示 XPU，后跟你的 Arc 型号名称（例如 XPU (Intel Arc A770)） * 启动日志打印 Backend: PYTORCH 和 GPU: XPU (Intel Arc ...)
XPU 上的引擎
所有基于 PyTorch 的引擎都支持 XPU。性能通常介于 CPU 和 CUDA 之间 — 对于较大模型，预计比 CPU 快 2-3 倍。
DirectML
这是 Windows 用户非 NVIDIA、非 Intel-Arc GPU（如较旧的 AMD 独立显卡、集成 GPU 等）的回退方案。速度比 CUDA 和 XPU 慢，但相比 CPU 仍有一定加速。
当没有其他 GPU 后端可用时自动选择。
AMD ROCm (Linux)
ROCm 为 AMD 独立 GPU 提供 PyTorch GPU 加速。Voicebox 会为需要覆盖的常见显卡自动配置 HSA_OVERRIDE_GFX_VERSION。
验证 ```bash # 在终端中 echo $HSA_OVERRIDE_GFX_VERSION # 应显示例如 10.3.0 用于 RX 6000 系列 ``` 如果检测失败，请在启动 Voicebox 前手动设置该变量： ```bash export HSA_OVERRIDE_GFX_VERSION=10.3.0 voicebox ```
常用值： * 10.3.0 — RX 6000 系列 (RDNA 2) * 11.0.0 — RX 7000 系列 (RDNA 3) * 9.0.0 — 较旧的 Vega 显卡
GPU 兼容性警告
Voicebox 0.4 增加了一个运行时检查，将你的 GPU 计算能力与捆绑的 PyTorch 编译支持的架构进行对比。如果不匹配，你将看到：
* 启动日志行：WARNING: GPU COMPATIBILITY: <你的 GPU> 不受此 PyTorch 构建支持... * 设置中的 GPU 标签显示 [UNSUPPORTED - see logs] * /health API 返回已填充的 gpu_compatibility_warning 字段
应对措施
最常见的触发因素是全新的 GPU 架构，预构建的 PyTorch wheel 尚未原生支持。按优先级排序：
* 更新 Voicebox — 新版本附带更新的 PyTorch，支持更广泛的架构 * 重新安装 CUDA 后端 — 设置 → GPU → Reinstall CUDA backend * 对于前沿 GPU（比当前 Blackwell 更新）：手动安装 PyTorch 夜间版： `pip install torch --index-url https://download.pytorch.org/whl/nightly/cu128 --force-reinstall` 然后通过 Remote Mode 将 Voicebox 指向该环境，直到稳定的 PyTorch 版本支持。 * 暂时回退到 CPU — 启动前设置 VOICEBOX_FORCE_CPU=1
纯 CPU 回退
当没有 GPU 可用（或你强制关闭了 GPU），Voicebox 将运行 PyTorch CPU 后端。预期表现：
* 生成速度慢 5-50 倍，具体取决于引擎和文本长度 * 生成期间 CPU 占用率高 * 不同引擎在 CPU 上的表现差异较大： * Kokoro 82M — 在现代 CPU 上实现实时运行 * LuxTTS — 在 CPU 上超过 150 倍实时速度 * Chatterbox Turbo (350M) — 可用但较慢 * 较大模型 (Qwen 1.7B, Chatterbox Multilingual, TADA 3B) — 体验较差
对于 CPU 受限的使用场景，建议优先选择更小、更轻量的引擎。
验证你的设置
检查是否使用了正确后端的三个地方：
* 显示检测到的后端、GPU 型号和 VRAM（如适用）。留意 [UNSUPPORTED - see logs] 后缀
* “Server logs”（服务器日志）选项卡显示启动横幅，包含 Backend:
故障排除
▶ 设置显示 CPU 而非我的 GPU * NVIDIA：安装 CUDA 后端（设置 → GPU） * Intel Arc：在启动日志中确认 IPEX 检测；驱动更新后重启应用 * AMD Linux：检查是否已设置 HSA_OVERRIDE_GFX_VERSION
▶ 'no kernel image is available' / 'CUDA error' 这几乎总是意味着捆绑的 PyTorch 没有针对你 GPU 计算能力编制的内核。 * 更新到 Voicebox ≥ 0.4.0（Blackwell 支持在该版本添加） * 重新安装 CUDA 后端 * 如果仍然损坏，通过 Remote Mode 安装 PyTorch 夜间版
▶ Out of memory (CUDA)（显存不足） * 切换到较小的模型尺寸（例如用 Qwen3 0.6B 替代 1.7B） * 使用 设置 → Models 卸载未使用的其他引擎 * 低内存使用功能（low_cpu_mem_usage）在 CPU 上已开启；对于 CUDA，引擎的 device_map 会自动处理卸载 * 关闭其他 GPU 应用程序
▶ macOS 上的 MPS 回退错误 某些操作没有 Metal 实现。Voicebox 会为需要它的引擎（特别是 Kokoro）设置 PYTORCH_ENABLE_MPS_FALLBACK=1，但如果你从自定义环境启动，请手动设置：`export PYTORCH_ENABLE_MPS_FALLBACK=1`
▶ 生成正常但在我的 GPU 上很慢 * 检查 设置 → GPU 是否显示你的 GPU（而非 CPU） * 检查 VRAM 使用情况 — 你可能正在向系统内存分页 * 尝试使用较小的模型 * 对于 NVIDIA：确认已安装 cu128（设置 → GPU → 版本）
下一步
* Remote Mode：在拥有更强 GPU 的另一台机器上运行后端 * Model Management：卸载模型以释放 GPU 内存 * Troubleshooting：通用的非 GPU 故障排除 * Edit on GitHub * Quick Start：5 分钟内上手 Voicebox * Dictation：在机器上任何地方按住一个键，说话，松开 — 转录文本将出现在你当前聚焦的文本字段中。
