基于 Vulkan 的 CosyVoice 3 GGUF¶

VoiceStudio 为那些不适合走官方 Python/PyTorch 路线的机器提供了一个可选的原生 CosyVoice 3 后端。它作为本地服务器运行社区 Lourdle/cosyvoice.cpp GGML 移植版。经测试的 AMD 路线是使用 Vulkan 的 Radeon RX 6700 XT。这确认了该显卡和构建可用；但并不保证适用于每块 AMD GPU。

这是一个名为 CosyVoice 3 GGUF 的独立引擎。现有的 Python CosyVoice 3 引擎和 VoiceStudio 默认行为不变。它需要一段参考录音及其转录文本，支持 CosyVoice 3 的九种语言，并将诸如“柔和、温暖、有气息感”之类的自由形式指令传递给模型。原生路线还支持语速和随机种子控制。它输出 24 kHz 的语音。它不提供纯文本语音设计，也不承诺与 ElevenLabs 功能对齐。量化输出在某些句子上可能听起来发闷；请查看上游模型卡并试听实际渲染效果。

构建原生运行时¶

可执行文件不随 VoiceStudio 捆绑提供，也不由 VoiceStudio 下载。你需要自行构建固定的社区源码，并保留其声明以及所有 GGML/Vulkan/ONNX Runtime 声明。在 Windows 上，安装 Git、CMake、Visual Studio C++ 构建工具和 Vulkan SDK，然后在 Developer PowerShell 中执行：

git clone --recursive https://github.com/Lourdle/cosyvoice.cpp.git
cd cosyvoice.cpp
git checkout 67d45feb2f654bbc66cca25bff78464b3ec08fa1
git submodule update --init --recursive
cmake -S . -B build -DGGML_VULKAN=ON -DCOSYVOICE_NO_ICU=ON -DCOSYVOICE_SERVER_NO_WEBUI=ON
cmake --build build --config Release --parallel

使用包含 cosyvoice-server.exe 和 cosyvoice-cli.exe 的构建输出。将 OMNIVOICE_COSYVOICE_GGUF_DIR 设置为该输出文件夹，或者分别设置 OMNIVOICE_COSYVOICE_GGUF_SERVER 和 OMNIVOICE_COSYVOICE_GGUF_CLI 变量。引擎会报告该运行时实际暴露了哪些原生设备。

安装并选择模型¶

打开 Settings → Models 并安装 CosyVoice 3 0.5B Q4_K_M (native GGUF/Vulkan)。该条目固定在一个不可变的模型修订版上，安装 GGUF 和两个 ONNX 前端资源。生成过程绝不会下载模型或运行时。已有的本地模型文件也可以改用 OMNIVOICE_COSYVOICE_GGUF_MODEL 和 OMNIVOICE_COSYVOICE_GGUF_FRONTEND 来指定。覆盖设置必须指向真实文件：模型或前端文件缺失属于错误，绝不会静默回退到已安装的资源。

后端选择器为 OMNIVOICE_COSYVOICE_GGUF_BACKEND：

对于测试用的 AMD 工作站，设置 OMNIVOICE_COSYVOICE_GGUF_BACKEND=Vulkan0，并确认引擎详情中列出 Vulkan0 且对应 AMD Radeon RX 6700 XT。语音提示以参考音频内容加转录文本为键在本地缓存；请求和配置变更会被串行化处理，因此一次渲染不能使用另一个声音的提示。服务器绑定到 loopback，使用每进程的 API 密钥，并在引擎卸载或停止响应时被停止；服务器拒绝的请求（HTTP 错误）会报告其状态，且服务器保持运行。

固定的运行时只接受以命令行参数形式传入的 API 密钥，因此同一台计算机上能够列出进程参数的其他账户可以在服务器运行期间读取它。该密钥在每次启动时重新生成，端口仅接受 loopback 连接；在共享的多用户机器上，请优先选用其他引擎。

模型与运行时条款¶

上游模型卡声明为 Apache-2.0。VoiceStudio 将该模型记录为未审查：组件溯源、商业推理、输出条款和再分发义务均尚未厘清。该运行时是非官方社区移植版；请保留其 MIT 及捆绑的第三方声明。这些声明不授予克隆参考语音的权利。只使用你有权处理的录音。参见模型清单和上游模型卡。