模型文件后缀大全:看懂后缀,选对引擎

0 阅读7分钟

模型文件后缀大全:看懂后缀,选对引擎

从 Hugging Face 下了个模型,兴冲冲丢给 Ollama,ollama run 直接报错。或者反过来,从 Ollama 拉下来的东西想塞进 Transformers,怎么都加载不了。

这两种挫败感来源一样:这些后缀根本不在同一个层级上。有的描述权重怎么存,有的描述整个计算图怎么存,有的描述「打包好的、可以脱离训练框架独立运行的产物」。把它们当同类比较,就会一直觉得「模型格式怎么这么乱」。

按谁读它来分,其实只有三类。

第一类:给训练框架读的权重

这类文件的存在前提是「你有一套 Python 环境,里面有 PyTorch 或 TensorFlow,还有对应的模型定义代码」。

后缀谁生成特点坑
.safetensorsHugging Face纯张量、无代码执行、可内存映射,加载快只存权重,模型结构还在 config.json 里
.binPyTorch(torch.save)老格式,本质是 picklepickle 能执行任意代码,来源不明的一律别加载
.pt / .pthPyTorch通常是训练检查点,可能带优化器状态文件往往是完整模型的数倍大,推理用不上
.h5TensorFlow / KerasTF 时代的主力新项目基本不用了,遇到多半是老资产
.msgpackFlax / JAXJAX 生态的权重格式生态小,工具链支持一般

这张表里最该记住的是 .safetensors 和 .bin 的关系:它们是同一件事(存权重)的两种做法,前者是后者的安全替代品。safetensors 只允许存张量,没有反序列化执行逻辑的入口,所以不存在「加载模型等于执行了一段陌生代码」这个风险。

这也是为什么现在主流模型仓库优先发 safetensors。你在 HF 上看到 pytorch_model.bin 和 model.safetensors 同时存在,优先下后者,别图省事下 .bin。

两者的体积几乎一样,差在加载方式。safetensors 可以直接内存映射,加载时不需要把整个文件读进内存再反序列化,所以对于几十 GB 的权重,冷启动时间能差出十几秒到几十秒。这个差别在本地测试时感觉不到,在容器里频繁重启的服务上很明显。

第二类:给推理引擎读的打包产物

这类文件的特点是:它自带结构和权重,不需要原始训练代码。你不需要知道这个模型有几层注意力,引擎自己能读明白。

后缀谁读特点
.ggufllama.cpp / Ollama / LM Studio单文件,含元信息 + 量化权重,CPU 也能跑
.onnxONNXRuntime / TensorRT / 各种端侧框架计算图 + 权重,跨框架、跨语言,部署友好

.gguf 值得多说两句,因为它是最多人踩坑的地方。HF 上下的 safetensors 不能直接喂给 Ollama —— 那是原始权重,Ollama 要的是量化打包后的 GGUF。两者不互通,这是格式层面的不同,不是配置问题。

反过来也一样:GGUF 是为推理优化的产物,你想拿它继续微调,得先反量化,精度和效果都会损失。拿推理格式当训练起点,是很多人白折腾一星期的原因。

.gguf 的文件名里通常带量化等级,比如 Q4_K_M、Q5_K_S、Q8_0。这套命名有规律:Q4 表示 4 bit,K 表示用了 k-quant 混合量化策略,M / S 是对同一 bit 数下不同层的精度分配。经验上 Q4_K_M 是质量与体积的平衡点,Q8_0 接近原始精度但体积大,Q2 那种能跑但回答质量已经明显退化。选之前先想清楚你是要「塞进显存」还是「回答质量」。

一个粗略的换算:7B 模型 fp16 大约 14 GB,Q4 量化后大约 4 GB 左右,差距主要在「能不能塞进一张消费级卡的显存」这条线上。所以本地跑的第一道门槛往往不是算力,是显存,而量化就是拿一点点质量去换这条线。

这也是为什么同一个模型会有五六个 GGUF 变体。它们不是不同模型,是同一套权重的不同精度切片。挑之前先算清楚你的显存还剩多少,比看别人推荐什么有用。

.onnx 的定位不一样:它解决的是「同一套模型能不能在 Python 之外的地方跑」。浏览器、移动端、C++ 服务、各种加速卡,只要实现了 ONNX 运行时就能加载。代价是转换过程可能丢算子,遇到不支持的自定义算子就得自己补实现。

第三类:描述怎么用这个模型的小文件

这类文件没有权重,但少了它模型就跑不起来,而且报错往往很隐晦。

文件作用缺了会怎样
config.json层数、隐藏维度、注意力头数等结构参数加载时报 shape 不匹配,或者干脆认不出架构
generation_config.json默认的采样参数(温度、top_p、eos)能跑,但输出风格和官方演示不一样
tokenizer.json / tokenizer.model分词规则直接报 vocab 相关错误
special_tokens_map.jsonBOS/EOS/PAD 等特殊符号映射生成的文本边界会出错,表现为重复或截断
model.safetensors.index.json分片索引:哪个张量在哪个文件里大模型分片下载时缺了它,等于没有地图

最后这条特别值得说。7B 以上的模型经常被切成好几个文件(model-00001-of-00004.safetensors 这种),索引文件负责告诉加载器「去哪个文件找哪块权重」。下载中断只下了两片,索引却齐全,报错信息会指向一个莫名其妙的张量名,很难联想到是缺分片。

一张报错对照表

比读文档更快的是认报错。

报错大致长什么样多半是什么先查什么
OSError: ... does not appear to have a file named config.json目录不对,或者只下了部分文件ls 看目录,确认是仓库根而不是子目录
size mismatch for ... / shape 不匹配权重和结构对不上,常是混用了不同版本config.json 与权重是不是同一仓库同一次发布
Unable to load weights from pytorch checkpoint.bin 不完整或损坏文件大小对不对,重新下
There is no ... key in the state dict缺分片,或者这是 LoRA 适配器而不是完整模型看有没有 index.json、看文件名带不带 adapter
ollama: file does not exist / 加载后乱码拿 safetensors 当 GGUF,或者反过来格式根本不互通,换产物

这张表的价值不在准确,在能让你在前两分钟里排除掉大半错误方向。

一条判断链

顺序本身比每一条的内容更重要。按顺序走,你是在排除错误;乱着看,你是在猜。

拿到一个模型目录,按这个顺序看,基本不会错:

第一步,有没有 config.json。没有的话,这可能不是「可直接加载的模型」,而是一个导出中间产物或者数据集。

第二步,权重是 safetensors 还是 bin。有前者用前者。

第三步,有没有 .gguf。有的话,说明这是给 llama.cpp 系引擎准备的,直接拿去做本地推理,别往 Transformers 里塞。

第四步,看有没有 index.json。有的话,先确认分片数量齐全,再看总大小对不对得上。

第五步,才轮到看量化等级和显存够不够。

这个顺序的作用是把「格式问题」和「资源问题」分开。很多人一上来就算显存,算完发现还差 20G,其实是把 .pt 检查点当推理权重下了。

什么时候该换工具,而不是换格式

一个经验判断:如果你在花时间转格式,多半是工具选错了,不是格式选错了。

想在笔记本上跑个 7B 聊天,用 Ollama 或 LM Studio,直接拉 GGUF,别碰 Transformers。

想做微调、改结构、接自定义训练流程,用 Transformers + safetensors,别拿 GGUF 当起点。

想部署到端侧、嵌入式、或者某个只认 C++ 的推理服务,走 ONNX。

这三条路各自有成熟的默认选择。真正麻烦的从来不是「哪个格式好」,而是「你以为自己在 A 路,其实需求在 B 路」。前面那些下载报错、加载失败,绝大多数是这一步没对齐。


这类「先分清层次再动手」的判断,我在书里讲了不止一处。为什么不用参数表和技术栈清单来讲这件事,理由其实不在技术细节里 —— 那套讲法我留在了公众号。

书在这儿:effective-llm.pages.dev/ 代码在这儿:github.com/agentgeex/e…