LLM-GUIDELLM × llama.cpp Конфигуратор …
Главная / 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.

Что читать дальше

Конвертация в GGUF → Квантование → Типы квантования.

Живые вопросы — ассистенту
Ответы по статьям справочника с цитатами ID источников; моделирование конфигураций под ваше железо — детерминированным калькулятором.
🤖 Спросить ассистента 🧮 Подобрать конфигурацию