Qwen2.5-14B-Instruct-AWQ 模型文件结构分析

txt 复制代码

huggingface/data/models/Qwen2.5-14B-Instruct-AWQ$ ls -all
total 9757656
drwxrwxr-x 3 ruler ruler       4096 Oct 29 02:24 ./
drwxrwxr-x 3 ruler ruler       4096 Oct 29 03:05 ../
drwxrwxr-x 3 ruler ruler       4096 Oct 27 01:24 .cache/
-rw-rw-r-- 1 ruler ruler        841 Oct 27 01:24 config.json
-rw-rw-r-- 1 ruler ruler        243 Oct 27 01:24 generation_config.json
-rw-rw-r-- 1 ruler ruler       1518 Oct 27 01:24 .gitattributes
-rw-rw-r-- 1 ruler ruler      11343 Oct 27 01:24 LICENSE
-rw-rw-r-- 1 ruler ruler    1671839 Oct 27 01:24 merges.txt
-rw-rw-r-- 1 ruler ruler 3988804408 Oct 27 08:53 model-00001-of-00003.safetensors
-rw-rw-r-- 1 ruler ruler 3968309440 Oct 27 08:32 model-00002-of-00003.safetensors
-rw-rw-r-- 1 ruler ruler 2023056736 Oct 27 08:39 model-00003-of-00003.safetensors
-rw-rw-r-- 1 ruler ruler     107402 Oct 27 01:24 model.safetensors.index.json
-rw-rw-r-- 1 ruler ruler       6372 Oct 27 01:24 README.md
-rw-rw-r-- 1 ruler ruler       7305 Oct 27 01:24 tokenizer_config.json
-rw-rw-r-- 1 ruler ruler    7031645 Oct 27 01:25 tokenizer.json
-rw-rw-r-- 1 ruler ruler    2776833 Oct 27 01:25 vocab.json
ruler@ruler-Super-Server:~/ex_huggingface/data/models/Qwen2.5-14B-Instruct-AWQ$

一、目录概览

模型根目录：Qwen2.5-14B-Instruct-AWQ

text 复制代码

Qwen2.5-14B-Instruct-AWQ/
├── .cache/huggingface/           # Hugging Face 下载缓存（非模型运行必需）
├── .gitattributes                # Git LFS 文件属性配置
├── LICENSE                       # Apache License 2.0
├── README.md                     # 模型说明与使用示例
├── config.json                   # 模型架构/超参数配置
├── generation_config.json        # 默认生成策略配置
├── merges.txt                    # BPE 合并规则表
├── vocab.json                    # BPE 词表
├── tokenizer.json                # 完整 tokenizer 配置（含特殊 token、chat_template）
├── tokenizer_config.json         # tokenizer 配置与聊天模板
├── model.safetensors.index.json  # 权重到文件分片的索引
├── model-00001-of-00003.safetensors  # 权重分片 1（3.71 GB）
├── model-00002-of-00003.safetensors  # 权重分片 2（3.70 GB）
└── model-00003-of-00003.safetensors  # 权重分片 3（1.88 GB）

总权重大小 ：约 9.29 GB（未解压/反量化前），由 model.safetensors.index.json 中的 total_size: 9980028928 给出。

二、配置文件解析

1. `config.json` --- 模型架构配置

字段	值	含义
`architectures`	`["Qwen2ForCausalLM"]`	模型类：因果语言模型
`model_type`	`qwen2`	Transformers 模型类型标识
`hidden_size`	`5120`	隐藏层维度
`num_hidden_layers`	`48`	Transformer 层数
`num_attention_heads`	`40`	注意力 Query 头数
`num_key_value_heads`	`8`	GQA（Grouped Query Attention）KV 头数
`intermediate_size`	`13824`	MLP 中间层维度
`hidden_act`	`silu`	激活函数：SwiGLU 的 silu 部分
`max_position_embeddings`	`32768`	预训练位置编码长度
`sliding_window`	`131072`	长上下文滑动窗口上限
`max_window_layers`	`70`	使用滑动窗口注意力的层数（此处大于实际层数，表示全部层启用）
`use_sliding_window`	`false`	当前是否默认开启滑动窗口
`rope_theta`	`1000000.0`	RoPE 基频
`rms_norm_eps`	`1e-06`	RMSNorm 稳定项
`vocab_size`	`152064`	词表大小
`bos_token_id`	`151643`	开始符 `<
`eos_token_id`	`151645`	结束符 `<
`tie_word_embeddings`	`false`	输入/输出嵌入矩阵不共享
`torch_dtype`	`float16`	权重默认 dtype
`attention_dropout`	`0.0`	注意力 dropout
`quantization_config`	AWQ 4-bit	量化配置
`transformers_version`	`4.41.1`	生成该配置时使用的 Transformers 版本

量化配置详情：

json 复制代码

"quantization_config": {
  "bits": 4,           // 4-bit 量化
  "group_size": 128,   // 每 128 个权重共享一组缩放/零点
  "quant_method": "awq", // 使用 AWQ（Activation-aware Weight Quantization）
  "version": "gemm",   // AWQ GEMM 内核版本
  "zero_point": true   // 使用零点（asymmetric）量化
}

2. `generation_config.json` --- 默认生成参数

字段	值	含义
`do_sample`	`true`	使用采样生成
`temperature`	`0.7`	采样温度
`top_k`	`20`	Top-k 采样
`top_p`	`0.8`	Nucleus 采样
`repetition_penalty`	`1.05`	重复惩罚
`eos_token_id`	`[151645, 151643]`	两个结束 token
`pad_token_id`	`151643`	Padding token `<
`bos_token_id`	`151643`	序列起始 token

三、权重文件解析

1. `model.safetensors.index.json`

这是一个权重索引文件，将每个参数名映射到对应的分片文件，用于多文件模型加载。

总权重字节数：9980028928（≈ 9.29 GB）
参数分片统计：
- model-00001-of-00003.safetensors：443 个张量
- model-00002-of-00003.safetensors：723 个张量
- model-00003-of-00003.safetensors：85 个张量

典型参数命名模式：

text 复制代码

model.embed_tokens.weight                # 输入 token 嵌入矩阵
model.layers.{i}.self_attn.q_proj.*      # 第 i 层 Query 投影
model.layers.{i}.self_attn.k_proj.*      # 第 i 层 Key 投影
model.layers.{i}.self_attn.v_proj.*      # 第 i 层 Value 投影
model.layers.{i}.self_attn.o_proj.*      # 第 i 层输出投影
model.layers.{i}.mlp.gate_proj.*         # SwiGLU gate 投影
model.layers.{i}.mlp.up_proj.*           # SwiGLU up 投影
model.layers.{i}.mlp.down_proj.*         # SwiGLU down 投影
model.layers.{i}.input_layernorm.weight  # 注意力前 RMSNorm
model.layers.{i}.post_attention_layernorm.weight  # 注意力后 RMSNorm
model.norm.weight                        # 最终输出层 RMSNorm
lm_head.weight                           # 输出 logits 投影

AWQ 量化张量后缀：

后缀	含义
`.qweight`	4-bit 量化后的整数权重（dtype: I32）
`.qzeros`	量化零点（用于反量化）
`.scales`	量化缩放因子（dtype: F16）
`.bias`	注意力 Q/K/V 投影的偏置（Qwen2.5 特有）

未量化层（如 input_layernorm.weight、model.norm.weight、lm_head.weight）为 F16。

2. 三个 `.safetensors` 分片文件

文件名	大小	张量数	主要内容
`model-00001-of-00003.safetensors`	3.71 GB	443	`embed_tokens`、layers 0--16 的 AWQ 权重与层归一化
`model-00002-of-00003.safetensors`	3.70 GB	723	layers 17--44 的 AWQ 权重与层归一化
`model-00003-of-00003.safetensors`	1.88 GB	85	layers 44--47 剩余权重、layer 47、最终 `model.norm.weight`、`lm_head.weight`

张量 dtype 分布：

.qweight 与 .qzeros 为 I32（32 位整数打包存储多个 4-bit 值）
.scales、归一化权重、嵌入/输出头为 F16

示例张量信息：

text 复制代码

model.layers.0.mlp.down_proj.qweight
  dtype: I32
  shape: [13824, 640]
  data_offsets: [0, 35389440]

shape 的第二个维度 640 对应 hidden_size(5120) / 8（因为每 8 个 int32 打包 32 个 4-bit 权重）。

四、Tokenizer 文件解析

1. `tokenizer_config.json`

tokenizer_class: Qwen2Tokenizer
model_max_length: 131072（支持 128K 上下文）
bos_token: null（Qwen2.5 Instruct 不使用显式 BOS）
eos_token: <|im_end|>（ID: 151645）
pad_token: <|endoftext|>（ID: 151643）
add_bos_token: false
chat_template: Jinja2 模板，定义系统提示、用户/助手消息、工具调用格式。

特殊 token 列表 （added_tokens_decoder）：

ID	Token	说明
151643	`<	endoftext
151644	`<	im_start
151645	`<	im_end
151646--151656	`<	object_ref_start/end
151657--151658	`<tool_call>`、`</tool_call>`	工具调用标记
151659--151662	`<	fim_prefix/middle/suffix/pad
151663--151664	`<	repo_name

2. `tokenizer.json`

version: 1.0
model.type: BPE
vocab 大小：151643
added_tokens：22 个特殊 token
pre_tokenizer：
1. Split：基于正则拆分英文缩写、字母、数字、标点、空白/换行。
2. ByteLevel：字节级 BPE，不添加前缀空格，不修剪偏移。

3. `vocab.json`

条目数：151643
标准 BPE 词表，key 为子词 token，value 为整数 ID。
前 220 个 ID 通常为 ByteLevel 的 256 字节表示（含控制字符映射）。

4. `merges.txt`

条目数：151291
BPE 合并规则，每行两个 token，按训练时学习到的合并优先级排列。
示例：

text 复制代码

Ġ Ġ
ĠĠ ĠĠ
i n
Ġ t

Ġ 表示空格前缀（ByteLevel 约定）。

五、其他文件

1. `README.md`

模型卡片，包含：

基础模型：Qwen/Qwen2.5-14B-Instruct
任务：text-generation / chat
许可证：apache-2.0
模型特点：14.7B 参数、48 层、GQA、AWQ 4-bit、128K 上下文、多语言支持。
Quickstart 代码：使用 AutoModelForCausalLM + AutoTokenizer 加载，配合 apply_chat_template。
长文本处理说明：使用 YaRN 扩展位置编码到 128K。
引用信息。

注意：README 中有一处笔误，将本模型描述为 "72B Qwen2.5 model"，实际应为 14B。

2. `LICENSE`

3. `.gitattributes`

配置 Git LFS 管理的二进制扩展名列表，包括：

*.safetensors
*.bin、*.pt、*.pth
*.arrow、*.parquet、*.onnx 等

确保大模型文件不会被 Git 当作文本处理。

4. `.cache/huggingface/`

Hugging Face 下载缓存目录，包含：

CACHEDIR.TAG：缓存标记文件
download/*.lock、* .metadata、* .incomplete：下载锁、元数据、未完成的临时文件
trees/*.json：仓库文件树缓存

这些文件仅用于 huggingface_hub 的下载/缓存管理，不影响模型推理。出现 .incomplete 文件表明部分文件可能曾经历中断下载，但最终模型文件已完整（因为存在非 .incomplete 的目标文件且大小正常）。

六、模型架构总结

项目	配置
模型系列	Qwen2.5
参数量	14.7B（README）/ 约 14B
类型	Causal LM（ decoder-only Transformer）
层数	48
隐藏维度	5120
注意力头数	40 Q / 8 KV（GQA）
MLP 中间维度	13824（SwiGLU）
位置编码	RoPE，基频 1e6
归一化	RMSNorm
注意力偏置	有（QKV bias）
上下文长度	训练 32K，最大可扩展到 131072（需 YaRN）
词表大小	151643 BPE tokens + 特殊 token → config 中报告 152064
量化	AWQ 4-bit，group_size=128，zero_point=true
存储精度	反量化计算通常为 FP16/BF16
推理建议	transformers >= 4.37.0；推荐 vLLM

七、关键注意事项

AWQ 推理依赖 ：运行该模型需要支持 AWQ 的后端，例如 autoawq 或 vLLM 的 AWQ 支持。
长上下文 ：默认 config.json 中 max_position_embeddings=32768，处理 32K 以上文本需要开启 YaRN（在 config.json 中加入 rope_scaling）。
下载缓存完整性 ：.cache/huggingface/download/ 中存在 .incomplete 文件，但目标模型文件已存在且大小完整，不影响使用。
聊天模板 ：必须使用 tokenizer.apply_chat_template(..., add_generation_prompt=True) 构造 prompt，以正确插入 <|im_start|> / <|im_end|> 标记。
tokenizer 最大长度 ：tokenizer_config.json 声明 model_max_length=131072，但实际支持的生成长度受显存和推理框架限制。

分析生成时间：2026-10-29

八、训练框架推断与关键参数作用

1. 能反推出什么训练框架？

从当前目录里的文件不能直接 100% 确定预训练框架，只能确定：

发布/推理框架 ：Hugging Face transformers（model_type: qwen2，transformers_version: 4.41.1，.safetensors 格式）。
底层计算框架 ：PyTorch（.safetensors 元数据里 format: pt）。
预训练框架 ：配置本身不写明训练代码。Qwen2.5 由阿里云通义团队开发，公开技术报告显示预训练通常基于 PyTorch + 自研分布式训练系统 ，结合类似 Megatron-LM / DeepSpeed 的 3D 并行（数据并行、张量并行、流水线并行）以及 FlashAttention 等优化。

因此可以合理推断：

阶段	可能使用的框架/技术	依据
预训练（Pretraining）	PyTorch + 自研/Megatron/DeepSpeed 分布式框架	超大模型（14B）需要 TP/PP/DP；Qwen 团队公开资料
指令微调（SFT）	PyTorch + Transformers / DeepSpeed / LLaMA-Factory 等	模型卡片未说明，但这是行业常见做法
AWQ 量化	autoawq / LLM-AWQ	`quantization_config.quant_method: awq`
发布格式	Hugging Face Transformers 4.41.1	`transformers_version`、标准 transformers 配置

注意：transformers_version: 4.41.1 只说明该 checkpoint 是用这个版本的 transformers 保存/验证的，不代表训练时用的就是 transformers。

2. 关键参数在训练中的作用

模型容量与形状参数

参数	值	训练中的作用
`hidden_size`	`5120`	模型宽度，即每层隐藏向量维度。决定embedding、注意力、MLP 的矩阵规模，是计算量和参数量最大的因素之一。
`num_hidden_layers`	`48`	模型深度。层数越多，模型抽象能力越强，但训练稳定性、梯度传播、显存占用都会增加。
`num_attention_heads`	`40`	Query 注意力头数。决定注意力机制的多头数量，通常 `head_dim = hidden_size / num_heads = 128`。
`num_key_value_heads`	`8`	GQA（Grouped Query Attention）的 KV 头数。训练时降低 KV 缓存和通信量，但保持 40 个 Query 头；`40/8=5`，每个 KV 头被 5 个 Query 头共享。
`intermediate_size`	`13824`	MLP 中间层维度。配合 `hidden_act: silu` 实现 SwiGLU：`silu(gate_proj(x)) ⊙ up_proj(x)`，再经 `down_proj` 投影回 `hidden_size`。
`tie_word_embeddings`	`false`	输入 embedding 与输出 `lm_head` 不共享权重。训练时多出一组可学习参数，通常能提升性能，但增加显存。
`vocab_size`	`152064`	词表大小。决定 embedding 矩阵输出维度，也影响最后的分类头大小。

归一化、初始化与正则化

参数	值	训练中的作用
`hidden_act`	`silu`	SwiGLU 的激活函数部分，是现代 LLM 常用的门控激活，提升 MLP 表达能力。
`rms_norm_eps`	`1e-06`	RMSNorm 的小常数，防止除零，影响训练数值稳定性。
`initializer_range`	`0.02`	线性层/嵌入层权重的初始化标准差。较大或较小的值都会影响收敛和梯度爆炸/消失风险。
`attention_dropout`	`0.0`	注意力层的 dropout 率。当前设为 0，说明预训练/SFT 时没有使用 attention dropout（大模型常见）。

位置编码与上下文长度

参数	值	训练中的作用
`max_position_embeddings`	`32768`	训练时使用的最大序列长度，决定 RoPE 频率表长度和 attention mask 的规模。
`rope_theta`	`1000000.0`	RoPE 基频。值越大，高频分量的波长越长，有助于长上下文外推（NTK-aware 行为）。
`sliding_window`	`131072`	支持的最大上下文窗口。结合 YaRN 等技术可将 32K 模型外推到 128K。
`max_window_layers`	`70`	启用滑动窗口注意力的层数（本模型仅 48 层，所以实际全部层都参与长上下文策略）。
`use_sliding_window`	`false`	当前默认不启用滑动窗口；在特定长文本推理配置中可开启。

训练目标与推理优化

参数	值	训练中的作用
`architectures`	`Qwen2ForCausalLM`	训练目标为因果语言建模（Causal LM），即下一个 token 预测，损失函数为交叉熵。
`use_cache`	`true`	推理时使用 KV Cache 加速自回归生成；训练时通常关闭或不使用。
`torch_dtype`	`float16`	发布权重的存储/计算 dtype。训练本身可能使用 BF16/FP16 混合精度，AWQ 量化后的权重以 FP16 缩放+I32 量化值形式存储。
`quantization_config`	AWQ 4-bit	训练后量化（Post-Training Quantization），用于降低部署显存和加速推理，不参与训练过程。

Tokenizer / 数据相关

参数/文件	说明	训练中的作用
`chat_template`	Jinja2 模板	决定 SFT/指令微调数据的 prompt 格式（system/user/assistant/tool_call），直接影响模型遵循指令的能力。
`added_tokens_decoder`	22 个特殊 token	在 tokenizer 训练后追加的特殊标记，用于对话边界、多模态占位、FIM、工具调用等。
`vocab.json` / `merges.txt`	BPE 词表与合并规则	定义文本如何被切分为 subword token，是预训练和 SFT 的输入编码基础。

3. 小结

训练框架：配置文件只能说明发布格式是 Hugging Face transformers + PyTorch；真正的预训练框架大概率是阿里云基于 PyTorch 自研或兼容 Megatron/DeepSpeed 的分布式训练系统。
关键参数决定：模型容量（hidden/layers/heads）、注意力效率（GQA）、训练长度（RoPE、max_position_embeddings）、优化稳定性（RMSNorm eps、初始化）、训练目标（CausalLM）以及部署量化（AWQ）。
训练 vs 推理 ：quantization_config、use_cache、torch_dtype 主要服务于推理/部署；hidden_size、num_layers、rope_theta 等才是训练阶段的核心设计选择。

Qwen2.5-14B-Instruct-AWQ 模型文件结构分析

一、目录概览

二、配置文件解析

1. config.json --- 模型架构配置

2. generation_config.json --- 默认生成参数

三、权重文件解析

1. model.safetensors.index.json

2. 三个 .safetensors 分片文件

四、Tokenizer 文件解析

1. tokenizer_config.json

2. tokenizer.json

3. vocab.json

4. merges.txt

五、其他文件

1. README.md

2. LICENSE

3. .gitattributes

4. .cache/huggingface/

六、模型架构总结

七、关键注意事项

八、训练框架推断与关键参数作用

1. 能反推出什么训练框架？

2. 关键参数在训练中的作用

模型容量与形状参数

归一化、初始化与正则化

位置编码与上下文长度

训练目标与推理优化

Tokenizer / 数据相关

3. 小结

1. `config.json` --- 模型架构配置

2. `generation_config.json` --- 默认生成参数

1. `model.safetensors.index.json`

2. 三个 `.safetensors` 分片文件

1. `tokenizer_config.json`

2. `tokenizer.json`

3. `vocab.json`

4. `merges.txt`

1. `README.md`

2. `LICENSE`

3. `.gitattributes`

4. `.cache/huggingface/`