GGUF Format Guide

用于量化本地 LLM 推理的通用格式

Model Weights

Specification

GGUF（GPT-Generated Unified Format）是一种二进制文件格式，专为存储量化大语言模型以实现高效本地推理而设计。该格式由 Georgi Gerganov 作为 llama.cpp 项目的一部分开发，于 2023 年 8 月取代了旧版 GGML 格式，增加了自描述元数据系统，将模型架构细节、分词器配置和量化参数直接嵌入文件中。这使得 GGUF 文件具有可移植性和自包含性——加载和运行模型所需的一切都在一个文件中。

GGUF 格式由三个部分组成：包含格式版本和张量数量的头部，包含模型配置（架构类型、上下文长度、词汇表大小、嵌入维度、注意力头数量和分词器数据）的元数据键值存储，以及包含实际模型权重量化表示的张量数据部分。元数据系统使用类型化的键值对，支持整数、浮点数、布尔值、字符串和数组，无需外部配置文件即可实现丰富的模型描述。

GGUF 支持多种量化类型，从全精度的 F32 和 F16 到激进量化的 Q2_K 和 IQ1_S。最常用的量化级别包括 Q4_K_M（在质量和大小之间取得良好平衡）、Q5_K_M（稍大但质量更高）和 Q8_0（接近无损）。K-quant 变体（Q4_K_S、Q4_K_M、Q5_K_S 等）使用精密的混合精度方法，根据不同层的敏感度将其量化到不同级别，在相似文件大小下产生比均匀量化更好的质量。

When to Use GGUF

当你需要在本地运行 LLM 推理时——无论是个人电脑、边缘设备还是不依赖 GPU 推理框架的本地服务器——GGUF 都是首选格式。它是 llama.cpp 的原生格式，并得到广泛本地推理工具生态系统的支持，包括 Ollama、LM Studio、GPT4All、koboldcpp 和 text-generation-webui。如果你的目标是部署微调模型用于本地使用且不依赖云服务，GGUF 应该是你的目标导出格式。

当你需要高效的 CPU 推理或部署目标 GPU 内存有限时，应选择 GGUF。GGUF 的量化选项允许你在模型质量和更小的文件大小及更快的推理速度之间权衡，使大型模型能够在消费级硬件上运行。一个 FP16 下需要 14 GB 的 7B 参数模型，通过 Q4_K_M 量化可缩减至约 4 GB，同时保留大部分性能。这使得 GGUF 对于数据不能离开本地机器的隐私敏感型部署至关重要。

当你需要在 GPU 集群上实现最大推理吞吐量时（此类场景请使用 SafeTensors 配合 vLLM 或 TensorRT-LLM），或需要继续训练模型时（GGUF 是仅推理格式——训练请使用 SafeTensors 或 PyTorch 检查点），GGUF 不太适用。对于 llama.cpp 不支持的非 Transformer 架构，它也不是正确的选择。

Schema / Structure

text

GGUF File Structure:
┌─────────────────────────────────────┐
│ Header                              │
│  - Magic number: 0x46475547 "GGUF"  │
│  - Version: uint32 (currently 3)    │
│  - Tensor count: uint64             │
│  - Metadata KV count: uint64        │
├─────────────────────────────────────┤
│ Metadata Key-Value Pairs            │
│  - general.architecture: string     │
│  - general.name: string             │
│  - llama.context_length: uint32     │
│  - llama.embedding_length: uint32   │
│  - llama.block_count: uint32        │
│  - llama.attention.head_count: u32  │
│  - tokenizer.ggml.model: string     │
│  - tokenizer.ggml.tokens: [string]  │
│  - ... (additional metadata)        │
├─────────────────────────────────────┤
│ Tensor Info (for each tensor)       │
│  - Name: string                     │
│  - Dimensions: uint32[]             │
│  - Type: enum (F32/F16/Q4_K/...)    │
│  - Offset: uint64                   │
├─────────────────────────────────────┤
│ Tensor Data (aligned, contiguous)   │
│  - Raw quantized weight data        │
└─────────────────────────────────────┘

GGUF 二进制文件结构，包含头部、元数据、张量信息和权重数据部分

Example Data

bash

# Convert a HuggingFace model to GGUF using llama.cpp
python convert_hf_to_gguf.py ./my-fine-tuned-model \
  --outfile model-f16.gguf \
  --outtype f16

# Quantize to Q4_K_M for efficient local inference
./llama-quantize model-f16.gguf model-q4_k_m.gguf Q4_K_M

# Run inference with llama.cpp
./llama-cli -m model-q4_k_m.gguf \
  -p "Explain quantum computing in simple terms:" \
  -n 256 --temp 0.7

# Inspect GGUF metadata
python -c "
from gguf import GGUFReader
reader = GGUFReader('model-q4_k_m.gguf')
for field in reader.fields.values():
    print(f'{field.name}: {field.parts[-1].tolist()}')"

GGUF 模型文件的转换、量化、运行和元数据检查

Ertas Support

GGUF 是 Ertas Studio 的一等导出格式。在通过 Ertas 云训练流水线完成模型训练或微调后，你可以直接导出为 GGUF 并选择所需的量化级别。导出过程会自动处理从训练检查点格式到 GGUF 的转换，包括嵌入分词器配置和模型元数据，生成一个可直接用于本地推理的自包含文件。

GGUF 导出功能是 Ertas 隐私优先架构的核心。通过导出为 GGUF，你的微调模型完全在本地硬件上运行，无需云推理调用、无需 API 依赖、数据不会离开你的环境。这使得 GGUF 导出对于要求数据主权、HIPAA、GDPR 合规或气隙运行的敏感合规部署至关重要。

Related Resources

Glossary

Quantization

Ship AI that runs on your users' devices.

Early bird pricing starts at $14.50/mo — locked in for life. Plans for builders and agencies.

View early bird pricing or join the waitlist →