← 返回首页

GGUF 元数据读法:header 与 tensor 信息里的八个陷阱

ggufllama.cpp模型量化

TL;DR:我用 gguf-py 0.19.0 在 Windows 上从零写了一个 GGUF 文件,再读回来逐字段对照,发现八处「写进去」和「读出来」不一致,其中三处连异常都没有。最狠的一处是 general.alignment:只把它当普通元数据写进文件,写盘时仍按 32 字节补位,而读回时按 64 字节找偏移,于是同一个库写出的文件自己读不回来,报错是 ValueError: cannot reshape array of size 0 into shape (3,)。本文的每条结论都能用文中的命令复现,正文不含任何联盟推广链接。

// FLOW_01本文的元数据对照链路6 NODES01STEP_01写最小 GGUF02STEP_02读回全部字段03STEP_03与写入值对照04STEP_04分清类型与对齐05STEP_05逐项修调用06STEP_06回归复验END_OF_FLOW
本文的元数据对照链路 · 依据本文步骤自绘示意图
Python
文中涉及的技术标识 · 图标来自 Simple Icons(CC0)

为什么值得自己造一个最小 GGUF 文件

网上讲 GGUF 的文章大多停在「GGUF 是 llama.cpp 用的模型格式,量化后体积更小」。真到自己动手核对一个模型文件的元数据时,问题立刻变成另一类:哪些字段决定加载行为,字段的类型和长度谁来保证,写错了会在哪一步炸。

我这次的起点很小:想确认一个模型文件的 general.file_type 和每个张量的维度到底是什么。手上没有 GPU,也不想下载几个 GB 的权重,于是反过来做——用官方 Python 包自己写一个文件,再自己读回来。文件只有几百字节,但把元数据层的语义全都走了一遍。

结果是:这份「自己写、自己读」的对照表里,有八处在没有报错的情况下给出了错误答案。这比报错更麻烦,因为它不会打断你的脚本。

环境与两条可复制的命令

全部实验在 Windows 11(10.0.26300)、CPython 3.13.14、gguf 0.19.0(PyPI 上传时间 2026-05-06)、numpy 2.5.5 上完成。装包用隔离目录,避免污染主环境:

python -m pip install --target ./pylibs gguf==0.19.0 numpy
python -c "import sys; sys.path.insert(0,'./pylibs'); import gguf; print(gguf.GGUF_VERSION, gguf.GGUF_MAGIC, gguf.READER_SUPPORTED_VERSIONS)"

第二条命令打印 3 1179993927 [2, 3]:当前写入版本是 3,magic 的十进制值,以及读端只接受版本 2 和 3。这三个数后面都会用到。

下面这段脚本就是本文所有结论的最小复现体,可以直接存成 demo.py 跑:

import sys
sys.path.insert(0, "./pylibs")
import numpy as np
from gguf import GGUFWriter, GGUFReader

w = GGUFWriter("demo.gguf", "llama")
w.add_file_type(1)
w.add_uint32("demo.uint", 4294967295)
w.add_array("demo.arr", [1, 2, 3])
w.add_tensor("demo.weight", np.arange(6, dtype=np.float32).reshape(2, 3))
w.write_header_to_file()
w.write_kv_data_to_file()
w.write_tensors_to_file()
w.close()

r = GGUFReader("demo.gguf")
print([k for k in r.fields if not k.startswith("GGUF.")])
print(r.get_field("demo.uint").contents())
print(r.tensors[0].shape.tolist())
print(r.tensors[0].data.shape)

输出里最后两行分别是 [3, 2] 和 (2, 3)。同一块数据,两个 API 给出两套维度——这就是后面的第一个「不报错但反直觉」。

陷阱一:教程里的 write_header 和 write_footer 都不存在

第一批踩到的坑来自照抄示例。很多教程写:

w.write_header()
w.write_kv_data_to_file()
w.write_tensors_to_file()
w.write_footer()

在 0.19.0 上第一行就死:

AttributeError: 'GGUFWriter' object has no attribute 'write_header'

用 hasattr 逐个打一遍就清楚了:write_header 是 False,write_footer 也是 False,真正存在的是 write_header_to_file、write_kv_data_to_file、write_tensors_to_file、ti_data_to_file、flush、close。写入顺序是固定的四步:

读端也有一处同名陷阱:GGUFReader 没有 get(),只有 get_field() 和 get_tensor()。写 r.get("general.architecture") 会得到 AttributeError: 'GGUFReader' object has no attribute 'get'。

陷阱二:reader.tensors 是列表,不是字典

几乎所有示例都这么取值:

reader = GGUFReader(path)
t = reader.tensors["blk.0.attn_q.weight"]

0.19.0 里这行直接抛异常:

TypeError: list indices must be integers or slices, not str

因为 reader.tensors 是 list,ReaderTensor 是 NamedTuple,要按索引或先建映射:

by_name = {t.name: t for t in reader.tensors}
t = by_name["blk.0.attn_q.weight"]

这个差别不是装饰性的。用字典写法时,你写的是「按名字查」,实际语义却是「按顺序查」,一旦某个版本改了张量顺序,取值就会静默错位——这里恰好被 TypeError 挡住了,算运气好。

陷阱三:shape 是文件里的顺序,不是 numpy 的顺序

前面 demo.py 里我写进一个 (2, 3) 的数组,读回来 tensors[0].shape 是 [3, 2],而 tensors[0].data.shape 是 (2, 3)。

原因在两边源码里写得很直白:写端循环是 ti.shape[n_dims - 1 - j],也就是把 numpy 维度倒着写进文件(ggml 约定第一维是最内层);读端把原始 dims 原样存进 ReaderTensor.shape,再用 reversed(dims) 去 reshape 数据。所以 shape 字段的语义是「文件里的维度顺序」,data.shape 才是「numpy 的维度顺序」。想在打印或日志里放维度,用后者。

量化张量更绕一层。我写了 144 字节打包数据、raw_dtype 指定 Q4_K:

w.add_tensor("q4", np.zeros(144, dtype=np.uint8), raw_dtype=GGMLQuantizationType.Q4_K)

读回后 shape 是 [256](元素数),n_bytes 是 144,而 data.shape 是 (144,)(打包字节数)。也就是说,对量化张量,shape 与 data.shape 不是「顺序不同」,而是量的根本不是同一个东西。拿 shape 去算内存占用会算错 256/144 倍。

陷阱四:get_field 找不到键时返回 None,不报错

f = r.get_field("general.quantization_version")
print(f.contents())

如果这个键不存在,get_field 返回 None,然后在 .contents() 上炸:

AttributeError: 'NoneType' object has no attribute 'contents'

这个报错至少会炸。真正麻烦的是不做后续取值的写法:if r.get_field(key): 在「键存在但值为 0」时同样为假,于是「字段缺失」和「字段值是 0」被混成一件事。要区分两者,用 key in r.fields 判断存在性,用 .contents() 取值。

顺便记一下 contents() 的返回形态:标量返回 Python 标量,字符串返回 str,数组返回 list,空数组返回 []。不要指望它返回 numpy 数组。

陷阱五:add_array 传空列表,这个键根本不会被写入

这是本文最「安静」的一处。源码里 add_array 第一件事就是:

if len(val) == 0:
    return

直接返回,不写键、不打日志、不抛异常。我构造了三个键——before、ghost(空数组)、after——文件里只读到两个:

字段: ['general.architecture', 'before', 'after']
ghost 是否存在: False | kv_count 声明: 3

头部声明的 KV 数是 3,实际能读到的自定义键是 2 个。也就是说,一个「可选词表」或「可选适配层列表」参数如果是空的,你的文件里就真的没有这个字段,下游按「字段存在」判断的逻辑会全部落到 else 分支。

深层那个本该拦住它的检查还在:_pack_val 里有 raise ValueError("Invalid GGUF metadata array. Empty array"),但 add_array 的提前返回让它永远走不到。两层防线,第一层把第二层废了。

陷阱六:同名键只打一条 warning,然后连类型一起覆盖

先写 add_uint32("dup", 1),再写 add_string("dup", "one"),文件照样生成,读回来是:

同键改类型后: STRING = one

日志里只有一行 Duplicated key name 'dup', overwriting it with new value 'one' of type STRING。如果你的日志级别是 ERROR(生产环境常见),这行完全看不到。结果是:一个本该是 uint32 的字段被写成字符串,读取方按 uint32 解析时会拿到完全不同的东西,或者干脆在别处炸。

同一条链路上还有个相关的坑:数组元素类型只由第一个元素决定,且 Python 的 int 一律当 INT32。源码里 GGUFValueType.get_type 对 int 直接返回 INT32,旁边还留着 # TODO: need help with 64-bit types in Python。所以下面这行(1099511627776 就是 2 的 40 次方):

w.add_array("big", [1099511627776])

会在写盘阶段抛

struct.error: 'i' format requires -2147483648 <= number <= 2147483647

而 w.add_array("mixed", [1, 2.5]) 抛的是 ValueError: All items in a GGUF array should be of the same type。两个报错,一个在类型推断阶段,一个在字节打包阶段,都不在 add_array 调用那一行——排查时容易误判成文件写入失败。

陷阱七:general.alignment 写进元数据,写盘时却还按 32 补位

这是本次实验里唯一一个「写得出、读不回」的问题,也是我认为最该写进笔记的一条。

GGUF 的布局规则是:张量信息表之后补零,补到 general.alignment 的整数倍,之后才是张量数据。规范里写得很清楚,默认对齐是 32,align_offset 就是按这个字段算的。

于是我照字面理解,把对齐当成普通元数据写:

w.add_uint32("general.alignment", 64)

写出来的文件 192 字节。再用同一个库读回:

ValueError: cannot reshape array of size 0 into shape (3,)

原因在写端源码:self.data_alignment = GGUF_DEFAULT_ALIGNMENT(32)是构造时定死的,补位用的是 self.data_alignment,跟 KV 里的 general.alignment 毫无关系。写端按 32 补位(数据从第 160 字节起),读端按 64 找偏移(从第 192 字节起找),于是读到 0 字节,reshape 失败。

正确写法是专用方法,它会把两件事一起做:

w.add_custom_alignment(64)

这个方法内部先校验「非零且是 2 的幂」,再同时设置 self.data_alignment 和写 KV。改完之后:文件 256 字节,读回 alignment=64、data_offset=192、数据 [1. 1. 1.]。

三种写法的对照如下:

写法文件大小data_offset能否读回
不写对齐(默认 32)160 B128能
只写 general.alignment=64192 B写端仍按 32不能,reshape 报错
用 add_custom_alignment(64)256 B192能

读端对这个字段还有两道校验,值得抄下来当自查项:类型不是 UINT32 会抛 ValueError: Bad type for general.alignment field;值不是 2 的幂会抛 ValueError: Invalid alignment: must be a non-zero power of two。我把值改成 0 和 3,两次都命中后一条。

陷阱八:头部的两个计数被无条件相信

GGUF 头部除了 magic 和版本,还有两个 uint64:张量数、元数据 KV 数。读端完全按这两个数去解析,不做任何交叉验证。

我把一个合法文件的 tensor_count 改成 0,读回成功,len(reader.tensors) 是 0——文件里明明还有 256 字节张量数据,读端安静地忽略了它。把 kv_count 改成 999,读回抛的是:

IndexError: index 0 is out of bounds for axis 0 with size 0

一个越界 IndexError,跟「你的 KV 数写错了」毫无字面关系。截断文件同理,四种长度给出四种完全不同的异常(ValueError: not enough values to unpack、ValueError: When changing to a larger dtype...、IndexError: index 0 is out of bounds...、cannot reshape array of size 39 into shape (8, 8)),没有一个提到「文件不完整」。

所以判一个 GGUF 文件是否完整,只能自己算:文件长度 >= data_offset + 所有张量 n_bytes 之和,并且头部声明的张量数要等于实际解析出的张量数。这套「头部声明一个数、内容另算一个数」的结构,和 CSV 记录边界 里那个字段数固定的假设是同一类风险:只要声明的数目和实际不符,后面的解析全都要错位。

版本、字节序与规范的落差

读端只接受版本 2 和 3。我把版本号分别改成 0、1、2、3、4,只有 2 和 3 能读,其余三种都是同一句:

ValueError: Sorry, file appears to be version 1 which we cannot handle

magic 写成 GGML 抛 ValueError: GGUF magic invalid——注意这是全小写的自定义文案,不是 struct.error,用异常类型做兜底时要单独认它。

字节序这一条,规范与实现有落差。规范原文是「At the time of writing, there is no way to determine if a model is big-endian; this may be rectified in future versions.」,但 gguf-py 的读端其实做了启发式判断:读到的版本号低 16 位为 0 时,就认定这是反字节序文件并翻转解析。我用 endianess=GGUFEndian.BIG 写了一个大端文件,读回时 reader.byte_order 是 'S',字段内容正确。

还有一个规范上限没被实现强制:规范写张量的 n_dimensions「Currently at most 4」,而写端对 5 维张量照写不误,n_dimensions 字段真的写成了 5,读端也照读。也就是说「规范不允许」和「这个库会拒绝」是两件事,别拿库不报错当合规证明。

Troubleshooting:四个真实报错与修复

以下四条全部在本文环境里现场复现,报错原文可直接搜索。

报错一:AttributeError: 'GGUFWriter' object has no attribute 'write_header'

python -c "import sys; sys.path.insert(0,'./pylibs'); from gguf import GGUFWriter, GGUFReader; print([m for m in ('write_header','write_header_to_file','write_footer','write_tensors_to_file') if hasattr(GGUFWriter, m)]); print([m for m in ('get','get_field','get_tensor') if hasattr(GGUFReader, m)])"

报错二:ValueError: cannot reshape array of size 0 into shape (3,)

报错三:TypeError: list indices must be integers or slices, not str

报错四:struct.error: 'i' format requires -2147483648 <= number <= 2147483647

另外两个不常见的形态也记一下:只调 add_tensor_info 不给数据,write_tensors_to_file() 抛的是没有消息的 AssertionError(消息为空串,日志里只有类型);状态机顺序错则抛 ValueError: Expected output file to contain KV data, got WriterState.HEADER——这条文案里的状态名(NO_FILE / HEADER / KV_DATA)比报错本身更有用,直接指出了你卡在第几步。

上线前的六条自查

常见问题

Q:既然同一个库自己都读不回自己写的文件,是不是这个库不能用?

A:不是。对齐那条是调用方式错了——用 add_custom_alignment() 就一致,写端读端都按 64 走。真正需要警惕的是那些不报错的项(空数组、重复键、计数被信任),它们不会给你第二次机会。

Q:为什么不直接下载一个真实的 GGUF 模型来验证?

A:两个原因。体积(最小的可用模型也要几百 MB,量化版更大)和可解释性(真实文件里字段成百上千,出问题时无法定位到具体哪一行写入逻辑)。自己造的文件只有几百字节,每个字节都是自己写的,对照才有意义。真实模型适合做最后一轮回归,不适合用来定位语义。

Q:元数据里的字符串长度按字符数还是字节数算?

A:字节数。我写了三个键:cafe 的长度字段是 4,café 是 5(4 个字符),中文「中文」是 6(2 个字符)。所以用 len(s) 去校验长度字段,遇到非 ASCII 一定算错。这和编码层的坑是同一个根:字符串在文件里是字节串,不是字符序列。五种 decode 策略的对照 里我逐条测过同一个坏字节会被变成什么,可以对照着看。

Q:GGUF 的版本号与量化类型号是同一套编号吗?

A:不是。版本号是文件结构版本(当前 3,读端接受 2 和 3),量化类型号是 ggml_type 枚举(F32=0、F16=1、Q8_0=8、Q4_K=12 这类)。两者都在头部附近出现,但一个是 uint32 的格式版本,一个是张量信息里的类型码,混用会直接读错数据。

写在最后

我原本只想确认一个字段的值,最后写出了一张八行的「读回来和写进去不一致」对照表。这类问题的共同点是:没有任何一层负责校验语义。写端只保证字节能落盘,读端只保证按头部声明解析,中间的「你写的和你以为的」没有人管。

如果这篇让你少踩一次对齐的坑,它的价值就到了。想做同类对照的话,YAML 解析层的类型归属(no 变成 False、1:30 变成 90)是同一个思路的另一个战场;打包层的六个静默失败(pip install 成功却跑旧代码)则是「产物和源码不一致」的第三种形态。三篇连起来看,「写进去的东西不等于读出来的东西」这条线就比较完整了。

本文不含任何联盟推广链接,所有结论均可用文中命令复现。

👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务

👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速

📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测

🔗 精选推荐工具

使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):

作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。

☁️ DigitalOcean 云服务器 ⚡ Vultr 高性能 VPS 🤖 QoderWork 中国版(推荐有奖) ☁️ 阿里云爆款 AI 产品 📚 WordPress 实用书单 🧠 AI / 大模型书单 🏗️ 系统设计/云架构书单 🐳 Docker/K8s 书单 🐧 Linux 系统管理书单 🐍 Python 编程书单 🗄️ 数据库/PostgreSQL 书单 🚀 DevOps/SRE 书单 🤖 小米 MiMo 开放平台
← 返回首页