【保姆级喂饭教程】【抽丝剥茧知识讲解】2025年最新Windows从Hugging Face下载模型全部方法总结

前言

AI开发绕不过一个问题是，如何从hugging face下载模型/数据集，由于众所周知的原因，访问和下载需要科学上网，还不稳定，总是下载失败。大部分教程都比较专业，即使命令比较详细，从0开始的新手可能也不知道在哪使用，许多命令还不区分Windows和Linux和mac，也缺少图片的指示。
本教程选取几个常用和简单的方法下载模型，以bert模型为例

环境版本

• 操作系统：Windows 10 专业版
• pycharm：PyCharm 2022.3.2 (Professional Edition)
• uv：0.8.3
• python：3.11.13

【保姆级喂饭教程】uv教程一文讲透：安装，创建，配置，工具，命令

一、手动下载

同GitHub一样，hugging face就是一个在线仓库，既可通过网页点击下载链接下载，也可以通过命令下载。因为模型不是一个单独的项目，是用在项目中的，所以多出来的一种是可以通过python代码下载。
先通过手动下载简单了解一下hugging face，此方法需要科学上网。

1. 在线下载

打开hugging face官网，最顶部是导航栏，最核心的就是models（模型）和Datasets（数据集），下方右边有一个热点榜单，还可以看到openai最新开源的gpt-oss-20b和gpt-oss-120b
https://huggingface.co/
先点击models进入专门的页面

在模型页面，左边是筛选区域，可以按照任务类型、参数量，框架库、应用平台等分类进行筛选
右边是模型区域，最上方动态匹配，输入后会自动过滤，这里我们选择google-bert/bert-base-chinese

页面内有模型的详细介绍，右上角的Use This Model提供了使用代码和下载代码，下方是当前模型衍生出的适配器、微调模型、量化模型，我们点击Files and versions查看模型文件

可以看到仓库有好多文件

简单介绍一下

文件名	作用	是否必须下载
.gitattributes	Git LFS 的元数据，告诉服务器这些文件用 LFS 存储，对实际使用无影响	❌ 不需要
README.md	模型介绍、用法示例、引用格式等，纯文档	❌ 可选
config.json	模型结构配置（隐藏层大小、注意力头数、词表大小等），加载模型时必须	✅ 必须
flax_model.msgpack	JAX/Flax 框架的权重（.msgpack 格式）	❌ 仅当你用 JAX/Flax 才下
model.safetensors	与 pytorch_model.bin 等价的 safetensors 格式 权重；官方推荐的新格式，加载更快、更安全	✅ 推荐（与 .bin 二选一即可）
pytorch_model.bin	PyTorch 原生 .bin 权重；与 model.safetensors 功能重复	✅ 推荐（与 .safetensors 二选一即可）
tf_model.h5	TensorFlow/Keras 的 .h5 权重	❌ 仅当你用 TF/Keras 才下
tokenizer.json	分词器的核心实现（包含 BPE/SentencePiece 等算法和词表）	✅ 必须
tokenizer_config.json	分词器的超参与特殊标记定义（如 [CLS]、[SEP]）	✅ 必须
vocab.txt	纯文本格式的词汇表（BERT 中文用字级别 vocab，共 21128 行）	✅ 必须

不同模型的文件不同，但是必须下载的5个文件是一致的：

• config.json：模型结构配置文件（隐藏层大小、注意力头数、词表大小等）
• model.safetensors：模型权重文件，或 pytorch_model.bin，两者选其一即可
• tokenizer.json：分词器的核心实现（包含 BPE/SentencePiece 等算法和词表）
• tokenizer_config.json：分词器特殊配置文件
• vocab.txt：纯文本格式的词汇表

特殊情况-模型权重文件：

• 用 TF 就再下 tf_model.h5；
• 用 JAX 就再下 flax_model.msgpack；否则忽略。

找到必须下载的五个文件，点击右边的下载按钮

打开vpn下载还是很快的，400m的权重文件也就几十秒，下载后如图

在项目中创建目录后移动过去

给大家展示下文件内容

1.1 config.json

1.2 model.safetensors

1.3 tokenizer.json

1.4 tokenizer_config.json

1.5 vocab.txt

2. idm下载

浏览器默认采用单线程下载，由于国内网络运营商线路质量、QoS等因素有时候会很慢，多线程加速是一种有效、显著提高下载速度的方法。
Windows经典多线程工具是IDM，右键下载图标，选择复制链接，之后可以在idm里面进行下载，此处暂不展示。

二、代码和命令行下载

手动下载毕竟不优雅，文件多了操作麻烦，hugging face的huggingface_hub库提供了两种下载器，由此又衍生出两种方法，下面一一介绍下，此方法也需要科学上网。

从 HuggingFace Hub 下载文件官方文档
【AI翻译】从 HuggingFace Hub 下载文件官方文档
【技术变迁脉络解析】一文带你彻底搞懂 Transformer、Transformers、Hugging Face 与 huggingface-hub，以及发展历史

首先要安装huggingface-hub库

uv add huggingface-hub

目前最新版为0.34.3

huggingface-hub提供了

• hf_hub_download：用于下载单个指定文件
• snapshot_download：用于下载整个模型库文件，基于hf_hub_download

维度	snapshot_download	hf_hub_download
作用域	整个 repo（可过滤）	单个文件
主要参数	repo_id, revision, allow_patterns, ignore_patterns, local_dir 等	repo_id, filename, subfolder, revision, local_dir
返回值	本地目录路径（字符串）	该文件的缓存绝对路径（字符串）
内部实现	循环调用 hf_hub_download 并发下载多个文件	直接下载并缓存单个文件
典型场景	离线部署、CI/CD、一次性缓存完整模型/数据集	仅下载权重或配置文件，脚本按需取用
并发	支持 max_workers 并发下载	仅单文件，无并发
示例	snapshot_download("bert-base-chinese") → 目录	hf_hub_download("bert-base-chinese", filename="config.json") → 文件路径

1. hf_hub_download

hf_hub_download是hugging face提供的最基础的下载方法，用于下载单个文件，也是其他所有下载方法的底层实现

1.1 介绍

hugging face doc官网：huggingface_hub.hf_hub_download

实现代码可以在虚拟环境的库文件中进行查看：
.venv -> Lib -> site-packages -> huggingface_hub -> file_download.py(812行) -> def hf_hub_download()

给注释翻译总结一下：

参数	类型	默认值	中文释义
函数描述	-	-	若本地缓存不存在指定文件，则下载；返回本地文件路径。
缓存结构示例	-	-	models--用户--仓库/ ├─ blobs/：真实文件块（按 git-sha 或 sha256 命名） ├─ refs/：最新 commit 指针 └─ snapshots/：每个 commit 的软链视图
local_dir 行为	-	-	若指定 local_dir，不再用默认缓存，而是把仓库目录结构原样复制到该目录；同时在根目录生成 .cache/huggingface/ 存放元数据。
repo_id	str	-	组织或用户名与仓库名，如 google-bert/bert-base-chinese
filename	str	-	仓库内要下载的文件名
subfolder	str | optional	-	仓库中的子目录路径
repo_type	str | optional	None	"dataset"、"space"、"model" 之一
revision	str | optional	-	分支名、标签或 commit hash
library_name	str | optional	-	对应库的名称
library_version	str | optional	-	对应库的版本
cache_dir	str | Path | optional	-	自定义缓存根目录
local_dir	str | Path | optional	-	自定义落盘目录（会复制仓库结构）
user_agent	dict | str | optional	-	自定义 User-Agent
force_download	bool | optional	False	强制重新下载，即使已存在
proxies	dict | optional	-	字典映射协议到传递给代理的 URL requests.request 中。
etag_timeout	float | optional	10	获取 ETag 时的超时秒数
token	str | bool | optional	-	访问令牌；True 读本地配置，字符串则直接作为 token
local_files_only	bool | optional	False	仅使用本地缓存，不联网下载
headers	dict | optional	-	额外请求头
返回值	str	-	本地文件绝对路径，或在离线模式下返回缓存中旧版本路径
可能抛出的异常	-	-	RepositoryNotFoundError（仓库不存在或无权限） RevisionNotFoundError（指定版本不存在） EntryNotFoundError（指定文件不存在） LocalEntryNotFoundError（离线且本地无缓存） EnvironmentError（未找到 token） OSError（无法获取 ETag） ValueError（参数非法）

1.2 示例

使用示例：

from huggingface_hub import hf_hub_download
path = hf_hub_download(
    repo_id="google-bert/bert-base-chinese", # 组织/模型名称
    filename="config.json" # 文件名称
)
print(path)

右键run运行，先不开vpn试试


打开vpn下载成功，hf_hub_download会返回文件绝对路径

有时候有意外情况，没有走VPN，可以显示声明一下

import os
# 把 7897 换成你自己的代理端口。
os.environ["HTTP_PROXY"] = "http://127.0.0.1:7897"
os.environ["HTTPS_PROXY"] = "http://127.0.0.1:7897"

用tree命令查看缓存目录：

tree /F C:\Users\Alien\.cache\huggingface

1.3 缓存格式

插播一句，为什么hugging face的缓存格式这样设置呢，不设置成目录下就是文件名呢？
官方-缓存文件说明文档

一句话： Hugging Face 把文件按内容-hash 存储，再用软链/“视图”提供人类文件名，是为了“内容去重 + 多版本共存 + 断点续传”。

详细原因：

1. 去重
   同一权重文件（如 pytorch_model.bin）在多个版本里往往完全一样，按 hash 存只需保留一份实体，节省磁盘。
2. 多版本共存
   每个 commit（或 tag、branch）只需在 snapshots/<commit>/ 里放软链指向实体；切换版本时只改链接，不复制文件。
3. 断点续传 & 完整性校验
   下载前比本地 hash 与服务器 ETag，若一致直接跳过；若中断，下次继续只下缺失块。
4. 兼容 Git-LFS 语义
   这种“blob + ref + snapshot”三层结构正是 Git-LFS 的做法，方便后续 git clone 也能识别。
5. 软链/视图开销极低
   .cache/huggingface/ 通常只有几十 KB 的索引和软链，不会带来额外磁盘压力。

1.4 修改目录

由于默认在c盘，但我习惯把下载目录和工作目录都放到d盘，添加一个local_dir参数

from huggingface_hub import hf_hub_download
path = hf_hub_download(
    repo_id="google-bert/bert-base-chinese", # 组织/模型名称
    filename="config.json", # 文件名称
    # 路径字符串前面要加r，声明后面的字符串是普通字符串，否则 \u 会识别成ASCII编码的开头，其他转义字符 \n \t
    local_dir=r"D:\Data\WorkSpace\PyCharm\Test\uv-test\models\hf_hub" # 下载目录，个人推荐配置，不想下载到默认的c盘
)

会直接下载到设置的目录，创建.cache/huggingface，但是下载其他模型的config文件会覆盖之前的

原来是有一个参数local_dir_use_symlinks可以选择是否生成缓存那样的符号连接，现在已经废弃了，不再依赖符号链接

这样不同模型的文件会相互覆盖，肯定不行，两种优化方法

• 方案A：可以通过设置环境变量解决：

import os
os.environ["HF_HOME"] = r"D:\Data\WorkSpace\PyCharm\Test\uv-test\models\hf_hub" # 设置模型路径

from huggingface_hub import hf_hub_download
path = hf_hub_download(
    repo_id="google-bert/bert-base-chinese", # 组织/模型名称
    filename="config.json" # 文件名称
)
print(path)

补充，后面发现直接用cache_dir参数设置缓存目录就可以，还不会多创建一层hub文件夹

from huggingface_hub import hf_hub_download
path = hf_hub_download(
    repo_id="google-bert/bert-base-chinese", # 组织/模型名称
    filename="config.json", # 文件名称
    cache_dir = r"D:\Data\WorkSpace\PyCharm\Test\uv-test\models\hf_hub"  # 缓存目录
)
print(path)

• 方案B：也可通过构造模型目录解决

后续知晓local_dir就是用来下载到指定目录的，不是用来当作模型仓库目录的，自然不会创建模型文件夹

from huggingface_hub import hf_hub_download
# 路径字符串前面要加r，声明后面的字符串是普通字符串，否则 \u 会识别成ASCII编码的开头，其他转义字符 \n \t
root_dir = r"D:\Data\WorkSpace\PyCharm\Test\uv-test\models\hf_hub"  # 下载目录，个人推荐配置，不想下载到默认的c盘
repo_id="google-bert/bert-base-chinese" # 组织/模型名称
path = hf_hub_download(
    repo_id=repo_id, # 组织/模型名称
    filename="config.json", # 文件名称
    local_dir=root_dir + "/" + repo_id
)
print(path)

缺点是每个模型目录下都会创建一个.cache文件夹，虽然一般只有几kb

用环境变量修改缓存目录还是构造目录呢？区别在于是否采用符号连接

维度	方案 A：修改缓存 cache_dir / HF_HOME	方案 B：root_dir + repo_id
目录结构	自动创建 models--用户--仓库 多级目录	你手动指定，完全可控
软链接	✅ 必然有，节省磁盘	❌ 没有
多版本共存	✅ 天然支持，切换 commit 只改软链	✅ 同样支持（只要你愿意多建文件夹）
部署/打包	需把 cache_dir / HF_HOME 一并带走，路径嵌套深	路径扁平，直接拷走即可
CI/CD 或容器	需挂载/缓存整个 HF_HOME，体积稍大	只挂指定目录，镜像更干净
一键换机	拷整个缓存即可	需逐个模型拷
推荐场景	日常开发、需要频繁切版本	保存传输、离线部署、Docker 镜像、路径洁癖

一句话结论

• 本地开发 / 频繁实验：修改缓存 cache_dir / HF_HOME。
• 保存传输 / 打包发布 / Docker / 路径必须简洁：local_dir=root_dir + “/” + repo_id

小结：hf_hub_download主要用于下载单个文件，模型一般包含5个文件，下载多个文件需要复制多套命令替换不同的文件名，十分的不方便，不推荐

2. snapshot_download

huggingface 官方提供了基于hf_hub_download进行封装的snapshot_download 方法l来下载完整模型，主要是增加了断点续传、多线程批量下载。

2.1 介绍

hugging face doc官网：huggingface_hub.snapshot_download

实现代码可以在虚拟环境的库文件中进行查看：
.venv -> Lib -> site-packages -> huggingface_hub -> _snapshot_download.py -> def snapshot_download()

给注释翻译总结一下：

参数	类型	默认值	中文释义
函数描述	-	-	一次性下载仓库指定版本的所有文件（快照）。若不知道需要哪些文件，这是最方便的方案。
local_dir 行为	-	-	若提供 local_dir，将把仓库目录结构原样复制到该目录，并在此根目录创建 .cache/huggingface/ 存放少量元数据；此时 不再使用默认缓存。
与 git clone 对比	-	-	相比 git clone： 1. 不需要安装 git / git-lfs； 2. 支持 allow_patterns / ignore_patterns 过滤文件； 3. 对拉取最新版本做了优化。
repo_id	str	-	组织/用户名与仓库名，如 google/flan-t5-xl
repo_type	str | optional	None	"dataset" / "space" / "model"（缺省为 "model"）
revision	str | optional	-	分支、tag 或 commit hash
cache_dir	str | Path | optional	-	自定义缓存根目录
local_dir	str | Path | optional	-	自定义落盘目录（见上）
library_name	str | optional	-	对应库名称
library_version	str | optional	-	对应库版本
user_agent	str | dict | optional	-	自定义 User-Agent
proxies	dict | optional	-	代理字典
etag_timeout	float | optional	10	获取 ETag 时的超时秒数
force_download	bool | optional	False	强制重新下载，即使已存在
token	str | bool | optional	-	访问令牌；True 读本地配置，字符串则直接使用
headers	dict | optional	-	额外请求头（优先级最高）
local_files_only	bool | optional	False	仅使用本地缓存，不联网
allow_patterns	List[str] | str | optional	-	只下载匹配至少一条 pattern 的文件
ignore_patterns	List[str] | str | optional	-	忽略匹配任一 pattern 的文件
max_workers	int | optional	8	并发线程数，1 线程对应 1 个文件
tqdm_class	tqdm | optional	-	自定义进度条类，需继承自 tqdm.auto.tqdm
返回值	str	-	下载完成后仓库快照所在的本地目录路径
可能抛出的异常	-	-	RepositoryNotFoundError（仓库不存在或无权限） RevisionNotFoundError（指定版本不存在） EnvironmentError（未找到 token） OSError（无法获取 ETag） ValueError（参数非法）

2.2 示例

使用示例，先测试下载到指定目录：

from huggingface_hub import snapshot_download
path = snapshot_download(
    repo_id="google-bert/bert-base-chinese",
    local_dir=r"D:\Data\WorkSpace\PyCharm\Test\uv-test\models\hf_snapshot",
)
print(path)

下载的时候有进度条，网络原因下载失败了

这里报了一个警告，Hugging Face 新推出的 xet 存储格式可以提升下载速度和性能，建议安装它

官方文档说从 0.32.0 huggingface_hub 开始，会同时安装 hf_xet，我安装的版本是0.34，不知道为什么没有。
huggingface-xet说明文档

uv add hf_xet

• hf_xet：1.1.7

下载了一部分，仍然没有创建模型的目录，直接下载到了指定目录，原因和上面说的一样
可以看到全仓库下载会把其他框架的权重文件也下载下来，有点浪费空间，下载完的部分多了一个tf框架的权重文件

再次运行会继续下载剩余文件

监听下载可以看到有多个http连接，即多线程下载（实际是xet的作用，下面有验证）

这下都下载回来了，四个权重文件，可以用allow_patterns和ignore_patterns参数设置过滤文件，但是不同的仓库差异较大，感觉也比较麻烦

2.3 断点续传

感觉刚刚的不对劲，把tf_model.h5删掉，把hf_xet库移除再次运行，只有一个下载连接

强行中断后在打开缓存文件夹（前面有说指定local_dir后会创建一个.cache文件夹）可以看到一个200多m的文件，这个就是实现断点续传的原理

再次运行，通过流量监控也能看到只下载了200m，没截上流量的图

2.4 hf_xet 多线程

再次把tf_model.h5删掉，安装hf_xet库再次运行，确认xethub的这些连接不是snapshot_download的多线程，而是hf_xet库的作用

支持这种下载方式的hugging face上都有标注

但是xet也会在c盘的.cache文件夹下创建一遍缓存，之后下载会直接从这里复制，可以自行删除缓存
xet缓存文件说明文档

2.5 修改目录

前面测试的时候还未想到两种目录设置，下面补充一下

• 修改缓存目录

from huggingface_hub import snapshot_download
path = snapshot_download(
    repo_id="google-bert/bert-base-chinese",
    cache_dir=r"D:\Data\WorkSpace\PyCharm\Test\uv-test\models\hf_snapshot"
)
print(path)

• 构造目录方案

from huggingface_hub import snapshot_download
root_dir = r"D:\Data\WorkSpace\PyCharm\Test\uv-test\models\hf_snapshot"  # 根目录
repo_id="google-bert/bert-base-chinese" # 组织/模型名称
path = snapshot_download(
    repo_id=repo_id, # 组织/模型名称
    local_dir=root_dir + "/" + repo_id # 构造目录
)
print(path)

小结
snapshot_download相比于hf_hub_download主要是可以自动下载整个仓库，且每个文件一个线程实现多线程，.cache文件实现断点续传，这个hf_hub_download应该也能做到，因为它也创建了相同的文件。
hf_xet效果非常明显，真正实现了多线程，不过只针对权重文件，毕竟配置文件和词汇表等文件都不大。经过测试，hf_xet对hf_hub_download也有用，或者说是直接作用于hf_hub_download的，自然也对snapshot_download起作用。

3. hf download

snapshot_download还是需要写python代码，在ide中运行，hugging face提供了基于huggingface-hub库的命令行工具hf.exe（v0.34+ 引入，之前是huggingface-cli.exe，新旧工具完全相同，只是命令更短），拥有huggingface-hub库的全部功能，如登录您的帐户、创建存储库、上传和下载文件、管理缓存等，这里暂时只用下载命令hf download

• huggingface main分支-命令行界面 （CLI）说明文档

• huggingface 0.33.5-命令行界面 （CLI）说明文档
  

• huggingface 0.34.4-命令行界面 （CLI）说明文档
  

3.1 介绍

hf 下载 说明文档

安装了huggingface-hub库后就可以在命令行使用hf或huggingface-cli了，不知道你有没有想过这是为什么?

原理：使用uv add huggingface-hub 或 pip install huggingface_hub 安装依赖后，会在 site-packages 的 Scripts 目录 里自动生成可执行文件hf.exe或huggingface-cli.exe，它被 Python 自动加入 PATH，所以安装完即可直接在命令行使用。
如下图：

字段	翻译
用法	hf <命令> [<参数>] download [-h] …
位置参数
repo_id	要下载的仓库 ID（例如 username/repo-name）。
filenames	要下载的文件列表（例如 config.json、data/metadata.jsonl）。留空则下载整个仓库。
可选参数
-h, --help	显示此帮助信息并退出。
--repo-type {model,dataset,space}	仓库类型，默认为 model。
--revision REVISION	Git 版本号，可以是分支名、标签或完整提交哈希。
--include [INCLUDE …]	Glob 模式，仅下载匹配到的文件。
--exclude [EXCLUDE …]	Glob 模式，排除匹配到的文件。
--cache-dir CACHE_DIR	自定义缓存目录路径。
--local-dir LOCAL_DIR	若设置，文件将下载到此目录并保持原目录结构；见官方文档。
--force-download	强制重新下载，即使已缓存。
--token TOKEN	用户访问令牌，可在 https://huggingface.co/settings/tokens 生成。
--quiet	静默模式，隐藏进度条，仅输出下载路径。
--max-workers MAX_WORKERS	下载最大并发线程数，默认为 8。

3.2 示例

这里不再分别测试cache_dir和local_dir了，根据自己的情况进行选择，我这里是进行多模型微调，后续就只考虑cache_dir了

• 下载单个文件

hf download google-bert/bert-base-chinese config.json --cache-dir D:\Data\WorkSpace\PyCharm\Test\uv-test\models\hf_cli

• 下载整个仓库

hf download google-bert/bert-base-chinese --cache-dir D:\Data\WorkSpace\PyCharm\Test\uv-test\models\hf_cli

觉得日志太多了可以添加--quiet参数开启安静模式

• 使用 --include 和 --exclude 过滤要下载的文件
  根据自己需要编写正则即可，比如只下载json文件

hf download google-bert/bert-base-chinese --cache-dir D:\Data\WorkSpace\PyCharm\Test\uv-test\models\hf_cli --include "*.json"

3.3 hf_transfer 多线程

后面又了解到一种多线程加速方法，hf_transfer ，同hf_xet 一样都是用Rust编写的 Python 包。
就目前来说，安装 hf_xet 后，不必再装 hf_transfer；Xet 已覆盖 LFS 与 Xet 文件，且成为官方默认。
但如果有权重文件很大且不支持xet下载，那就只能尝试hf_transfer了，简单说明下使用方法，就不测试了

uv add hf_transfer

hf_xet安装后默认使用，hf_transfer需要将 HF_HUB_ENABLE_HF_TRANSFER=1 设置为环境变量。

• 编辑环境变量永久修改
  

• terminal命令行（powershell）临时修改

$env:HF_HUB_ENABLE_HF_TRANSFER=1;hf download google-bert/bert-base-chinese --cache-dir D:\Data\WorkSpace\PyCharm\Test\uv-test\models\hf_cli

• 代码临时修改

import os
os.environ["HF_HUB_ENABLE_HF_TRANSFER"] = "1"
from huggingface_hub import snapshot_download
path = snapshot_download(
    repo_id="google-bert/bert-base-chinese",
    cache_dir=r"D:\Data\WorkSpace\PyCharm\Test\uv-test\models\hf_snapshot"
)
print(path)

小结：个人不太推荐命令行的方法，
一个是在命令行编辑比较麻烦，复制粘贴修改都不方便
第二是代码相当于保存了操作记录，更容易回顾，日志和错误信息也容易保存

4. from_pretrained

讲了半天huggingface-hub提供的方法，接下来要说的是伟大的transforms库，huggingface-hub提供了管理模型的方法，而transforms提供了模型的全套使用流程，内部依赖的也是huggingface-hub的snapshot_download方法

4.1 介绍

简单看下transforms库和huggingface-hub库的发展历史

时间	事件	说明
2016-11	Hugging Face 公司成立	总部纽约，3 位创始人 Clement、Julien、Thomas，最早做 iOS 聊天机器人 App，名字叫 Hugging Face。
2017-06	Transformer 架构论文发布	Google 提出自注意力架构，奠定后续所有预训练模型的设计范式，引爆 NLP 界。
2018-10	pytorch-pretrained-BERT 开源	Hugging Face 首次将 BERT PyTorch 实现开源，成为 Transformers 库的前身。
2019-06	pytorch-transformers 1.0	改名并扩展支持 GPT、XLNet 等，仅 PyTorch 后端。
2019-10	Transformers 2.0 发布	正式定名Transformers（pip install transformers），同时支持 PyTorch 与 TensorFlow 2.x；论文获 EMNLP 最佳 Demo 奖。
2020-02	Model Hub 上线	Hugging Face 推出模型仓库，人人可上传/下载模型，支持 Git LFS 上传/下载。
2021-09	huggingface-hub 0.1.0	把“与 Hub 交互”的底层函数拆成独立包 huggingface_hub，提供下载/上传/搜索 API。
2022-12	huggingface-hub 1.0 GA	提供完整 Python/CLI，Transformers ≥4.21 默认依赖它。
2023-今	生态分家治理	Transformers 专注模型实现，huggingface-hub 专注仓库管理，各自独立发版。

transforms提供了AutoModelForMaskedLM和AutoTokenizer类用于自动加载模型和分词器，都使用from_pretrained函数
transformers.AutoModelForMaskedLM.from_pretrained 官方文档

模型类型是通过配置参数或者pretrained_model_name_or_path参数来判断的，transforms为每种类型提供了单独的自动加载类，比如bert模型对应的就是BertForMaskedLM

点过去查看一下
transformers.BertForMaskedLM 官方文档

同样的也有AutoTokenizer和BertTokenizer
transformers.AutoTokenizer.from_pretrained 官方文档
transformers.BertTokenizer 官方文档

4.2 安装

安装transformers和torch库，transformers 库中依赖了 huggingface-hub，安装torch库是因为transformers的AutoModelForMaskedLM.from_pretrained方法会自动下载模型、加载权重、创建 PyTorch 模型

uv add transformers torch

• transformers：4.55.0
• torch：2.8.0

之前的方法下载模型时都使用了修改缓存目录的方式，当时为了测试都设置的是项目中的不同文件夹，其实应该设置到一个d盘的公共目录，没必要同样的模型每个项目都下载一遍，推荐采用永久修改的方式编辑系统环境变量
先看下huggingface-hub环境变量的官方文档，默认是在C:\Users\用户名\.cache\huggingface，由于各缓存目录都拼接了HF_HOME，所以只修改这一个就可以
https://huggingface.co/docs/huggingface_hub/v0.34.4/package_reference/environment_variables#generic

再看下transforms的环境变量，TRANSFORMERS_CACHE在最新版本已经废弃了，设置HF_HOME可以同时作用于huggingface-hub，就不设置HF_HUB_CACHE了
https://huggingface.co/docs/transformers/main/en/installation#cache-directory

设置HF_HOME环境变量，改为需要重新启动pycharm

setx HF_HOME "D:\Data\WorkSpace\HuggingFace" # 替换为自定义huggingface目录

或

4.3 通用模型下载

一般直接修改组织/模型名称参数就可以

from transformers import AutoTokenizer, AutoModelForMaskedLM
tokenizer = AutoTokenizer.from_pretrained("google-bert/bert-base-chinese")
model = AutoModelForMaskedLM.from_pretrained("google-bert/bert-base-chinese")

huggingface上也示例了使用代码和下载代码

可惜没有进度条

查看下刚刚设置的文件夹，没问题

4.4 专用下载类

每个模型基本上都有两个：BertModel和BertTokenizer

from transformers import BertTokenizer, BertForMaskedLM
tokenizer = BertTokenizer.from_pretrained("bert-base-chinese")
model = BertForMaskedLM.from_pretrained("bert-base-chinese")

from transformers import BertTokenizer, BertModel
tokenizer = BertTokenizer.from_pretrained("bert-base-chinese")
model = BertModel.from_pretrained("bert-base-chinese")

BertModel和BertTokenizer主要区别在于下载完成后：

• BertModel：只加载 BERT 主干网络（无任务头）。
• BertForMaskedLM（AutoModelForMaskedLM）：加载 BERT + MLM 任务头（cls.predictions，即带 MaskedLM 分类层）。
  任务头：模型末尾的“专用输出层”，用于把隐藏状态映射成最终预测结果。

这里注意下载目录创建的模型目录会按照传入的参数创建，最好是全局统一都用 组织/模型名称
因为之前加了组织id，这次没加，就没下载到一起

下载后目录如下：

小结：用from_pretrained来下载其实有些重，from_pretrained核心是加载，只不过在加载前会检查模型有没有，没有先自动下载，一般在项目中用这种方法比较好，BertModel加载的会稍微少一点。
自动下载的好处是不用考虑下载哪些文件，也不会下载重复，默认下载safetensors格式的权重文件。

三、换镜像源

前面主要讲的是不同的下载方式，但是都需要科学上网，总归是不太稳定，所以最好是把下载地址换到国内的镜像源

目前国内用的最多的是padeoe大神开源的镜像站，
主地址为：https://hf-mirror.com/
备用地址为：https://alpha.hf-mirror.com/
主地址稳定，备用地址应该快一些

大概有以下几种更换方式：

1. python

在py文件最上面添加，适用于三种代码方法

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

2. Powershell

临时修改镜像源，适用于hf download命令行方法

$env:HF_ENDPOINT = "https://hf-mirror.com"

3. 环境变量

永久修改镜像源，适用于所有方法

setx HF_ENDPOINT "https://hf-mirror.com"

或

测试了一下很快，十几兆的速度，不到半分钟就下载好了

4. 库文件

还有天才网友找到的方法，直接修改库文件，适用于所有方法
找到：{python解释器路径}\site-packages\huggingface_hub\constants.py
虚拟环境的就比较简单了：.venv\site-packages\huggingface_hub\constants.py
第65行（0.34.3版本）就是下载地址，直接修改为

_HF_DEFAULT_ENDPOINT = "https://hf-mirror.com"

再往下找到os.getenv("HF_ENDPOINT", _HF_DEFAULT_ENDPOINT)，第一个参数是获取系统环境变量，第二个参数就是默认值，所以我们相当于直接改了默认值

不过这种方法只能改一个环境，还是不如修改系统环境变量一劳永逸

四、git clone

hugging face是一个提供了上传下载模型的平台，基于git进行版本管理，所以我们也可以使用git clone来下载仓库

可以按照下图方式找到克隆命令


这里就不作测试了，因为git会把所有的版本历史下载下来，完全没有必要，除非你想上传自己的模型，那就是另一个任务了

git lfs install
git clone https://huggingface.co/google-bert/bert-base-chinese

五、登录

有些模型需要注册登录申请才能下载，暂时没有需要，这部分等以后再完善。

1. 注册登录
2. 申请许可
3. 获取 access token（用于命令行和python方法调用）
4. 如下：

函数 / CLI	添加 token 的方式	示例
hf_hub_download	token 参数	hf_hub_download(repo_id="xxx", filename="config.json", token="hf_XXXX")
snapshot_download	token 参数	snapshot_download(repo_id="xxx", token="hf_XXXX")
from_pretrained	token 参数	AutoModel.from_pretrained("xxx", token="hf_XXXX")
huggingface-cli 或 hf	--token 参数	huggingface-cli download xxx --token hf_XXXX

六、总结

由于是边了解边梳理，前面的部分有些乱，最后再整体总结一下

1. 手动下载：网页内，IDM

5个文件缺一不可

• config.json：模型结构配置文件（隐藏层大小、注意力头数、词表大小等）
• model.safetensors：模型权重文件，或 pytorch_model.bin，两者选其一即可
• tokenizer.json：分词器的核心实现（包含 BPE/SentencePiece 等算法和词表）
• tokenizer_config.json：分词器特殊配置文件
• vocab.txt：纯文本格式的词汇表

2. 代码或命令行下载

• 安装依赖

uv add huggingface-hub hf_xet
uv add transformers torch

• 设置环境变量

setx HF_HOME "D:\Data\WorkSpace\HuggingFace" # 替换为自定义huggingface目录
setx HF_ENDPOINT "https://hf-mirror.com" # 换源

• hf_hub_download：下载单个文件

from huggingface_hub import hf_hub_download
hf_hub_download(repo_id="google-bert/bert-base-chinese", filename="config.json")

• snapshot_download：下载整个仓库

from huggingface_hub import snapshot_download
snapshot_download(repo_id="google-bert/bert-base-chinese")

• hf download：命令行下载

hf download google-bert/bert-base-chinese

• from_pretrained：下载+自动加载模型

from transformers import AutoTokenizer, AutoModelForMaskedLM
tokenizer = AutoTokenizer.from_pretrained("google-bert/bert-base-chinese")
model = AutoModelForMaskedLM.from_pretrained("google-bert/bert-base-chinese")

维度	hf_hub_download	snapshot_download	hf download (CLI)	from_pretrained
作用	下载单个文件	下载整个仓库	命令行下载/仓库	下载+自动加载模型
导入	from huggingface_hub import hf_hub_download	from huggingface_hub import snapshot_download	无需导入，安装后 hf download …	from transformers import AutoModel, AutoTokenizer
最小示例	hf_hub_download(repo_id="bert-base-uncased", filename="config.json")	snapshot_download("bert-base-uncased")	hf download bert-base-uncased	AutoModel.from_pretrained("bert-base-uncased")
仓库类型	任意（model / dataset / space）	任意	任意	任意（由 Auto 类自动识别）
指定本地目录	local_dir="…"	local_dir="…"	--local-dir …	cache_dir="…"（注意：不是 local_dir）
过滤文件	不支持	allow_patterns="*.json" / ignore_patterns="*.bin"	--include *.json --exclude *.bin	不支持（需用 snapshot 先下）
登录/Token	token="hf_XXXX" 或 token=True	token="hf_XXXX" 或 token=True	--token hf_XXXX	token="hf_XXXX" 或先 huggingface_hub.login("hf_XXXX")
下载并发	单文件	max_workers=8（默认 8）	max_workers（CLI 参数）	依赖 transformers 内部逻辑
是否自动加载模型	❌ 仅下载	❌ 仅下载	❌ 仅下载	✅ 下载并加载
主要用途	脚本里拿单个文件	脚本/运维整仓	命令行一键下载	训练/推理直接加载

3. git clone

git lfs install
git clone https://huggingface.co/google-bert/bert-base-chinese

七、使用建议

这么多方法和命令，该用哪个呢，个人推荐一下，咱分为两种：

• 单纯下载：那直接用pip+cli下载到指定目录最方便，没有符号连接方便复制移动

pip install -U "huggingface_hub[hf_xet]
hf download google-bert/bert-base-chinese --local-dir D:\models\bert-base-chinese

• 模型开发：使用transforms的自动下载不用考虑过滤文件的事，再设置目录和换源

uv add huggingface-hub hf_xet transformers torch
setx HF_HOME "D:\Data\WorkSpace\HuggingFace" # 替换为自定义huggingface目录
setx HF_ENDPOINT "https://hf-mirror.com" # 换源

from transformers import AutoTokenizer, AutoModelForMaskedLM
tokenizer = AutoTokenizer.from_pretrained("google-bert/bert-base-chinese")
model = AutoModelForMaskedLM.from_pretrained("google-bert/bert-base-chinese")

参考文献

如何快速下载huggingface模型——全方法总结

---

后记

python的一大特点就是变化快，依赖库日新月异，本文以一个新手小白的角度从0开始下载模型，尽可能的把知识和问题都讲清楚，如有错误请评论指出，让我们一起学习进步~

---

喜欢的点个关注吧><！祝你永无bug~

/*
                   _ooOoo_
                  o8888888o
                  88" . "88
                  (| -_- |)
                  O\  =  /O
               ____/`---'\____
             .'  \\|     |//  `.
            /  \\|||  :  |||//  \
           /  _||||| -:- |||||-  \
           |   | \\\  -  /// |   |
           | \_|  ''\---/''  |   |
           \  .-\__  `-`  ___/-. /
         ___`. .'  /--.--\  `. . __
      ."" '<  `.___\_<|>_/___.'  >'"".
     | | :  `- \`.;`\ _ /`;.`/ - ` : | |
     \  \ `-.   \_ __\ /__ _/   .-` /  /
======`-.____`-.___\_____/___.-`____.-'======
                   `=---='
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
            佛祖保佑       永无BUG
*/