GGUF (GGML Universal File) 是 llama.cpp 使用的统一模型文件格式，将模型权重、词表和元数据打包在单一二进制文件中。

为什么需要 gguf

LLM 模型通常包含权重、词表、超参数等多种数据，分散存储不利于分发和使用。GGUF 将所有信息打包到单一文件中，支持 mmap 高效加载，且设计为可扩展格式。

核心原理

GGUF 文件结构：

┌──────────────────┐
│ Header            │  magic (0x46475547) + version + tensor_count + metadata_count
├──────────────────┤
│ Metadata KV Pairs │  key-value 存储（架构、超参数、词表等）
├──────────────────┤
│ Tensor Info Array │  每个张量的名称、维度、类型、偏移量
├──────────────────┤
│ Alignment Padding │  对齐到指定边界
├──────────────────┤
│ Tensor Data       │  所有张量的二进制数据
└──────────────────┘

关键特性：

• 单一文件 — 权重 + 词表 + 配置一体化
• mmap 友好 — 支持内存映射，按需加载权重页
• 量化内置 — 张量可以是任意 GGML 数据类型
• 可扩展 — 通过 metadata KV 支持任意扩展信息

在源码中的实现

• ggml/src/gguf.cpp — GGUF 读写实现
• src/llama-model-loader.cpp — 使用 GGUF API 加载模型
• gguf-py/ — Python GGUF 工具库
• convert_hf_to_gguf.py — HuggingFace 模型转 GGUF

相关概念

• ggml — GGUF 底层的张量库
• tensor — GGUF 中存储的张量数据
• quantization — GGUF 支持的量化类型