HuggingFace镜像网站

声明：转载自https://padeoe.com/huggingface-large-models-downloader/ AND https://zhuanlan.zhihu.com/p/663712983

镜像网站：https://hf-mirror.com/

https://alpha.hf-mirror.com/

​image​

1. 如何利用镜像站下载hf模型?

方法一 网页下载

在本站搜索，并在模型主页的Files and Version​中下载文件。

‍

方法二 huggingface-cli

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

1. 安装依赖

1
pip install -U huggingface_hub
1
pip install -U huggingface_hub -i https://pypi.mirrors.ustc.edu.cn/simple/

2.设置环境变量
Linux

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

Windows Powershell

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

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

3.下载

3.1 下载模型

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

3.2 下载数据集

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

可以添加 --local-dir-use-symlinks False​ 参数禁用文件软链接，这样下载路径下所见即所得，详细解释请见上面提到的教程。

方法三：使用 hfd

hfd 是本站开发的 huggingface 专用下载工具，基于成熟工具 aria2​，可以做到稳定高速下载不断线。

1. 下载hfd

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

2. 设置环境变量
Linux

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

Windows Powershell

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

3.1 下载模型

1
./hfd.sh gpt2

3.2 下载数据集

1
./hfd.sh wikitext --dataset

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

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

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

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

其他方式

定位到文件："/home1/miniconda3/envs/xmf/lib/python3.8/site-packages/huggingface_hub/constants.py"​

修改网址代码：

1
2
#_HF_DEFAULT_ENDPOINT = "https://huggingface.co"
_HF_DEFAULT_ENDPOINT = "https://hf-mirror.com"

​image​

用前面的下载命令。

‍

​​

代码类工具设置 HF_ENDPOINT 环境变量

适用于 huggingface 官方的工具和库，包括：

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

设置方法

Windows Powershell

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

Linux

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

Python

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

注意os.environ​得在import huggingface库相关语句之前执行。

‍

2.如何下载huggingface大模型

1.浏览器下载

模型项目页的 Files​ 栏中可以获取文件的下载链接。直接网页复制下载链接，或用其他下载工具下载。

​image​

2. 多线程下载器

经典多线程工具推荐两个：IDM、Aria2。 IDM 适用于 Windows、aria2 适用于 Linux。

手动获取仓库中所有 URL 并导入到多线程下载工具比较麻烦，一个命令行脚本 hfd.sh（Gist链接），结合自动获取 url 以及 aria2​ 多线程下载，适合于 Linux。

2.1 hfd 脚本

链接：hfd.sh（Gist链接)，该工具同样支持设置镜像端点的环境变量:

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

基本命令：

1
./hfd.sh bigscience/bloom-560m --tool aria2c -x 4

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

1
./hfd.sh bigscience/bloom-560m

3. Git clone

此外官方还提供了 git clone repo_url​ 的方式下载，这种方法相当简单，然而却是最不推荐直接用的方法，缺点有二：

  • 1）不支持断点续传，断了重头再来；
  • 2）clone 会下载历史版本占用磁盘空间，即使没有历史版本，.git​文件夹大小也会存储一份当前版本模型的拷贝以及元信息，导致整个模型文件夹磁盘占用两倍以上，对于有些存在历史版本的模型，下载时间两倍以上，对于网络不够稳，磁盘不够大的用户，严重不推荐！

一种比较好的实践是，设置 GIT_LFS_SKIP_SMUDGE=1​ 环境变量，再 git clone​，这样 Git 会先下载仓库中除了大文件之外的文件。然后我们再用一些支持断点续传的工具来下载大文件，这样既支持了断点续传，.git​ 目录也不会太大（一般几百KB）。

4. huggingface-cli+hf_transfer

​huggingface-cli​ 和 hf_transfer​ 是 hugging face 官方提供的专门为下载而设计的工具链。前者是一个命令行工具，后者是下载加速模块。

4.1 huggingface-cli

​huggingface-cli​ 隶属于 huggingface_hub​ 库，不仅可以下载模型、数据，还可以可以登录huggingface、上传模型、数据等。

安装依赖

1
pip install -U huggingface_hub

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

基本用法

1
huggingface-cli download --resume-download bigscience/bloom-560m --local-dir bloom-560m

下载数据

1
huggingface-cli download --resume-download --repo-type dataset lavita/medical-qa-shared-task-v1-toy

huggingface-cli 属于官方工具，其长期支持肯定是最好的。非常推荐。

除了长期支持这个优点，官方工具最大的一个优点，在于可以用模型名直接引用模型。

什么意思呢？我们知道，from_pretrain​ 函数可以接收一个模型的id，也可以接收模型的存储路径。

假如我们用浏览器下载了一个模型，存储到服务器的 /data/gpt2​ 下了，调用的时候你得写模型的绝对路径

1
AutoModelForCausalLM.from_pretrained("/data/gpt2")

然而如果你用的 huggingface-cli download gpt2 --local-dir /data/gpt2​ 下载，即使你把模型存储到了自己指定的目录，但是你仍然可以简单的用模型的名字来引用他。即：

1
AutoModelForCausalLM.from_pretrained("gpt2")

原理是因为huggingface工具链会在 .cache/huggingface/​ 下维护一份模型的符号链接，无论你是否指定了模型的存储路径 ，缓存目录下都会链接过去，这样可以避免自己忘了自己曾经下过某个模型，此外调用的时候就很方便。

所以用了官方工具，既可以方便的用模型名引用模型，又可以自己把模型集中存在一个自定义的路径，方便管理。

当然，该工具目前还是有一些缺点的：

一是其存储逻辑不太直观，其默认会把模型下载到 ~/.cache/huggingface/hub/​ 中，即使设置了 --local-dir​，也会采用符号链接的形式进行链接，其目的在于防止重复下载。然而我们有时候只想简单的下载到特定目录，其中有一项 --local-dir-use-symlinks​，设置为 False 可以部分解决该问题，虽然仍会临时下载到 ~/.cache/huggingface/hub/​，但下载完成后会移动到 --local-dir​ 指定的目录。

二是由于上述逻辑的问题，主动Ctrl+C中断后，断点续传有时存在bug，导致同样的文件无法中断恢复，会重头下载。相信官方后续会改进。

三是不支持单文件多线程。目前的行为是多文件并行，一次性会同时下载多个文件。

四是遇到网络中断会报错退出，不会自动重试，需要重新手动执行。

4.2 hf_transfer

​hf_transfer​ 依附并兼容 huggingface-cli​，是 hugging face 官方专门为提高下载速度基于 Rust 开发的一个模块，开启后在带宽充足的机器上可以跑到 500MB/s。

然而缺点是：

  • 1. 没有进度条：是真的没有进度条，有进度条说明你没有开启成功。
  • 2. 鲁棒性差，遇到网络不稳定会报错，并提示用户考虑关闭该模块提高容错性。可能这个模块还没有很成熟吧，对国内这种丢包率高的网络还是水土不服。

项目地址：https://github.com/huggingface/hf_transfer。

开启方法

(1)安装依赖

1
pip install -U hf-transfer

(2)设置 ​HF_HUB_ENABLE_HF_TRANSFER​​ 环境变量为 1

Linux

1
export HF_HUB_ENABLE_HF_TRANSFER=1

Windows Powershell

1
$env:HF_HUB_ENABLE_HF_TRANSFER = 1

开启后使用方法同 huggingface-cli​：

1
huggingface-cli download --resume-download bigscience/bloom-560m --local-dir bloom-560m

注意：​如果看到进度条，说明** ​hf_transfer​​ 没开启成功！ 例如以下情况：

​--resume-download​ 参数，指的是从上一次下载的地方继续，一般推荐总是加上该参数，断了方便继续。然而如果你一开始没有开启 hf_transfer​，下载中途停掉并设置环境变量开启，此时用 --resume-download​ 会由于不兼容导致 hf_transfer​ 开启失败！总之观察是否有进度条就可以知道有没有开启成功，没有进度条就说明开启成功！

5. snapshot_download

huggingface 官方提供了snapshot_download​ 方法下载完整模型，参数众多、比较完善。相比下文另两个 python 方法，推荐 ​snapshot_download​​ 方法来下载模型，支持断点续传、指定路径、配置代理、排除特定文件等功能。然而有两个缺点：

  • 1)）该方法依赖于 transformers 库，而这个库是个开发用的库，对于自动化运维有点重；
  • 2） 该方法调用比较复杂，参数较多，例如默认会检查用户缓存目录下是否已有对应模型，如已有则会创建符号链接，不理解的容易导致问题。外加需要配置代理。最佳实践的参数配置如下：
1
2
3
4
5
6
7
8
from huggingface_hub import snapshot_download

snapshot_download(
  repo_id="bigscience/bloom-560m",
  local_dir="/data/user/test",
  local_dir_use_symlinks=False,
  proxies={"https": "http://localhost:7890"}
)

对于需要登录的模型，还需要两行额外代码：

1
2
import huggingface_hub
huggingface_hub.login("HF_TOKEN") # token 从 https://huggingface.co/settings/tokens 获取

很难记住这么多代码，经常性要下载模型的，不如用上文介绍的官方的命令行工具 huggingface-cli​ 了。

3.如何下载hf上需要登陆的模型?

由于模型发布者的版权的要求，部分模型无法公开访问下载，需要在 huggingface 上申请许可通过后，才可以下载。这类模型称之为 Gated Model​。基本步骤是：

  • 1.申请许可
  • 2.获取 access token（用于命令行和python方法调用）
  • 3.下载

申请许可

此步骤必须在 huggingface 官网注册登录后申请，由于网络安全原因，镜像站一般不支持。

​Gated Model申请​

申请后一般等待几分钟到几天不等（一般几分钟就行），会发邮件通知你审批结果。

获取 access token

申请通过后，就可以在模型主页的 Files and versions​ 中看到模型文件了，浏览器的话直接点击下载即可。但是如果想要用工具例如 huggingface-cli​ 下载，则需要获取 access token。

Access Token 获取地址： https://huggingface.co/settings/tokens

​
访问 huggingface 设置页面的 token 管理页，选择 New 一个 token，只需要 Read​ 权限即可，创建后便可以在工具中调用时使用了。

下载

除了登陆后浏览器直接下载，几种工具的使用方法分别介绍如下：

Git

1
git clone https://hf_username:hf_token@huggingface.co/meta-llama/Llama-2-7b-chat-hf

huggingface-cli： 添加 –token 参数

1
huggingface-cli download --token hf_*** --resume-download bigscience/bloom-560m --local-dir bloom-560m

curl, wget：在 header 中添加token

1
curl -L --header "Authorization: Bearer hf_***" -o model-00001-of-00002.safetensors https://huggingface.co/meta-llama/Llama-2-7b-chat-hf/resolve/main/model-00001-of-00002.safetensors
1
wget --header "Authorization: Bearer hf_***" https://huggingface.co/meta-llama/Llama-2-7b-chat-hf/resolve/main/model-00001-of-00002.safetensors

snapshot_download：调用 login 方法

1
2
import huggingface_hub
huggingface_hub.login("hf_***")