VoiceStudio: CosyVoice 引擎¶

CosyVoice 是一个可选的多语言 TTS 后端，用于零样本声音克隆和指令式语音。一键安装会在独立的环境和进程中运行它；已有的源码安装则继续以进程内方式运行。

下载的权重与引擎可用状态是两回事¶

Model Catalogue 单独跟踪模型权重与引擎运行时可用性。已下载的 FunAudioLLM/Fun-CosyVoice3-0.5B-2512 缓存表示模型文件已到达本机。这并不证明 VoiceStudio 后端能够导入并运行 CosyVoice。

对于已有的源码安装，运行 VoiceStudio 后端的同一个 Python 解释器必须能够导入：

from cosyvoice.cli.cosyvoice import AutoModel

随后它会加载 OMNIVOICE_COSYVOICE_MODEL 指定的目录，若未设置则默认使用 pretrained_models/Fun-CosyVoice3-0.5B。该路径必须解析到可用的模型目录，而不只是 Hugging Face 缓存根目录。

一键安装¶

在 Model Catalogue → Engines → CosyVoice 中点击 Install。VoiceStudio 会在数据目录下为 CosyVoice 单独创建文件夹和独立的 Python 3.10 环境，并让它在单独的进程中运行。该安装会：

• 克隆一个经过审查的 CosyVoice 提交及其依赖的 Matcha-TTS 代码；
• 下载 CosyVoice 3 权重（约 5.4 GB）。

它与上游自己的安装方式不同：

• PyTorch 2.7.0。 在 NVIDIA GPU 上使用 CUDA 12.8 构建，在其他 Windows 和 Linux 机器上使用 CPU 构建，在 Apple Silicon 上使用常规构建。上游的 2.3.1 仅针对 CUDA 12.1 存在，无法在 RTX 50 系列 GPU 上运行。在 Linux ARM64（例如 DGX Spark）上，只有 torch 采用该构建，而 torchaudio 安装的是不带 +cu128 或 +cpu 标签的普通 2.7.0 wheel，因为 PyTorch 发布的 ARM64 torchaudio 2.7.0 没有这些标签。
• 更精简的依赖项。 不包含 TensorRT、DeepSpeed 或 GPU 版 onnxruntime，也不使用第三方包索引。上游在 Linux 上使用这些来获得额外速度；没有它们合成也能正常工作。PyWORLD 需要 C++ 编译器：在 macOS 上需要 Xcode Command Line Tools，在 Windows 上需要带 C++ 的 Visual Studio Build Tools，在 Linux 上需要发行版的 C++ 构建工具。如果没有编译器，安装会以 “no C++ compiler found” 停止，并列出适合你系统的工具；安装它们后再次点击 Install 即可继续。SoX 不是必需的。
• 已修补的依赖项。 当上游锁定的某个发行版存在已发布的安全公告时（diffusers、hydra-core、lightning、modelscope、onnx、protobuf、transformers），安装会使用修复后的版本。该组合已在 Windows 上安装并通过了安装的导入检查。
• 没有文本规范化器。 上游的（wetext）在每次加载模型时都会从 ModelScope 下载其数据，而 ModelScope 会对这些下载做速率限制，因此规范化器可能下载到一半就静默失败。一键安装不包含它，CosyVoice 会按原样读取文本：在发音关键的地方，请把数字、日期和符号拼写出来。
• 只包含 CosyVoice 3 加载的权重。 不包括与其仓库共享的 RL 和 TensorRT 变体。

它安装的任何内容都不会影响 VoiceStudio 本身或其他引擎；同一行中的 Uninstall 只会删除该文件夹。已有的源码安装保持原样继续工作。在 Intel Mac 上不提供该按钮，因为 PyTorch 2.7.0 没有适用于这些机器的构建。

CosyVoice 3 没有内置音色。在没有参考音频片段时，它会使用上游自带示例提示的语音来发声。

源码构建与现有安装¶

上游 CosyVoice 项目建议使用它自己的 Python 3.10 Conda 环境和 SoX。上面的一键安装为 CosyVoice 提供了同样的独立环境。如果将上游固定的依赖版本安装到 VoiceStudio 的共享后端环境中，也可能与其他引擎发生冲突。

当 VoiceStudio 后端的解释器已经能导入 cosyvoice.cli.cosyvoice.AutoModel 时，已有的源码安装仍然可用。请保留可用的安装。在启动 VoiceStudio 之前，通过源码检出目录的环境或项目的 .env 文件，将 OMNIVOICE_COSYVOICE_MODEL 设置为可用的模型目录。

有关上游安装的详细信息，请阅读 官方 CosyVoice 安装指南。这些步骤会创建一个独立的 CosyVoice 环境。对于 Electron 应用，建议优先使用上面提到的受管一键安装器。

诊断不可用的引擎¶

在支持问题或 Bug 报告中请包含以下事实：

1. 确切的 VoiceStudio 版本。
2. 选择 Re-check 后，Model Catalogue > Engines > CosyVoice 下显示的完整原因。
3. 执行该检查后，Settings > Logs > Backend 中与 CosyVoice 相关的日志行。
4. 在 Windows 上，PowerShell 中 where.exe sox 的输出。

这些事实可以区分以下不同状态：模型已下载、缺少 Python 运行时、缺少 SoX 可执行文件、或模型目录不正确。在日志明确指出哪个状态失败之前，不要删除模型缓存或重新安装依赖。

公开揭示这种误导性安装状态的报告是 Discussion 1631。

在没有 CUDA 的主机上，受管 sidecar 会将 LLM、flow 和 vocoder 权重转换为 float32，以匹配上游 CPU 输入。CUDA 则保持其选定的精度。这样可以避免 CPU 上的 Float/BFloat16 矩阵不匹配；但这并不代表所有报告的安装或语音质量问题都已修复。

修复缺失的运行时导入¶

受管方案包含 gdown、wget 和 pyarrow，并构建不再需要 pkg_resources 的固定版本 PyWORLD 源码。其最终检查除了导入 AutoModel 外，还会导入数据集处理器和 Matcha 工具。旧的完成标记会被视为需要修复；重试 Install 即可复用已有的模型权重。用户自行管理的环境不会被重写。不要仅仅为了恢复 pkg_resources 而降级 setuptools。

较新版本 Transformers 中的语音上下文¶

受管 sidecar 在应用训练后的检查点之前，会以 float32 加载 Qwen，然后保留上游显式选择的精度。它还会在增量注意力掩码中包含缓存的提示 token：否则，较新版本 Transformers 中的单 token 掩码会隐藏文本和语音上下文，从而产生不相关或乱码的语音。现有的 Transformers 4 环境和旧版缓存元组仍受支持；完整掩码会保持不变。

现在，使用 Transformers 5.10.1 的真实 CosyVoice 3 CPU 检查可完整重现包含 89 个单词的英文输入，并已通过独立的本地语音识别器验证。一个随机初始化的微型 Qwen 回归测试可在 CI 中无需下载任何模型，检查缓存解码与全上下文解码。这并不保证对所有语言、语音参考或 GPU 配置的验证。