现象:模型名没错,卡在下载这一步
代码里写 AutoModel.from_pretrained("bert-base-chinese"),运行后抛出一长串 OSError,关键信息是 We couldn't connect to 'https://huggingface.co' to load this file,后面还带着 Max retries exceeded 或 Connection timed out。同样一行代码在别人的机器上能直接跑通。
原因:请求根本没有到达模型仓库
- 网络不可达。域名解析被污染或链路被限制,握手阶段就超时,报错里通常是 Read timed out。
- 代理只配给了浏览器。终端和 Python 进程没有继承
HTTPS_PROXY,命令行里 curl 能通、脚本里却不行。 - 生产环境是离线机器。没有外网出口,但代码每次启动都去拉一次配置。
- 缺少访问凭证。私有模型或限流仓库需要 token,未登录时返回的是 401,包装后看起来像连接失败。
解决步骤
第一步,先把下载链路单独跑通,排除模型代码本身的问题:
curl -I https://huggingface.co
huggingface-cli download bert-base-chinese
第二步,切换镜像地址,国内环境这是最有效的一步,镜像站点同步了主流模型:
export HF_ENDPOINT=https://hf-mirror.com
export HF_HOME=/data/hf_cache
设置后重新执行下载,缓存会落到 HF_HOME 指定的目录,后续加载不再重复请求。
第三步,需要代理时显式传给进程,只设浏览器的代理对 Python 无效:
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
第四步,离线环境改成只读本地文件,把模型目录整个拷过去,加载时禁止联网检查,否则启动仍然会卡住:
model = AutoModel.from_pretrained(
"/models/bert-base-chinese",
local_files_only=True,
)
第五步,私有仓库补 token。用 huggingface-cli login 写入凭证,或者设置 HF_TOKEN 环境变量,注意不要把它提交到代码仓库。
小结
这类报错本质是"下载失败",不是模型不兼容。先确认终端能连通,再设镜像或代理,最后用 local_files_only 固化离线路径,启动才稳定。
建议把镜像地址和缓存目录写进项目文档或启动脚本,而不是留在某个人的终端历史里,团队换机器时能少踩一遍。
