文件头解析：从魔数到元数据起点

GGUF 文件的第一眼，就看文件头。它像一张身份证，告诉你：这是不是有效文件？用什么版本？里面有多少东西？从哪个位置开始找真正的干货？

我刚开始接触 GGUF 时，也犯过傻——直接跳过头校验，拿着数据就开干。结果解析到一半程序崩溃，愣是找了半天才发现是魔数不对，文件被截断了。从那以后，我养成了个习惯：文件头字段，必须一个不落地校验。

1. 魔数（Magic Number）—— 文件身份的第一道关

魔数就是文件开头的固定字节序列。GGUF 的魔数是 0x465547474C474D55，转换成 ASCII 就是 "GGUF" 加上些填充（实际上是 "GGUF" 后跟 0x0D 0x0A 等，但标准读取时按 8 字节无符号整数处理）。

在 C 里，我一般这样读：

uint64_t magic;
fread(&magic, sizeof(magic), 1, file);
if (magic != 0x465547474C474D55ULL) {
    fprintf(stderr, "Not a valid GGUF file\n");
    exit(1);
}

注意小端序。GGUF 规定所有多字节整数都是小端存储。如果你的机器是大端，得做字节序转换。不过现在大部分 x86 平台都是小端，所以直接读没问题。

我曾经踩过的坑： 有人把 GGML 和 GGUF 文件搞混。GGML 的魔数是 0x67676D6C（"ggml" 的 ASCII），长度不一样。如果你只校验最低 4 字节，GGML 文件可能误闯进来。请始终校验完整的 8 字节魔数。

2. 版本号（Version）—— 解析器兼容性的关键

紧接魔数之后，是一个 32 位无符号整数：版本号。当前稳定版本是 3（GGUF v3），早期还有 v1、v2。

版本号直接影响后续字段的解析逻辑。比如 v2 和 v3 的元数据偏移布局就有细微差别。我建议在解析时做一次显式的版本检查：

uint32_t version;
fread(&version, sizeof(version), 1, file);
if (version < 2 || version > 3) {
    fprintf(stderr, "Unsupported GGUF version: %u\n", version);
    exit(1);
}

别问我为什么 v1 要排除——我在一个遗留项目里见过 v1 文件，它的 tensor_count 字段类型跟 v2 以后不一样，直接解析会读乱。最好统一只支持 v2/v3。

3. 张量数量（Tensor Count）—— 规划内存分配

再往下是 64 位无符号整数：张量数量 tensor_count。它告诉你这个文件里有多少个权重张量。

这个数字很重要。我在写解析器时，会根据它提前 malloc 好张量指针数组。如果读错成 32 位，碰到大模型（比如 100 万个张量）就会溢出崩溃。

对应的 C 代码：

uint64_t tensor_count;
fread(&tensor_count, sizeof(tensor_count), 1, file);

然后你可以用 tensor_count 分配一个 ggml_tensor** 数组。记得 tensor_count 也可能是 0——纯元数据模型，没有权重。虽然不常见，但解析器得能处理。

4. 元数据键值对起始偏移（Metadata KV Start Offset）

v3 新增了这个字段（v2 里它叫 metadata_offset，含义稍有不同）。它是一个 64 位整数，指向元数据键值对在文件中的起始字节位置（通常紧跟在文件头之后）。

有了它，你可以不需要先扫描一遍所有元数据，就能直接定位到键值对区域，然后逐个读取 key-value。偏移量是相对于文件开头的绝对字节数。我当时第一次看到这个字段时，觉得没什么用，直到我需要跳过大量元数据（比如整个 tokenizer 配置）去读张量数据时，才发现它节省了一次遍历。

读取方式一样：

uint64_t metadata_kv_start;
fread(&metadata_kv_start, sizeof(metadata_kv_start), 1, file);
字段类型字节数描述
Magicuint648固定值 0x465547474C474D55
Versionuint324GGUF 版本号，当前为 3
Tensor Countuint648文件中张量的数量
Metadata KV Start Offsetuint648元数据键值对起始偏移量

文件头总大小：8 + 4 + 8 + 8 = 28 字节。读取 28 字节后，你就能获得所有关键信息，再往后就是元数据区。

GGUF 文件头布局（28 字节） Magic 8 字节 Version 4 字节 Tensor Count 8 字节 Metadata Offset 8 字节 元数据区 键值对 所有多字节整数均为小端序，总偏移从 0 开始

5. 实战：用 Python 解析 GGUF 文件头

下面是一个 Python 示例，使用 struct 模块读取并打印文件头信息：

import struct

def read_gguf_header(filepath):
    with open(filepath, 'rb') as f:
        header_bytes = f.read(28)
        magic, ver, tensor_cnt, meta_off = struct.unpack(
            '<QQII', header_bytes  # Q=uint64, I=uint32, 小端
        )
        # 注意：这里为了简洁用了 <QQII，但实际顺序是 Q Q I Q
        # 正确的 unpack 应为 <Q I Q Q
        magic, ver, tensor_cnt, meta_off = struct.unpack(
            '<Q I Q Q', header_bytes
        )
        return magic, ver, tensor_cnt, meta_off

magic, ver, tc, off = read_gguf_header("model.gguf")
print(f"Magic: 0x{magic:016X}")
print(f"Version: {ver}")
print(f"Tensor Count: {tc}")
print(f"Metadata Offset: {off}")
小技巧： 如果你需要极速解析，可以用 mmap 将文件映射到内存，然后通过切片直接取 28 字节，避免多次系统调用。对于几百 GB 的大模型，这个优化能省不少时间。
曾经踩过的坑（续）： 我遇到过有人把 meta_off 误认为是元数据总长度，直接拿它分配缓冲区。结果分配了 4GB 的虚拟内存，程序瞬间被 OOM 杀掉。记住：那是偏移量，不是长度。

解析完这 28 字节，你就能决定下面如何前进：如果 tensor_count == 0，整个文件可能只有元数据；否则，从 meta_off 开始读取键值对，然后依次解析张量信息。文件头就是整个解析流程的起跑线，校验得越严，后续越稳。

← 上一章 📖 返回目录 下一章 →