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 匯出讓訓練好的模型可以帶著走。這個檔案可在本機硬體上以 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.