GGUF

GGUF — бинарный формат файлов для хранения языковых моделей, созданный в проекте llama.cpp. Один файл .gguf содержит всё необходимое для запуска: веса (обычно квантизованные), словарь и правила токенизатора, шаблон чата и параметры архитектуры. Благодаря этому GGUF стал стандартом де-факто для локального запуска моделей на ноутбуках, компьютерах Mac с Apple Silicon и потребительских видеокартах.

История

Георгий Герганов в марте 2023 года выпустил llama.cpp — реализацию модели LLaMA на чистом C/C++ поверх своей тензорной библиотеки ggml. Первые форматы файлов (GGML, затем GGJT) хранили мало метаданных, и каждое изменение ломало совместимость. В августе 2023 года их заменил GGUF — расширяемый формат, в который можно добавлять новые поля без поломки старых программ.^[1] Сегодня на Hugging Face размещены десятки тысяч моделей в GGUF, а Hub умеет показывать их метаданные и тензоры прямо в браузере.^[4]

Устройство файла

Файл состоит из трёх частей:^[1]

1. Заголовок — магическое число GGUF, версия формата, количество тензоров и метаданных.
2. Метаданные — пары «ключ — значение» с типами: general.architecture = llama, llama.context_length, tokenizer.ggml.tokens, tokenizer.chat_template и т. д.
3. Описание и данные тензоров — имена, формы, тип квантизации и смещения; данные выровнены, чтобы файл можно было отобразить в память (mmap) и начать работу без полного чтения.

Поскольку токенизатор и шаблон чата хранятся внутри, модель запускается одним файлом без конфигураций из исходного репозитория.

Квантизация

GGUF поддерживает множество способов сжатия весов. Названия кодируют число бит и вариант:^[3]

K-кванты (_K) группируют веса в блоки с собственными масштабами и разной точностью для разных слоёв (суффиксы S, M, L — меньше или больше бит на важные тензоры). IQ-кванты используют более сложные кодовые книги и дают лучшее качество при 2–3 битах. Для низкобитных вариантов применяют матрицу важности (imatrix), рассчитанную на калибровочном тексте.

Практическое правило: из двух моделей при одинаковом объёме памяти обычно лучше бо́льшая модель с Q4, чем меньшая с Q8. Оценить качество можно по перплексии (llama-perplexity) и на собственных задачах.

Конвертация

git clone https://github.com/ggml-org/llama.cpp && cd llama.cpp
pip install -r requirements.txt

# из формата Hugging Face в GGUF F16
python convert_hf_to_gguf.py ../Qwen2.5-7B-Instruct --outfile qwen-f16.gguf

# квантизация
./build/bin/llama-quantize qwen-f16.gguf qwen-Q4_K_M.gguf Q4_K_M

Готовые квантизованные файлы для популярных моделей обычно уже лежат на Hugging Face — их публикуют сами авторы моделей и энтузиасты.^[2]

Запуск

# llama.cpp: консоль или сервер с OpenAI-совместимым API
llama-cli -m qwen-Q4_K_M.gguf -p "Привет"
llama-server -m qwen-Q4_K_M.gguf -c 8192 -ngl 99   # -ngl: слои на GPU

# Ollama: прямо с Hugging Face
ollama run hf.co/Qwen/Qwen2.5-7B-Instruct-GGUF:Q4_K_M

Параметр -ngl (число слоёв на GPU) позволяет частично выгрузить модель в видеопамять, а остальное оставить в оперативной памяти — так большие модели работают даже на скромных видеокартах. В Ollama собственный GGUF подключается через Modelfile со строкой FROM ./model.gguf.^[5]

GGUF и другие форматы

vLLM умеет загружать GGUF, но для высокой нагрузки на серверных GPU эффективнее родные форматы. GGUF силён там, где важны простота — один файл — и работа на обычном железе.

См. также

• Локальный запуск LLM (llama.cpp, Ollama)
• Квантизация моделей
• vLLM и инференс-серверы
• Hugging Face

Источники

1. ggml — GGUF specification
2. llama.cpp — репозиторий
3. llama.cpp — quantize tool README
4. Hugging Face Docs — GGUF
5. Ollama — Importing a model (Modelfile)