GGUF Format Guide
用於量化本地 LLM 推論的通用格式
Model WeightsSpecification
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
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 │
└─────────────────────────────────────┘Example Data
# 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()}')"Ertas Support
GGUF 是 Ertas Studio 的一級匯出格式。在透過 Ertas 雲端訓練管線訓練或微調模型後,您可以選擇量化級別直接匯出為 GGUF。匯出過程自動處理從訓練檢查點格式到 GGUF 的轉換,包括嵌入分詞器配置和模型中繼資料。這產生一個單一的、自 包含的檔案,準備好供本地推論使用。
GGUF 匯出讓訓練好的模型可以帶著走。這個檔案可在本機硬體上以 llama.cpp、Ollama 或 LM Studio 執行,執行時不依賴 Ertas,也不會把推論請求送往第三方,適合模型處理的資料必須留在自家系統內的部署情境。訓練本身在 Ertas 的雲端 GPU 上執行,因此訓練資料會上傳至 Ertas;部署是否符合 HIPAA、GDPR 等規範,仍由貴組織自行負責。
Related Resources
Ship AI that runs on your users' devices.
Start free with 150 credits after card verification. Paid plans from $20/mo USD.