Python 比较huggingface_hub库的hf_hub_download函数和snapshot_download函数

梳理 hf_hub_download 和 snapshot_download 的区别、相同点,以及各自适合的场景。


1. 相同点

  1. 都来自 huggingface_hub

    python 复制代码
    from huggingface_hub import hf_hub_download, snapshot_download
  2. 都用于下载 Hugging Face Hub 上的模型或文件

    • 都可以指定 repo_id(仓库名)、revision(分支/commit/tag)等参数。
    • 都支持设置缓存目录 cache_dir。
    • 都可以配合 proxies 或国内镜像使用。
  3. 缓存机制相同

    • 下载后的文件会缓存在 HF_HOME 或指定 cache_dir 中。
    • 如果文件已经存在缓存中,下次直接读取,无需重新下载。

2. 不同点

特性 hf_hub_download snapshot_download
下载粒度 单个文件 仓库快照(整个模型目录)
返回值 本地文件路径 仓库本地路径(目录)
适合场景 只想下载仓库中的单个文件,比如 model.safetensors 或 config.json 想获取整个仓库内容,包括多个文件、权重、tokenizer、配置等
使用方法 python local_file = hf_hub_download(repo_id, filename) python local_dir = snapshot_download(repo_id)
耗时 快(只下载一个文件) 慢(下载整个仓库)
存储空间 小 大

3. 场景示例

hf_hub_download

python 复制代码
from huggingface_hub import hf_hub_download

# 下载单个模型权重文件
local_file = hf_hub_download(
    repo_id="bert-base-uncased",
    filename="pytorch_model.bin",
    cache_dir="/home/user/.cache/huggingface/hub"
)

✅ 场景:

  • 只需要模型权重或 tokenizer 文件。
  • 快速下载一个文件,不需要整个仓库。
  • 适合自定义加载模型时使用(如 FastLanguageModel.from_pretrained(local_file))。

snapshot_download

python 复制代码
from huggingface_hub import snapshot_download

# 下载整个仓库快照
local_dir = snapshot_download(
    repo_id="bert-base-uncased",
    cache_dir="/home/user/.cache/huggingface/hub"
)

✅ 场景:

  • 需要整个模型仓库,包括 config.json、tokenizer 文件、权重文件等。

  • 想离线完整使用模型,或者需要对多个文件进行统一管理。

  • 适合加载 Transformers 模型时直接传目录:

    python 复制代码
    from transformers import AutoModel
    model = AutoModel.from_pretrained(local_dir)

4. 小结

  • hf_hub_download → 下载单个文件,速度快,适合下载模型权重或配置文件。
  • snapshot_download → 下载整个仓库,完整快照,适合一次性获取整个模型目录用于离线或批量操作。

5. example

使用国内镜像下载模型

python 复制代码
import os
from huggingface_hub import snapshot_download
from unsloth.models import FastLanguageModel

# -------------------------------
# 1. 设置缓存目录和镜像
# -------------------------------
os.environ["HF_HOME"] ="/home/xjg/.cache/huggingface/hub"  # 可自定义缓存路径
os.environ["HF_DATASETS_OFFLINE"] = "1"     # 只从本地缓存读取数据集,不访问网络
os.environ["TRANSFORMERS_OFFLINE"] = "0"    # "0" 表示在线模式;如果设置为 "1",transformers 会只从本地缓存加载模型


# 国内 Hugging Face 官方 CDN 镜像(无需代理)
HF_ENDPOINT = "https://hf-mirror.com/"

# -------------------------------
# 2. 下载模型到本地
# -------------------------------
model_name = "unsloth/DeepSeek-R1-Distill-Qwen-1.5B-unsloth-bnb-4bit"
filename = "model.safetensors"

# 使用 snapshot_download 下载整个模型目录
local_model_dir = snapshot_download(
    repo_id=model_name,
    cache_dir=os.environ["HF_HOME"],
    use_auth_token=None,  # 如果是私有模型,需要填入 token
    endpoint=HF_ENDPOINT
)
print(f"模型下载到本地目录:{local_model_dir}")


# -------------------------------
# 3. 从本地加载模型和分词器
# -------------------------------
max_seq_length = 2048
dtype = "float16"
load_in_4bit = True

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name=local_model_dir,
    max_seq_length=max_seq_length,
    dtype=dtype,
    load_in_4bit=load_in_4bit
)

print("模型和分词器加载成功!")

输出结果:

python 复制代码
🦥 Unsloth: Will patch your computer to enable 2x faster free finetuning.
🦥 Unsloth Zoo will now patch everything to make training faster!
Fetching 8 files: 100%|███████████████████████████████████████████████████████████████| 8/8 [00:00<00:00, 56299.38it/s]
模型下载到本地目录:/home/xjg/.cache/huggingface/hub/models--unsloth--DeepSeek-R1-Distill-Qwen-1.5B-unsloth-bnb-4bit/snapshots/c93b549ceae3f8137b567af565c2b204b3045091
==((====))==  Unsloth 2025.8.5: Fast Qwen2 patching. Transformers: 4.55.2.
   \\   /|    NVIDIA GeForce RTX 3060 Laptop GPU. Num GPUs = 1. Max memory: 5.799 GB. Platform: Linux.
O^O/ \_/ \    Torch: 2.7.1+cu126. CUDA: 8.6. CUDA Toolkit: 12.6. Triton: 3.3.1
\        /    Bfloat16 = TRUE. FA [Xformers = 0.0.31.post1. FA2 = False]
 "-____-"     Free license: http://github.com/unslothai/unsloth
Unsloth: Fast downloading is enabled - ignore downloading bars which are red colored!
模型和分词器加载成功!
相关推荐
TomEval2 小时前
【测AI】第26篇:线上模型监控与告警体系 — 测试不是终点
人工智能·python·功能测试·ai
prince_zxill3 小时前
PEP 751 pylock.toml 实测:pip 26.3 装 6 个包版本全钉死,但 [web] 选不中任何东西
python·pip·依赖管理·pep 751
ShineWinsu4 小时前
对于Qt:QFormLayout常见属性以及方法的解析
开发语言·c++·qt·面试·客户端·表单·qformlayout
Thanks_ks4 小时前
Python 的垃圾回收——引用计数撑起日常,分代回收收拾残局
python·内存管理·垃圾回收·循环引用·引用计数·gc 模块·weakref
CyrusYiVPP5 小时前
实测 uv 0.13.7:同一套包,pip 装 94 秒,它只用 19 秒
人工智能·python
yiangL_5 小时前
Python 学习笔记:递归、turtle绘图、字符串与函数
笔记·python·学习
lula8886 小时前
PVC-U、PVC-C、PVC-O 差一个字母,差的是三种增强路线
python
数字工作台7 小时前
给 LangGraph 加一道可审计记忆:替换默认 Checkpointer,实现防篡改 + 崩溃不丢数据
python·agent
DKPT8 小时前
Python 的 Web 框架:选型选错的人,都踩了同一个坑
python
2401_868534788 小时前
逻辑网络设计
网络·python