模型文件与格式

模型格式是模型在磁盘上保存、分发和加载的方式。
它不只是“权重文件后缀名”，还会影响推理框架兼容性、量化方式、加载速度、安全性、跨平台部署和后续微调。

在大模型工程化中，常涉及的概念包括：

• Hugging Face 目录：最常见的模型发布结构，通常包含权重、配置、tokenizer 和 chat template。
• safetensors：安全、快速的张量权重文件格式。
• PyTorch checkpoint：常见后缀为 .bin、.pt、.pth，训练和研究场景常见。
• GGUF：llama.cpp 生态常用格式，适合本地推理和多种量化版本分发。
• ONNX：通用模型交换格式，适合跨框架和推理引擎部署。
• TensorRT / TensorRT-LLM engine：面向 NVIDIA GPU 的高性能推理格式。
• Adapter 权重：LoRA、QLoRA 等微调产物，通常不是完整模型。

理解模型格式的重点不是背后缀名，而是知道一个格式能被哪个运行时加载、包含哪些元数据、是否保留 tokenizer 和对话模板、是否绑定硬件和框架版本。

1. 模型文件到底包含什么

一个可用的大模型通常不只有权重。

完整模型目录常见内容包括：

文件 / 目录	作用
config.json	模型结构配置，例如层数、hidden size、attention heads、模型类型
model.safetensors / pytorch_model.bin	模型权重
model-00001-of-000xx.safetensors	分片保存的大模型权重
model.safetensors.index.json	权重分片索引，说明每个参数在哪个分片里
tokenizer.json	tokenizer 的完整定义
tokenizer_config.json	tokenizer 相关配置，可能包含 chat_template
special_tokens_map.json	特殊 token 映射，例如 BOS、EOS、PAD
generation_config.json	默认生成参数，例如 temperature、top_p、eos_token_id
preprocessor_config.json	多模态模型的图像、音频预处理配置
adapter_config.json	LoRA / Adapter 的配置
adapter_model.safetensors	LoRA / Adapter 权重

部署时经常出问题的不是权重本身，而是 tokenizer、special tokens、chat template 或多模态预处理配置没有一起迁移。

2. Hugging Face 模型目录

Hugging Face 模型目录不是单一文件格式，而是一组约定好的文件结构。

典型目录如下：

Qwen3-8B/
  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

这种结构的优点是生态兼容性强：

• Transformers 可以直接加载。
• vLLM、SGLang、TensorRT-LLM 等框架通常都支持从 HF 目录读取模型。
• tokenizer、模型配置和生成配置可以和权重一起分发。
• 大模型权重可以自动分片，便于下载和加载。

它的工程特点是：目录里的每个文件都可能影响最终行为。换权重、换 tokenizer、换 chat template，都可能让同一个模型表现不同。

3. safetensors

safetensors 是一种专门保存张量的文件格式，常见后缀为 .safetensors。

它解决的是传统 PyTorch pickle 权重文件的一些问题：

• 更安全：加载时不会执行任意 Python 代码。
• 加载更快：支持内存映射，适合大模型权重。
• 元数据清晰：文件中记录张量名称、形状和 dtype。
• 生态成熟：Hugging Face、vLLM、SGLang 等常见工具普遍支持。

典型文件：

model.safetensors
model-00001-of-00008.safetensors
adapter_model.safetensors

需要注意的是，safetensors 只保存张量。它不会自动包含模型结构、tokenizer、chat template 或生成参数。实际部署时仍然需要配套的 config.json 和 tokenizer 文件。

4. PyTorch checkpoint

PyTorch checkpoint 常见后缀包括：

• .bin
• .pt
• .pth

在早期 Hugging Face 模型和训练代码中，pytorch_model.bin 很常见。

优点：

• 与 PyTorch 训练流程天然兼容。
• 可以保存复杂对象，例如模型权重、优化器状态、训练步数和 scheduler 状态。
• 研究代码和自定义训练脚本中使用广泛。

缺点：

• 通常基于 pickle，加载不可信文件有安全风险。
• 跨语言、跨运行时兼容性不如 safetensors。
• 生产部署中可控性较弱。

工程上，如果只是发布推理权重，通常优先选择 safetensors。如果是保存训练断点，PyTorch checkpoint 仍然很常见。

5. GGUF

GGUF 是 llama.cpp 生态常用的模型格式，常见文件后缀为 .gguf。

它的定位和 Hugging Face 目录不同：GGUF 通常把本地推理需要的大量信息打包到一个文件里，包括权重、部分模型元数据、tokenizer 信息和量化信息。

常见文件名类似：

Qwen3-8B-Q4_K_M.gguf
Llama-3.1-8B-Instruct-Q5_K_M.gguf
DeepSeek-R1-Distill-Qwen-7B-Q8_0.gguf

文件名里的 Q4、Q5、Q8 通常表示量化等级，但具体含义取决于 llama.cpp 生态的量化类型。

5.1 GGUF 适合什么场景

GGUF 常见于：

• 本地桌面推理。
• CPU 推理。
• Mac Metal 推理。
• 消费级 GPU 推理。
• 边缘设备部署。
• 需要单文件分发的模型应用。

它的优势是使用门槛低，生态工具丰富，一个文件就能被 llama.cpp、Ollama、LM Studio 等工具加载。

5.2 GGUF 的注意点

GGUF 很适合本地推理，但不是所有服务端推理框架的首选格式。

需要注意：

• 不是所有模型结构都能稳定转换成 GGUF。
• 转换质量依赖 tokenizer、特殊 token 和 chat template 是否正确处理。
• 量化版本很多，Q4_K_M、Q5_K_M、Q8_0 等不能只看 bit 数，还要实际评估质量和速度。
• 某些新模型、多模态模型或 MoE 模型在 GGUF 生态中的支持可能滞后。
• GGUF 文件方便分发，但后续继续微调通常不直接基于 GGUF 进行。

如果目标是本地运行，GGUF 很合适。如果目标是生产服务端高并发，通常还要比较 vLLM、SGLang、TensorRT-LLM 等框架支持的格式。

6. GPTQ 与 AWQ 格式

GPTQ 和 AWQ 首先是量化方法，但在工程上也经常表现为特定的模型目录结构。

常见目录可能包含：

config.json
quantize_config.json
model.safetensors
tokenizer.json
tokenizer_config.json

或者：

awq_config.json
model-00001-of-00002.safetensors
model.safetensors.index.json

这里的关键不是后缀，而是推理框架需要知道：

• 权重是几 bit。
• 使用什么量化算法。
• group size 是多少。
• 是否使用 zero point。
• 哪些层被量化。
• 推理时应该使用哪种 kernel。

因此，部署 GPTQ / AWQ 模型时，不能只复制 .safetensors 权重，还要保留量化配置文件。

7. ONNX

ONNX（Open Neural Network Exchange）是一种通用模型交换格式，常见后缀为 .onnx。

它的目标是让模型从一个训练框架导出后，可以被不同推理引擎加载，例如 ONNX Runtime、TensorRT、OpenVINO 等。

ONNX 的优势：

• 跨框架。
• 推理引擎支持广。
• 适合传统深度学习模型、Embedding 模型、分类模型和部分 encoder 模型。
• 便于做图优化、算子融合和静态部署。

ONNX 的挑战：

• 自回归 LLM 的导出和部署更复杂。
• 动态 shape、KV Cache、多模态预处理和自定义算子容易带来兼容问题。
• 新模型结构可能需要较新的 opset 或自定义算子支持。
• 导出成功不等于推理结果完全一致，需要做数值和任务对齐验证。

对大语言模型来说，ONNX 更常见于 Embedding、reranker、分类模型或特定优化部署链路。通用 chat LLM 服务端部署通常会优先考虑 vLLM、SGLang、TensorRT-LLM 或 llama.cpp 生态。

8. TensorRT 与 TensorRT-LLM Engine

TensorRT engine 通常是为特定硬件、特定精度、特定 shape 或特定配置编译出来的推理产物。

它不是通用交换格式，而是高度优化后的运行时格式。

特点：

• 面向 NVIDIA GPU。
• 可以做算子融合、kernel 选择、低精度优化和图优化。
• 推理性能强，但构建过程更复杂。
• 常常和 GPU 架构、TensorRT 版本、CUDA 版本、模型配置绑定。

工程上要注意：

• engine 文件不一定能跨机器、跨 GPU 架构或跨 TensorRT 版本复用。
• 构建 engine 时的 batch、序列长度、精度、并行策略会影响可用范围。
• 模型升级、驱动升级或 TensorRT 升级后可能需要重新构建。
• 需要保存构建参数，否则后续很难复现性能和问题。

TensorRT-LLM 更适合对性能要求高、部署环境可控、工程团队能维护构建链路的生产场景。

9. Adapter 与 LoRA 权重

LoRA、QLoRA、Adapter 微调通常输出的不是完整模型，而是增量权重。

常见文件：

adapter_config.json
adapter_model.safetensors

这类文件必须和基座模型一起使用：

最终模型行为 = 基座模型 + Adapter 权重

部署时有两种方式：

方式	含义	适合场景
动态加载 Adapter	推理时加载基座模型，再挂载 adapter	多租户、多任务、频繁切换适配器
合并权重	把 adapter 合并进基座模型，导出完整权重	单一任务部署、简化推理链路

需要注意：

• Adapter 必须匹配训练时的基座模型版本。
• 同名模型的不同 revision 也可能不兼容。
• 合并后再量化，和先量化再挂 adapter，效果和部署方式可能不同。
• 只保存 adapter，不保存基座模型版本信息，会给复现带来很大风险。

10. Tokenizer 与 Chat Template

很多模型格式问题表面看是“权重加载失败”，实际是 tokenizer 或 chat template 不匹配。

部署时至少要确认：

• tokenizer 文件是否和训练时一致。
• bos_token、eos_token、pad_token 是否正确。
• eos_token_id 是否和推理框架的停止条件一致。
• chat template 是否和模型训练格式一致。
• 工具调用、思考模式、多模态占位符是否被正确渲染。

同一组 messages，不同 chat template 渲染后的 prompt 可能完全不同。模型格式迁移时，如果只迁移权重，不迁移 tokenizer 和模板，输出质量可能明显下降。

11. 多模态模型的额外文件

多模态模型通常不只有语言模型权重，还可能包含视觉塔、投影层和预处理配置。

常见文件包括：

• preprocessor_config.json
• processor_config.json
• image_processor_config.json
• video_processor_config.json
• 视觉 encoder 权重
• projector 权重
• 多模态 special tokens 配置

多模态模型转换格式时更容易出问题：

• 图片尺寸和归一化参数不一致。
• 图像占位 token 不匹配。
• vision encoder 没有一起导出。
• projector 权重遗漏。
• 推理框架只支持 language model 部分。

因此，多模态模型不要只按普通文本 LLM 的方式处理格式转换。

12. 格式选择建议

目标	推荐优先考虑	原因
Hugging Face 生态训练 / 微调	HF 目录 + safetensors	兼容 Transformers、PEFT、TRL 等工具
服务端通用推理	HF 目录 + safetensors / AWQ / GPTQ	vLLM、SGLang 等框架支持较好
本地桌面推理	GGUF	单文件分发，llama.cpp / Ollama / LM Studio 生态成熟
CPU 或边缘部署	GGUF / ONNX / OpenVINO	根据目标硬件选择
NVIDIA 高性能生产部署	TensorRT-LLM engine	性能强，但构建和维护成本高
LoRA 多任务部署	基座模型 + Adapter	便于多个任务共享同一个基座模型
跨框架传统模型部署	ONNX	交换格式成熟，推理引擎选择多

简单判断：

• 要训练或继续微调：优先保留 Hugging Face 目录。
• 要本地跑：优先看 GGUF。
• 要服务端高并发：优先看推理框架支持的 HF / AWQ / GPTQ / FP8 格式。
• 要极致 NVIDIA 性能：评估 TensorRT-LLM。

13. 转换格式时要检查什么

格式转换不是简单改后缀。

转换前后建议检查：

• 模型结构是否被目标格式支持。
• tokenizer 是否完整保留。
• special tokens 是否一致。
• chat template 是否保留或重新指定。
• 量化配置是否完整。
• dtype 是否符合预期。
• max position embeddings / rope scaling 是否正确。
• 多模态 processor 是否完整。
• 推理输出是否和原模型对齐。
• 目标框架是否真正使用了期望的低精度 kernel。

最小验证方式是准备一组固定 prompt，对比转换前后的输出：

• 短问答。
• 长上下文。
• JSON 格式输出。
• 工具调用。
• 中文和英文。
• 业务关键样本。
• 安全拒答样本。

不要只验证“模型能启动”。能启动只说明格式基本可读，不代表行为正确。

14. 版本与复现

模型格式和工具版本强相关。工程记录中建议保留：

• 原始模型名称和 revision / commit hash。
• 权重格式和分片信息。
• tokenizer 文件版本。
• chat template 内容或来源。
• 量化算法、bit 数、group size、校准数据。
• 转换工具和版本。
• 推理框架和版本。
• CUDA、驱动、TensorRT 等运行时版本。
• 构建 engine 的参数。

这些信息决定了后续能不能复现同样的模型行为和性能。

15. 常见问题

15.1 safetensors 和 GGUF 是一类东西吗

不完全是。

safetensors 主要是张量权重保存格式，常作为 Hugging Face 模型目录的一部分。GGUF 更偏向 llama.cpp 生态的本地推理模型格式，通常把权重、量化信息和部分元数据打包到单个文件中。

15.2 GGUF 可以直接拿去微调吗

通常不建议。GGUF 主要面向推理分发和加载。微调一般使用 Hugging Face 格式的基座模型，再用 PEFT、Transformers、LLaMA-Factory、Unsloth 等工具训练。

15.3 只有权重文件能不能部署

多数情况下不够。还需要模型结构配置、tokenizer、special tokens、chat template 和生成参数。多模态模型还需要 processor 和视觉相关权重。

15.4 量化格式和模型格式是什么关系

量化描述的是数值精度和压缩方法，模型格式描述的是保存和加载方式。二者会交织在一起。例如 GGUF 文件可以承载多种量化版本，AWQ / GPTQ 模型通常以 safetensors 权重加量化配置的目录形式存在。

15.5 为什么同一个模型换格式后效果变差

常见原因包括：

• tokenizer 不一致。
• chat template 丢失。
• special tokens 配置不同。
• 量化误差。
• rope scaling 或上下文长度配置错误。
• 推理框架默认生成参数不同。
• 多模态预处理不一致。

16. 总结

模型格式决定了模型如何被保存、迁移、加载和运行。对工程部署来说，格式选择会直接影响兼容性、性能、可复现性和排障难度。

可以按这个思路选择：

• 训练和微调优先保留 Hugging Face 目录和 safetensors。
• 本地推理优先考虑 GGUF。
• 服务端推理优先跟随 vLLM、SGLang、TensorRT-LLM 等框架支持的格式。
• LoRA 这类 adapter 要始终记录基座模型版本。
• 转换格式后必须验证 tokenizer、chat template、量化配置和真实任务输出。

工程上最稳妥的做法是：把“权重、配置、tokenizer、模板、量化参数、转换脚本、运行时版本”作为一个整体管理，而不是只管理某个权重文件。