Hugging Face 无法访问的解决方案

一、最省事的办法是使用 Hugging Face 国内镜像

国内访问 Hugging Face 时，比较常见的报错有，

复制代码

Connection to huggingface.co timed out
Max retries exceeded with url
Failed to connect to huggingface.co port 443

可以先尝试使用国内镜像，

复制代码

https://hf-mirror.com

在浏览器里，只需要把原网址中的 huggingface.co 替换成 hf-mirror.com。例如，原始地址是，

复制代码

https://huggingface.co/Qwen/Qwen2.5-7B-Instruct

替换后是，

复制代码

https://hf-mirror.com/Qwen/Qwen2.5-7B-Instruct

后面的组织名称、模型名称和文件路径都不需要修改。

如果是在命令行或者 Python 程序里下载模型，可以设置 HF_ENDPOINT 环境变量。Linux 和 macOS 当前终端临时生效，

复制代码

export HF_ENDPOINT=https://hf-mirror.com

Windows CMD 当前窗口临时生效，

复制代码

set HF_ENDPOINT=https://hf-mirror.com

Windows PowerShell 当前窗口临时生效，

复制代码

$env:HF_ENDPOINT = "https://hf-mirror.com"

设置完成后，可以检查环境变量是否正确。Linux 和 macOS，

复制代码

echo $HF_ENDPOINT

Windows PowerShell，

复制代码

echo $env:HF_ENDPOINT

如果输出，

复制代码

https://hf-mirror.com

说明设置已经生效。如果希望 Linux 每次打开终端时都自动使用镜像，可以把配置写入 ~/.bashrc，

复制代码

echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc
source ~/.bashrc

Windows 中可以使用下面的命令永久写入用户环境变量，

复制代码

setx HF_ENDPOINT https://hf-mirror.com

设置完成后，需要重新打开 CMD、PowerShell、VS Code 或 PyCharm。

也可以直接在 Python 代码中设置，

复制代码

import os

os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained(
    "Qwen/Qwen2.5-0.5B-Instruct"
)

完整加载模型时可以这样写，

复制代码

import os

os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"

from transformers import AutoModelForCausalLM
from transformers import AutoTokenizer

model_id = "Qwen/Qwen2.5-0.5B-Instruct"

tokenizer = AutoTokenizer.from_pretrained(model_id)

model = AutoModelForCausalLM.from_pretrained(
    model_id,
    device_map="auto"
)

第一次运行时，模型会被下载到 Hugging Face 的缓存目录，后续运行一般会直接复用本地文件。如果想把模型下载到指定目录，可以先安装新版命令行工具，

复制代码

python -m pip install -U huggingface_hub

然后使用，

复制代码

hf download Qwen/Qwen2.5-0.5B-Instruct \
    --local-dir ./models/Qwen2.5-0.5B-Instruct

Windows PowerShell 可以写成一行，

复制代码

hf download Qwen/Qwen2.5-0.5B-Instruct --local-dir .\models\Qwen2.5-0.5B-Instruct

部分旧教程使用的是，

复制代码

huggingface-cli download

新版本通常更推荐使用，

复制代码

hf download

如果想在 Python 中下载完整仓库，可以使用 snapshot_download，

复制代码

import os

os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"

from huggingface_hub import snapshot_download

snapshot_download(
    repo_id="Qwen/Qwen2.5-0.5B-Instruct",
    local_dir="./models/Qwen2.5-0.5B-Instruct"
)

只下载单个文件时，可以使用 hf_hub_download，

复制代码

import os

os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"

from huggingface_hub import hf_hub_download

file_path = hf_hub_download(
    repo_id="Qwen/Qwen2.5-0.5B-Instruct",
    filename="config.json"
)

print(file_path)

模型下载完成后，可以直接从本地路径加载，

复制代码

from transformers import AutoModelForCausalLM
from transformers import AutoTokenizer

model_path = "./models/Qwen2.5-0.5B-Instruct"

tokenizer = AutoTokenizer.from_pretrained(
    model_path,
    local_files_only=True
)

model = AutoModelForCausalLM.from_pretrained(
    model_path,
    local_files_only=True,
    device_map="auto"
)

local_files_only=True 表示只使用本地文件，不再尝试联网。如果服务器完全无法联网，还可以开启离线模式，

复制代码

export HF_HUB_OFFLINE=1
export HF_DATASETS_OFFLINE=1

Hugging Face 默认会把缓存放在用户目录下。Linux 中常见路径是，

复制代码

~/.cache/huggingface

大模型比较占空间，可以把缓存改到数据盘，

复制代码

export HF_HOME=/data/huggingface

或者只修改模型缓存目录，

复制代码

export HF_HUB_CACHE=/data/huggingface/hub

镜像主要解决的是公开模型的访问和下载问题。如果模型是私有仓库，或者需要申请权限，仍然要先登录 Hugging Face，

复制代码

hf auth login

检查登录状态，

复制代码

hf auth whoami

对于需要接受协议的模型，还要先在 Hugging Face 官方页面申请访问权限。镜像不会绕过模型原有的权限限制。

二、镜像没有对应模型时可以尝试国内平台

如果 Hugging Face 镜像中没有需要的模型，可以尝试 ModelScope。ModelScope 地址是，

复制代码

https://modelscope.cn

安装 ModelScope，

复制代码

python -m pip install -U modelscope

使用 Python 下载模型，

复制代码

from modelscope import snapshot_download

model_dir = snapshot_download(
    "Qwen/Qwen2.5-0.5B-Instruct",
    cache_dir="./modelscope_cache"
)

print(model_dir)

ModelScope 上有不少常用的大语言模型、视觉模型、语音模型和数据集，国内访问速度通常比较稳定。不过，ModelScope 和 Hugging Face 不是完全相同的两个平台。即使模型名称看起来一样，仓库结构、文件版本和更新时间也可能不同。从 ModelScope 下载后，可以检查目录中是否包含，

复制代码

config.json
tokenizer.json
tokenizer_config.json
generation_config.json
model.safetensors

有些模型也可能由多个权重分片组成，

复制代码

model-00001-of-00004.safetensors
model-00002-of-00004.safetensors
model-00003-of-00004.safetensors
model-00004-of-00004.safetensors

如果模型兼容 Transformers，可以尝试直接从本地路径加载，

复制代码

from transformers import AutoModelForCausalLM
from transformers import AutoTokenizer

model_path = "./modelscope_cache/模型目录"

tokenizer = AutoTokenizer.from_pretrained(
    model_path,
    trust_remote_code=True
)

model = AutoModelForCausalLM.from_pretrained(
    model_path,
    trust_remote_code=True,
    device_map="auto"
)

三、常见报错需要根据类型处理

如果报错是连接超时，例如，

复制代码

ConnectTimeoutError
Max retries exceeded with url

可以先检查镜像环境变量，

复制代码

import os

print(os.environ.get("HF_ENDPOINT"))

正常情况下应该输出

复制代码

https://hf-mirror.com

如果输出 None，说明当前 Python 进程没有读取到环境变量。这种情况通常是因为设置环境变量后没有重新打开终端，或者是在一个终端中设置，却在另一个终端或开发工具中运行。在 Jupyter Notebook 中设置环境变量后，最好重启 Kernel。VS Code 和 PyCharm 中设置系统环境变量后，也建议重新启动软件。

如果报错是，

复制代码

401 Unauthorized

一般说明没有登录、Token 无效，或者当前账号没有仓库权限。可以执行，

复制代码

hf auth login

然后检查，

复制代码

hf auth whoami

如果模型需要申请权限，还要先进入官方模型页面接受协议。如果报错是，

复制代码

403 Forbidden

通常说明账号已经登录，但仍然没有访问权限，也可能是镜像不支持该模型的鉴权流程。这种情况不能只靠更换下载地址解决。

如果报错是，

复制代码

429 Too Many Requests

说明短时间内请求太多，被服务端限流。可以减少并发下载，不要反复清除缓存，也不要写无限重试脚本。稍后重新执行相同下载命令即可。

如果报错是，

复制代码

SSL certificate verify failed

可以先升级证书相关包，

复制代码

python -m pip install -U certifi requests urllib3

同时检查系统时间是否正确。如果是在公司或学校网络中使用，也可能是代理服务器替换了 HTTPS 证书。

如果模型下载到一半失败，不要马上删除整个目录。重新执行相同的 hf download 或 snapshot_download 命令，通常可以复用已经下载完成的文件。例如，

复制代码

hf download Qwen/Qwen2.5-7B-Instruct \
    --local-dir ./models/Qwen2.5-7B-Instruct

如果本地已经有模型，但程序仍然访问网络，应该把 from_pretrained() 的参数改成本地路径，并设置，

复制代码

local_files_only=True

例如，

复制代码

tokenizer = AutoTokenizer.from_pretrained(
    "./models/Qwen2.5-0.5B-Instruct",
    local_files_only=True
)