如何优雅地下载 Hugging Face 模型

Hugging Face 已经成为事实上的开源模型分发中心，无论是 NLP、CV 还是多模态模型，几乎都可以通过一个 model id 直接获取完整权重与配置文件。

本文将系统介绍 推荐的 Hugging Face 模型下载方式，并解释为什么有些方法不推荐，有些方法则更优雅、更工程化。

---

下载方法

直接在网页页面点击下载（不推荐）

很多人在第一次接触 Hugging Face 时，会直接打开模型页面，在 Files and versions 中逐个点击下载文件。

这种方式存在明显问题：

• 每次只能下载一个文件，大模型往往包含几十个文件
• 不支持断点续传，网络稍有波动就可能失败
• 容易遗漏关键文件（如 tokenizer、config）
• 完全不适合自动化与工程使用

因此，这种方式只适合临时查看模型的配置文件内容或下载极小文件，不推荐作为正式下载方案。

---

使用 git lfs clone 下载模型（不推荐作为常规方案）

在 Hugging Face 的模型页面中，官方仍然提供了如下方式：

git lfs clone https://huggingface.co/Qwen/Qwen3-8B

但实际使用中并不推荐这样做。

git lfs clone 的适用场景

需要明确的是，Hugging Face 的模型仓库本质上是 Git + Git LFS，因此 git lfs clone 在以下场景下仍然合理：

• 模型作者或维护者
• 需要查看、修改仓库结构
• 需要提交 PR 或管理分支
• 希望完整保留 Git 历史与版本控制

git lfs clone 的局限性

但对于绝大多数模型使用者来说，这种方式并不理想：

• 会下载完整仓库内容，而不仅是运行所需文件
• 与 from_pretrained 的缓存体系不兼容
• 国内网络环境下 Git LFS 失败率较高

因此，git lfs clone 更适合作为开发者的模型维护工具，而不是用户的模型下载工具。

---

使用 hf 工具下载模型（推荐）

hf 工具简介

不少旧教程仍然在使用：

huggingface-cli download ...

但需要明确的是：

• huggingface-cli 已经进入维护期
• 命令结构不统一，可发现性差
• 新功能不会优先接入

2025 年起，官方推荐统一使用新的 hf 命令行工具。

hf 工具的命令按“资源”（hf auth, hf cache, hf repo 等）分组。HuggingFace还将 hf upload 和 hf download 放在根级别，因为它们预计是使用最频繁的命令

安装方式

hf 工具与旧 CLI 共用同一套依赖：

pip install -U "huggingface_hub[cli]"

使用 hf download 下载模型

hf download Qwen/Qwen3-8B

该命令会：

• 自动解析模型结构
• 下载所有必要文件
• 支持断点续传与校验
• 将模型存入 Hugging Face 全局缓存

如果希望下载到指定目录：

hf download Qwen/Qwen3-8B --local-dir 指定目录的路径地址

在代码中使用 from_pretrained 自动下载（推荐）

在实际工程中，最推荐的方式是让代码自行管理模型下载，使用AutoModel类的from_pretrained方法，在其中填入model id，即可自动下载模型：

from transformers import AutoModelForCausalLM, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-7B")
model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-7B")

这种方式具备以下优点：

• 代码即配置
• 自动复用缓存
• 天然支持镜像站
• 易于复现与部署

在大多数场景下，你甚至不需要关心模型是否已经下载。

---

模型存储位置

Hugging Face 模型的默认下载位置

无论使用 hf download，还是在代码中调用 from_pretrained，模型默认都会被存储在：

~/.cache/huggingface/hub

这是 Hugging Face 统一的缓存目录，能够实现：

• 模型文件去重
• 多项目复用
• 避免重复下载

---

自定义模型下载目录

如果不想下载到默认目录下，可以通过环境变量 HF_HOME修改HuggingFace的资源存储默认路径：

export HF_HOME=/data/huggingface

或仅修改模型缓存目录 HF_HUB_CACHE：

export HF_HUB_CACHE=/data/huggingface/hub

设置后，所有 Hugging Face 相关工具都会自动使用新的路径。

---

配置镜像网站

在国内网络环境下，直接使用 huggingface.co 经常会遇到加载缓慢、下载失败等问题。

为此，可以通过设置环境变量 HF_ENDPOINT的方式，使用 Hugging Face 镜像站点来加速下载，hf-mirror就是一个最常用的镜像站点：

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

设置后：

• hf 命令行工具
• from_pretrained
• huggingface_hub

的所有下载行为

都会自动走镜像地址，对现有代码几乎没有影响。

具体用法可以参考：https://hf-mirror.com

---

身份认证

如果你需要下载：

• 私有模型
• 需要授权的模型（如部分 LLaMA 系列）

需要先使用以下命令登录你的HuggingFace账号：

hf auth login

登录成功后登录信息会被统一存储，并被 CLI 与 Python API 共享，之后无需再次登录。

小结

综合来看，下载 Hugging Face 模型的推荐实践是：

• 不使用网页手动下载
• 避免将 git lfs clone 作为常规下载方式
• 使用新版 hf download 命令
• 在工程中优先使用 from_pretrained 方法
• 国内环境配置 HF_ENDPOINT