模型文件命名说明

如果你要找的是 safetensors、ONNX、GGUF、adapter、MLX 这些“格式”本身，而不是文件名怎么读，看：模型格式说明。

这篇文章解决什么问题

很多人第一次下载开源模型时，会同时被两套名字绕晕：

模型本身的名字
仓库里的文件名字

比如你可能会同时看到这些东西：

text

Qwen/Qwen2.5-7B-Instruct
Meta-Llama-3.1-8B-Instruct
model.safetensors
model-00001-of-00004.safetensors
model.safetensors.index.json
tokenizer.json
adapter_model.safetensors
Q4_K_M.gguf

如果不把它们拆开，很容易产生这些误解：

以为 7B、BF16、Q4_K_M 说的是同一层信息
以为 model.safetensors 和 adapter_model.safetensors 是一回事
以为所有模型仓库文件名都有统一硬标准
以为看到 Instruct、Chat、it 就一定完全等价

这篇文章就是把“模型命名”和“文件命名”分开解释。

先说结论

模型文件命名没有一个全行业统一硬标准，但 Hugging Face / Transformers / PEFT / GGUF 这几条生态里，已经形成了非常稳定的惯例。
最重要的是先分层：
- 模型 ID：告诉你它是谁
- 权重文件：告诉你参数存在哪
- 配置文件：告诉你结构和推理参数
- tokenizer / processor 文件：告诉你怎么把输入变成模型能吃的格式
- adapter 文件：告诉你这是不是增量微调权重
- 量化文件：告诉你这是不是给本地推理或特定引擎准备的压缩版本
很多名字不是“标准字段”，而是行业约定，所以看名字时要把“官方规范”和“社区习惯”分开看。

先分清：你看到的名字属于哪一层

最容易看乱，是因为不同层的名字长得很像。

层级	例子	它回答什么问题
模型仓库 ID	`Qwen/Qwen2.5-7B-Instruct`	这是什么模型
权重文件名	`model.safetensors`	权重存在哪个文件
分片权重文件	`model-00001-of-00004.safetensors`	权重是否被拆分保存
权重索引	`model.safetensors.index.json`	每一层权重在哪个分片里
tokenizer 文件	`tokenizer.json`	文字怎么切成 token
adapter 文件	`adapter_model.safetensors`	这是不是 LoRA / PEFT 这类增量权重
量化文件	`Q4_K_M.gguf`	这是不是压缩后的本地推理版本

只要先按这个层级看，后面大部分名字都不难读。

第一部分：模型 ID 一般怎么命名

这里先说一个最重要的前提：

模型 ID 没有统一全球标准。

也就是说，没有一个组织规定所有模型都必须按完全相同格式命名。
你现在看到的大部分规律，更接近“主流社区约定”。

一个最常见的阅读顺序

很多文本模型名字，大体可以按下面顺序拆：

text

[模型家族]-[版本]-[参数规模]-[用途/调教类型]-[可选补充标签]

比如：

text

Qwen2.5-7B-Instruct
Llama-3.1-8B-Instruct
gemma-3-4b-it

这些例子不完全同构，但基本都在表达几类信息。

1. 模型家族

这部分说明它属于谁家的哪条系列。

常见例子：

Qwen
Llama
Gemma
Mistral
DeepSeek

这一段最像“产品线名称”。

2. 版本

这部分说明同一系列的代际或迭代版本。

常见写法：

2
2.5
3
3.1

比如：

Qwen2.5
Llama-3.1
gemma-3

它通常表示：

这一代模型的训练版本
架构或数据更新后的新系列

但它不直接表示参数大小。

3. 参数规模

这部分最常见，通常是：

0.5B
1.5B
7B
8B
14B
32B
72B

这里的 B 是 Billion，表示十亿级参数。

它回答的是：

这个模型大概有多大

它不直接表示：

是否量化
是否适合聊天
是否是视觉模型

4. 调教类型 / 用途标签

这部分最容易混淆，因为不同家族写法并不完全统一。

常见写法包括：

Base
Instruct
Chat
it

大意通常是：

标签	通常表示什么
`Base`	预训练底座，没有专门做聊天对齐
`Instruct`	做过指令微调，更适合直接问答
`Chat`	聊天导向版本
`it`	instruction-tuned 的缩写，Gemma 常见

这里要特别注意：

Instruct
Chat
it

它们语义接近，但不能简单视为完全相同的硬标准字段。
它们更像各家自己选的命名习惯。

5. 可选补充标签

有些模型名后面还会再带一层补充信息，比如：

Vision
VL
Audio
Code
MoE
GGUF
AWQ
GPTQ

这些标签通常表示：

模态能力
用途方向
导出格式
量化方式

但不同作者会混着用，所以一定要结合仓库说明看。

一个通俗拆解例子

text

Qwen2.5-7B-Instruct

可以读成：

Qwen2.5：Qwen 系列第 2.5 代
7B：大约 70 亿参数级别
Instruct：做过指令微调，偏直接问答和聊天

再比如：

text

gemma-3-4b-it

通常可以读成：

gemma-3：Gemma 第 3 代
4b：40 亿参数级别
it：instruction-tuned 版本

第二部分：文件命名才是“模型文件命名规则”

如果你真正问的是“下载下来以后文件名怎么看”，重点其实在这一部分。

在 Hugging Face Transformers 库生态里，一个标准文本模型仓库，最常见会包含两大类文件：

model files
preprocessor files

Hugging Face 官方文档对这两类有非常明确的说明。

一组最常见的基础文件

text

config.json
generation_config.json
model.safetensors
tokenizer.json
tokenizer_config.json
special_tokens_map.json

下面逐个拆。

1. `config.json`

这是模型结构配置。

它通常描述：

hidden size
层数
attention heads
vocab size
position / rope 相关配置

你可以把它理解成：

模型蓝图

它不是权重本身，但没有它，框架通常不知道该按什么结构把权重装起来。

2. `model.safetensors`

这是最常见的主权重文件。

Hugging Face 官方文档明确说：

model.safetensors 存模型预训练层和权重
safetensors 是比 pickle 类格式更安全、更快的序列化格式

也就是说：

config.json 决定骨架
model.safetensors 决定骨架里具体参数值

3. `generation_config.json`

这个文件不是每个仓库都有，但很多生成模型会带。

它通常保存：

temperature
top_k
top_p
bos / eos 相关生成设置
某些默认生成参数

它不是模型架构本身的一部分，更像默认生成行为配置。

4. `tokenizer.json`

这是 tokenizer 主文件。

它保存的是：

词表
分词规则
tokenizer pipeline

可以理解成“怎么把输入文字切成 token”的核心定义。

5. `tokenizer_config.json`

这个文件通常补充：

tokenizer class
特殊 token
最大输入长度
返回哪些字段

Hugging Face 文档还特别提到：

对其他模态，tokenizer_config.json 可能会被 preprocessor_config.json 替代

6. `special_tokens_map.json`

这个文件专门映射特殊 token。

比如：

bos_token
eos_token
pad_token
某些 chat / multimodal 占位 token

这个文件的价值在于：

让框架知道哪些 token 有特殊语义

第三部分：为什么有时不是一个权重文件，而是一堆分片

很多人第一次看到这种文件名会困惑：

text

model-00001-of-00004.safetensors
model-00002-of-00004.safetensors
model-00003-of-00004.safetensors
model-00004-of-00004.safetensors
model.safetensors.index.json

这并不是四个不同模型，而是：

一个模型
被拆成多个 shard 保存

Hugging Face Transformers 库官方文档明确写到：

大于一定体积的 checkpoint 会自动 sharded
同时生成一个 index 文件映射参数名到具体分片

分片文件名怎么读

text

model-00001-of-00004.safetensors

可以读成：

model：这还是主模型权重
00001：这是第 1 片
of-00004：总共 4 片
.safetensors：文件格式

这套命名的重点不是“模型类型”，而是“分片顺序”。

`model.safetensors.index.json` 是什么

这是分片索引文件。

它不存权重本体，而是存映射关系。
Hugging Face 文档里给出的结构核心包括：

metadata
weight_map

其中：

metadata.total_size：总大小
weight_map：每个参数名在哪个分片文件里

所以你可以把它理解成：

第四部分：为什么有时会看到 `.bin`、`.pth`、`.ckpt`

这些通常是较旧或其他生态的权重格式。

Hugging Face 文档明确提到，你仍然可能遇到：

bin
pth
ckpt

但现在越来越推荐的是：

safetensors

原因很简单：

更安全
更快
在当前生态里兼容越来越好

所以如果你看到：

text

pytorch_model.bin

它通常表示：

这是旧式或兼容 PyTorch checkpoint 的命名

如果你看到：

text

model.safetensors

通常表示：

这是更现代、也更推荐的保存方式

第五部分：tokenizer 文件为什么有时不是一套

不同 tokenizer 后端，文件可能长得并不一样。

最常见的几种情况是：

1. 单文件 tokenizer

常见是：

text

tokenizer.json

这表示分词规则已经整体打包在一个 JSON 里。

2. BPE 双文件

某些 BPE tokenizer 常见组合是：

text

vocab.json
merges.txt

这类名字在 Transformers 库的 tokenizer 实现里非常常见。

它们大意是：

vocab.json：词表
merges.txt：BPE merge 规则

3. SentencePiece 文件

有些模型会看到：

text

spiece.model

这通常表示它走的是 SentencePiece 这条线。

4. tiktoken 文件

Transformers 库文档现在也提到某些模型会有：

text

tokenizer.model

这可能是 tiktoken 文件，再由 Transformers 库转成 fast tokenizer 使用。

所以 tokenizer 文件名不能只死记一个。
更稳的理解是：

不同 tokenizer 后端，对应不同文件组合

第六部分：多模态模型为什么常看到 `processor`

如果是图像、音频、多模态模型，你经常会看到：

text

preprocessor_config.json
processor_config.json

因为这时不只是文本 tokenizer，还涉及：

image processor
audio processor
多模态占位配置

所以这类仓库文件名通常不止 tokenizer_*.json。

第七部分：微调后为什么文件名变成 `adapter_*`

这是 LoRA / PEFT 最容易看错的地方。

如果你保存的是 PEFT adapter，最常见会看到：

text

adapter_model.safetensors
adapter_config.json
README.md

Hugging Face PEFT 官方文档明确写到：

adapter_model.safetensors 只包含 adapter 参数
它不包含 base model 完整权重
adapter_config.json 保存 adapter 的配置

所以如果你看到：

text

adapter_model.safetensors

不要以为这就是完整模型。
很多情况下它只是“补丁”，还需要原始 base model 一起加载。

`adapter_config.json` 在说什么

它通常描述：

base model name
peft type
target modules
rank / alpha / dropout 等 adapter 配置

你可以把它理解成：

这块补丁是给谁打的
怎么打进去

第八部分：GGUF 文件名怎么读

如果你下载本地推理版本，经常会看到：

text

Llama-3-8B-Instruct-Q4_K_M.gguf
Qwen2.5-7B-Instruct-IQ4_XS.gguf

这一层已经不只是“仓库文件命名”，而是：

模型名
量化名
文件格式

混在一起了。

这里有三段最重要：

text

[模型名]-[量化类型].gguf

比如：

text

Qwen2.5-7B-Instruct-Q4_K_M.gguf

可以拆成：

Qwen2.5-7B-Instruct：原始模型身份
Q4_K_M：量化方案
.gguf：GGUF 文件格式

`GGUF` 是什么

Hugging Face 官方 GGUF 文档明确说：

GGUF 是一个二进制格式
为快速加载和保存优化
用于 GGML 以及相关执行器
不只是 tensor，还会编码标准化 metadata

所以它和 safetensors 的一个重要区别是：

safetensors 更像权重保存格式
GGUF 更像面向本地推理引擎的一体化分发格式

GGUF 量化名字里的类型有哪些

Hugging Face GGUF 文档列出了当前常见量化类型，包括：

Q2_K
Q3_K
Q4_K
Q5_K
Q6_K
Q8_K
Q4_0
Q5_0
Q8_0
IQ4_XS
IQ4_NL
IQ3_S
IQ2_XS
IQ1_M
TQ1_0
TQ2_0

这里先抓最重要的规律：

1. `Q4` / `Q5` / `Q8`

这通常表示量化位宽等级。

2. `_K`

表示 K 系列量化方法。

3. `IQ`

通常表示 importance matrix 这条线。

4. `_0` / `_1`

多见于 legacy 命名。

也就是说：

Q4_K 和 Q4_0 不是一回事
IQ4_XS 和 Q4_K 也不是一回事

一个很重要的边界

Q4_K_M 这种写法，更多是社区量化文件名习惯，不是所有模型仓库都会严格按同一模板来。

也就是说：

GGUF 类型本身是有明确定义的
但完整文件名怎么拼，社区发布者可能会有细节差异

所以看 GGUF 名字时，最稳的做法是分三层：

模型身份
量化类型
文件格式

第九部分：哪些名字是“规范”，哪些只是“习惯”

这点很重要。

名字	更像规范还是习惯	说明
`config.json`	更像规范	Transformers 生态非常稳定
`model.safetensors`	更像规范	当前主流保存方式
`model-00001-of-00004.safetensors`	更像规范	分片命名非常稳定
`model.safetensors.index.json`	更像规范	分片索引文件
`tokenizer.json`	更像规范	常见 tokenizer 主文件
`adapter_model.safetensors`	更像规范	PEFT 官方约定
`Qwen2.5-7B-Instruct`	更像社区主流习惯	不是跨厂商硬标准
`it` / `Chat` / `Instruct`	更像社区主流习惯	语义相近，但不完全统一
`Q4_K_M.gguf` 完整文件名	半规范半习惯	量化类型定义稳定，整名拼法社区会有差异

一个最实用的阅读方法

以后看到模型文件，不要一口气整串读。
按下面顺序拆最快：

先看这是“模型名”还是“文件名”

如果有 /，通常先把它当仓库 ID 看：

text

Qwen/Qwen2.5-7B-Instruct

再看是不是权重

如果是：

text

model.safetensors
model-00001-of-00004.safetensors

那重点是：

是完整权重还是分片权重

再看是不是 tokenizer / processor

如果是：

text

tokenizer.json
tokenizer_config.json
special_tokens_map.json
preprocessor_config.json

那重点是：

它管的是输入预处理，不是模型参数

再看是不是 adapter

如果是：

text

adapter_model.safetensors
adapter_config.json

那重点是：

这是增量补丁，不是完整模型

最后看是不是量化发布文件

如果是：

text

Qwen2.5-7B-Instruct-Q4_K_M.gguf

那重点是：

原始模型是谁
压成了什么量化
用什么推理格式保存

一个完整例子

假设你看到一个目录：

text

config.json
generation_config.json
model-00001-of-00004.safetensors
model-00002-of-00004.safetensors
model-00003-of-00004.safetensors
model-00004-of-00004.safetensors
model.safetensors.index.json
tokenizer.json
tokenizer_config.json
special_tokens_map.json

它通常表示的是：

这是一个完整 base / instruct 模型仓库
权重体积比较大，所以被拆成 4 片
tokenizer 文件也在仓库里
可以直接被 Transformers 生态加载

如果你看到的是：

text

adapter_model.safetensors
adapter_config.json

那通常表示：

这是 LoRA / PEFT adapter
必须配合 base model 使用

如果你看到的是：

text

Qwen2.5-7B-Instruct-Q4_K_M.gguf

那通常表示：

这是给 GGUF 引擎准备的量化单文件版本
不再是标准 Transformers 目录结构

我的判断

模型文件命名最难的地方，不是名字太长，而是多层信息叠在一起。

真正要掌握的不是死记某个文件名，而是先判断：

这是模型身份
还是权重文件
还是 tokenizer
还是 adapter
还是量化发布文件

只要这层分清，大部分名字都能很快拆出来。

如果只记一句话，我建议记这个：

模型名字是在回答“它是谁”，文件名字是在回答“它怎么被保存、怎么被加载”。

TODO：围绕模型文件继续补的关联问题

[ ] config.json 里最值得读的字段有哪些
[ ] tokenizer.json、tokenizer_config.json、special_tokens_map.json 分别该怎么排查问题
[ ] safetensors 和 GGUF 本质差别是什么
[ ] AWQ、GPTQ、GGUF 三类量化发布形式怎么区分
[ ] LoRA adapter 和 merge 后整模文件，目录结构有什么区别
[ ] 多模态模型仓库里 processor 相关文件怎么读

模型文件命名说明 ​

这篇文章解决什么问题 ​

先说结论 ​

先分清：你看到的名字属于哪一层 ​

第一部分：模型 ID 一般怎么命名 ​

一个最常见的阅读顺序 ​

1. 模型家族 ​

2. 版本 ​

3. 参数规模 ​

4. 调教类型 / 用途标签 ​

5. 可选补充标签 ​

一个通俗拆解例子 ​

第二部分：文件命名才是“模型文件命名规则” ​

一组最常见的基础文件 ​

1. config.json ​

2. model.safetensors ​

3. generation_config.json ​

4. tokenizer.json ​

5. tokenizer_config.json ​

6. special_tokens_map.json ​

第三部分：为什么有时不是一个权重文件，而是一堆分片 ​

分片文件名怎么读 ​

model.safetensors.index.json 是什么 ​

第四部分：为什么有时会看到 .bin、.pth、.ckpt ​

第五部分：tokenizer 文件为什么有时不是一套 ​

1. 单文件 tokenizer ​

2. BPE 双文件 ​

3. SentencePiece 文件 ​

4. tiktoken 文件 ​

第六部分：多模态模型为什么常看到 processor ​

第七部分：微调后为什么文件名变成 adapter_* ​

adapter_config.json 在说什么 ​

第八部分：GGUF 文件名怎么读 ​

GGUF 是什么 ​

GGUF 量化名字里的类型有哪些 ​

1. Q4 / Q5 / Q8 ​

2. _K ​

3. IQ ​

4. _0 / _1 ​

一个很重要的边界 ​

第九部分：哪些名字是“规范”，哪些只是“习惯” ​

一个最实用的阅读方法 ​

先看这是“模型名”还是“文件名” ​

再看是不是权重 ​

再看是不是 tokenizer / processor ​

再看是不是 adapter ​

最后看是不是量化发布文件 ​

一个完整例子 ​

我的判断 ​

TODO：围绕模型文件继续补的关联问题 ​

参考链接 ​

模型文件命名说明

这篇文章解决什么问题

先说结论

先分清：你看到的名字属于哪一层

第一部分：模型 ID 一般怎么命名

一个最常见的阅读顺序

1. 模型家族

2. 版本

3. 参数规模

4. 调教类型 / 用途标签

5. 可选补充标签

一个通俗拆解例子

第二部分：文件命名才是“模型文件命名规则”

一组最常见的基础文件

1. `config.json`

2. `model.safetensors`

3. `generation_config.json`

4. `tokenizer.json`

5. `tokenizer_config.json`

6. `special_tokens_map.json`

第三部分：为什么有时不是一个权重文件，而是一堆分片

分片文件名怎么读

`model.safetensors.index.json` 是什么

第四部分：为什么有时会看到 `.bin`、`.pth`、`.ckpt`

第五部分：tokenizer 文件为什么有时不是一套

1. 单文件 tokenizer

2. BPE 双文件

3. SentencePiece 文件

4. tiktoken 文件

第六部分：多模态模型为什么常看到 `processor`

第七部分：微调后为什么文件名变成 `adapter_*`

`adapter_config.json` 在说什么

第八部分：GGUF 文件名怎么读

`GGUF` 是什么

GGUF 量化名字里的类型有哪些

1. `Q4` / `Q5` / `Q8`

2. `_K`

3. `IQ`

4. `_0` / `_1`

一个很重要的边界

第九部分：哪些名字是“规范”，哪些只是“习惯”

一个最实用的阅读方法

先看这是“模型名”还是“文件名”

再看是不是权重

再看是不是 tokenizer / processor

再看是不是 adapter

最后看是不是量化发布文件

一个完整例子

我的判断

TODO：围绕模型文件继续补的关联问题

参考链接