在国内访问 Huggingface 官方源，时常会因为网络问题导致模型下载速度慢甚至失败。为了解决这个问题，可以将 Huggingface 源切换到国内镜像，极大提升模型和数据集的下载速度。以下介绍三种常见的切换方式，并附常用国内镜像源和注意事项。
环境变量设置镜像源
设置 HF_ENDPOINT 环境变量后，Huggingface 的各类工具（如 transformers、datasets、diffusers 等）均会自动使用指定镜像。
Linux/macOS 下执行：
bash
export HF_ENDPOINT=https://hf-mirror.comWindows 命令行执行：
cmd
set HF_ENDPOINT=https://hf-mirror.com也可以将该变量添加到系统环境变量中，实现全局生效。
from_pretrained 方法直接指定镜像
部分模型加载方法支持在代码中直接指定镜像，适合只对单次调用加速，无需全局配置。例如：
python
from transformers import AutoModel
model = AutoModel.from_pretrained(
"bert-base-uncased",
mirror="hf-mirror.com"
)该方式无需更改环境变量，代码中显式指定镜像即可。
修改 Huggingface 配置文件
Huggingface 会在本地生成配置文件（一般在 ~/.cache/huggingface/hub/config.json）。手动编辑该文件，添加或修改如下内容：
json
{
"endpoint": "https://hf-mirror.com"
}保存后，Huggingface 工具会自动读取新的 endpoint，从而走国内镜像源。
常用国内镜像源一览
| 镜像名称 | 地址 |
|---|---|
| 官方推荐镜像 | https://hf-mirror.com |
| 阿里云模型库 | https://modelscope.cn |
| 清华大学镜像 | https://mirrors.tuna.tsinghua.edu.cn/huggingface |
注意事项：
- 镜像和官方源同步存在延迟，部分新模型、新数据集可能尚未同步；
- 部分私有模型、授权模型无法通过镜像下载；
- 下载大模型建议配合
huggingface-cli工具，避免因中断导致重复下载； - 如遇到配置、环境变量无效等问题，可尝试清除本地缓存后重试。
额外技巧：避免代理干扰
部分环境下，如果设置了 HTTP 代理，可能影响镜像源访问。可在代码中临时取消代理设置：
python
import os
os.environ.pop('HTTP_PROXY', None)
os.environ.pop('HTTPS_PROXY', None)
os.environ['NO_PROXY'] = '127.0.0.1,localhost'总结
切换 Huggingface 镜像源后，国内访问 Huggingface 生态会更加顺畅。无论是通过环境变量、配置文件，还是直接在代码里指定镜像，都能有效提升模型、数据集的下载速度和体验。遇到卡顿、下载失败等问题时，优先尝试切换国内镜像。
持续关注镜像源状态，结合自身需求灵活选择配置方式，可极大提升 Huggingface 的使用效率。