GGUF Format Guide

用於量化本地 LLM 推論的通用格式

Model Weights

Specification

GGUF（GPT-Generated Unified Format）是一種二進位檔案格式，專為儲存量化大型語言模型以進行高效本地推論而設計。由 Georgi Gerganov 作為 llama.cpp 專案的一部分開發，GGUF 於 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 的量化選項允許您以模型品質換取更小的檔案大小和更快的推論，使大型模型能在消費級硬體上運行。使用 Q4_K_M 量化，需要 14 GB FP16 的 7B 參數模型可以減小到大約 4 GB，同時保留大部分能力。這使 GGUF 對於資料不能離開本地機器的隱私敏感部署至關重要。

GGUF 不太適合需要在 GPU 叢集上獲得最大推論吞吐量的情況（請改用帶有 vLLM 或 TensorRT-LLM 的 SafeTensors），或者需要繼續訓練模型的情況（GGUF 是僅限推論的格式——請使用 SafeTensors 或 PyTorch 檢查點進行訓練）。對於 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 →