Формат GGUF: полное руководство по локальному выводу LLM

Что такое GGUF?

GGUF, расшифровывается как GGML Unified Format, — это двоичный файловый формат, который упаковывает веса модели, данные токенизатора, метаданные об архитектуре и информацию о квантизации в один переносимый файл для инференса в средах на базе GGML (в частности, llama.cpp).

GGUF решает проблему развёртывания LLM. Многие форматы моделей требуют держать вместе несколько файлов, включая веса, файлы токенизатора, конфигурации и архитектурно-зависимый код загрузки. GGUF упрощает это, делая файл модели в значительной степени самоописательным.

Обычно файл GGUF содержит:

• Тензоры модели
• Квантованные или неквантованные веса
• Словарь токенизатора
• Конфигурацию токенизатора
• Метаданные об архитектуре модели
• Настройки длины контекста
• Размерность эмбеддингов
• Количество голов внимания
• Конфигурацию RoPE
• Названия тензоров, их формы и типы данных

Ключевая идея — файл описывает сам себя. Среда выполнения может прочитать метаданные, понять архитектуру, загрузить токенизатор и отобразить тензоры без отдельного config.json или папки токенизатора.

Это не означает, что любой GGUF-файл совместим с любой средой навсегда. Среда всё равно должна поддерживать архитектуру модели и типы тензоров, используемые в файле. Однако GGUF значительно упрощает совместимость по сравнению со старыми форматами, поскольку файл содержит гораздо больше структурированной информации.

Четыре определяющих характеристики GGUF:

1. Развёртывание одним файлом
2. Поддержка отображения в память для эффективной загрузки
3. Расширяемые типизированные метаданные в формате ключ–значение
4. Поддержка множества типов квантизации — от агрессивных низкобитных до полной точности

GGUF был представлен в составе экосистемы llama.cpp и GGML в 2023 году. Сейчас это доминирующий формат распространения квантованных локальных LLM на Hugging Face.

GGUF vs. GGML

GGML (Georgi Gerganov Machine Learning) был предшественником GGUF. Он сыграл важную роль, сделав возможным ранний локальный инференс. Но по мере выхода за рамки исходных моделей LLaMA проявились практические ограничения.

Типичные трудности GGML:

• Менее гибкая работа с метаданными
• Больше допущений, зависящих от архитектуры, при загрузке
• Менее самодостаточная обработка токенизатора и конфигурации
• Сложное расширение по мере появления новых семейств моделей

GGUF устранил эти ограничения за счёт более структурированного формата. Он ввёл типизированные метаданные, улучшенную интеграцию эмбеддингов токенизатора и более понятную структуру файла. Это упростило поддержку большего количества архитектур в llama.cpp и родственных инструментах без постоянной переработки конвейера загрузки.

Для пользователей важное отличие простое: GGUF — современный формат. Если вы скачиваете модели сегодня, почти всегда стоит выбирать GGUF, а не устаревшие файлы GGML.

GGUF vs. GPTQ и AWQ

Изучая форматы файлов, вы наверняка встречали GGUF, GPTQ (Generative Post-Training Quantization) и AWQ (Activation-Aware Weight Quantization). Их часто обсуждают вместе, поскольку все три используются для повышения эффективности инференса LLM. Однако это не идентичные категории.

GGUF — прежде всего файловый формат и контейнер для развёртывания. Он поддерживает множество типов квантизации и тесно связан с локальным инференсом в стиле llama.cpp.

GPTQ и AWQ — это методы квантизации и экосистемы, часто используемые для оптимизированного под GPU инференса, особенно на оборудовании NVIDIA через такие фреймворки, как Transformers, ExLlama, AutoGPTQ и рабочие процессы, совместимые с vLLM.

Если ваша цель — максимальная совместимость на ноутбуках, десктопах, Apple Silicon и смешанном оборудовании, GGUF обычно безопаснее.

Если ваша цель — максимальная пропускная способность на выделенных серверах NVIDIA для инференса, форматы и методы, оптимизированные под GPU — GPTQ, AWQ, FP8 и др. — могут подойти лучше.

Зачем использовать GGUF?

GGUF стал популярным, потому что решает практические задачи развёртывания. Мне он также кажется крайне удобным при локальном запуске без сложной настройки.

Раньше локальные LLM включали разрозненные инструменты, большие некомпрессированные веса, несовместимые форматы моделей и сложные шаги настройки. GGUF помогает стандартизировать значительную часть этого процесса.

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

Запуск моделей локально

GGUF позволяет запускать LLM на вашей собственной машине. Это означает:

• Нет покомпонентной оплаты за токены в API
• Нет зависимости от хостингового провайдера инференса
• Нет необходимости отправлять подсказки в сторонний API
• Возможен офлайн-инференс после загрузки модели

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

Локальный инференс сам по себе не обеспечивает автоматической безопасности. По-прежнему нужно корректно управлять машиной, логами, приложениями и доступом. Но GGUF делает частное локальное развёртывание гораздо доступнее.

Для практики локального запуска смотрите наши руководства по подаче Mistral Medium 3.5 в SGLang, локальному запуску DeepSeek V4 Flash, запуску эффективной модели Bonsai 1-bit на старом ноутбуке и локальному запуску MiniMax M2 в роли помощника по коду.

Гибкость по оборудованию

GGUF полезен, потому что работает на множестве конфигураций.

В зависимости от среды выполнения и бэкенда модели GGUF можно запускать на:

• Машинах только с CPU
• GPU NVIDIA через CUDA
• Apple Silicon через Metal
• GPU AMD через HIP или Vulkan
• GPU Intel через SYCL или Vulkan
• Некоторых ARM- и мобильных средах

Эта гибкость — одна из причин влияния llama.cpp. Он был спроектирован не только для высокопроизводительных серверных GPU, а для локального инференса на самом разном оборудовании.

Например, пользователь Mac может полагаться на ускорение Metal, а пользователь Linux-десктопа — на CUDA или Vulkan. Пользователь только с CPU всё ещё может запускать меньшие квантованные модели, хотя скорость генерации будет ниже.

Широкая поддержка в экосистеме

GGUF поддерживается многими инструментами локального инференса. Например:

• llama.cpp для инференса из командной строки и серверного режима
• Ollama для CLI-ориентированного управления моделями и доступа к API
• LM Studio — настольный графический интерфейс
• GPT4All для локального чата с прицелом на приватность
• KoboldCpp для локальных сценариев ролевого чата и генерации текста
• Jan и Open WebUI для локальных AI-интерфейсов

Это важно, потому что пользователи не привязаны к одному интерфейсу. Один и тот же общий формат модели можно применять в разных процессах.

Разработчик может бенчмаркать модель в llama.cpp, общаться с ней в LM Studio, подавать её через Ollama и подключать к браузерному интерфейсу через Open WebUI.

Дистрибуция на Hugging Face

Hugging Face стал крупным центром распространения моделей GGUF.

Источник: Hugging Face

Многие популярные модели с открытыми весами вскоре после релиза получают загруженные сообществом варианты GGUF. Эти репозитории часто включают несколько опций квантизации, чтобы пользователи могли подобрать модель под своё железо.

Обычные варианты загрузок:

• Q4_K_M
• Q5_K_M
• Q6_K
• Q8_0
• IQ4_XS
• IQ3_M
• IQ2_XXS

Это означает, что ручная конвертация зачастую не нужна. Для самых популярных моделей кто-то из сообщества уже создал файлы GGUF с типовыми уровнями квантизации.

Тонкая настройка баланса размера и качества

GGUF даёт пользователям тонкий контроль над компромиссом «размер–качество». Вы можете выбрать:

• Более мелкие квантизации для машин с малой памятью
• Средний диапазон для сбалансированного ежедневного использования
• Более высокие биты для кодинга, рассуждений или структурированного вывода
• Полную или почти полную точность, если память не ограничение

Эта гибкость — одно из главных преимуществ формата. Вместо одного фиксированного целевого варианта GGUF позволяет адаптировать одно семейство моделей под множество классов оборудования.

Как работает GGUF?

Файл GGUF состоит из трёх основных частей:

1. Заголовок
2. Метаданные и информация о тензорах
3. Данные тензоров

Точная структура определена спецификацией GGUF. Важно, что метаданные и информация о тензорах располагаются перед «сырыми» данными тензоров, что позволяет среде выполнения понять, что именно она собирается загрузить.

Заголовок

Заголовок идентифицирует файл как GGUF и сообщает среде, как парсить остальную часть файла. Он включает:

• Магическое число GGUF
• Версию формата
• Количество тензоров
• Количество пар ключ–значение метаданных

Современные файлы часто используют версию GGUF 3.

Движки инференса сначала проверяют магическое число. Если файл не начинается с ожидаемого идентификатора GGUF, среда может отклонить его ещё до попытки парсинга тензоров или выделения памяти.

Это простой, но важный шаг для надёжности и безопасности. Он предотвращает случайное принятие несвязанного двоичного файла за модель.

Пары ключ–значение метаданных

Метаданные GGUF — это типизированное хранилище ключ–значение. В метаданных могут описываться:

• Общая информация о модели
• Семейство архитектур
• Длина контекста
• Размер эмбеддингов
• Количество слоёв
• Количество голов внимания
• Параметры RoPE
• Словарь токенизатора
• Специальные токены
• Информация о квантизации

Ключи обычно имеют неймспейсы. Примеры:

• general.architecture
• general.alignment
• llama.context_length
• tokenizer.ggml.tokens

Неймспейсы важны, поскольку позволяют GGUF поддерживать многие архитектуры без изменения всего формата. Модель семейства LLaMA может использовать ключи llama.*, тогда как другие семейства — свои архитектурно-специфичные метаданные.

Благодаря этому GGUF хорошо адаптировался к моделям за пределами исходного семейства LLaMA, включая архитектуры Qwen, Mistral, Gemma, DeepSeek, Phi и другие.

Информация о тензорах и данные тензоров

После метаданных в файле идут информация о тензорах и сами данные тензоров.

Информация о тензоре описывает:

• Имя тензора
• Форму
• Тип данных
• Смещение в секции данных тензоров

Секция данных тензоров содержит фактические веса модели. Эти веса могут храниться в полной точности или в одном из поддерживаемых GGUF квантованных типов тензоров.

GGUF использует значение выравнивания, задаваемое в метаданных, обычно general.alignment. Многие файлы GGUF используют выравнивание на 32 байта, но корректнее говорить, что выравнивание управляется метаданными, а не жёстко зашито.

Выравнивание важно, так как позволяет средам выполнения эффективно обращаться к блокам тензоров.

Отображение в память

Одно из практических преимуществ GGUF — отображение в память, часто называемое mmap.

С отображением в память операционная система может отобразить файл модели в виртуальную память вместо того, чтобы заставлять среду выполнения копировать весь файл в ОЗУ заранее.

Это может заметно ускорить старт модели, особенно на SSD. Также ОС может подкачивать данные модели по мере необходимости.

Однако отображение в память — не волшебство. Модели всё равно нужна достаточная пропускная способность памяти и доступная ОЗУ или VRAM для хорошей работы. Если система постоянно подкачивает с диска, инференс может стать медленным.

Правильнее думать о mmap так:

• Повышает эффективность загрузки
• Снижает избыточное копирование
• Позволяет ОС управлять подкачкой
• Не устраняет требования к памяти для инференса

Понимание типов квантизации GGUF

Квантизация сжимает веса модели в представления с пониженной точностью.

Вместо хранения каждого веса как 16-битного числа с плавающей точкой квантованная модель хранит приближённые значения с использованием меньшего числа бит. Это уменьшает размер на диске, потребление ОЗУ и VRAM и нагрузку на пропускную способность памяти.

Ключевая идея: многим весам нейросети не нужна полная плавающая точность во время инференса. Аккуратная квантизация может сохранить большую часть поведения исходной модели, сделав её при этом значительно меньше.

Схема именования квантизаций GGUF

Названия квантизаций GGUF обычно соответствуют такой схеме:

• Q означает квантованную
• Число указывает примерное число бит на вес
• K относится к семейству k-quant
• S, M и L обычно означают small, medium и large-варианты

Примеры:

• Q4_K_M
• Q5_K_M
• Q6_K
• Q8_0

Название полезно как ориентир, но не всегда точно отражает итоговый размер файла. Реальный размер зависит от набора тензоров, архитектуры, метаданных, размера токенизатора и того, остаются ли некоторые тензоры в более высокой точности.

Распространённые типы квантизации GGUF

Эти числа — приблизительны для плотных моделей класса 7B. Новые архитектуры, модели с смесью экспертов (MoE), большие токенизаторы и различные раскладки тензоров могут изменить фактический размер файла.

На практике Q4_K_M стал популярным по умолчанию, так как обеспечивает сильный баланс между размером и качеством. Многим он достаточен для общего чата, суммаризации, переписывания и экспериментальной локальной работы с ИИ.

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

Причина проста: эти задачи более чувствительны к мелким деградациям качества.

K-quants vs. I-quants

K-quants — широко используемое семейство квантизаций за форматами вроде Q4_K_M, Q5_K_M и Q6_K.

Они используют групповую квантизацию с масштабированием, что помогает сохранить поведение модели при снижении требований к памяти. Они популярны благодаря надёжности, широкой поддержке и доступности в сообществах GGUF.

I-quants, часто обозначаемые как IQ-форматы, — это более новые типы квантизации, например:

• IQ4_XS
• IQ3_M
• IQ2_XXS
• IQ1_S

I-quants создаются, чтобы обеспечить более высокое качество при очень малых размерах. Они могут использовать методы важностно-осознанной квантизации и нелинейные кодбуки. В некоторых процессах применяется матрица важности (imatrix), чтобы лучше сохранить наиболее значимые веса во время квантизации.

Обратная сторона — сложность. I-quants могут давать отличные результаты по соотношению размер–качество, особенно на очень низких битрейтах, но часто требуют более аккуратных процессов квантизации и поддержки в среде выполнения.

Для большинства новичков K-quants остаются самым простым стартом.

Выбор уровня квантизации под ваше оборудование

Следующая таблица — практические отправные точки. Рассматривайте их как эмпирические правила, а не строгие гарантии. Длина контекста, накладные расходы ОС, оффлоад на GPU, размер KV-кэша и конкретная архитектура модели могут менять требования к памяти.

Общие рекомендации:

• Используйте Q4_K_M как безопасный дефолт для большинства локальных сценариев.
• Выбирайте Q5_K_M, когда качество важнее экономии каждого гигабайта.
• Переходите на Q6_K или Q8_0 при наличии памяти и потребности в лучшей точности.
• Избегайте Q2_K для серьёзной работы, если только не тестируете экстремально ограниченную память.
• Оставляйте запас памяти под KV-кэш, особенно при длинных окнах контекста.

KV-кэш легко упустить из виду. Модель может помещаться в ОЗУ на коротком контексте, но выдавать ошибки или замедляться при длинном, потому что кэш растёт с длиной последовательности.

Экосистема GGUF

Распространение GGUF движется не меньше инструментами, чем самим форматом.

Формат становится полезным только тогда, когда пользователи легко могут скачивать, запускать, исследовать, конвертировать и подавать модели. GGUF выигрывает от сильной экосистемы CLI-инструментов, настольных приложений, API и хостинговых репозиториев моделей.

1. llama.cpp

llama.cpp — исходная и важнейшая среда выполнения GGUF. Это лёгкий C/C++-движок инференса, созданный Георгием Гергановым и поддерживаемый сообществом GGML. Его главная цель — обеспечить эффективный инференс LLM с минимальной настройкой на множестве платформ.

Современный llama.cpp поддерживает множество бэкендов, включая:

• CPU
• CUDA для GPU NVIDIA
• Metal для устройств Apple
• Vulkan
• HIP для GPU AMD через ROCm
• SYCL для GPU Intel
• OpenCL в отдельных средах
• Другие специализированные бэкенды, такие как CANN, OpenVINO и WebGPU, в зависимости от платформы

Также включены инструменты для конвертации, квантизации, сервинга, бенчмаркинга и инференса из командной строки. Общие инструменты:

• convert_hf_to_gguf.py
• llama-quantize
• llama-cli
• llama-server
• llama-bench

Команды для базовой сборки CPU через CMake:

cmake -B build
cmake --build build --config Release

Для некоторых конфигураций к первой из этих двух команд нужно добавить флаги:

• Отключить Apple Metal на macOS (по умолчанию включён): -DGGML_METAL=OFF
• Сборка Vulkan: -DGGML_VULKAN=1
• Сборка CUDA для GPU NVIDIA: -DGGML_CUDA=ON

Обратите внимание, что в текущих сборках используются CMake-опции GGML_*, такие как GGML_CUDA, GGML_VULKAN и GGML_HIP.

2. Ollama

Ollama — один из самых простых способов запускать локальные модели. Она предоставляет:

• Простой CLI
• Загрузку и управление моделями
• Локальный REST API
• Официальные библиотеки Python и JavaScript
• Интеграцию со многими локальными AI-фронтендами

Ollama хранит и управляет моделями за вас, поэтому пользователи обычно не взаимодействуют с файлами .gguf напрямую. Однако Ollama построена вокруг совместимого с llama.cpp локального инференса и может импортировать файлы GGUF через workflow Modelfile.

Ollama предоставляет локальный API по адресу:

http://localhost:11434/api

Два самых используемых эндпоинта:

• /api/generate — для дополнения подсказок
• /api/chat — для сообщений в стиле чата

Для новичков Ollama часто — самый быстрый путь от нуля до локального инференса.

3. LM Studio

Источник: LM Studio

LM Studio — настольное приложение для поиска, загрузки и общения с локальными моделями. Полезно для тех, кто предпочитает графический интерфейс вместо командной строки.

4. GPT4All

Источник: GPT4All

GPT4All — ещё одно кроссплатформенное локальное AI-приложение, ориентированное на приватные локальные сценарии чата. Поддерживает модели GGUF и обеспечивает дружественную к новичкам среду для локального инференса.

Эти инструменты делают GGUF доступным для неспециалистов. Пользователям не нужно разбираться в CMake, раскладках тензоров или тонкостях квантизации, чтобы просто попробовать локальную модель.

С чего начать работу с моделями GGUF

Есть два практичных пути старта:

1. Использовать Ollama для максимально простого опыта.
2. Использовать напрямую llama.cpp для большего контроля.

Запуск модели в Ollama

Самый простой процесс — скачать модель и начать интерактивную сессию:

ollama pull llama3.3
ollama run llama3.3

Вызов модели из Python через REST API:

import requests

payload = {
    "model": "llama3.3",
    "prompt": "Give me three practical use cases for GGUF.",
    "stream": False
}

response = requests.post(
    "http://localhost:11434/api/generate",
    json=payload
)

print(response.json()["response"])

Для приложений в стиле чата используйте /api/chat:

import requests

payload = {
    "model": "llama3.3",
    "messages": [
        {"role": "user", "content": "What is GGUF used for?"}
    ],
    "stream": False
}

response = requests.post(
    "http://localhost:11434/api/chat",
    json=payload
)

print(response.json()["message"]["content"])

Поле stream: false важно для простых скриптов. Без него Ollama вернёт поток JSON-объектов, а не один финальный JSON-ответ.

Также можно воспользоваться официальной библиотекой Python для Ollama:

from ollama import chat

response = chat(
    model="llama3.3",
    messages=[
        {"role": "user", "content": "Explain GGUF quantization simply."}
    ]
)

print(response.message.content)

Запуск файла GGUF в llama.cpp

Если у вас уже есть файл .gguf, вы можете запустить его напрямую в llama.cpp после сборки проекта.

Пример:

./build/bin/llama-cli \
  -m models/model.Q4_K_M.gguf \
  -p "Explain the difference between GGUF and GPTQ." \
  -n 256

Если у вас включена поддержка GPU, можно выгружать слои на GPU:

./build/bin/llama-cli \
  -m models/model.Q4_K_M.gguf \
  -p "Summarize GGUF in five bullet points." \
  -n 256 \
  -ngl 99

Флаг -ngl управляет количеством слоёв, выгружаемых на GPU. Высокое значение, например 99, часто используют, чтобы выгрузить максимум, при условии что модель помещается в VRAM.

Для подачи через API используйте llama-server:

./build/bin/llama-server \
  -m models/model.Q4_K_M.gguf \
  -ngl 99 \
  --host 127.0.0.1 \
  --port 8080

Это даст вам локальный серверный интерфейс для интеграции llama.cpp в приложения.

Конвертация модели Hugging Face в GGUF

Большинству пользователей не нужно конвертировать модели вручную, так как широко доступны релизы GGUF от сообщества.

Однако ручная конвертация полезна, когда:

• Вы дообучили свою модель
• GGUF-версии ещё нет
• Вы хотите контролировать процесс квантизации сами
• Вам нужен конкретный тип квантизации

Типичный процесс:

1. Скачать модель с Hugging Face.
2. Преобразовать её в GGUF.
3. Квантовать файл GGUF.

Пример:

huggingface-cli download mistralai/Mistral-7B-Instruct-v0.3 \
  --local-dir mistral-7b

Затем конвертируйте в GGUF:

python convert_hf_to_gguf.py mistral-7b \
  --outfile mistral-f16.gguf \
  --outtype f16

Затем выполните квантизацию:

./build/bin/llama-quantize \
  mistral-f16.gguf \
  mistral-q4_k_m.gguf \
  Q4_K_M

В текущих процессах llama.cpp актуальны инструменты convert_hf_to_gguf.py и llama-quantize. Старые туториалы могут ссылаться на устаревшие скрипты конвертации или бинарники.

Преимущества и ограничения формата GGUF

GGUF оптимизирован для практического локального инференса. Это не универсальная замена каждому формату модели или стеку сервинга.

Для CPU-первого, Apple Silicon, смешанного по оборудованию и приватно-ориентированного инференса GGUF часто — отличный выбор.

Для высокопроизводительного серверного развёртывания на NVIDIA другие форматы и движки могут быть быстрее — в зависимости от модели, размера батча, метода квантизации и фреймворка сервинга.

Заключение

GGUF делает локальный инференс LLM практичным, упаковывая всё необходимое для среды выполнения (веса, токенизатор, метаданные, сведения о квантизации) в один переносимый файл. Его настоящая сила — экосистема вокруг: llama.cpp, Ollama, LM Studio и Hugging Face сделали его форматом по умолчанию для локального развёртывания ИИ.

Для большинства пользователей путь прост: установите Ollama, скачайте модель и запустите её. Q4_K_M — надёжный дефолт; переходите на Q5_K_M или Q6_K, когда нужны лучшие рассуждения или код и у вас хватает памяти.

Если вы хотите глубже разобраться в развёртывании LLM, оптимизации моделей и локальных рабочих процессах инференса, изучите карьерные треки Associate AI Engineer for Data Scientists и Associate AI Engineer for Developers.