解决Hugging Face模型下载难题

解决Hugging Face模型下载难题

本文将详细介绍如何解决Hugging Face模型下载难题，包括查找项目所需模型、了解模型安装目录，以及使用huggingface-cli工具进行模型下载的具体步骤。

前情提示：

1. 找到项目需要什么模型

一般我们只要通过pycharm的搜索功能（按三次Shift键）去找，以下关键字

BertTokenizer	#类名
from_pretrained	#方法名，这个比较好用
tokenizer
tokenizer = BertTokenizer.from_pretrained("模型名字或模型安装位置") #为模型名就通过访问默认安装位置或网络下载，为安装位置就是要先下载模型到本地然后通过本地模型位置访问

然后可以看到
每一个都看过之后发现，主要在这两个地方有
（1）第一个是把获取模型封装成了一个函数，里面指明了模型roberta
（2）第二个是在一个config.py文件下有一个tokenizer指明了模型，bert-base-uncased

2. 知道huggingface模型的安装目录

在Linux中huggingface模型一般自动下载在当前用户主目录下的 .cache/huggingface目录下的hub中。

~/.cache/huggingface/

具体样子是这样的，可以看一下下载的roberta-base模型

3. Huggingface国内开源镜像：https://hf-mirror.com/

使用官方huggingface-cli工具

1. 安装依赖

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

创建项目的虚拟环境后，虚拟环境python版本一定要>=3.9，激活该环境并执行：

pip install -U huggingface_hub

安装完成后可以运行
huggingface-cli download --h
命令来查看download功能的参数，如下图

2. 设置环境变量

• Linux

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

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

vim ~/.bashrc
export HF_ENDPOINT=https://hf-mirror.com
source ~/.bashrc	#更新一下bashrc

3. 下载模型

以下载roberta模型为例，现在huggingface官网或者hf-mirror.com找到想要的模型完整的名字。可以看到有很多我们就找自己要的就行一般项目里有写，如果没写就一般都是找比较有名的如这里的FacebookAI。

运行以下命令

运行以下命令

huggingface-cli download  roberta-base --local-dir ./bert

huggingface-cli download 模型名 --local-dir 下载位置 #最好自己指定目录这样后面调用时好找，eg：tokenizer = BertTokenizer.from_pretrained("模型下载位置") 
huggingface-cli download 模型名	#没有下载位置默认安装在上面说的huggingface的hub目录中

1.**可选参数
--local-dir-use-symlinks False
**，【请注意，v0.23.0开始加 --local-dir 时默认会关闭符号链接，可以用 True 改回来】
关闭符号链接，但我不太喜欢关闭符号链接，因为符号链接其最大方便点在于，调用时可以无论在哪个目录都可以通过直接使用模型名来引用模型，而非指定模型路径，默认符号链接是打开的不用指定。但这里最好还是用绝对路径比较好因为试了几次用模型名读取不到，用绝对路径可以读取得到
如果想使用可以输入

huggingface-cli download --local-dir-use-symlinks False 模型名 --local-dir 下载路径
huggingface-cli download --local-dir-use-symlinks False bert-base-uncased --local-dir ./bert

下载完成后是这样的

#之后引用就改为
AutoModelForCausalLM.from_pretrained("./bert")

现在因为huggingface的工具链默认会使用符号链接来存储下载的文件，导致v0.23.0之前版本使用
--local-dir
指定下载目录里下载的都是一些“链接文件”，真实模型则存储在
~/.cache/huggingface
下，如果不喜欢这个可以用
--local-dir-use-symlinks False
不用这个参数。
我们知道，
from_pretrain
函数可以接收一个模型的id，也可以接收模型的存储路径。
假如我们自己直接在网络上下载了huggingface中的一个模型，存储到服务器的
/data/gpt2
下了，调用的时候你得写模型的绝对路径来调用

AutoModelForCausalLM.from_pretrained("/data/gpt2")

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

AutoModelForCausalLM.from_pretrained("gpt2")

原理是因为huggingface工具链会在
.cache/huggingface/
下维护一份模型的符号链接，无论你是否指定了模型的存储路径 ，缓存目录下都会链接过去，这样可以避免自己忘了自己曾经下过某个模型，此外调用的时候就很方便。
所以用了官方工具，既可以方便的用模型名引用模型，又可以自己把模型集中存在一个自定义的路径，方便管理。
可选参数 --resume-download
【更新：huggingface_hub v0.23.0 已弃用
--resume-download
参数，现在默认断点续传】
通过添加该参数，huggingface-cli的下载可断点续传，可以恢复上次因主动取消或网络波动异常退出的未完成的下载。
3.如果是下载数据集可以用这个

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

其他常见问题:

Q1: 有些项目需要登录，如何下载？

A：部分 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

hfd： 添加
--hf_username``--hf_token
参数

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

其余如
from_pretrained
、
wget
、
curl
如何设置认证 token。