Confucius4-TTS（选择启用引擎）¶

状态：已于 2026-07-02 端到端验证。 集成（引擎注册、专用虚拟环境引导、sidecar 通信协议、选择启用门控）已完成，sidecar 的纯逻辑已通过单元测试（tests/test_confucius4_sidecar.py），并且在 Apple Silicon（CPU）上的实际合成运行生成了可听见的克隆语音——验证了模型 API 和真实的输出采样率 22 050 Hz。CUDA 是推荐硬件；CPU 可用但较慢（约 17 倍实时——生成 6 秒音频大约需要 100 秒）。MPS 也能运行，但比 CPU 更慢（约 64 倍实时），因此 sidecar 有意不选择它。该引擎由 OMNIVOICE_CONFUCIUS4_TTS_DIR 门控，因此在你选择启用之前它完全处于惰性状态——它不会影响任何平台上的默认安装。

Confucius4-TTS（netease-youdao）是一个基于 LLM 的多语言 / 跨语言零样本语音克隆 TTS。

• 14 种语言：中文、英文、日文、韩文、德文、法文、西班牙文、印尼文、意大利文、泰文、葡萄牙文、俄文、马来文、越南文。
• 无约束克隆——无需参考转录文本。
• 跨语言音色迁移——跨语言保持同一音色。
• 许可证： Apache-2.0。硬件： 推荐 NVIDIA GPU（CUDA 12.6）；CPU 已在 Apple Silicon 上验证，但约为 17 倍实时。输出：22 050 Hz 单声道。

与 IndexTTS-2 / MOSS-TTS-v1.5 / dots.tts 一样，它在自己的子进程虚拟环境中运行，因此其依赖栈永远不会触及默认的 VoiceStudio 解释器。

一键安装¶

Model Catalogue → Confucius4-TTS → Install 会为你执行以下步骤，适用于 Windows、Linux 和 macOS。它会安装到 VoiceStudio 数据目录下的独立文件夹中，并自带独立的 Python 环境。它所安装的任何内容都不会触及 VoiceStudio 本身或其他引擎，因此你可以切换到它再切回来，而不会破坏已有的功能。同一行的 Uninstall 只会删除该文件夹。在 NVIDIA 机器上，它会安装 PyTorch 的 CUDA 构建版本；在其他机器上则安装 CPU 构建版本。约 5 GB 的权重仍会在首次合成时下载。

首次合成时会下载权重，在慢速连接下可能需要一段时间。下载进行期间生成过程会保持存活；如果下载停滞并超时，请在 设置 → 性能与设备 中提高计算时间预算，然后重试。

安装¶

git clone https://github.com/netease-youdao/Confucius4-TTS.git
cd Confucius4-TTS
uv venv --python 3.10
uv pip install -r requirements.txt

上游没有随附 pyproject.toml/setup.py，因此没有可 pip install -e 的包——不要尝试；会失败。VoiceStudio 的 sidecar 会自己将克隆仓库加入 sys.path（与上游 example.py 的做法相同）。

模型权重——首次合成时全部自动从 HuggingFace 获取（总计约 5 GB，缓存在 $HF_HUB_CACHE 中）：

• netease-youdao/Confucius4-TTS — t2s_model.safetensors + s2a_model.pt（tokenizer 和 wav2vec2bert_stats.pt 已随克隆仓库的 checkpoints/ 提供）。
• facebook/w2v-bert-2.0 — 语义特征提取器（约 2.3 GB）。
• funasr/campplus — 说话人风格编码器（较小）。
• nvidia/bigvgan_v2_22khz_80band_256x — 声码器（BigVGAN 和 CAMPPlus 代码已随克隆仓库的 external/ 一并提供；无需安装 Amphion）。

如果遇到速率限制，请设置你的 HF_TOKEN（设置 → 凭据）。

然后将 VoiceStudio 指向克隆仓库并重启：

• macOS/Linux： export OMNIVOICE_CONFUCIUS4_TTS_DIR=/path/to/Confucius4-TTS
• Windows（PowerShell）： [Environment]::SetEnvironmentVariable("OMNIVOICE_CONFUCIUS4_TTS_DIR","C:\path\to\Confucius4-TTS","User")

在 Model Catalogue 中选择 Confucius4-TTS（TTS 标签页 → 使用）。首次合成会触发上述权重下载，然后生成。

sidecar 会从克隆目录解析捆绑的模型资产。相对路径的克隆/配置覆盖项以及 Hugging Face 缓存设置会保留其原始的启动目录含义；现有缓存会被重用，无需迁移。参考音频片段由父进程在 sidecar 更改目录之前解析。生成需要参考音频片段；其转录文本是可选的。

可选覆盖项¶

• OMNIVOICE_CONFUCIUS4_CONFIG — 指向 inference_config.yaml 的路径（如果该文件不在 <clone>/config/inference_config.yaml 下）。

验证记录（2026-07-02，Apple Silicon M 系列，CPU）{#validation-record-2026-07-02-apple-silicon-m-series-cpu}¶

sidecar（backend/engines/confucius4/main.py）使用：

from confuciustts.cli.inference import ConfuciusTTS
model = ConfuciusTTS(config_path=..., device="cuda")  # or "cpu"
audio = model.generate(text=..., lang="en", prompt_wav="ref.wav")  # → tensor
sr = model.sample_rate  # 22050

• ✅ 实测端到端运行：使用 9.5 秒参考音频进行英文零样本克隆——在 CPU 上 102 秒内生成 6.06 秒可听见的语音（峰值 0.85）。model.sample_rate 返回 22 050，与 config/inference_config.yaml 中的 target_sample_rate 一致；CONFUCIUS_SAMPLE_RATE / _DEFAULT_SAMPLE_RATE 已固定为该值（回归测试通过）。
• ✅ 上游不可通过 pip 安装——在实测中发现；现在引导过程会跳过可编辑安装，除非上游提供打包；导入探查和 sidecar 都通过克隆仓库在 sys.path 上解析 confuciustts。
• ✅ MPS 已探查并否决：可以运行，但比 CPU 慢约 4 倍（Metal 算子回退）——sidecar 在可用时选择 CUDA，否则选择 CPU，绝不选择 MPS。
• ✅ sidecar 逻辑已通过单元测试（tests/test_confucius4_sidecar.py）：语言归一化、张量→PCM（单声道/立体声/裁剪）、配置路径解析、克隆仓库 sys.path 注入、通信帧、合成调度。

加速器路由¶

sidecar 会将运行时可用的 CUDA/ROCm、XPU 或已注册的 NPU 传递给上游的设备感知模型加载。引擎虚拟环境需要匹配的 PyTorch/厂商运行时，Model Catalogue 安装提示中也提到了这一点。XPU/NPU 的选择由模拟加载器和路由测试覆盖；此变更并未认证在物理 XPU/NPU 硬件上的合成。MPS 保留上述验证记录所述的现有 CPU 回退。如果现代加速器检测或旧版 CUDA 探测引发异常，加载会回退到 CPU，而不是在模型构建前中止。

共享模型管理器将已注册的 Ascend NPU 内存识别为专用 VRAM，并在引擎卸载时清除其分配器缓存。这由模拟加速器测试覆盖；它并不证明在物理 Ascend 硬件上的生成能力。