VoiceStudio 接入 dots.tts2B 全连续自回归语音克隆引擎的隔离安装、零样本克隆与 sidecar 实战指南【免费下载链接】VoiceStudioVoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription audiobook creation in 646 languages.项目地址: https://gitcode.com/GitHub_Trending/om/VoiceStudiodots.ttsrednote-hilab是一个 2B 参数、全连续fully-continuous自回归 TTS 模型被公认为开源零样本语音克隆领域的最强模型之一支持 24 种语言、输出 48 kHz 音频并以 Apache-2.0 协议开源代码与权重。由于上游将transformers锁定在4.57.0与 VoiceStudio 主进程的transformers5.3无法共存因此 VoiceStudio 将其作为可选opt-in引擎运行在独立子进程与独立 Python 虚拟环境中。读完本文你将掌握在 Linux/macOS 上手动安装与一键安装 dots.tts 的完整流程、venv 探测优先级、环境变量调优、零样本/延续克隆的最佳实践以及底层 sidecar 通信协议与常见故障排查方法。引擎概览为什么 dots.tts 值得单独一个 venvdots.tts 的核心特性如下模型规模2B 参数全连续自回归架构语言覆盖24 种语言支持自动语言检测输出规格48 kHz 采样率由 checkpoint 的vocoder.sample_rate决定许可协议Apache-2.0代码与 checkpoint 均为开源克隆能力零样本语音克隆被广泛引述为开源最强梯队。dots.tts 无法直接跑在 VoiceStudio 主环境中根源是依赖冲突。上游在constraints/recommended.txt中锁定了transformers4.57.0而 VoiceStudio 主进程要求transformers5.3——同一个解释器里不可能同时存在这两个版本。因此 VoiceStudio 采用与 IndexTTS-2、MOSS-TTS-v1.5 相同的隔离原语独立的 subprocess 独立的 venv。这一点在 backend/engines/dots_tts/init.py 的模块文档字符串中有明确说明。需要特别强调的是dots.tts 是显式选择、绝非默认。你需要在Model Catalogue模型目录中显式勾选或设置环境变量OMNIVOICE_TTS_BACKENDdots-tts它不包含在默认安装中。平台支持与硬件前提dots.tts 上游包只声明了 Linux 和 macOS 平台分类器没有任何 Windows 安装路径Linux / macOS only在 Windows 上引擎会在 Model Catalogue 中以明确原因报告自身不可用。若你使用 Windows请在 WSL2 下运行 VoiceStudio或改用 Linux/macOS 主机。is_available()的判定逻辑位于 backend/engines/dots_tts/init.py在win32平台上直接返回False并附上提示文案。无 MPS上游运行时runtime.py的设备选择只有 CUDA 或 CPU 两条分支没有 Metal 分支。因此在 Apple Silicon 上官方包只能在CPU上运行正确但慢。更快的 Apple Silicon 路径仅存在于社区 MLX 移植版本中VoiceStudio 不会自动接入。VRAMcheckpoint 约 9 GB实际目标硬件建议12–16 GB 的 CUDA GPU。上述平台与硬件约束在 tests/test_dots_tts.py 中有对应测试test_gpu_compat_cuda_cpu_no_mps断言gpu_compat (cuda, cpu)test_windows_is_gated_off断言 Windows 上is_available()必须干净地拒绝并提及 Windows。一键安装Linux / macOS在 Linux 和 macOS 上Model Catalogue → dots.tts → Install会为你自动完成以下步骤安装到 VoiceStudio 数据目录下自己的文件夹中自带独立 Python 环境不触碰 VoiceStudio 本身或任何其他引擎——你可以随时切换回来不会破坏已可用的配置同一行的Uninstall只删除该引擎自己的文件夹Windows 上不提供该入口上游没有 Windows 安装包约 9 GB 的 checkpoint 仍在首次合成时才下载。首次合成会下载权重在慢速网络下耗时较长。生成任务会在下载推进期间保持存活若下载停滞导致超时请在Settings → Performance Device中调高 compute-time budget计算时长预算后重试。手动安装逐步骤dots.tts不随 VoiceStudio 捆绑原因checkpoint 体积大 transformers版本冲突。手动安装流程如下第 1 步克隆上游仓库到本地磁盘git clone https://github.com/rednote-hilab/dots.tts.git第 2 步在全新 venv 中按上游约束安装 editable 包使用uv pip install -e . -c constraints/recommended.txt。千万不要使用uv sync --all-extras——那会以transformers4.57覆盖 VoiceStudio 的 lock 文件从而破坏主进程cd dots.tts uv venv .venv uv pip install -e . -c constraints/recommended.txt第 3 步首次合成时下载 checkpoint约 9 GB 的权重在首次 synthesize 时从 HuggingFace 下载。主进程会把HF_HOME/HF_HUB_CACHE转发给 sidecar使缓存与 VoiceStudio 其他下载共享。第 4 步设置OMNIVOICE_DOTS_TTS_DIR环境变量指向克隆仓库根目录即包含pyproject.toml与constraints/的目录# macOS / Linux echo export OMNIVOICE_DOTS_TTS_DIR$HOME/code/dots.tts ~/.zshrc source ~/.zshrc第 5 步重启 VoiceStudio重启后dots.tts 会出现在Model Catalogue中状态为available: true、isolation_mode: subprocess。手动安装方式在 backend/engines/dots_tts/init.py 的DotsTTSBackend类文档字符串中亦有完整示例is_available()未检测到 venv 时返回的提示信息会包含OMNIVOICE_DOTS_TTS_DIR与指向本文档的指引见 tests/test_dots_tts.py 的test_is_available_not_installed_is_honest。Venv 解析顺序三阶段探测与懒加载VoiceStudio 按以下优先级探测可用的 dots.tts Python 解释器完整实现见 backend/engines/dots_tts/bootstrap.py${OMNIVOICE_DOTS_TTS_DIR}/.venv/—— 你已有克隆的 venv老用户的既有安装优先零迁移成本backend/engines/dots_tts/.venv/—— VoiceStudio 自有的 venv由第 3 步按需创建懒加载 bootstrap——uv venv然后uv pip install -e clone -c clone/constraints/recommended.txt。此路径要求设置OMNIVOICE_DOTS_TTS_DIR。探测实现中有几个值得注意的工程细节三态探测_venv_can_import_dots每个候选 venv 会 spawn 解释器执行import dots_tts.runtime结果分为yes / no / unproven。探测超时只证明来不及验证不证明不可用——处理该情况时优先采用已存在但未验证的候选见 issue #1414 的注释而不是误判引擎缺失后重复重装结果缓存首次成功后记忆化测试通过invalidate()清除缓存安全姿态bootstrap 从不触碰HF_TOKENsidecar 的 stderr 由父进程的HFTokenRedactor脱敏editable 安装来自用户自己信任的克隆跨卷安装_uv_env()会将 uv 缓存定位到与 venv 同卷的位置如 D 盘/便携安装场景避免 uv 在系统盘暂存所有 wheel 后发生跨卷复制bootstrap 超时uv venv120 秒、uv pip install1800 秒失败时抛出带 stderr 内容的RuntimeError并指引阅读本文档。is_dots_tts_installed()是一个轻量的文件存在性检查不 spawn 解释器用于 Model Catalogue 的可用性展示。底层机制sidecar 通信协议与隔离设计dots.tts 的 sidecar 入口是 backend/engines/dots_tts/main.py。它在 import 阶段只依赖标准库dots_tts与 torch 均在首次 synthesize 时懒加载这样ready帧能挤进父进程 30 秒的 spawn 握手窗口即使在冷文件系统上也一样。线协议长度前缀 JSON与 backend/services/subprocess_backend.py 字节级一致[ 4 字节大端 uint32 长度 ][ N 字节 UTF-8 JSON ]操作流程sidecar → 父进程{op: ready, engine: dots-tts, sample_rate: 48000}父进程 → sidecar{op: ping}→{op: pong, vram_mb: N}VRAM 测量见_measure_vram_mbCPU 上返回 0永不抛异常父进程 → sidecar{op: synthesize, text: ..., ref_audio: /path/ref.wav, ref_text: transcript, language: EN, num_steps: 10, guidance_scale: 1.2}→ 冷加载时先发{op: progress, ...}随后{op: audio, audio_pcm_b64: ..., sample_rate: 48000, n_samples: N}父进程 → sidecar{op: shutdown}→ 退出码 0关键实现细节帧大小上限MAX_FRAME_BYTES 64 * 1024 * 1024与父进程一致防止超长帧攻击stdout 污染防护sidecar 加载的库wetextprocessing 的 FST 日志、tqdm 进度条、torch/ONNX 的原生打印都会向 fd 1 输出一旦与协议帧交错父进程会把日志文本的 4 个字节误读为长度前缀导致OSError: frame too large且流失步、无法重试。main()先把 fd 1 复制到私有 fd再把 fd 1 重定向到 fd 2从而保证帧通道纯净、库噪音进入父进程日志经过 token 脱敏见 backend/engines/dots_tts/main.py音频下混_tensor_to_pcm_b64沿通道轴argmin(shape)做下混规避了 channels-last 数组沿时间轴取均值导致波形被破坏的问题issue #1328语言归一化_normalize_language将 OmniVoice 的语言值映射为 dots.tts 可接受的格式——2 字母 ISO 码转大写EN/ZH、名字原样传递english、空值/auto 转None表示自动检测模型加载DotsTtsRuntime.from_pretrained(repo, precision..., optimize...)内部自选 CUDA-or-CPU 设备precision 在 CUDA 上默认 bf16CPU 上回退 fp32bf16 的 CPU kernel 支持参差不齐。若 CUDA 可用性探测抛异常则保持 float32 安全默认绝不强推半精度——这一点由 tests/test_dots_tts_accelerator_precision.py 的test_precision_probe_failure_uses_safe_default_or_explicit_override验证。磁盘成本与 uv 去重dots.tts 运行在独立 sidecar venv 中意味着多一份 ML 依赖栈。好消息是dots.tts 锁定torch2.8.0与主进程约束的构建相同因此几乎全部 torch 字节与主 venv 共享只有transformers4.57与模型相关依赖是新增的对比 MOSS-TTS-v1.5 锁定torch2.9.1cu128是不同构建需要完整的多 GB 额外副本。uv 在 macOS/Linux 上使用 reflinkclone 模式、Windows 上使用 hardlink 去重同一 wheel前提是UV_CACHE_DIR与 venv 在同一文件系统上。详细分析见 docs/engines/disk-usage.md。零样本与延续克隆Voice cloning为了获得最佳保真度continuation cloning延续克隆请同时提供参考音频ref_audio与其精确转录文本ref_text。只给参考音频时走的是仅 x-vector 的克隆路径。参考音频建议保持约10 秒。上游要求只要给出了转录文本就必须同时给出参考音频。因此 VoiceStudio 会丢弃只有ref_text、没有ref_audio的孤立转录文本而不是让 sidecar 抛错——这条仲裁逻辑在 backend/engines/dots_tts/init.py 的generate()中实现并有对应测试test_orphan_ref_text_dropped_and_dots_defaults。生成参数的父进程仲裁DotsTTSBackend.generate()会对参数做 dots.tts 专属的默认值仲裁见 backend/engines/dots_tts/init.py参数dots.tts 专属默认说明ref_audio无参考音频路径 →prompt_audio_path零样本克隆ref_text无需伴随ref_audio参考转录 →prompt_text延续克隆languageNone自动检测ISO 码 / 语言名 / 不传num_steps10流匹配步数。OmniVoice 通用默认是 16此处用 dots.tts 自己的默认 10guidance_scale1.2CFG 引导系数。dots.tts 默认 1.2通用默认 2.0 会导致能量过冲参数转发与默认值行为由 tests/test_dots_tts.py 的test_clone_with_transcript_and_overrides、test_orphan_ref_text_dropped_and_dots_defaults覆盖验证。可选环境变量一览变量默认值用途OMNIVOICE_DOTS_TTS_DIR—dots.tts 克隆根目录路径必填OMNIVOICE_DOTS_TTS_MODELrednote-hilab/dots.tts-soarcheckpoint 覆盖-base/-soar/-mfOMNIVOICE_DOTS_TTS_PRECISIONbfloat16CUDA/float32CPU推理精度OMNIVOICE_DOTS_TTS_OPTIMIZE0设为1启用torch.compile首次调用更慢之后更快使用dots.tts-mfMeanFlow 蒸馏checkpoint它针对4步流匹配调优——请传入num_step4。关于精度还有一条重要说明上游运行时内部自行选择 CUDA 或 CPU自动精度跟随该选择——CUDA 上 bf16其余包括在 CPU 上执行的 XPU/NPU/MPS 主机用 float32。OMNIVOICE_DOTS_TTS_PRECISION始终作为显式覆盖生效。若 CUDA 可用性探测抛异常自动精度默认保持 float32设备选择仍由上游负责。这一行为由 tests/test_dots_tts_accelerator_precision.py 的参数化测试test_precision_matches_runtime_device验证。常见错误排查dots.tts is not supported on Windows ...上游仅支持 Linux/macOS。请使用 WSL2或改用 Linux/macOS 主机。dots.tts venv not found. Set OMNIVOICE_DOTS_TTS_DIR ...你还没有把 VoiceStudio 指向 dots.tts 克隆。请按上文手动安装完成第 1、4、5 步克隆仓库、设置OMNIVOICE_DOTS_TTS_DIR指向包含pyproject.toml的目录、重启 VoiceStudio。uv is required to bootstrap the dots.tts venv ...懒加载 bootstrap 依赖uv可执行文件。将其加入PATH或设置OMNIVOICE_BUNDLED_UV指向 uv 二进制文件的绝对路径后重新启动 VoiceStudio。许可与文档延伸dots.tts 以Apache-2.0开源代码与 checkpoint 均为如此具体以上游 README 为准。关于 sidecar venv 为什么增加磁盘占用、uv 如何控制成本详见 Engine venvs disk usage相同的隔离模式也用于 IndexTTS-2 与 MOSS-TTS-v1.5若想深入源码探测与懒加载逻辑在 backend/engines/dots_tts/bootstrap.pysidecar 入口在 backend/engines/dots_tts/main.py父进程仲裁在 backend/engines/dots_tts/init.py配套测试见 tests/test_dots_tts.py 与 tests/test_dots_tts_accelerator_precision.py。【免费下载链接】VoiceStudioVoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription audiobook creation in 646 languages.项目地址: https://gitcode.com/GitHub_Trending/om/VoiceStudio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考