原生 CosyVoice GGUF/Vulkan 后端¶

目标¶

通过社区 Lourdle/cosyvoice.cpp GGML 运行时添加 CosyVoice 3 推理，作为独立的可选用 VoiceStudio TTS 引擎。已验证的目标是使用 Vulkan 的 Windows x64 + AMD Radeon RX 6700 XT。现有的 Python CosyVoice（cosyvoice）保持不变，继续维持当前行为。

证据与范围¶

• 本地构建固定到 Lourdle/cosyvoice.cpp 提交 67d45feb2f654bbc66cca25bff78464b3ec08fa1，配置 GGML_VULKAN=ON，编译成功，并显示 Vulkan0 - AMD Radeon RX 6700 XT。
• Q4_K_M CosyVoice3-2512 模型使用用户的本地 Mira 配置文件生成了 24 kHz 单声道语音。服务器 API 还生成了一个带有 instruct/气声提示的样本。
• 上游是社区非官方移植；该结果仅确立了这台机器的可用路线，并不代表对 AMD 的通用支持，也不等同于完整的 ElevenLabs 兼容性。

设计¶

1. 注册一个独立的 cosyvoice-gguf 引擎。它声明支持 CosyVoice 3 语言、参考音色克隆、自由格式 instruct 文本和 24 kHz 输出；不声明支持纯文本音色设计。
2. 从显式环境变量覆盖或应用管理的引擎目录解析原生运行时。V1 不会下载/重新分发可执行运行时文件：用户自行构建固定版本的源码，或指向现有构建；安装指南会列出所需依赖并保留上游声明。GGUF 文件及两个 ONNX 前端文件仅从显式且不可变的 Model Catalogue 修订版或显式文件覆盖中解析。生成过程绝不会隐式下载文件。
3. 探测实际原生运行时的后端列表。V1 通过 OMNIVOICE_COSYVOICE_GGUF_BACKEND（auto、CPU 或检测到的后端名称如 Vulkan0）选择设备；引擎元数据和指南会显示实际检测到的目标及回退原因。如果选择自动模式，则选一个可用的 Vulkan 设备，否则使用 CPU 并展示可见原因；绝不单凭 OS Vulkan 驱动就声称 GPU 加速。专门的设置选择器将推迟到后端行为明确后再提供。
4. 以音频内容和转写文本的 SHA-256 为每个参考 Prompt 建立缓存，使用原生 CLI 前端创建一次后复用。保持一个仅回环（loopback）的服务器常驻。在同一个锁下对生成操作与配置文件变更进行串行化；仅在当前活动的参考 Prompt 变化时重启它。在发送音频请求前，确认受管进程确实拥有该回环端点。
5. 将服务器的 WAV 响应按引擎声明的 24 kHz 采样率转换为单声道 float 张量。在支持时传递 instruct、language 和 seed；对于不支持的控制项要如实报告，而不是默默声称支持。
6. 记录运行时构建/安装流程、固定源码修订版、模型资产与许可证、显式 Vulkan 选择、验证步骤和已知限制。所有代码模块保持 200 行以内。

安全性与兼容性¶

• 不更改默认引擎，不自动下载运行时/模型，不进行远程推理，也不新增对本地网络的访问。原生服务仅绑定回环地址，由 VoiceStudio 拥有并终止。手动构建的运行时需固定版本，且必须保留上游运行时、GGML、ONNX Runtime 以及模型/组件声明；VoiceStudio 在此阶段不会重新分发这些二进制文件。
• 不修改当前 Python CosyVoice 实现或 AMD ROCm 路径。
• 在运行时和模型文件都存在之前，引擎不可用；诊断信息会说明缺失的先决条件。
• 模型和运行时来源固定。模型包标识为 Apache-2.0，但商业使用和完整组件的许可证闭合性尚未审查；文档不得声称更宽泛的许可授权。社区运行时是 MIT 许可且非官方，构建后的运行时中保留第三方依赖声明。
• 此聚焦实现的问题关联到总问题 #2468，但不关闭 #2468。

验收检查¶

• 单元测试覆盖路径优先级、运行时/设备选择、Prompt 缓存键、请求构造、响应解码以及无网络访问时的失败清理。
• 现有 TTS 注册表和 CosyVoice sidecar 测试仍然通过。
• 针对用户构建的运行时进行的本地端到端检查，应返回非静音 24 kHz 单声道输出，并记录 Vulkan0 (AMD Radeon RX 6700 XT)。
• GPU 路由只有在原生运行时报告所选 Vulkan 设备后才被标记为加速；并发请求/配置文件切换不得使用过期或不匹配的 Prompt 映射。