AI Transformers 架构体系权重文件类型 safeterson和gguf格式转换【2-1】

模型权重文件：存储训练好的模型参数,也就是w和b，是模型推理和微调的基础
- .pt、.ckpt、.safetensors、gguf
配置文件：确保模型架构的一致性，使得权重文件能够正确加载
- config.json、generation_config.json
词汇表文件：保证输入输出的一致性
- tokenizer.json、tokenizer_config.json

1、模型权重文件

模型权重文件是存储训练好的模型参数，是模型推理和微调的基础，常见的有.pt、.ckpt、.safetensors
不同的框架（如TensorFlow、PyTorch）使用不同的模型文件格式

例如：

safetensors：适配多种框架，支持transformers库的模型加载
PyTorch：选择下载.pt或.bin格式的模型文件。
TensorFlow：选择下载.ckpt或.h5格式的模型文件。

1.1 safetensors是什么？

.safetensors是由Hugging Face提出的一种新型的模型权重文件格式，有以下特点：

安全性：.safetensors采用了加密和校验机制，防止模型文件被篡改或注入恶意代码
性能：优化了数据加载和解析速度
跨框架支持：有多种深度学习框架的兼容性，便于在不同环境中使用

.safetensors中，大模型可被分为多个部分，格式类似modelname-0001.safetensors、modelname-0002.safetensors
model.safetensors.index.json是索引文件，记录了模型的各个部分的位置和大小信息

2、配置文件

config.json、generation_config.json

2.1 config.json

config.json包含模型的配置信息（如模型架构、参数设置等）,可能包含隐藏层的数量、每层的神经元数、注意力头的数量等
config.json的基本结构如下:

(base) [root@inspur-nf5468m6-001 Qwen2.5-VL-32B-Instruct]# cat config.json 
{"architectures": ["Qwen2_5_VLForConditionalGeneration"],"attention_dropout": 0.0,"eos_token_id": 151645,"hidden_act": "silu","hidden_size": 5120,"image_token_id": 151655,"initializer_range": 0.02,"intermediate_size": 27648,"max_position_embeddings": 128000,"max_window_layers": 64,"model_type": "qwen2_5_vl","num_attention_heads": 40,"num_hidden_layers": 64,"num_key_value_heads": 8,"pad_token_id": 151643,"rms_norm_eps": 1e-06,"rope_scaling": {"mrope_section": [16,24,24],"rope_type": "default","type": "default"},"rope_theta": 1000000.0,"sliding_window": 32768,"tie_word_embeddings": false,"torch_dtype": "bfloat16","transformers_version": "4.49.0","use_cache": true,"use_sliding_window": false,"video_token_id": 151656,"vision_config": {"hidden_size": 1280,"in_chans": 3,"intermediate_size": 3456,"model_type": "qwen2_5_vl","out_hidden_size": 5120,"spatial_patch_size": 14,"tokens_per_second": 2,"torch_dtype": "bfloat16"},"vision_end_token_id": 151653,"vision_start_token_id": 151652,"vision_token_id": 151654,"vocab_size": 152064
}

例如architectures字段指定了模型的架构，hidden_act字段指定了隐藏层的激活函数，hidden_size字段指定了隐藏层的神经元数
num_attention_heads字段指定了注意力头的数量，max_position_embeddings字段指定了模型能处理的最大输入长度等

2.2 generation_config.json

generation_config.json是用于生成文本的配置文件，包含了生成文本时的参数设置，如max_length、temperature、top_k等
generation_config.json的基本结构如下:

(base) [root@inspur-nf5468m6-001 Qwen2.5-VL-32B-Instruct]# cat generation_config.json 
{"bos_token_id": 151643,"pad_token_id": 151643,"do_sample": true,"eos_token_id": [151645,151643],"repetition_penalty": 1.05,"temperature": 0.000001,"transformers_version": "4.49.0"
}

例如bos_token_id字段指定了开始标记的ID，eos_token_id字段指定了结束标记的ID，do_sample字段指定了是否使用采样，temperature字段用于控制生成文本的随机性，max_length字段指定了生成文本的最大长度，top_p字段指定了采样的概率等
config.json 和 generation_config.json 都可能包含 "bos_token_id"（Beginning of Sequence Token ID）和 "eos_token_id"（End of Sequence Token ID）。在config.json中，这两个字段用于模型的加载和训练，而在generation_config.json中，这两个字段用于生成文本时的参数设置
config.json 提供模型的基本信息，而 generation_config.json 则细化为生成任务的具体需求

3、词汇表文件

词汇表文件包含了模型使用的词汇表或标记器信息，是自然语言处理模型理解和生成文本的基础。

tokenizer.json、tokenizer_config.json

3.1 tokenizer.json

tokenizer.json包含了模型使用的词汇表信息，如词汇表的大小、特殊标记的ID等
tokenizer.json的基本结构如下:

{"version": "1.0","truncation": {"max_length": 128,"strategy": "longest_first"},"padding": {"side": "right","pad_id": 0,"pad_token": "[PAD]"},"added_tokens": [{"id": 128010,"content": "[CUSTOM]"}],"normalizer": {"type": "NFD","lowercase": true,"strip_accents": true},"pre_tokenizer": {"type": "ByteLevel","add_prefix_space": true},"post_processor": {"type": "AddSpecialTokens","special_tokens": {"cls_token": "[CLS]","sep_token": "[SEP]"}},"decoder": {"type": "ByteLevel"},"model": {"type": "BPE",...}
}

其中truncation是定义截断策略，用于限制输入序列的最大长度，padding用于统一输入序列的长度,added_tokens列出分词器额外添加到词汇表中的特殊标记或自定义标记
normalizer用于定义文本标准化的步骤和规则，用于在分词前对输入文本进行预处理，pre_tokenizer定义分词器如何将输入文本分割为初步的tokens，post_processor定义分词后处理的步骤
decoder定义如何将tokens ID 序列解码回原始文本,model定义了分词器的模型信息，如词汇表、合并规则（对于 BPE）等

3.2 tokenizer_config.json

tokenizer_config.json是用于生成文本的配置文件，包含了生成文本时的参数设置，如max_length、temperature、top_k等
tokenizer_config.json的基本结构如下:

{"added_tokens_decoder": [],"bos_token": "begin_of_text |>","clean_up_tokenization_spaces": true,"eos_token": "<|end_of_text|>","model_input_names": ["input_ids", "attention_mask"],"model_max_length": 1000000,"tokenizer_class": "PreTrainedTokenizerFast"
}

其中added_tokens_decoder定义分词器在解码（将 token ID 转换回文本）过程中需要额外处理的特殊标记或自定义标记
bos_token、eos_token定义开始、结束标记，clean_up_tokenization_spaces定义了是否清除分词后的多余空格等
tokenizer.json和tokenizer_config.json的区别：tokenizer.json侧重于分词器的训练和加载，而tokenizer_config.json更侧重于生成文本时的参数设置

为什么很多模型都没有 vocab.txt 了？现代分词器采用了更为丰富和灵活的文件格式，如 tokenizer.json，以支持更复杂的分词策略和特殊标记处理

一、背景介绍

在AI模型部署领域，模型格式的选择直接影响推理效率、内存占用和跨平台兼容性。Safetensors和GGUF作为两种重要格式，分别服务于不同的应用场景：

Safetensors
基于protobuf的二进制格式，提供安全的张量存储
支持分片（sharding）和加密功能
广泛用Hugging Face生态系统
典型应用：模型微调、分布式训练
GGUF
基于GGML生态的新型格式（GGML v2）
针对CPU推理优化的内存布局
支持多种量化模式（4/5/8bit）
典型应用：边缘设备部署、低资源环境

本文将详细讲解如何通过Transformers框架将Safetensors模型转换为GGUF格式，并深入探讨转换过程中的关键技术细节。

二、转换原理与核心流程

2.1 格式转换的本质

Safetensors到GGUF的转换本质是： 1. 张量数据的序列化格式转换 2. 内存布局的优化重组 3. 可选的量化参数调整

2.2 核心转换流程

graph TDA[Safetensors模型] --> B[加载模型权重]B --> C[转换为PyTorch张量]C --> D[执行量化操作]D --> E[生成GGUF格式文件]E --> F[验证输出文件]

三、环境准备

3.1 依赖安装

# 安装Transformers库
pip install transformers# 安装GGUF工具链
pip install llama-cpp-python

3.2 硬件要求

CPU：Intel/AMD x86-64架构（推荐支持AVX2指令集）
内存：至少为模型未量化状态的2倍
存储：SSD推荐（处理大模型时提升速度）

公司环境 .

四、转换步骤详解

4.1 加载Safetensors模型

from transformers import AutoTokenizer, AutoModelForCausalLMmodel_name = "Qwen/Qwen2.5-VL-32B-Instruct"
model = AutoModelForCausalLM.from_pretrained(model_name, device_map="gpu")
tokenizer = AutoTokenizer.from_pretrained(model_name)

4.2 初始化GGUF转换器

from llama_cpp import GGUFConverterconverter = GGUFConverter(model=model,tokenizer=tokenizer,max_seq_len=2048,target_format="ggufv2"
)

4.3 执行转换操作

output_path = "Qwen2.5-VL-32B-Instruct.gguf"
converter.convert(output_path=output_path,quantization="q4_0",  # 可选量化模式force=True            # 覆盖已有文件
)

4.4 验证转换结果

from llama_cpp import Llamallm = Llama(model_path=output_path,n_ctx=2048,n_threads=8
)prompt = "你好，我是jettech"
output = llm(prompt, max_tokens=512)
print(output["choices"][0]["text"])

五、高级配置选项

5.1 量化参数设置

参数名称	说明	推荐值
quantization	量化模式	"q4_0"
group_size	量化分组大小（影响精度）	128
use_mmap	使用内存映射加速加载	True

5.2 内存优化策略

# 启用内存优化模式
converter = GGUFConverter(...,memory_friendly=True,temp_dir="/tmp/gguf_conversion"
)

六、常见问题与解决方案

6.1 转换失败处理

错误信息：Invalid tensor shape
解决方案：检查模型架构是否兼容（需为CausalLM类型）
错误信息：Out of memory
解决方案：分块处理模型（使用chunk_size参数）

七、格式对比与应用场景

7.1 关键指标对比

指标	Safetensors	GGUF
典型文件大小	原始浮点数	量化后1/4-1/8
加载速度	较慢（需反序列化）	极快（内存映射）
推理速度	CPU/GPU优化	CPU极致优化
跨平台支持	全平台	x86/ARM