hf-mirror （huggingface 的国内镜像）_hf mirror

官网： https://hf-mirror.com/
网站域名 hf-mirror.com，用于镜像 huggingface.co 域名。作为一个公益项目，致力于帮助国内AI开发者快速、稳定的下载模型、数据集。

---

如何使用HF-Mirror

方法一：网页下载

在https://hf-mirror.com/搜索，并在模型主页的Files and Version中下载文件

方法二：huggingface-cli

huggingface-cli 是 Hugging Face 官方提供的命令行工具，自带完善的下载功能。

1. 安装依赖

pip install -U huggingface_hub
1

注意：huggingface_hub 依赖于 Python>=3.8，此外需要安装 0.17.0 及以上的版本，推荐0.19.0+。

2. 设置环境变量

Linux

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

Windows Powershell

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

建议将上面这一行写入 ~/.bashrc。

3.1 下载模型

huggingface-cli download --resume-download gpt2 --local-dir gpt2
1

3.2 下载数据集

huggingface-cli download --repo-type dataset --resume-download wikitext --local-dir wikitext
1

值得注意的是，有个--local-dir-use-symlinks False 参数可选，因为huggingface的工具链默认会使用符号链接来存储下载的文件，导致--local-dir指定的目录中都是一些“链接文件”，真实模型则存储在~/.cache/huggingface下，如果不喜欢这个可以用 --local-dir-use-symlinks False取消这个逻辑。

方法三：使用 hfd （推荐）

hfd 是https://hf-mirror.com/开发的 huggingface 专用下载工具，基于成熟工具 git+aria2，可以做到稳定下载不断线。

1. 下载hfd

wget https://hf-mirror.com/hfd/hfd.sh
chmod a+x hfd.sh
1
2

2. 设置环境变量

HF_ENDPOINT 该变量是 HF 相关库官方支持的一个环境变量，设置后，相关库会尊重该变量指定的主机名，替换 huggingface.co 域名进行模型、数据集的下载和上传，从而做到无需修改python的transformers代码，即可利用上镜像站来加载模型。具体支持以下库：

• huggingface-cli
• snapshot_download
• from_pretrained
• hf_hub_download
• timm.create_model

Linux

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

Linux 写入到~/.bashrc中：

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

Windows Powershell

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

Python

import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
1
2

3.1 下载模型（例子： gpt2）

./hfd.sh gpt2 --tool aria2c -x 4
1

如果没有安装 aria2，则可以默认用 wget：

./hfd.sh gpt2 
1

3.2 下载数据集 (例子： wikitext )

./hfd.sh wikitext --dataset --tool aria2c -x 4
1

方法四：使用环境变量（非侵入式）

非侵入式，能解决大部分情况。huggingface 工具链会获取HF_ENDPOINT环境变量来确定下载文件所用的网址，所以可以使用通过设置变量来解决。

HF_ENDPOINT=https://hf-mirror.com python your_script.py
1

不过有些数据集有内置的下载脚本，那就需要手动改一下脚本内的地址来实现了。

---

补充：
如何快速下载huggingface模型——全方法总结
stackoverflow：how-to-download-a-model-from-huggingface

常见错误问答

0, 有些项目需要登录，如何下载？

部分 Gated Repo 需登录申请许可。为保障账号安全，本站不支持登录，需先前往 Hugging Face 官网登录、申请许可，在官网这里获取 Access Token 后回镜像站用命令行下载。

部分工具下载 Gated Repo 的方法：

huggingface-cli： 添加–token参数

huggingface-cli download --token hf_*** --resume-download meta-llama/Llama-2-7b-hf --local-dir Llama-2-7b-hf
1

hfd： 添加–hf_username–hf_token参数

hfd meta-llama/Llama-2-7b --hf_username YOUR_HF_USERNAME --hf_token hf_***
1

其余如from_pretrained、wget、curl如何设置认证 token，详见上面第一段提到的教程。

1, huggingface-cli: error: invalid choice: ‘download’

版本问题。huggingface-hub>=0.17.0 && Python>=3.8。

huggingface-cli 需安装 0.17.0 及以上的版本才支持download子命令，但如果你pip显示的可安装的最新版本都低于0.17.0，可能是你的Python版本没有达到huggingface_hub要求的3.8+的要求。

2, Error downloading … https://cdn-lfs.huggingface.co/xxx…

报错中有出现http://huggingface.co这个域名的，多半是因为没有正确设置镜像断点环境变量，导致走的仍然是hf官方服务器出现的网络错误。请正确设置 HF_ENDPOINT

3, 429 Client Error: Too Many Requests

网站访问量过大，达到速率上限，过五分钟会重置限制。

---

补充：魔塔

比较有名的模型，魔塔 上也都有， 下载也挺快