Stackoverflow 上有个AI开发入门的最常见问题 How to download model from huggingface?，回答五花八门，可见下载 huggingface 模型的方法是十分多样的。
其实网络快、稳的话，随便哪种方法都挺好，然而结合国内的网络环境，断点续传、多线程下载等特性还是非常有必要的，否则动辄断掉重来很浪费时间。基于这个考虑，对各类方法做个总结和排序：
| 方法类别 | 推荐程度 | 优点 | 缺点 | |
|---|---|---|---|---|
| 基于URL | 浏览器网页下载 | ⭐⭐⭐ | 通用性好 | 手动麻烦/无多线程 |
| 多线程下载器 | ⭐⭐⭐⭐ | 通用性好 | 手动麻烦 | |
| CLI工具 | git clone命令 | ⭐⭐ | 简单 | 无断点续传/冗余文件/无多线程 |
| 专用CLI工具 | huggingface-cli+hf_transfer | ⭐⭐⭐ | 官方下载工具链，功能最全 | 无进度条/容错性低 |
huggingface-cli | ⭐⭐⭐⭐⭐ | 官方下载工具 | 不支持多线程 | |
| Python方法 | snapshot_download | ⭐⭐⭐ | 官方支持，功能全 | 脚本复杂/无多线程 |
from_pretrained | ⭐ | 官方支持，简单 | 不方便存储，功能不全 | |
hf_hub_download | ⭐ | 官方支持 | 不支持全量下载/无多线程 |
1. 浏览器网页下载
模型项目页的 Files 栏中可以获取文件的下载链接。直接网页复制下载链接，或用其他下载工具下载。
2. 多线程下载器
常规工具如浏览器默认采用单线程下载，由于国内网络运营商线路质量、QoS等因素有时候会很慢，多线程加速是一种有效、显著提高下载速度的方法。
经典多线程工具推荐两个：IDM、Aria2。 IDM 适用于 Windows、aria2 适用于 Linux。本文头图就是 IDM 工具。因此获取URL后，可以利用这些多线程工具来下载。以我的一次实测为例，单线程700KB/s，IDM 8线程 6MB/s。千兆宽带下，利用IDM能跑到80MB/s+。
当然，手动获取仓库中所有 URL 并导入到多线程下载工具比较麻烦，因此我写了一个命令行脚本 hfd.sh（Gist链接），结合自动获取 url 以及 aria2 多线程下载，适合于 Linux。具体原理见下一节。
2.1 hfd 脚本
链接：hfd.sh（Gist链接)，该工具同样支持设置镜像端点的环境变量:
export HF_ENDPOINT=“https://hf-mirror.com”
基本命令：
./hfd.sh bigscience/bloom-560m --tool aria2c -x 4
如果没有安装 aria2，则可以默认用 wget：
./hfd.sh bigscience/bloom-560m
3. Git clone
此外官方还提供了 git clone repo_url 的方式下载，这种方法相当简单，然而却是最不推荐直接用的方法，缺点有二：
- 1）不支持断点续传，断了重头再来；
- 2）clone 会下载历史版本占用磁盘空间，即使没有历史版本，.git文件夹大小也会存储一份当前版本模型的拷贝以及元信息，导致整个模型文件夹磁盘占用两倍以上，对于有些存在历史版本的模型，下载时间两倍以上，对于网络不够稳，磁盘不够大的用户，严重不推荐！
一种比较好的实践是，设置 GIT_LFS_SKIP_SMUDGE=1 环境变量（这可能也是为什么官方huggingface页面提到这个参数的原因），再 git clone，这样 Git 会先下载仓库中除了大文件之外的文件。然后我们再用一些支持断点续传的工具来下载大文件，这样既支持了断点续传，.git 目录也不会太大（一般几百KB）。这整个流程，其实就是我上一节提到的 hfd 脚本的实现逻辑，感兴趣的可以参考/使用。
4. huggingface-cli+hf_transfer
huggingface-cli 和 hf_transfer 是 hugging face 官方提供的专门为下载而设计的工具链。前者是一个命令行工具，后者是下载加速模块。
4.1 huggingface-cli
huggingface-cli 隶属于 huggingface_hub 库，不仅可以下载模型、数据，还可以可以登录huggingface、上传模型、数据等。
安装依赖
pip install -U huggingface_hub
注意：huggingface_hub 依赖于 Python>=3.8，此外需要安装 0.17.0 及以上的版本，推荐0.19.0+。
基本用法
huggingface-cli download --resume-download bigscience/bloom-560m --local-dir bloom-560m
下载数据
huggingface-cli download --resume-download --repo-type dataset lavita/medical-qa-shared-task-v1-toy
huggingface-cli 属于官方工具，其长期支持肯定是最好的。非常推荐。
除了长期支持这个优点，官方工具最大的一个优点，在于可以用模型名直接引用模型。
什么意思呢？我们知道，from_pretrain 函数可以接收一个模型的id，也可以接收模型的存储路径。
假如我们用浏览器下载了一个模型，存储到服务器的 /data/gpt2 下了，调用的时候你得写模型的绝对路径
AutoModelForCausalLM.from_pretrained(“/data/gpt2”)
然而如果你用的 huggingface-cli download gpt2 --local-dir /data/gpt2 下载，即使你把模型存储到了自己指定的目录，但是你仍然可以简单的用模型的名字来引用他。即：
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。本人实测了三台不同网络环境的机器，确实有黑科技啊，都把带宽跑满了（千兆）。
然而缺点是：
-
- 没有进度条：是真的没有进度条，有进度条说明你没有开启成功。
-
- 鲁棒性差，遇到网络不稳定会报错，并提示用户考虑关闭该模块提高容错性。可能这个模块还没有很成熟吧，对国内这种丢包率高的网络还是水土不服。
尽管如此，还是推荐给大家，看各自网络情况吧。
项目地址：https://github.com/huggingface/hf_transfer。
开启方法
(1)安装依赖
pip install -U hf-transfer
(2)设置 HF_HUB_ENABLE_HF_TRANSFER 环境变量为 1
Linux
export HF_HUB_ENABLE_HF_TRANSFER=1
Windows Powershell
$env:HF_HUB_ENABLE_HF_TRANSFER = 1
开启后使用方法同 huggingface-cli：
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） 该方法调用比较复杂，参数较多，例如默认会检查用户缓存目录下是否已有对应模型，如已有则会创建符号链接，不理解的容易导致问题。外加需要配置代理。最佳实践的参数配置如下：
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"}
)
对于需要登录的模型，还需要两行额外代码：
import huggingface_hub
huggingface_hub.login("HF_TOKEN") # token 从 https://huggingface.co/settings/tokens 获取
很难记住这么多代码，经常性要下载模型的，不如用上文介绍的官方的命令行工具 huggingface-cli 了。
6. from_pretrained
不过多介绍了。常规方法。
7. hf_hub_download
不过多介绍了。常规方法。
最后
我觉得HF-MIRROR作者提供的镜像和hfd.sh非常好用，但同时，今天用 hf_transfer 也非常惊喜（下行居然可以破百，平时才30MB/s）。
