下载模型 — 速度与故障排查¶

VoiceStudio 在首次使用时从 Hugging Face Hub 下载模型。本页说明如何加快下载速度、如何读取进度，以及在网络缓慢或受限时该怎么做。

未知或用户管理的缓存布局也被允许通过，因此现有的手动引擎安装仍然兼容。

下载后端：默认使用传统 LFS（精确进度）¶

VoiceStudio 随附 hf_xet（Hugging Face 的分块、并行、去重传输后端——即 IDM/uGet 式的高速路径），但目前实际运行于 Xet 禁用状态（由应用设置的 HF_HUB_DISABLE_XET=1）。原因：Xet 的传输进度在带外报告，绕过了字节级进度挂钩，因此下载界面无法显示真实的字节数/速度。在正式的 Xet 进度挂钩落地之前，应用会强制走经典 LFS 路径，该路径通过标准进度报告器进行流式传输，并提供准确的已下载/剩余/速度信息。

为了让 Xet 关闭时该路径仍然快速，应用默认启用内置的多连接（分段）下载器。它最多同时保持八个字节范围在途，将每个范围上限设为 16 MB，并将每个已完成范围记录在恢复清单中。连接断开后，只会重新获取未完成的范围：安装过程会重试加速器并恢复该清单。不支持范围请求的源站会在加速器中保持单流。非暂时性故障或最后一次尝试会导致该次安装的其余部分禁用加速，并让普通的 snapshot_download 接管。添加免费的 Hugging Face token（首次运行设置或“设置 → 凭据”）可以进一步提升速度——经过身份验证的下载可获得更高的速率限制和更少的停顿。要强制使用旧的单流路径，请设置 OMNIVOICE_SEGMENTED_DOWNLOAD=0。

状态在 设置 → 关于 / GET /system/info 中报告：

• fast_download.xet_installed — hf_xet 存在（true）
• fast_download.xet_active — Xet 是否实际驱动下载（默认为 false，因为 HF_HUB_DISABLE_XET）
• 仅当 Xet 处于 active 状态时，GET /system/info 才报告 fast_download.xet_enabled。

后端在启动时记录一行日志，例如： downloads: Xet disabled → legacy LFS (hf_xet 1.4.2 installed=True).

重新启用 Xet（高级，可选加入）¶

想要 Xet 的速度且不介意更粗略进度的高级用户，可以设置 HF_HUB_DISABLE_XET=0。Xet 启用后，总进度条按文件推进，并在完成时跳到精确总量（不显示逐文件的字节速度——这正是它默认关闭的原因）。Xet 需要 64 位操作系统（所有受支持的 VoiceStudio 平台均满足）。

读取进度¶

下载开始时，你会按顺序看到：

1. 解析中（Resolving） — 应用获取文件列表并计算精确计划：总大小、已缓存多少，以及实际将下载多少（在字节开始移动前显示）。
2. 下载中（Downloading） — 一个总进度条，包含文件数量（例如 3/7 files）、总大小，以及在报告逐字节进度的网络上的实时速度和预计剩余时间（ETA）。
3. 完成（Done） — 进度条在真实总大小处到达 100%。

注意：精确总量以及“已缓存 / 待下载”的拆分在开始时即可获知（预检解析），因此剩余量从一开始就是准确的。当某个文件大到足以在数秒内流式传输时，实时逐字节速度才会出现；非常小/快的文件可能直接跳到完成。进度条在完成时总是落在精确总量上。（如果重新启用 Xet，进度将变为按文件粒度——见上文。）

高级 / 可选优化¶

这些设置在所有平台上的作用相同。将它们设置为环境变量（或通过设置 → API 密钥 / 环境）。分段加速器默认开启（将其变量设为 0 可禁用）；其余默认关闭。

受限网络 / 镜像（例如中国）¶

自动（默认）。 当未显式配置端点时，VoiceStudio 会为你选择一个：它会并行探测 huggingface.co 和社区镜像 hf-mirror.com（简短的 HTTPS 可达性 + 延迟检查——不进行地理位置 IP 查询，也不使用第三方服务；你的设备语言/时区仅决定哪个端点被最先探测），除非镜像明显更快，否则优先使用官方端点，并记住胜出者。该决定只在首次运行系统检查、发生网络类下载失败（失败的下载会在新的胜出端点上重试一次）、上次检查超过 7 天，或在 设置 → 模型 → Hugging Face 镜像中点击重新测试时才会重新评估。镜像完整性不是问题：huggingface_hub 无论使用哪个端点，都会通过校验和对每次下载进行验证。通过 OMNIVOICE_HF_ENDPOINT_MODE=manual 选择退出。

显式指定（始终优先）。 要自行固定端点：

HF_ENDPOINT=https://hf-mirror.com

在 设置 → 模型 → Hugging Face 镜像中设置（快速选择预设和自定义 URL——任何显式选择都会将面板切换到手动模式，并且不会被自动切换），或在启动前作为环境变量设置。首次运行时，安装向导的网络检查会报告自动选择选择了哪个端点，并且在没有任何端点可达时仍提供镜像快速选择——该检查是警告而非阻止项，因此只要模型可用（通过镜像或下面的手动下载），离线或受防火墙限制的机器仍可完成设置。如果向导下载因已配置的镜像不可达而失败，同一快速选择（包括 Hugging Face（官方））会紧挨着失败的那一行出现——切换会立即应用到下载（无需重启；只有已加载的引擎会在启动时重新读取端点），清除重试冷却时间，并立即重试失败的下载。注意事项：

• 镜像提供的是经典下载路径，而非 Xet — 你会失去分块去重和 Xet 的并行获取，但能获得可达性。在经典路径上，逐字节速度/ETA 会持续显示。
• 俄罗斯和某些网络没有官方镜像；请使用 VPN/隧道。
• 自定义镜像 URL 必须使用 https://（纯 http:// 仅对位于 localhost/127.0.0.1 的本地代理接受），并且不得包含用户名、密码、查询参数或片段。
• 你的 Hugging Face 令牌只会发送给 Hugging Face，绝不会发送给镜像 — 包括令牌检查和门控访问检查。因此，门控模型（说话人分离）会从官方端点下载：在 Auto 模式下它们始终如此，即使自动选择选中了镜像；如果你自己选择了镜像，安装将因 HF_MIRROR_GATED 而失败 — 切换到 Hugging Face（官方） 即可安装它们。

取消下载¶

Model Catalogue 中引擎的 Weights 列表让你可以取消正在进行的安装。传输会在下一个数据块处停止（或者如果你在仍处于解析阶段时取消，则会在开始前停止；对于选择加入的 Xet 传输，已在进行的文件可能会先完成），并且该行会显示 cancelling，直到清理完成。清理会移除该下载写入的内容：不完整的 *.incomplete / *.part 文件、已完成的文件以及新的快照条目。在你开始之前就已存在于缓存中的文件（早期版本或其他模型的文件）会被保留，因此模型会恢复到之前的状态。在 Windows 上，仍被打开的文件会先重试几秒钟，之后才会留在原处。取消还会清除失败冷却时间，因此你可以立即重新开始下载。

故障排查¶

• 卡在“Resolving…” — Hub 返回元数据的速度很慢，或者你在没有令牌的情况下被限流。添加一个令牌（参见 docs/setup/huggingface-token.md）然后重试。
• 非常慢 / 停滞 — 尝试镜像（见上文），或使用有线连接。高性能模式只有在 RAM 和带宽充足时才有帮助。
• “download finished but no model weights were found” — 下载被中断，留下了一个不完整的快照。在 Model Catalogue 中删除引擎 Weights 列表中的该模型，然后重新安装。
• 磁盘空间不足 — 目录中会显示模型大小；请释放空间或使用 HF_HOME / HF_HUB_CACHE 更改缓存位置。安装还会在下载完成后在模型磁盘上保留 2 GB 可用空间，因此它需要下载大小再加上 2 GB；Model Catalogue 中的警告会显示这两个数字。