当我们在公司机房或者隔离研发网中执行 from_pretrained 加载权重时，经常会遇到 ConnectionError: Could not reach Hugging Face Hub。这个报错并不是模型文件损坏，而是 Hugging Face 的 Python 客户端在尝试访问 huggingface.co 的接口时被网络层拦截。企业安全策略通常只允许流量经过指定的代理服务器出站，而默认情况下的客户端并不会读取系统代理，于是连接直接被重置。
要理解这个问题，得先看清 Hugging Face Hub 库的网络行为。它在底层使用 requests 或 huggingface_hub 自带的 HTTP 会话去拉取模型索引和二进制分片。如果环境中存在 HTTP_PROXY 与 HTTPS_PROXY 变量，新版本的库会自动继承；但老版本或者部分离线打包环境会忽略它们。此时即便你能在浏览器里通过代理打开官网，Python 进程依然连不上。
另一个容易被忽视的点是 DNS。内网往往没有对 huggingface.co 的解析记录，客户端在建立 TCP 连接前就失败了。这种情况下单纯设代理不够，还要确认代理服务器本身具备对外递归查询能力，或者在 /etc/hosts 中临时指向代理网关。只有连通性与命名解析同时解决，ConnectionError 才会消失。
企业内网代理的正确设置方式
最稳妥的做法是在启动 Python 任务前导出标准代理变量。下面这段 Shell 配置适用于 Linux 与 macOS 的 CI 节点，Windows 可在系统属性里等价设置。注意代理地址必须是内网运维提供的合法出口，且支持 CONNECT 隧道以转发 HTTPS。
export HTTP_PROXY=http://proxy.ipipp.com:8080 export HTTPS_PROXY=http://proxy.ipipp.com:8080 export NO_PROXY=localhost,127.0.0.1,192.168.0.1
在代码层面，如果你使用的 huggingface_hub 版本低于 0.10，需要显式传入 proxies 参数。示例如下，我们把代理字典交给 hf_hub_download，确保每一次分片请求都走内网代理而不是直连。
from huggingface_hub import hf_hub_download
proxies = {
"http": "http://proxy.ipipp.com:8080",
"https": "http://proxy.ipipp.com:8080"
}
path = hf_hub_download(
repo_id="bert-base-uncased",
filename="pytorch_model.bin",
proxies=proxies
)
print(path)
透明代理是另一种思路。运维可以在网关做重定向，让所有出站 443 流量无声经过过滤层，应用代码无需任何改动。这种方案对算法工程师最友好，但要求网络团队配合，且要防范代理证书被客户端证书校验拒绝。若使用自签 CA，记得用 REQUESTS_CA_BUNDLE 指定信任链，否则仍会报 SSL 错误而非 ConnectionError。
离线模式与本地缓存同步策略
当代理也无法申请开通时，只能切到离线模式。Hugging Face 提供了 HF_HUB_OFFLINE 环境变量，设为 1 后客户端不再发起任何网络请求，只从本地缓存目录 ~/.cache/huggingface 读取。前提是这台机器之前在有网环境把模型完整拖过一次。
export HF_HUB_OFFLINE=1 export TRANSFORMERS_OFFLINE=1
为了把模型合法搬进内网，我们通常在跳板机执行 snapshot_download 后，用移动介质或单向传输工具拷贝整个仓库文件夹。下面代码演示如何把模型及其分词器快照存到指定路径，方便后续归档。
from huggingface_hub import snapshot_download
local_dir = "/data/models/bert-base-uncased"
snapshot_download(
repo_id="bert-base-uncased",
local_dir=local_dir,
local_dir_use_symlinks=False
)
离线模式虽彻底隔绝外联，却带来版本僵化问题。当上游修复了 tokenizer 的缺陷，内网无法感知。建议建立内部模型 registry，记录快照的 commit hash，并定期在受控窗口做增量同步。这样既满足合规，又不至于技术债务累积。
常见误区与排错清单
不少人看到 ConnectionError 就盲目重试，甚至调高 retry 次数，这纯属浪费时间。先抓包确认是 TCP 超时还是 TLS 拒绝，再用 curl -v https://huggingface.co 走同样代理验证。如果 curl 成功而 Python 失败，基本是库没读环境变量。
还有人误把 offline 模式当成免配置神器，却在容器里忘了挂载缓存卷，导致每次启动都是空目录，离线加载直接报文件不存在。正确做法是在 Dockerfile 里把 /root/.cache/huggingface 声明为命名卷，并在部署编排中固定挂载。
最后注意，部分企业代理会限制单连接时长，大模型分片可能下到一半被掐断。此时应在客户端侧启用断点续传，或改用 git lfs 克隆后再离线导入。把上述代理、离线、排错三点串起来，就能系统性消灭 ConnectionError: Could not reach Hugging Face Hub。
Hugging_Face_Hub企业内网代理离线模式修改时间：2026-08-14 11:06:28