# GGUF

> Формат файлов для квантизованных языковых моделей экосистемы llama.cpp — веса, токенизатор и метаданные в одном файле; используется Ollama, LM Studio и другими.

Источник: https://llmdocs.ru/wiki/gguf/ · обновлено 2026-11-09 · лицензия CC BY-SA 4.0

- **Полное название**: GPT-Generated Unified Format (по распространённой версии)
- **Появление**: август 2023
- **Предшественник**: GGML, GGJT
- **Проект**: llama.cpp / ggml (Георгий Герганов)
- **Содержимое**: тензоры, токенизатор, шаблон чата, гиперпараметры
- **Типы квантизации**: F16, Q8_0, Q6_K, Q5_K_M, Q4_K_M, IQ-кванты
- **Используют**: llama.cpp, Ollama, LM Studio, GPT4All, koboldcpp
**GGUF** — бинарный формат файлов для хранения языковых моделей, созданный в проекте llama.cpp. Один файл `.gguf` содержит всё необходимое для запуска: веса (обычно [квантизованные](https://llmdocs.ru/wiki/quantization.md)), словарь и правила [токенизатора](https://llmdocs.ru/wiki/tokenization.md), шаблон чата и параметры архитектуры. Благодаря этому GGUF стал стандартом де-факто для [локального запуска моделей](https://llmdocs.ru/wiki/local-llm.md) на ноутбуках, компьютерах Mac с Apple Silicon и потребительских видеокартах.

## История

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

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

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

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

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

## Квантизация

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

| Тип | Бит на вес (≈) | Размер модели 8B | Качество |
|---|---|---|---|
| F16 / BF16 | 16 | ~16 ГБ | исходное |
| Q8_0 | 8,5 | ~8,5 ГБ | практически без потерь |
| Q6_K | 6,6 | ~6,6 ГБ | очень близко к исходному |
| Q5_K_M | 5,7 | ~5,7 ГБ | хороший баланс |
| Q4_K_M | 4,8 | ~4,9 ГБ | самый популярный выбор |
| Q3_K_M | 3,9 | ~4 ГБ | заметная деградация |
| IQ2_XS | 2,3 | ~2,5 ГБ | только для очень больших моделей |

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

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

## Конвертация

```bash
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]

## Запуск

```bash
# 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 и другие форматы

| Формат | Для чего |
|---|---|
| **GGUF** | локальный запуск, CPU и смешанный CPU+GPU, Apple Silicon |
| **safetensors** | исходные веса на Hugging Face, обучение, серверные движки |
| **AWQ, GPTQ, FP8** | квантизованные веса для серверных GPU в [vLLM](https://llmdocs.ru/wiki/vllm.md) и подобных |
| **[ONNX](https://llmdocs.ru/wiki/onnx.md)** | кроссплатформенный инференс небольших моделей |
| **MLX** | оптимизированный запуск на Apple Silicon через фреймворк Apple |

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

## См. также

- [Локальный запуск LLM (llama.cpp, Ollama)](https://llmdocs.ru/wiki/local-llm.md)
- [Квантизация моделей](https://llmdocs.ru/wiki/quantization.md)
- [vLLM и инференс-серверы](https://llmdocs.ru/wiki/vllm.md)
- [Hugging Face](https://llmdocs.ru/wiki/hugging-face.md)

## Источники

1. [ggml — GGUF specification](https://github.com/ggml-org/ggml/blob/master/docs/gguf.md)
2. [llama.cpp — репозиторий](https://github.com/ggml-org/llama.cpp)
3. [llama.cpp — quantize tool README](https://github.com/ggml-org/llama.cpp/blob/master/tools/quantize/README.md)
4. [Hugging Face Docs — GGUF](https://huggingface.co/docs/hub/gguf)
5. [Ollama — Importing a model (Modelfile)](https://github.com/ollama/ollama/blob/main/docs/import.md)