本文介绍解决 HuggingFace 模型下载失败的四种方法，适用于网络连接异常或代理配置问题。

解决 HuggingFace 下载模型时报错：HTTPSConnectionPool(host='huggingface.co', port=443)

在使用 HuggingFace 下载模型或 Tokenizer 时，常常会遇到如下错误：

HTTPSConnectionPool(host='huggingface.co', port=443): Max retries exceeded with url: ...

即使你已正确配置了网络代理，该错误仍可能发生。

例如，执行以下代码时：

python
from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("csebuetnlp/mT5_multilingual_XLSum")

可能会报上述错误。

本文提供 四种解决方法，可根据你的实际环境选择合适方式。

方法一：手动下载模型并使用本地路径加载

你可以在 HuggingFace 模型页面中找到 Files and versions，将相关模型文件全部下载至本地。

下载完成后，使用本地路径加载模型：

python
tokenizer = AutoTokenizer.from_pretrained("本地模型文件夹路径")

这样模型将不会再尝试联网下载，而是直接读取本地文件。

📷 示例图（手动下载模型文件）：

方法二：降级 requests 与 urllib3 版本

如果你希望仍然在线下载，但又不想手动下载全部文件，可以尝试降级以下库的版本：

bash
pip install requests==2.27.1
pip install urllib3==1.25.11

这两个版本被很多用户验证为兼容 HuggingFace 下载流程，能解决连接失败的问题（前提是网络环境已正确设置）。

执行后再次运行下载代码，会看到如下正常的下载输出：

Downloading (…)okenizer_config.json: 100%|██████████| 375/375
Downloading (…)lve/main/config.json: 100%|██████████| 730/730
Downloading spiece.model: 100%|██████████| 4.31M/4.31M
Downloading (…)cial_tokens_map.json: 100%|██████████| 65.0/65.0

方法三：在代码中配置代理环境变量

如果你已配置本地代理服务（如 Clash、Surge 等），可以在代码中直接设置 HTTP 和 HTTPS 代理：

python
import os

os.environ["http_proxy"] = "http://127.0.0.1:33210"
os.environ["https_proxy"] = "http://127.0.0.1:33210"

⚠️ 注意：端口号应与你本地代理软件的实际配置一致。

方法四：检查 IDE 中的代理设置（以 PyCharm 为例）

如果你使用 PyCharm 开发，也可以在 IDE 内设置全局代理，路径如下：

File > Settings > Appearance & Behavior > System Settings > HTTP Proxy

📷 示例图：

小结