引擎虚拟环境与磁盘占用¶

Model Catalogue 现在会在安装前提供结构化的磁盘占用明细：模型权重下载、软件包下载、唯一安装字节、潜在共享字节、临时空闲空间需求、目标卷，以及估算置信度。缺失的软件包或去重测量值会显示为“未知”而不是“零”。打开已安装引擎的磁盘详情时，会分别测量其模型、环境、共享缓存，以及应用自有总量。这些值来自 config/models.yaml 和 sidecar 安装器规范；UI 不维护自己的大小表。

大多数引擎在 VoiceStudio 的主环境中以进程内方式运行。少数引擎（IndexTTS2、MOSS-TTS-v1.5、dots.tts，以及任何依赖项与主环境的 torch/transformers 固定版本冲突的引擎）在专用的 sidecar 虚拟环境中运行，这样它们的固定版本就不会破坏应用的其余部分。这些 sidecar 正是磁盘占用累积之处——本页将解释原因，以及如何控制磁盘上的成本。

为什么 sidecar 需要自己的虚拟环境¶

IndexTTS2 固定 transformers<5，而 VoiceStudio 要求 transformers>=5.3。你无法在同一个环境中同时满足两者，因此 IndexTTS2 在首次使用时会被创建独立的虚拟环境（uv venv + uv pip install，参见 backend/engines/indextts/bootstrap.py）。代价是重型 ML 技术栈的第二份副本——其中大部分是 torch + 捆绑的 CUDA 库。

“第二个 torch”有多大？¶

测量时间（2026-06）：

因此，如果 sidecar 固定的 torch 版本与主环境不同，就会产生数 GB 的额外开销。如果 sidecar 固定相同的 torch + CUDA 构建，则几乎可以共享所有这些内容（见下文）。

uv 对相同 wheel 去重——免费，但有一个条件¶

uv 通过从全局 wheel 缓存链接到每个虚拟环境的 site-packages 来安装包。链接模式：

• macOS + Linux — clone（写时复制 reflink）。安装了相同 wheel 的 N 个虚拟环境会共享这些字节，直到其中一个被修改——实际上磁盘上只有一份副本。
• Windows — hardlink。在单个卷上效果相同。

唯一条件：缓存和虚拟环境必须位于同一文件系统上。如果 UV_CACHE_DIR 与引擎虚拟环境位于不同的驱动器上，uv 会退化为完整复制（不去重，更慢）。请将它们放在一起。

去重是按每个相同的 wheel进行的。torch==2.6.0+cu124 和 torch==2.8.0+cu128 是不同的 wheel → 零共享 → 需要额外一份完整的数 GB 副本。因此，对 sidecar 而言，最大的磁盘决策是：只要引擎允许，就固定与主环境相同的 torch 构建。当引擎不允许时（IndexTTS2 的 transformers<5 迫使使用更旧的 torch 系列），这第二份副本就是隔离不可避免的代价——而不是缺陷。

可选加入的 #498 引擎展示了这两种情况：dots.tts 固定 torch==2.8.0——与主环境约束的相同构建——因此它与主虚拟环境共享几乎全部 torch，只有它的 transformers==4.57 和模型依赖是新增的。MOSS-TTS-v1.5 固定 torch==2.9.1+cu128，这是一个不同的构建，因此在 CUDA 主机上需要额外支付一份完整的数 GB torch 副本（这是运行一个技术栈固定 transformers==5.0 的 8B 模型的代价）。

在 Linux 上，nvidia-* CUDA 包是独立的 wheel，因此即使是不同的 torch 版本，任何固定版本恰好匹配的 nvidia-* 仍然会被共享。在 Windows 上，CUDA DLL 位于 torch wheel 内部，因此跨 torch 版本时没有任何内容会被共享。

实用指南¶

• 将 UV_CACHE_DIR 和引擎虚拟环境放在同一文件系统上（默认情况下——两者都在你的主目录下——已经满足此要求）。应用会自动强制这一点：当应用环境或引擎虚拟环境位于与 uv 默认缓存不同的卷上（例如安装到 D: 盘、便携模式）时，每次受管理的 uv 调用都会将 UV_CACHE_DIR 指向虚拟环境旁边的缓存（<env root>/uv-cache、<data dir>/engines/.uv-cache）。你自己显式设置的 UV_CACHE_DIR 始终优先。
• 在 Linux ext4（无 reflink）上，export UV_LINK_MODE=hardlink 可保证在任意单个文件系统上去重；默认的 clone 只在支持 reflink 的文件系统（带 reflink 的 XFS、btrfs、APFS）上去重。
• 回收空间：删除 sidecar 虚拟环境（backend/engines/<id>/.venv/）会释放其独有文件；共享缓存字节会一直保留到执行 uv cache prune。
• 展望未来：PyTorch 的实验性 wheel 变体（随 2.8 发布）最终将让 uv install torch 自动选择正确的 CUDA 构建，而 uv 已经提供了 --torch-backend=auto。