HuggingFace 镜像网站

环境准备（必做）
1 升级huggingface-hub（关键）
确保版本≥0.16.0（断点续传、镜像兼容性最佳）
pip install --upgrade huggingface-hub>=0.16.0

2 基础环境配置（临时/永久）
临时生效（终端会话）
# Linux/Mac
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”


8
永久生效（推荐）
Linux/Mac 编辑~/. rc或~/.zshrc

echo ‘export HF_ENDPOINT=https://hf-mirror.com’ >> ~/. rc
source ~/. rc # 立即生效


Windows
搜索「环境变量」→ 系统属性→高级→环境变量
新建系统变量
HF_ENDPOINT = https://hf-mirror.com
重启终端/IDE


全工具链镜像配置指南
1 huggingface-cli
基础下载（断点续传核心用法）
# 核心参数 --resume-download（断点续传）
# 强制下载文件（非符号链接）–local-dir-use-symlinks False
# --resume-download \ # 断点续传（中断后重新执行自动续传）
# --retries 5 # 自动重试5次（网络不稳定时）

huggingface-cli download LiveCodeBench/LiveCodeBench --local-dir LiveCodeBench --local-dir-use-symlinks False --resume-download --retries 5


高级用法（筛选/版本控制）
# 下载指定文件+断点续传
# --include “.bin,.json” \ # 只下载权重和配置文件
# --exclude “.md,.git*” \ # 排除无用文件
# --revision v1.0 \ # 指定版本


huggingface-cli download Qwen/Qwen2.5-7B-Instruct --include “.bin,.json” --exclude “.md,.git*” --revision v1.0 --resume-download



2 transformers库（Python代码）
方法1 环境变量自动生效（推荐）
from transformers import AutoModelForCausalLM, AutoTokenizer

# 自动使用HF_ENDPOINT配置的镜像源
model = AutoModelForCausalLM.from_pretrained(
“Qwen/Qwen2.5-3B-Instruct”,
device_map=“auto”
)
tokenizer = AutoTokenizer.from_pretrained(“Qwen/Qwen2.5-3B-Instruct”)



方法2 代码内显式设置
from huggingface_hub import set_endpoint
from transformers import AutoModel

set_endpoint(“https://hf-mirror.com”) # 显式指定镜像
model = AutoModel.from_pretrained(“bert-base-uncased”)


3 datasets库（数据集下载）
from datasets import load_dataset

# 自动使用镜像源
dataset = load_dataset(“lmsys/lmsys-chat-1m”, split=“train”)

# 显式指定镜像（可选）
import os
os.environ[“HF_ENDPOINT”] = “https://hf-mirror.com”
dataset = load_dataset(“glue”, “mrpc”)


4 snapshot_download（批量下载）
from huggingface_hub import snapshot_download

# 断点续传+镜像加速
snapshot_download(
repo_id=“Qwen/Qwen2.5-VL-7B”,
local_dir=“Qwen2.5-VL-7B”,
resume_download=True, # 断点续传
max_workers=4 # 多线程加速
)


5 Git+Git-LFS（大文件下载）
# 配置Git使用镜像源
git config --global url.“https://hf-mirror.com/”.insteadOf “https://huggingface.co/”

# 下载模型（自动走镜像）
git clone https://huggingface.co/Qwen/Qwen2.5-3B-Instruct
cd Qwen2.5-3B-Instruct
git lfs pull # 下载LFS大文件


四、断点续传深度优化（2026最新）
1 核心生效条件
本地保留.tmp临时文件（不要删除/移动）
重新执行命令与中断前参数完全一致（尤其是–local-dir）
目标文件在HF Hub未被修改（若更新会重新下载）

2 高级缓存配置（提升速度）
设置缓存路径（避免重复下载）

# Linux/Mac
export TRANSFORMERS_CACHE=/data/huggingface/cache
export HF_HUB_CACHE=/data/huggingface/cache

# Windows
set TRANSFORMERS_CACHE=D:\huggingface\cache




3 大模型 下载优化（>10GB）
# 1 增加超时时间（避免大文件超时）
export HF_HUB_ETAG_TIMEOUT=300
export HF_HUB_DOWNLOAD_TIMEOUT=3600

# 2 分块下载+断点续传 # 每块500MB（降低中断风险）
huggingface-cli download Qwen/Qwen2.5-72B-Instruct --resume-download --chunk-size 500MB


五、常见问题排查（2026最新）
1 镜像不生效（仍从官方源下载）
检查HF_ENDPOINT是否正确设置 echo $HF_ENDPOINT（Linux）或echo %HF_ENDPOINT%（Windows）
升级huggingface-hub到最新版
重启终端/IDE（环境变量生效需要重启）
2 断点续传失败（重新从头下载）
原因 临时文件丢失/参数不一致/文件更新
解决
保留–local-dir中的.tmp文件
确保重新执行的命令与中断前完全相同
若文件更新，删除旧文件后重新下载
3 LFS文件下载失败（403/404）
配置Git镜像 git config --global url.“https://hf-mirror.com/”.insteadOf “https://huggingface.co/”
登录HF账号（私有库/限流时） huggingface-cli login（需先执行pip install --upgrade huggingface-hub）
4 下载速度慢（<1MB/s）
切换镜像源（优先hf-mirror.com）
检查网络连接（避免VPN冲突）
使用多线程 --max-workers 4（snapshot_download）
配置DockerHub镜像（若在容器内运行）
六、进阶场景配置
1 Docker容器内使用镜像
在Dockerfile中添加环境变量

FROM python:3.10-slim
ENV HF_ENDPOINT=https://hf-mirror.com
RUN pip install huggingface-hub transformers

2 Jupyter Notebook/Lab
在Notebook开头添加

import os
os.environ[“HF_ENDPOINT”] = “https://hf-mirror.com”

3 私有库访问（镜像+认证）
先登录HF账号 huggingface-cli login
配置镜像环境变量（自动携带认证信息）
正常下载私有库
huggingface-cli download your-username/your-private-repo

4 离线环境部署
在联网机器用镜像下载模型 huggingface-cli download …
将下载目录复制到离线机器
使用
from_pretrained(local_dir=“path/to/model”)
加载

七、2026年最佳实践总结
核心配置
HF_ENDPOINT=https://hf-mirror.com

必备参数 --resume-download（断点续传）+ --retries 5（自动重试）
版本要求 huggingface-hub≥0.16.0（大文件/LFS支持最佳）

避坑要点
不要删除临时文件（.tmp）
命令参数保持一致（确保断点续传生效）
私有库先登录再下载
优先使用hf-mirror.com镜像+环境变量配置
配合断点续传参数
对于超大模型（>100GB）分块下载并配置多线程 提升下载效率