从Huggingface下载大模型到本地

欢迎使用 huggingface 国内镜像站

畅游星辰大海

9842人浏览 · 2024-08-12 23:53:56

畅游星辰大海 · 2024-08-12 23:53:56 发布

由于网络环境问题，我们并不能流畅访问 Huggingface 官网，并且很多 Linux 服务器在没有 root 权限的情况下也没办法自行安装加速工具
本篇教程在遵守法规的情况下，主要解决两个痛点：

高速下载 Huggingface 上的大模型或数据集
大模型动辄几十 GB，解决模型默认下载到 C盘（Win）或者系统盘（Linux）而引起的存储不足的情况

准备工作

pip install diffusers transformers accelerate -i https://pypi.tuna.tsinghua.edu.cn/simple

一、使用 python 代码下载

函数	效果
`from_pretrained`	模型加载函数，没下载的情况下可以无感下载
`snapshot_download`	专门的下载函数

from_pretrained：在你使用 diffusers，transformers等库的时候，此方法最为便捷加载模型。跑项目时遇见的相当多的报错都是此函数方法引起，（例如https://huggingface.co/连接超时），
原因：此函数方法会在默认路径下读取模型缓存，如果没有缓存，则会从https://huggingface.co/官网去下载。外网原因，可以挂梯子下载或者使用国内镜像站。

例如我们使用 stable-diffusion-v1-5模型来生成图像,会默认下载到用户目录--> .cache中，其他的from_pretrained用法基本相同

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

# 一定要在引用diffusers, transformers相关库之前使用以上环境变量
from diffusers import StableDiffusionPipeline
import torch

model_id = "runwayml/stable-diffusion-v1-5"
# 此方法只会下载加载pipeline所需要的模型，简单快捷
pipe = StableDiffusionPipeline.from_pretrained(model_id,        # 必选，可填入模型的仓库ID，或者已经下载好的模型的路径
                                               torch_dtype=torch.float16,   # 可选，设置为torch.float16时，显著减少GPU显存占用，加快推理速度
                                               cache_dir="填入预想缓存模型的位置",     # 可选，第一次运行后会将模型下载到你指定的位置
                                               force_download=False,    # 可选，默认为False，设置为True时，即使缓存模型存在，也会重新下载
                                               use_safetensors=False,  # 可选，默认为False，使用bin结尾的权重，为True时，使用safetensors结尾的权重
                                               variant=None,    # 可选，fp16, ema类型的权重，使用名称中含相关字样的权重加载
                                               )
pipe = pipe.to("cuda")

prompt = "a photo of an astronaut riding a horse on mars"
image = pipe(prompt).images[0]

image.save("astronaut_rides_horse.png")

注意：部分仓库模型文件很大，而且相同作用的文件以多种格式存储，例如 stable-diffusion-v1-5的 Unet 组件里相同的权重，以 6 种不同的格式展现，可以灵活的使用variant和use_safetensors两个变量控制，两变量都为 False 时，默认使用 bin 格式的模型

如果你想研究使用模型、或者并知道哪个文件重要，可以获取仓库中的全部文件，使用以下几种专门的下载方法

from huggingface_hub import snapshot_download

snapshot_download(repo_id=model_id,     # 必选，模型或数据集仓库ID
                  repo_type="model",  # 可选参数，默认为model，可选 dataset, space
                  revision="main",  # 可选参数，模型版本，默认为main
                  cache_dir="填入预想缓存模型的位置",  # 可选参数，如果指定了cache_dir，则将模型下载到该目录
                  local_dir="填入预想缓存模型的位置",  # 可选参数，如果指定了local_dir，则将模型下载到该目录
                  force_download=False, # 可选参数，默认为False，设置为True时，即使缓存模型存在，也会重新下载
                  allow_patterns=None,    # 可选列表或者字符串，默认为空，只下载指定格式的文件
                  ignore_patterns=None,    # 可选列表或者字符串，默认为空，忽略下载指定格式的文件
                  )

# 示例
import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'

from huggingface_hub import snapshot_download


model_id = "runwayml/stable-diffusion-v1-5"
snapshot_download(repo_id=model_id,     # 必选，模型或数据集仓库ID
                  repo_type="model",  # 可选参数，默认为model，可选 dataset, space
                  revision="main",  # 可选参数，模型版本，默认为main
                  cache_dir=None,  # 可选参数，如果指定了cache_dir，则将模型下载到该目录
                  local_dir="./model",  # 可选参数，将模型下载到 model 文件夹下
                  force_download=False, # 可选参数，默认为False，设置为True时，即使缓存模型存在，也会重新下载
                  allow_patterns=None,    # 可选
                  ignore_patterns=["*.ckpt", "*.bin"],    # 忽略仓库中以ckpt和bin结尾的文件
                  )

注意：
local_dir 和 cache_dir有何不同，官方这样解释

如果提供了local_dir参数，那么仓库中的文件结构将在该位置被复制。使用这个选项时，将不会使用cache_dir参数，而是在local_dir的根目录下创建一个.cache/huggingface/文件夹，用于存储与下载文件相关的一些元数据。虽然这种机制没有主缓存系统那样强大，但它是为定期拉取仓库的最新版本而优化的。

经过我的实践证明下载到local_dir的中的模型结构和原 huggingface 仓库文件结构基本一致，因此更推荐使用local_dir

二、使用命令行下载

只要成功安装了文章开始的三个包，即可在终端使用命令行下载模型或者数据集

# MacOS or Linux
export HF_ENDPOINT="https://hf-mirror.com"
# Windows Powershell
$env:HF_ENDPOINT = "https://hf-mirror.com"

# 下载stable-diffusion-v1-5 到models文件夹
huggingface-cli download runwayml/stable-diffusion-v1-5 --local-dir ./models

其余参数

# 一下参数和snapshot_download()函数的参数用法基本相同，不再重复介绍
--repo-type {model,dataset,space}
--revision REVISION
--include [INCLUDE ...]
--exclude [EXCLUDE ...] 
--cache-dir CACHE_DIR
--local-dir LOCAL_DIR
--local-dir-use-symlinks {auto,True,False}
--force-download
--resume-download 
--token TOKEN
--quiet

三、专属的 LInux 脚本下载

基于 git+aria2，由 huggingface 镜像站站长开发，速度极快基本上可以跑满带宽，默认下载到运行此脚本的同级目录

wget https://hf-mirror.com/hfd/hfd.sh

chmod a+x hfd.sh

apt update
apt install -y aria2 git-lfs

示例

# MacOS or Linux
export HF_ENDPOINT="https://hf-mirror.com"
# 下载模型
./hfd.sh runwayml/stable-diffusion-v1-5 --tool aria2c -x 16 --include *.ckpt
# 下载数据集
./hfd.sh wikitext --dataset --tool aria2c -x 8

参数	说明
model_id	Hugging Face 模型 ID，格式为 `repo/model_name`。
–include	（可选）用于指定要下载的文件其文件名的模式，即名称符合此处指定的字符串模式的文件都将被下载。
–exclude	（可选）用于指定不下载的文件其文件名的模式，即名称符合该字符串模式的文件都不下载，只下载该模型下的其他文件。
–hf_username	（可选）Hugging Face 用户名，用于身份验证。
–hf_token	（可选）Hugging Face 令牌，用于身份验证。
–tool	（可选）使用的下载工具。默认为 weget，可使用该参数指定为 aria2c。指定为 aria2c 时可接 -x 指定下载线程数。
–dataset	（可选）标志，表示下载数据集。