GIT_LFS_SKIP_SMUDGE可以clone时跳过大文件一种比较好的实践是，设置 GIT_LFS_SKIP_SMUDGE=1 环境变量（这可能也是为什么官方huggingface页面提到这个参数的原因），再 git clone，这样 Git 会先下载仓库中除了大文件之外的文件。然后我们再用一些支持断点续传的工具来下载大文件，这样既支持了断点续传，.git 目录也不会太大（一般几百KB）。这整个流程，其实就是我上一节提到的
hfd 脚本的实现逻辑，感兴趣的可以参考/使用。
huggingface-cli 和 hf_transfer 是 hugging face 官方提供的专门为下载而设计的工具链。前者是一个命令行工具，后者是下载加速模块。
4.1 huggingface-clihuggingface-cli 隶属于 huggingface_hub 库，不仅可以下载模型、数据，还可以可以登录huggingface、上传模型、数据等。huggingface-cli 属于官方工具，其长期支持肯定是最好的。优先推荐！
安装依赖
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
值得注意的是，有个--local-dir-use-symlinks False 参数可选，因为huggingface的工具链默认会使用符号链接来存储下载的文件，导致--local-dir指定的目录中都是一些“链接文件”，真实模型则存储在~/.cache/huggingface下，如果不喜欢这个可以用 --local-dir-use-symlinks False取消这个逻辑。
但我不太喜欢取消这个参数，其最大方便点在于，调用时可以用模型名直接引用模型，而非指定模型路径。
什么意思呢？我们知道，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/ 下维护一份模型的符号链接，无论你是否指定了模型的存储路径 ，缓存目录下都会链接过去，这样可以避免自己忘了自己曾经下过某个模型，此外调用的时候就很方便。
所以用了官方工具，既可以方便的用模型名引用模型，又可以自己把模型集中存在一个自定义的路径，方便管理。
当然，该工具目前还是有一些缺点的：
一是其存储逻辑不太直观，如上所属的缓存与链接逻辑，使得新手经常询问，模型究竟下载到哪里去了？
二是不支持单文件多线程。目前的行为是多文件并行，一次性会同时下载多个文件。
三是遇到网络中断会报错退出，不会自动重试，需要重新手动执行。【更新，v0.19.0已支持自动重试】
4.2 hf_transferhf_transfer 依附并兼容 huggingface-cli，是 hugging face 官方专门为提高下载速度基于 Rust 开发的一个模块，开启后在带宽充足的机器上可以跑到 500MB/s。本人实测了三台不同网络环境的机器，确实有黑科技啊，都把带宽跑满了（千兆）。
然而缺点是：
- 1. 没有进度条【更正，v0.19.0+开始支持进度条了】：是真的没有进度条，有进度条说明你没有开启成功。
- 2. 鲁棒性差，遇到网络不稳定会报错，并提示用户考虑关闭该模块提高容错性。可能这个模块还没有很成熟吧，对国内这种丢包率高的网络还是水土不服。
尽管如此，还是推荐给大家，看各自网络情况吧。
开启方法
(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_downloadhuggingface 官方提供了
snapshot_download 方法下载完整模型，参数众多、比较完善。相比下文另两个 python 方法，推荐 snapshot_download 方法来下载模型，支持断点续传、多线程、指定路径、配置代理、排除特定文件等功能。然而有两个缺点：
- 1)）该方法依赖于 transformers 库，而这个库是个开发用的库，对于自动化运维有点重；
- 2） 该方法调用比较复杂，参数较多，例如默认会检查用户缓存目录下是否已有对应模型，如已有则会创建符号链接，不理解的容易导致问题。外加需要配置代理。常见参数配置如下：
from huggingface_hub import snapshot_downloadsnapshot_download( repo_id="bigscience/bloom-560m", local_dir="/data/user/test", proxies={"https": "http://localhost:7890"}, max_workers=8)
对于需要登录的模型，还需要两行额外代码：
import huggingface_hubhuggingface_hub.login("HF_TOKEN") # token 从 https://huggingface.co/settings/tokens 获取
一般很难记住这么多代码，经常性要下载模型的，不如用上文介绍的官方的命令行工具 huggingface-cli 了。
6. from_pretrained不过多介绍了。常规方法。
7. hf_hub_download不过多介绍了。常规方法。
Q1:如何下载hf上需要登陆的模型?由于模型发布者的版权的要求，部分模型无法公开访问下载，需要在 huggingface 上申请许可通过后，才可以下载。这类模型称之为 Gated Model。基本步骤是：
- 1.申请许可
- 2.获取 access token（用于命令行和python方法调用）
- 3.下载
申请许可此步骤必须在 huggingface 官网注册登录后申请，由于网络安全原因，镜像站一般不支持。
申请后一般等待几分钟到几天不等（一般几分钟就行），会发邮件通知你审批结果。
获取 access token申请通过后，就可以在模型主页的 Files and versions 中看到模型文件了，浏览器的话直接点击下载即可。但是如果想要用工具例如 huggingface-cli 下载，则需要获取 access token。
访问 huggingface 设置页面的 token 管理页，选择 New 一个 token，只需要 Read 权限即可，创建后便可以在工具中调用时使用了。
下载除了登陆后浏览器直接下载，几种工具的使用方法分别介绍如下：
Git clone
https
git clone https://<hf_username>:<hf_token>@huggingface.co/meta-llama/Llama-2-7b-chat-hf
huggingface-cli： 添加 –token 参数
huggingface-cli download --token hf_*** --resume-download bigscience/bloom-560m --local-dir bloom-560m
curl, wget：在 header 中添加token
curl -L --header "Authorization: Bearer hf_***" -o model-00001-of-00002.safetensors https://huggingface.co/meta-llam ... f-00002.safetensors
wget --header "Authorization: Bearer hf_***" https://huggingface.co/meta-llam ... f-00002.safetensors
snapshot_download：调用 login 方法
import huggingface_hub huggingface_hub.login("hf_***")
Q2:如何利用镜像站下载hf模型?直接访问镜像站，获取文件URL
代码类工具设置 HF_ENDPOINT 环境变量适用于 huggingface 官方的工具和库，包括：
- huggingface-cli
- snapshot_download
- from_pretrained
- hf_hub_download
- timm.create_model
设置方法
Windows Powershell
$env:HF_ENDPOINT = "https://hf-mirror.com"
Linux
export HF_ENDPOINT="https://hf-mirror.com"
Python
import osos.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
注意os.environ得在import huggingface库相关语句之前执行。
总结以上，我们介绍了浏览器、多线程工具、git clone、huggingface-cli、hf_transfer、python方法、hfd脚本等众多方法，各自有其适用场景，大家根据自己的操作系统的支持情况以及个人习惯来选择。
个人推荐：
- Linux/Mac OS/windows 默认推荐使用huggingface-cli，对外网连接较好（丢包少）的时候，可尝试 huggingface-cli+hf_transfer（可选）。
- 网络连接不好，推荐先GIT_LFS_SKIP_SMUDGE=1 git clone，其次再对大文件用第三方、成熟的多线程下载工具，Linux 推荐hfd脚本+aria2c，Windows 推荐 IDM。用第三方工具的好处是，下载上百GB的模型、数据集，你可以放个一晚上，第二天就下载好了，而不是第二天早晨发现下载了10%断了还得继续。
- 偶尔小文件下载，直接访问镜像站，用浏览器下载。
发表于 2024-1-16 05:28:03
发表于 2024-1-17 19:35:27
