Hugging Face 加速
本文介绍如何在 Linux 环境中使用 HF-Mirror 加速 Hugging Face 模型和数据集下载，适合 GPU 容器、训练服务器及自动化任务。
概述
HF-Mirror 镜像地址为：
https://hf-mirror.comHugging Face 工具链会读取 HF_ENDPOINT 环境变量。将该变量设置为镜像地址后，hf、旧版 huggingface-cli 以及 huggingface_hub 的 Python API 会优先通过镜像下载资源。
HF-Mirror 是第三方公益服务，并非 Hugging Face 或立方云官方服务。镜像可用性和资源同步状态可能发生变化，使用前请同时保留 Hugging Face 官方地址作为回退方案。
安装命令行工具
安装或升级 huggingface_hub：
python3 -m pip install -U huggingface_hub确认新版 hf 命令可用：
hf --help如果环境中只有 huggingface-cli，可以继续使用本文后面的兼容命令，也可以升级 huggingface_hub。
配置镜像地址
当前终端临时生效
export HF_ENDPOINT=https://hf-mirror.com检查变量是否设置成功：
printf '%s\n' "$HF_ENDPOINT"输出应为：
https://hf-mirror.com该配置只在当前 Shell 会话中有效，关闭终端后会失效。
持久化配置
使用 Bash 时，将下面一行添加到 ~/.bashrc：
export HF_ENDPOINT=https://hf-mirror.com然后重新加载配置：
source ~/.bashrc使用 Zsh 时，将同一配置添加到 ~/.zshrc，然后执行：
source ~/.zshrc如只希望单次命令使用镜像，可以将环境变量写在命令前，不改变当前终端的后续配置：
HF_ENDPOINT=https://hf-mirror.com hf download openai-community/gpt2使用 hf 下载
下载模型
将整个模型仓库下载到指定目录：
hf download openai-community/gpt2 --local-dir ./gpt2只下载单个文件：
hf download openai-community/gpt2 config.json --local-dir ./gpt2下载数据集
下载数据集时添加 --repo-type dataset：
hf download Salesforce/wikitext \
--repo-type dataset \
--local-dir ./wikitext新版 hf download 会使用本地缓存并自动处理可恢复的下载，不需要额外添加旧版的 --resume-download 参数。
兼容 huggingface-cli
旧环境可以继续使用 huggingface-cli download。只要已经设置 HF_ENDPOINT，下载请求同样会使用镜像。
下载模型：
huggingface-cli download openai-community/gpt2 --local-dir ./gpt2下载数据集：
huggingface-cli download Salesforce/wikitext \
--repo-type dataset \
--local-dir ./wikitext如果命令不存在或参数不受支持，请升级 huggingface_hub 并改用新版 hf 命令。
在 Python 中使用
设置 HF_ENDPOINT 后，huggingface_hub 和 Transformers 会自动读取该配置。
下载完整仓库
from huggingface_hub import snapshot_download
snapshot_download(
repo_id="openai-community/gpt2",
local_dir="./gpt2",
)使用 Transformers 加载模型
from transformers import AutoModel, AutoTokenizer
model_id = "openai-community/gpt2"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModel.from_pretrained(model_id)如果脚本只需单次使用镜像，可以在启动时指定环境变量：
HF_ENDPOINT=https://hf-mirror.com python3 train.py部分数据集或项目包含独立下载脚本，脚本中可能写死其他下载地址。这类地址不会自动读取 HF_ENDPOINT，需要按照项目说明单独处理。
使用 hfd 下载
HF-Mirror 提供的 hfd 基于 aria2，适合下载较大的模型仓库。运行前先确认系统已经安装 aria2c：
command -v aria2c如果没有输出，请先使用当前 Linux 发行版的软件包管理器安装 aria2。然后下载脚本并添加执行权限：
wget https://hf-mirror.com/hfd/hfd.sh
chmod a+x hfd.sh下载模型：
./hfd.sh openai-community/gpt2下载数据集：
./hfd.sh Salesforce/wikitext --datasethfd.sh 是外部脚本，执行前应先阅读脚本内容，并确认来源和下载地址符合预期。
下载 Gated Repo
部分模型属于 Gated Repo，需要先在 Hugging Face 官方网站完成登录、阅读许可协议并申请访问权限：
- 打开对应模型的 Hugging Face 官方页面并提交访问申请。
- 获得权限后，在官方 Access Tokens 页面创建只读 Token。
- 将 Token 保存到当前会话的环境变量中，不要写入代码、镜像或公开日志。
export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx通过新版命令下载：
hf download OWNER/REPOSITORY \
--token "$HF_TOKEN" \
--local-dir ./repository使用完毕后可以清除当前会话中的变量：
unset HF_TOKEN公共镜像可能不支持登录或尚未同步受限资源。如果下载失败，请确认官方账号已经获得授权，并优先通过 Hugging Face 官方地址下载。不要把 Token 直接写入下载 URL，也不要在工单、截图或聊天记录中公开 Token。
恢复官方地址
只恢复当前终端：
unset HF_ENDPOINT如果已将配置写入 ~/.bashrc 或 ~/.zshrc，请删除对应的 export HF_ENDPOINT=... 行，再重新加载 Shell 配置。
常见问题
仍然访问 huggingface.co
先确认环境变量：
printf '%s\n' "$HF_ENDPOINT"然后确认命令与 Python 程序运行在同一个 Shell 会话中。部分第三方库可能不读取 HF_ENDPOINT，需要查看该项目自己的镜像或代理配置。
找不到仓库或文件
镜像同步可能存在延迟。请先在 Hugging Face 官方页面确认仓库 ID、文件名和 Revision 是否正确；官方存在但镜像暂未同步时，可以临时取消 HF_ENDPOINT 后重试。
磁盘空间不足
Hugging Face 默认会保留缓存，大模型可能同时占用缓存目录和 --local-dir 指定目录。下载前可以检查磁盘空间：
df -h
du -sh ~/.cache/huggingface 2>/dev/null确认缓存不再需要后，再按照 Hugging Face 官方缓存管理方式清理。
注意事项
- 镜像服务不保证所有仓库和 Revision 都能实时同步。
- 重要模型和数据集应记录仓库 ID、Revision 或 Commit Hash，保证结果可复现。
- 不要将 Hugging Face Token 写入代码仓库、Dockerfile、Shell 历史或公开日志。
- 下载模型和数据集前，请确认其 License、使用限制和访问授权。
- 生产任务应准备官方地址或内部对象存储作为备用下载源。