当前位置：首页 > news >正文

huggingface下载数据和模型，部分下载，本地缓存等常见问题踩坑

news 2025/7/4 19:07:04

huggingface

注：系统环境为windows11 23H2，macOS和Linux用户可以查看下【参考】里的链接文档，差异不大

安装huggingface-cli

虽然可以通过代码下载模型和数据集（下文会提及），但我依然推荐你用此方法来管理和下载，更直观可控一些。
pip install huggingface-cli 将hugginface-cli安装到全局的python环境下，这样打开terminal就能直接使用命令。

可选：修改huggingface镜像地址和缓存地址

win+r 搜索 修改系统环境变量(或者edit system variables 在用户变量或者系统变量分区下添加如下新变量：
HF_HOME=F:\hf_home （huggingface根地址）
HF_DATASETS_CACHE = F:\hf_home\datasets （数据集的存放地址，之后也会再说明）
HF_ENDPOINT=https://hf-mirror.com （镜像地址，新的模型同步需要时间）
HF_HUB_DOWNLOAD_TIMEOUT=60 （超时重试间隔，秒数）

预下载

以whisper-small为例，在网页点击按钮复制完整模型名，
在这里插入图片描述
terminal中输入命令下载：
huggingface-cli download --resume-download openai/whisper-small
下载数据集的命令：
huggingface-cli download --resume-download --repo-type dataset mozilla-foundation/common_voice_13_0

等待下载完成，就可以在ollaMA或者脚本里直接使用下载好的模型了。

边用边下载

模型

from huggingface_hub import hf_hub_download
import joblibmodel = joblib.load(hf_hub_download(repo_id='openai/whisper-small', repo_type="model", local_dir="./downloaded_models", filename='model.safetensors')
)
''' 加入local_dir可以指定下载位置：如 model = joblib.load(hf_hub_download(repo_id='openai/whisper-small', repo_type="model", local_dir="./downloaded_models", filename='model.safetensors'))'''

数据集

from huggingface_hub.hf_api import HfFolder
from huggingface_hub import snapshot_downloadsnapshot_download(repo_id="mozilla-foundation/common_voice_13_0", force_download=True, repo_type="dataset")

只下载&加载部分数据集

有的数据集非常之大但我们只需要部分进行训练，例如commonvoice包含了几百种世界语言，但我想使用单语言（如中文或者英文）的语音文件（全部下载大约需要500g以上）

from datasets import load_datasetcache_dir = "F:/hf_home/datasets"  # 这里指定了dataset的缓存目录，和上文提到的HF_DATASETS_CACHE 系统环境变量一致common_voice['train'] = load_dataset('mozilla-foundation/common_voice_13_0', 'en', split='train+validation', trust_remote_code=True, cache_dir=cache_dir, data_files="audio/en/*", download_mode="reuse_cache_if_exists" )
common_voice['test'] = load_dataset('mozilla-foundation/common_voice_13_0', 'en', split='test', trust_remote_code=True, cache_dir=cache_dir, data_files="audio/en/*", download_mode="reuse_cache_if_exists")

另外，有的数据集下载前需要登录huggngface账号，先前往HF个人资料在token设置页创建一个只读的token，
在这里插入图片描述
获取到token值，如hf_abc12345efg 后在snapshot_download 执行前新建一行：

hf_token = HfFolder.save_token('hf_abc12345efg')

使用命令行下载时候先huggingface-cli login 输入token登录后再下载即可，token会存储在%hf_home% 下同名文件里。

下载之后的数据集和模型在哪儿？

模型还好32b的ds也不过几十G，数据集动辄几十甚至上百g接近1T 不是小数目，这里我做了大概的总结，反复删除下载的确是个恼人的工作。
这里我做了大概总结，没什么必要的东西就可以删掉节约空间了。

如果你没按我先前说的修改huggingface根地址，那么你的数据集和模型都会下载到：C:\Users\用户名\.cache\huggingface，这就是 %hf_home%。也可以在资源管理器使用 %hf_home% 直接访问hf根目录：

模型
这个位置是固定的，一直在%hf_home%/models 下除非你手动修改下载模型到的地址：
如 F:\hf_home\hub\models--openai--whisper-small
数据集
这里有两个目录，一个用来存放真正的（未解压的数据集），均以mozzila/commonvoice/en/* 为例，即只下载和加载部分数据集
- 通过cli下载的模型，和模型一样放在%hf_home%/hub/ 下，如F:\hf_home\hub\datasets--distil-whisper--librispeech_long
- 未解压的数据集：%hf_home%/datasets/downloads/extracted/... (这里不能确定具体的文件）
- 解压的数据集（在加载过程中会越来越大，删掉的话下次load会重新生成）：%hf_home%/datasets//mozilla-foundation___common_voice_13_0/en-93cf6a7a474e4b7d/