玩AI开发、微调模型的小伙伴，大概率都被 Hugging Face 下载慢、连接超时、下载中断 的问题折磨过。官方源境外服务器延迟高、限速严重，几百MB的模型都要下半小时，几十GB的大模型更是几乎无法正常拉取。
今天给大家分享hf download（hfd）搭配国内镜像的全套实操方案，无需魔法上网，简单配置即可满血提速，下载速度稳定10-50MB/s，完美适配模型、数据集批量下载，Windows/Mac/Linux全平台通用。
全程无复杂操作，复制命令即用，新手也能一键搞定✅
一、先搞懂：什么是 hf download + 镜像加速？
1. hf download 是什么？
- 支持模型、数据集精准下载，可指定文件、过滤冗余内容
- 搭配
hf_transfer高速传输组件，多线程拉取，效率拉满 - 占用资源低，命令行/代码双模式，适配服务器、本地电脑所有场景
国内主流免费镜像 hf-mirror.com 实时同步 Hugging Face 官方资源，服务器部署在国内。我们只需通过环境变量 HF_ENDPOINT 将下载源从官方境外地址，替换为国内镜像地址，即可绕过网络限制，实现高速下载。
2. 镜像原理
该方案为社区免费维护，稳定无广告，无需付费，是目前国内开发者最优解。
二、前期准备：安装核心依赖
首先安装最新版官方下载工具与高速传输插件，确保镜像功能、多线程加速正常生效：
pip install -U huggingface_hub hf_transfer– huggingface_hub：提供 hf download 核心能力、镜像配置、断点续传功能
– hf_transfer：官方高速传输组件，大幅提升镜像下载速度，避免卡顿
三、全平台镜像配置教程（核心步骤）
镜像配置核心就是设置 HF_ENDPOINT 环境变量，指向国内镜像地址，分临时生效（单次终端）和永久生效两种方式，按需选择。
1. Linux / MacOS 系统
临时生效（当前终端窗口，重启失效）
export HF_ENDPOINT=https://hf-mirror.com永久生效（推荐，全局通用）
根据终端类型写入配置文件（zsh 对应 .zshrc，bash 对应 .bashrc）：
# MacOS Zsh 终端
echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.zshrc
source ~/.zshrc
# Linux Bash 终端
echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc
source ~/.bashrc2. Windows 系统
PowerShell 临时生效
$env:HF_ENDPOINT = "https://hf-mirror.com"CMD 临时生效
set HF_ENDPOINT=https://hf-mirror.com永久生效
setx HF_ENDPOINT "https://hf-mirror.com"执行后重启终端即可全局生效，所有下载操作自动走镜像。
3. 验证镜像是否配置成功
输入以下命令查看环境变量，输出镜像地址即配置成功：
# Linux/Mac
echo $HF_ENDPOINT
# Windows PowerShell
$env:HF_ENDPOINT四、hf download 镜像高速下载实操
配置完成后，所有 hf download 相关下载命令、代码，都会自动走国内镜像，无需额外修改参数。
1. 命令行下载（最常用）
下载模型（默认路径）
# 格式：huggingface-cli download 模型ID
huggingface-cli download gpt2下载模型到指定目录 + 断点续传
huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./qwen2.5-7b --resume-download下载数据集（加 –dataset 参数）
huggingface-cli download wikitext --dataset --local-dir ./wikitext_data2. Python 代码下载（开发必备）
适合脚本自动化下载，两种配置方式，任选其一即可：
方式1：代码内动态设置镜像（灵活，适配单脚本）
import os
from huggingface_hub import snapshot_download
# 临时指定镜像源
os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"
# 批量下载模型，支持断点续传
snapshot_download(
repo_id="sentence-transformers/all-MiniLM-L6-v2",
local_dir="./models/all-MiniLM-L6-v2",
resume_download=True,
force_download=False
)方式2：接口直接指定 endpoint（优先级最高）
from huggingface_hub import snapshot_download
snapshot_download(
repo_id="Qwen/Qwen2.5-VL-7B",
local_dir="./Qwen2.5-VL-7B",
endpoint="https://hf-mirror.com",
resume_download=True
)3. hfd 脚本极速下载（超大模型推荐）
针对几十GB超大模型，可使用官方 hfd 脚本+aria2c多线程加速，速度再升级：
# 下载模型（4线程加速）
./hfd.sh Qwen/Qwen2.5-7B-Instruct --tool aria2c -x 4
# 下载数据集
./hfd.sh wikitext --dataset --tool aria2c -x 4五、Transformer/Datasets 库自动适配镜像
配置 HF_ENDPOINT 环境变量后，日常加载模型、数据集的代码无需任何修改，transformers、datasets 会自动识别镜像源：
from transformers import AutoModel, AutoTokenizer
from datasets import load_dataset
# 自动走国内镜像高速下载
model = AutoModel.from_pretrained("bert-base-uncased")
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
dataset = load_dataset("glue", "mrpc")六、常见问题排查（避坑指南）
1. 配置镜像后速度依旧很慢
- 升级依赖：
pip install -U huggingface_hub hf_transfer，旧版本不支持高速传输 - 确认环境变量生效，重启终端/IDE，清除本地缓存
- 优先使用
snapshot_download而非原生from_pretrained批量下载
2. 私有模型/数据集下载失败
镜像不影响授权登录，搭配镜像登录即可：
huggingface-cli login --token 你的HF令牌 --endpoint https://hf-mirror.com3. 下载中断、文件损坏
开启 resume_download=True 断点续传参数，重新运行命令自动修复，无需重头下载。
七、总结
国内使用 Hugging Face 下载资源，hf download + hf-mirror 镜像 是目前零成本、最稳定、最高速的方案。核心逻辑就是配置 HF_ENDPOINT 环境变量，一次配置、全局生效，适配所有下载场景。
彻底告别超时、限速、下载失败问题，无论是本地调试、服务器部署、模型微调，都能大幅提升开发效率，建议所有AI开发者默认配置！
码字不易，收藏留存！后续持续更新AI开发实用技巧✨
