Wdrożenie

GGUF

2023AktywnyOpublikowano: 4 września 2026Aktualizacja: 4 września 2026Opublikowany

Binarny format pliku (następca GGML) do przechowywania i dystrybucji skwantyzowanych modeli językowych w ekosystemie llama.cpp/ggml.

Kluczowa innowacja

Spakowanie wag modelu, tokenizera i wszystkich metadanych do jednego, samoopisującego się pliku binarnego, co umożliwia dystrybucję i lokalne uruchamianie skwantyzowanych modeli bez zależności zewnętrznych.

Kategoria

Wdrożenie

Poziom abstrakcji

Building block

Poziom operacji

UdostępnianieWdrożenieInferencja

Zastosowania

Lokalne uruchamianie modeli językowych na CPU/GPUDystrybucja skwantyzowanych modeliInferencja na urządzeniach konsumenckichWdrażanie modeli w llama.cpp, Ollama i LM Studio

Jak działa

Plik GGUF składa się z nagłówka z liczbą magiczną i wersją formatu, sekcji par klucz-wartość z metadanymi (architektura, hiperparametry, konfiguracja tokenizera), tablicy informacji o tensorach (nazwa, kształt, typ danych/kwantyzacji, przesunięcie) oraz właściwych danych tensorów zapisanych jako bloki skwantyzowane lub w pełnej precyzji. Silnik inferencyjny (np. llama.cpp) mapuje plik do pamięci, odczytuje metadane, rekonstruuje graf modelu i wykonuje obliczenia bezpośrednio na skwantyzowanych blokach, dekwantyzując wartości w locie na CPU lub GPU.

Rozwiązany problem

Wcześniejsze formaty (GGML/GGMF/GGJT) były niestabilne i wymagały zewnętrznych plików oraz ręcznego podawania hiperparametrów, co utrudniało dystrybucję i zachowanie kompatybilności. GGUF konsoliduje wagi, metadane i tokenizer w jednym samoopisującym się pliku, zapewniając stabilność, rozszerzalność oraz proste, przenośne wdrażanie skwantyzowanych modeli.

Komponenty

Nagłówek (header)Identyfikacja formatu i wersji

Początek pliku z liczbą magiczną 'GGUF' i numerem wersji formatu, identyfikujący plik i jego strukturę.

Metadane klucz-wartośćSamoopis modelu

Standaryzowany zestaw par klucz-wartość opisujących architekturę, hiperparametry i konfigurację tokenizera modelu.

Informacje o tensorachIndeks tensorów

Tablica opisująca każdy tensor: nazwę, kształt, typ danych/kwantyzacji oraz przesunięcie w pliku.

Dane tensorówPrzechowywanie wag

Właściwe wagi modelu zapisane jako bloki skwantyzowane lub w pełnej precyzji, wyrównane dla mapowania pamięci.

Implementacja

Implementacje referencyjne

llama.cpp / ggml

C/C++ · Georgi Gerganov / ggml-org

Oficjalna

Pułapki implementacyjne

Zbyt agresywna kwantyzacjaWysoka

Bardzo niska precyzja (np. Q2_K, Q3_K) mocno redukuje rozmiar pliku, ale zauważalnie pogarsza jakość generacji, zwłaszcza dla mniejszych modeli.

Rozwiązanie:Dla większości zastosowań wybieraj Q4_K_M lub wyższe; do trudnych zadań preferuj Q5_K_M/Q6_K/Q8_0.

Niezgodność wersji formatu i silnikaŚrednia

Pliki GGUF utworzone nowszą wersją llama.cpp mogą zawierać metadane nieobsługiwane przez starsze wersje silnika, co uniemożliwia wczytanie modelu.

Rozwiązanie:Aktualizuj llama.cpp / narzędzie inferencyjne do wersji zgodnej z danym plikiem GGUF.

Brakujące lub błędne metadane szablonu czatu / tokenizeraŚrednia

Jeśli plik nie zawiera poprawnego szablonu promptu lub konfiguracji tokenizera, model może otrzymywać źle sformatowane wejście i generować gorsze odpowiedzi.

Rozwiązanie:Używaj plików GGUF z kompletnymi metadanymi lub jawnie ustaw właściwy szablon czatu w narzędziu inferencyjnym.

Ewolucja

2022

Powstanie biblioteki ggml (fundament formatów GGML/GGJT)

Georgi Gerganov tworzy bibliotekę tensorową ggml, na której opierają się wczesne formaty plików (GGML/GGMF/GGJT) do inferencji na CPU — bezpośredni poprzednik GGUF.

2023

Wprowadzenie GGUF jako następcy GGML

Punkt przełomowy

GGUF zastąpił formaty GGML/GGMF/GGJT w llama.cpp, wprowadzając samoopisujący się, rozszerzalny plik binarny.