VoiceStudio — MOSS-TTS-v1.5 引擎¶

MOSS-TTS-v1.5 (OpenMOSS) 是旗舰级 8B 零样本 TTS —— 以 Qwen3-8B 语言骨干网络外加 1.6B 音频编解码器构成。它覆盖 31 种语言，支持零样本声音克隆、token 级时长控制以及内联 [pause Ns] 标记。基于 Apache-2.0（代码 + 权重）发布。

它运行在独立的子进程 以及独立的 Python venv 中，使用 transformers==5.0.0，与固定 transformers>=5.3 的 VoiceStudio 父进程隔离。这与 IndexTTS-2 所用的隔离原语相同：两个 transformers 版本锁定无法共享同一个解释器，因此 MOSS 运行在 backend/services/subprocess_backend.py::SubprocessBackend 之后。

主动选择启用，绝非默认。 MOSS-TTS-v1.5 仅在 Model Catalogue（或 OMNIVOICE_TTS_BACKEND=moss-tts-v15）中被显式选择。它不是默认安装的一部分，也不会在任何平台上改变 VoiceStudio 的开箱即用行为。

硬件¶

• VRAM/RAM: 这是一个 8B 模型。上游 llama.cpp 流水线在量化后可将 8B 模型放入 8 GB GPU；此处使用的 bf16 Transformers 路径权重约 16 GB，因此 16 GB 及以上的 GPU 才是现实的 CUDA 目标。它也可以在 CPU (fp32) 上运行——结果正确但速度较慢。
• 设备： sidecar 进程使用运行时可用的 PyTorch CUDA/ROCm、XPU 或已注册的 NPU 后端，否则使用 CPU。隔离的引擎 venv 需要匹配的 torch/厂商集成。加速器探测失败时会回退到 CPU，包括在不具备统一加速器 API 的旧 venv 中。MPS 仍使用 CPU。XPU/NPU 路由由模拟加载器测试覆盖；物理设备合成尚未经本次变更验证。

一键安装¶

在配备 NVIDIA GPU 的机器上，Model Catalogue → MOSS-TTS-v1.5 → 安装 会为你完成以下所有步骤。它会安装到 VoiceStudio 数据目录下自己的文件夹中，并附带自己的 Python 环境。它安装的任何内容都不会影响 VoiceStudio 本身或任何其他引擎，因此你可以切换到它再切换回来，而不会破坏已经可用的功能。同一行中的 卸载 只会删除该文件夹。约 16 GB 的权重仍会在首次合成时下载。在仅 CPU 的主机上不会提供该按钮；请使用手动安装。

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

TTS 模型及其音频编解码器从各自固定的 Hugging Face 快照加载：OpenMOSS-Team/MOSS-TTS-v1.5（cdd3b911b1585e3f2dbc7775ef10f9926f58850a）和 OpenMOSS-Team/MOSS-Audio-Tokenizer（3cd226ba2947efa357ef453bcad111b6eafba782）。现有缓存文件会被复用；缺失的权重分片、tokenizer 资源或模型代码依赖会在下一次合成时恢复同一个固定下载。包含所有加载文件的快照即使在缺少 README.md 等可选文件时也能离线工作。

对于使用旧解码器方案创建的管理安装，请运行一次 Model Catalogue → MOSS-TTS-v1.5 → 安装 以应用更新。安装程序会修复现有 venv 中的依赖并保留模型缓存。外部克隆保留其自身的依赖设置；如果其 CUDA 解码器无法加载，请使用 常见错误 下的解码器替换命令。

安装¶

MOSS-TTS-v1.5 不会随附捆绑（模型体积大，且该包固定了有冲突的 transformers）。VoiceStudio 附带一个 sidecar 运行器，可按需将其加载到隔离的 venv 中。

1. 将 MOSS-TTS 仓库克隆到本地磁盘：

git clone https://github.com/OpenMOSS/MOSS-TTS.git

1. 将可编辑包安装到一个全新的 venv 中。请使用 uv pip install -e ".[torch-runtime]" —— 绝不要使用 uv sync --all-extras，它会用 transformers==5.0 覆盖 VoiceStudio 的锁文件并破坏父进程。torch-runtime extra 对应 CUDA（+cu128）：

cd MOSS-TTS
uv venv --python 3.11 .venv
uv pip install -e ".[torch-runtime]" "torchcodec===0.8.1"      --extra-index-url https://download.pytorch.org/whl/cu128      --index-strategy unsafe-best-match

该 extra 固定 torch==2.9.1+cu128，该版本仅发布在 PyTorch 自己的索引上，因此必须使用 --extra-index-url——没有它，uv 会在所有主机上报告依赖无法满足。精确的 torchcodec===0.8.1 要求会选中 CPU 音频解码器；==0.8.1 也允许 CUDA 构建，后者即使在 CPU 上解码参考音频时也需要额外的 NVIDIA NPP 库。

在 非 CUDA / CPU 主机（例如 Apple Silicon）上，请安装基础可编辑包及兼容的 PyTorch 配对版本，而不是 +cu128 extra（下面的自动引导仅面向 CUDA 主机）：

uv pip install -e . "torch==2.9.1" "torchaudio==2.9.1" "transformers==5.0.0" "torchcodec===0.8.1" --extra-index-url https://download.pytorch.org/whl/cpu --index-strategy unsafe-best-match

TorchCodec 0.8 要求 PyTorch 2.9。不要让 torch 或 torchaudio 处于未固定版本状态：更新的 PyTorch 可能导致该解码器无法加载。

1. 约 16 GB 的权重会在首次合成时从 HuggingFace 下载。父进程将 HF_HOME / HF_HUB_CACHE 转发给 sidecar，以便缓存与 VoiceStudio 的其他下载共享。

2. 将 OMNIVOICE_MOSS_TTS_V15_DIR 设置为仓库根目录（包含 pyproject.toml 的目录）：

# macOS / Linux
echo 'export OMNIVOICE_MOSS_TTS_V15_DIR=$HOME/code/MOSS-TTS' >> ~/.zshrc
source ~/.zshrc

# Windows PowerShell
[Environment]::SetEnvironmentVariable("OMNIVOICE_MOSS_TTS_V15_DIR","$env:USERPROFILE\code\MOSS-TTS","User")

1. 重启 VoiceStudio。MOSS-TTS-v1.5 会出现在 Model Catalogue 中，显示 available: true 和 isolation_mode: subprocess。

Venv 解析顺序¶

VoiceStudio 会按以下优先级探测可用的 MOSS Python 解释器（参见 backend/engines/moss_tts_v15/bootstrap.py）：

1. ${OMNIVOICE_MOSS_TTS_V15_DIR}/.venv/ —— 你现有克隆仓库的 venv。优先级最高，因此已经配置好 MOSS 的高级用户无需重新安装。
2. backend/engines/moss_tts_v15/.venv/ —— VoiceStudio 自己的 venv，按需由第 3 步创建。
3. 懒加载引导（lazy bootstrap） —— 如果两个 venv 都不存在，VoiceStudio 会运行 uv venv，然后执行 uv pip install --python <python> -e "${DIR}[torch-runtime]"。此步骤要求设置 OMNIVOICE_MOSS_TTS_V15_DIR，否则会抛出明确的错误。在非 CUDA 主机上，+cu128 extra 无法解析——请按第 2 步手动创建 venv。

声音克隆¶

将参考片段作为 ref_audio 传入。MOSS 的零样本克隆模式只需要音频（无需转写文本）。如果没有参考音频，MOSS 会使用自己的默认音色进行合成。duration（秒）会映射到 MOSS 的 tokens 参数，约为 12.5 tokens/秒。

可选的环境变量开关¶

常见错误¶

MOSS-TTS-v1.5 venv not found. Set OMNIVOICE_MOSS_TTS_V15_DIR ...¶

你还没有将 VoiceStudio 指向 MOSS-TTS 克隆仓库。请按照安装步骤操作。

uv pip install -e failed ... '[torch-runtime]' extra (cu128) cannot resolve¶

你当前位于非 CUDA 主机。上游的 torch-runtime extra 仅支持 CUDA；请按第 2 步中的固定 CPU 命令手动创建 venv。

Could not load libtorchcodec 或 libnppicc.so.12 在声音克隆期间¶

旧版安装可能包含 CUDA 版 TorchCodec 构建。请停止引擎，然后仅替换其音频解码器，保留模型权重和其他包不变：

uv pip install --python <moss-venv-python> --index-url https://pypi.org/simple --reinstall-package torchcodec --no-deps "torchcodec===0.8.1"

请使用 MOSS 引擎自带 .venv 中的 Python 可执行文件：macOS/Linux 上为 bin/python，Windows 上为 Scripts/python.exe。新的一次性安装和懒加载引导安装已经会选择该解码器。

许可证¶

上游模型卡将 TTS 模型和音频编解码器均标识为 Apache-2.0。VoiceStudio 将它们记录为独立组件；其完整条款尚未审核，因此使用前请接受所显示的模型许可声明。请参阅上游 README。

MOSS-TTS-v1.5 在专用的 sidecar venv 中运行（它固定使用 transformers==5.0，与父环境的 transformers>=5.3 冲突）。关于这为什么会增加磁盘占用，以及 uv 如何降低成本，请参阅 引擎 venv 与磁盘占用。