ChatTTS x OpenVoice安装模型下载失败？一招搞定

原创于 2025-12-10 22:12:46 发布 · 568 阅读

CC 4.0 BY-SA版权

文章标签：

ChatTTS x OpenVoice安装模型下载失败？一招搞定

在AI语音领域，ChatTTS的自然对话语音生成能力与OpenVoice的多语言、多风格语音克隆功能相结合，能实现诸多有趣的应用场景。但很多朋友在安装配置这两个工具时，都会卡在“模型下载失败”这一步——要么是下载速度趋近于零，要么是直接提示连接超时、无法访问资源。其实核心原因很简单：这两个工具的核心模型都托管在Hugging Face上，而国内直接访问Hugging Face时常存在网络不稳定的问题。今天就给大家分享一套万能解决方案：通过设置Hugging Face镜像站，轻松解决模型下载难题。
请添加图片描述

一、问题前置：先搞懂为啥会下载失败？

在动手设置之前，我们先明确两个关键信息，避免后续走弯路：

模型托管位置：ChatTTS（如official的ChatTTS模型）、OpenVoice（核心的voice conversion模型、speaker embedding模型等）的核心资源均存储在Hugging Face Hub上，安装时工具会自动从该平台拉取模型文件。
核心问题：Hugging Face的服务器位于海外，国内网络访问时会受到跨境网络波动、带宽限制等影响，导致TCP连接建立失败、下载超时，甚至直接被墙。

这里要区分一个误区：不是“工具本身有问题”，也不是“你的网络完全不能用”，而是“海外资源访问链路不稳定”。因此，解决思路就是“换一条更稳定的访问链路”——也就是借助国内的Hugging Face镜像站。

二、核心方案：选择靠谱的Hugging Face镜像站

国内有多个优质的Hugging Face镜像站，它们会同步Hugging Face Hub上的大部分公开模型资源，我们只需将工具的下载源指向这些镜像站，就能实现高速下载。目前比较稳定、常用的镜像站有以下几个（优先推荐前两个）：

阿里云镜像站：https://www.modelscope.cn/hub（不仅同步Hugging Face模型，还支持中文检索，兼容性极佳）
清华云镜像站：https://mirrors.tuna.tsinghua.edu.cn/hugging-face-models/（学术机构维护，同步及时，速度稳定）
字节跳动镜像站：https://hf-mirror.com/（专门针对Hugging Face的镜像，支持直接替换原链接）

提示：建议优先使用阿里云或清华云镜像站，因为它们不仅支持模型下载，还能兼容大部分基于Hugging Face Transformers库的工具（ChatTTS和OpenVoice均基于此库）。

三、分场景设置：覆盖Windows/Mac/Linux，适配不同安装方式

无论是通过Python代码手动安装，还是使用官方提供的一键启动脚本，核心设置逻辑都是“修改Hugging Face的默认下载源”。下面分系统、分场景给大家详细讲解操作步骤，新手也能轻松跟着做。

场景1：通用设置——通过环境变量指定镜像站（推荐，所有系统适用）

这种方法是最推荐的，因为它能全局生效（无论是ChatTTS、OpenVoice，还是其他基于Hugging Face的工具，都会自动使用镜像站下载）。核心原理是设置TRANSFORMERS_OFFLINE（可选，关闭在线检查）和HUGGINGFACE_HUB_CACHE（指定模型缓存路径），以及关键的HUGGINGFACE_HUB_ENDPOINT（指定镜像站地址）。

1.1 Windows系统设置环境变量

打开环境变量设置界面：按下Win + R，输入sysdm.cpl，回车；在弹出的“系统属性”窗口中，切换到“高级”选项卡，点击右下角的“环境变量”。
新建系统环境变量（针对所有用户，也可新建用户环境变量仅针对当前用户）：
变量名：HUGGINGFACE_HUB_ENDPOINT，变量值：https://www.modelscope.cn/api/v1/models（阿里云镜像站，推荐）或https://mirrors.tuna.tsinghua.edu.cn/hugging-face-models（清华云镜像站）
（可选）变量名：HUGGINGFACE_HUB_CACHE，变量值：自定义模型缓存路径（如D:\AI\Models\HuggingFace），避免默认存储在C盘占用空间
（可选）变量名：TRANSFORMERS_OFFLINE，变量值：1，开启离线模式（仅在已下载模型后使用，避免重复检查网络）
生效环境变量：设置完成后，关闭所有已打开的命令行窗口（CMD、PowerShell）和IDE（如PyCharm、VS Code），重新打开即可生效。

1.2 Mac/Linux系统设置环境变量

Mac和Linux系统操作类似，可通过临时设置（仅当前终端生效）或永久设置（所有终端生效）两种方式：

临时设置（快速测试，重启终端失效）：
打开终端，输入以下命令（二选一，推荐阿里云）：`# 阿里云镜像站
export HUGGINGFACE_HUB_ENDPOINT=https://www.modelscope.cn/api/v1/models

清华云镜像站（备选）

export HUGGINGFACE_HUB_ENDPOINT=https://mirrors.tuna.tsinghua.edu.cn/hugging-face-models

（可选）设置模型缓存路径

export HUGGINGFACE_HUB_CACHE=/Users/yourname/AI/Models/HuggingFace`

永久设置（一劳永逸）：
根据你的终端类型（bash或zsh），修改对应的配置文件：bash终端：编辑~/.bashrc文件
zsh终端（Mac默认）：编辑~/.zshrc文件

场景2：针对性设置——手动指定模型下载链接（适配部分特殊脚本）

有些ChatTTS或OpenVoice的第三方优化版本，可能在代码中硬编码了模型下载链接（直接指向Hugging Face官方地址），此时仅设置环境变量可能无效，需要手动修改代码中的模型路径。

找到代码中模型加载的关键行：
通常在load_model()、from_pretrained()等函数中，比如：`# 原代码（指向Hugging Face官方）
model = AutoModel.from_pretrained(“2Noise/ChatTTS”)

或OpenVoice的模型加载

voice_model = load_model(“microsoft/OpenVoice”)`

替换为镜像站链接：
以阿里云镜像站为例，只需在原模型名前加上镜像站前缀https://www.modelscope.cn/models/，修改后如下：`# 修改后（指向阿里云镜像站）
model = AutoModel.from_pretrained(“https://www.modelscope.cn/models/2Noise/ChatTTS”)

OpenVoice模型同理

voice_model = load_model(“https://www.modelscope.cn/models/microsoft/OpenVoice”)`

注意事项：如果镜像站中没有完全同步该模型（极少数情况），可更换其他镜像站链接（如清华云），或直接在镜像站搜索模型名，确认是否存在后再替换。

场景3：手动下载模型——适合极端网络环境

如果上述两种方法都无法生效（比如镜像站暂时维护），可直接手动从镜像站下载模型文件，再放到工具的默认缓存路径中，实现“离线加载”：

查找模型的镜像站地址：
以ChatTTS的2Noise/ChatTTS模型为例，在阿里云镜像站搜索“2Noise/ChatTTS”，进入模型详情页，点击“下载”按钮，获取完整的模型文件（通常是多个bin、json、config文件）。
下载模型文件：将所有模型相关文件下载到本地，按原目录结构整理（不要修改文件名和文件夹结构）。
放置到缓存路径：
默认缓存路径：Windows通常是C:\Users\你的用户名\.cache\huggingface\hub，Mac/Linux是~/.cache/huggingface/hub
自定义缓存路径：如果之前设置了HUGGINGFACE_HUB_CACHE，就放到该路径下的对应模型文件夹中（如D:\AI\Models\HuggingFace\models--2Noise--ChatTTS\snapshots\xxx）
重启工具：放置完成后，重新运行ChatTTS或OpenVoice，工具会自动从本地缓存加载模型，无需再联网下载。

四、验证设置：如何确认镜像站已生效？

设置完成后，我们可以通过简单的操作验证是否生效，避免白忙活：

通过命令行测试（推荐）：
打开终端（CMD/PowerShell/Mac终端），输入以下Python代码（需提前安装huggingface-hub库：pip install huggingface-hub）：`from huggingface_hub import get_hf_endpoint

查看当前使用的镜像站地址

print(“当前Hugging Face镜像站地址：”, get_hf_endpoint())`如果输出的是你设置的镜像站地址（如阿里云、清华云），说明设置生效。

实际下载测试：运行ChatTTS或OpenVoice的模型加载代码，如果下载速度从之前的几KB/s变成几十MB/s，且没有出现超时错误，就说明成功了。

五、常见问题排查（避坑指南）

设置后仍下载失败？
检查环境变量是否生效：关闭所有终端和IDE，重新打开再测试（最常见的问题）。
更换镜像站：可能当前镜像站暂时不稳定，切换到另一个镜像站（如从阿里云换成清华云）再试。
检查网络连接：确保本地网络正常，可尝试ping镜像站地址，确认网络通畅。
模型下载一半中断？
Hugging Face Hub会自动断点续传，重新运行下载命令即可继续下载，无需从头开始。
如果多次中断，建议手动下载模型文件（场景3的方法），避免网络波动影响。
镜像站中找不到目标模型？
确认模型名是否正确：有些模型可能有不同的别名，建议在Hugging Face官方站确认准确的模型ID。
等待镜像站同步：新发布的模型可能需要1-2天时间同步到国内镜像站，可过段时间再试。

六、总结

ChatTTS和OpenVoice的模型下载失败问题，本质上是跨境网络访问的问题，通过设置国内Hugging Face镜像站就能完美解决。优先推荐“环境变量全局设置”的方法，一劳永逸；如果遇到特殊脚本，可手动修改模型链接；极端情况则直接手动下载模型。按照本文的步骤操作，绝大多数朋友都能顺利完成模型安装，开启AI语音创作的乐趣。

如果大家在操作过程中遇到其他问题，或者有更优质的镜像站推荐，欢迎在评论区留言交流～