Главная / llama.cpp Handbook / Формат GGUF
Формат GGUF
Коротко: GGUF — контейнер «всё в одном файле»: тензоры весов + метаданные (архитектура, токенизатор, чат-шаблон, параметры квантования). llama.cpp работает только с GGUF; всё остальное (safetensors, PyTorch) сначала конвертируется.
Структура файла
┌────────────────────────────┐
│ Header: magic "GGUF", │ версия формата, число полей/тензоров
│ Metadata (KV-пары): │ general.architecture, *.block_count,
│ │ tokenizer.*, tokenizer.chat_template,
│ │ *.context_length, quant-схемы и пр.
│ Tensors: │ имя, размеры, тип; данные (квант-блоки)
│ Alignment-паддинг │
└────────────────────────────┘
- Метаданные — машиночитаемые KV-пары; из них llama.cpp узнаёт профиль модели
(трансформер: число слоёв, голов,
kv_heads) и строит вычисления. Переопределить отдельные поля на старте:--override-kv. - Токенизатор (tokenization) — словарь и правила внутри файла; модель не требует внешних файлов.
- Чат-шаблон (chat-templates) — jinja в метаданных
(
tokenizer.chat_template); применяется автоматически. - Тензоры — веса в f16/bf16 или квант-блоках (K/I-схемы — блоки с масштабами).
Крупные модели распространяются шардами (-00001-of-00003.gguf); llama.cpp
подхватывает нумерованные шарды автоматически; «лишние» файлы-дополнения подключаются
через --shard (например PLE-таблицы эмбеддингов — docs/models.md).
Как читать/править метаданные
- Python: библиотека
gguf-py(в составе llama.cpp) — чтение/запись GGUF. - В браузере: HF-спейс GGUF-editor (правка метаданных без кода,
docs/models.md). - Диагностика содержимого:
--check-tensors(проверка данных на невалидные значения).
Практические следствия
| Задача | Что делать |
|---|---|
| Нужен GGUF из HF-модели | Конвертация (convert_hf_to_gguf.py) |
| Нужен квант | llama-quantize поверх GGUF f16 |
| «unsupported architecture» | llama.cpp не знает профиль из метаданных — обновить версию / проверить файл: diag-load |
| «bad magic» | файл вообще не GGUF (HTML-страница, часть шардирования) — diag-load |
Связь с LLM Handbook
GGUF делает модель самодостаточной: токенизатор, профиль трансформера, чат-шаблон едут вместе с весами. Полную матрицу соответствий — CROSSMAP.
Что читать дальше
Живые вопросы — ассистенту
Ответы по статьям справочника с цитатами ID источников; моделирование
конфигураций под ваше железо — детерминированным калькулятором.