常见问题与故障排查¶
本页汇总 VoxCPM 社区里常见的安装、运行与部署问题。有关提示词写法、声音克隆技巧和质量调优，请参阅 使用指南。
安装与环境问题¶
Windows 上的 Triton 报错¶
现象： 在 Windows 上加载模型时出现 Python int too large to convert to C long，或与 Triton 相关的导入失败。
原因： Triton 对 Windows 的支持较有限，某些 PyTorch 与 Triton 的版本组合会触发已知问题。
解决方案：
通过社区项目 triton-windows 安装适用于 Windows 的 Triton（参见 #36）。Triton 与 PyTorch 的版本必须匹配：
PyTorch
Triton
2.4 / 2.5
3.1
2.6
3.2
2.7
3.3
2.8
3.4
如果 Triton 仍然无法正常工作，你可以在加载模型时完全跳过
torch.compile：model = VoxCPM.from_pretrained("openbmb/VoxCPM2", optimize=False)
这会禁用
torch.compile加速。推理速度会变慢，但功能仍然正常。如果你遇到的是
Python int too large to convert to C long这个特定错误，可以参考 PyTorch 修复方案，其中涉及对torch_python.dll打补丁（参见 #27）。
torchcodec / libtorchcodec 报错¶
现象： 在使用参考音频进行声音克隆时，出现 RuntimeError: Could not load libtorchcodec 或 ImportError: TorchCodec is required for load_with_torchcodec。
原因： torchaudio``（>= 2.9）默认使用 ``torchcodec 作为音频后端，而它要求系统正确安装 FFmpeg。
解决方案：
在系统范围安装 FFmpeg（支持 4–7 版本）：
Linux：
sudo apt install ffmpegmacOS：
brew install ffmpegWindows： 从 ffmpeg.org 下载，并加入
PATH
安装兼容的 torchcodec 版本：
pip install torchcodec
如果问题仍然存在，可以强制让 torchaudio 改用
soundfile后端：import torchaudio torchaudio.set_audio_backend("soundfile")
另见：关于 torchcodec 的 HuggingFace 讨论 <https://discuss.huggingface.co/t/cannot-load-torchcodec/169260/4>`_（在 `#86、#119、#123 中有引用）
首次运行时的 torch.compile 报错¶
现象： 在预热阶段出现 torch._dynamo.exc.Unsupported 错误（通常会提到 einops 或 symmetric_difference）。
原因： 某些 PyTorch、Triton 与 einops 的版本组合与 torch.compile 不兼容（参见 #19）。
解决方案：
快速修复： 禁用 torch.compile：
model = VoxCPM.from_pretrained("openbmb/VoxCPM2", optimize=False)
推荐环境（基于 #19，已在 4090 上验证）：
软件包
版本
PyTorch
2.5.1+
Triton
3.1.0+
einops
0.8.1
Python
3.10–3.11
如果你使用的是较旧、SM 数量较少的 GPU，可能还会看到
Not enough SMs to use max_autotune_gemm mode。这只是警告；如果推理能正常完成，可以忽略。
Mac / MPS 支持¶
问：VoxCPM 可以在 Mac（Apple Silicon）上运行吗？
可以。VoxCPM 支持在 Apple Silicon Mac 上使用 CPU 和 MPS（Metal Performance Shaders）（参见 #14、#20、#41）。
CPU： 开箱即用，但推理速度较慢（参见 #67）。
MPS： 当 CUDA 不可用时，
device="auto"会自动尝试使用 MPS。
备注
即使启用了 MPS，降噪器（ZipEnhancer）仍然运行在 CPU 上。如果你不需要增强 prompt 语音，可设置 load_denoiser=False 以节省内存。
重要
torch.backends.mps.is_available() 只表示 MPS 后端存在。它并不保证 VoxCPM 的所有推理路径都能在该后端上成功运行。如果你在 MPS 上遇到运行时错误，请显式切换到 CPU：
model = VoxCPM.from_pretrained("openbmb/VoxCPM2", device="cpu", optimize=False)
voxcpm design --text "Hello" --device cpu --no-optimize --output out.wav
WSL2 / ROCm 社区 workaround¶
问：VoxCPM 可以在 WSL2 下的 AMD ROCm 环境中运行吗？
社区中已有在 WSL2 + ROCm 上运行的案例，但这并不是项目当前的主要测试环境之一。在 #203 的报告中，用户需要两个 workaround：
将
torchaudio.load_with_torchcodec/save_with_torchcodecmonkey-patch 回标准的torchaudioI/O 函数，因为该 ROCm 环境中的torchcodec无法正常工作。通过设置
optimize=False禁用torch.compile。
如果你正在尝试 ROCm 或其他非 CUDA 平台，建议先从禁用 torch.compile 开始：
model = VoxCPM.from_pretrained("openbmb/VoxCPM2", optimize=False)
如果你的环境在默认设备路径下仍然失败，请先显式回退到 CPU，验证其余流程可用后，再尝试额外的加速设置。
Python 版本兼容性¶
VoxCPM 在 Python 3.10–3.11 上测试最充分。对于当前版本，推荐的运行范围是 Python 3.10–3.12。已知问题如下：
性能与部署¶
显存与 RTF 参考¶
模型 |
显存 |
RTF（官方） |
RTF（NanoVLLM-VoxCPM） |
|---|---|---|---|
VoxCPM 1.0（0.5B） |
~5 GB |
~0.17 |
~0.10 |
VoxCPM 1.5（0.8B） |
~6 GB |
~0.15 |
~0.08 |
VoxCPM 2（2B） |
~8 GB |
~0.3 |
~0.13 |
所有 RTF（Real-Time Factor）数值均在单张 NVIDIA RTX 4090 GPU 上、开启 torch.compile 且使用 inference_timesteps=10 的条件下测得。
RTF（官方）：标准推理流程（
VoxCPM.generate）。RTF（NanoVLLM-VoxCPM）：NanoVLLM-VoxCPM 的高吞吐服务方式，在并发数为 1 时测得。
CUDA Graphs 与多线程¶
警告
默认启用 torch.compile 的 VoxCPM 会使用 CUDA Graphs，而它**与多线程不兼容**（参见 #97、#107、#125）。如果在后台线程中运行推理，可能会在 cudagraph_trees 中触发 AssertionError。
解决方案：
如果你需要多线程，请禁用 torch.compile：
model = VoxCPM.from_pretrained("openbmb/VoxCPM2", optimize=False)
若要并发服务，请使用 NanoVLLM-VoxCPM，它能正确处理 batching 和 threading：
部署说明请参阅 NanoVLLM-VoxCPM。
对于 Gradio 应用（
app.py），请限制并发数以避免 CUDA Graph 冲突（参见 #97）：interface.queue(max_size=10, default_concurrency_limit=1).launch()
vLLM / lmdeploy 兼容性¶
VoxCPM 不兼容标准 LLM 推理框架（如 vLLM、lmdeploy 等），因为它使用的是扩散式架构，生成的是连续音频 latent，而不是离散 token（参见 #6、#91）。
若要进行高吞吐部署，请改用 NanoVLLM-VoxCPM。
还有问题？¶
如果这里还没有解决你的问题：
先搜索 GitHub Issues，可能已经有人提过相同问题。
提交一个 新 issue，并附上你的环境信息、错误日志以及复现步骤。
加入社区微信群（二维码见 README）。