GGUF-конвертер: простой способ квантизировать LLM (включая AWQ INT4 → FP16) под ваше железо

В последние два года формат GGUF стал стандартом для локального запуска больших языковых моделей: llama.cpp, koboldcpp, text-generation-webui и десятки GUI умеют работать именно с GGUF‑чекпойнтами.​

Проблема в том, что большинство моделей распространяются на Hugging Face в «сыром» виде (FP16/FP32, иногда в формате AWQ INT4), а конвертация в GGUF с нужной квантизацией требует отдельного набора скриптов, ключей и танцев с бубном.​

В этой статье покажу свою утилиту gguf-converter — маленький open‑source проект, который:

• автоматизирует конвертацию моделей в GGUF;

• выполняет классическую квантизацию (FP16 → q4/q5/q6/q8 и т.п.);

• поддерживает AWQ‑модели: умеет автоматически деквантизировать INT4 → FP16, а затем квантизировать в GGUF под ваше железо.​

Зачем нужен GGUF и квантизация

Формат GGUF — это бинарный контейнер, который хранит:

• архитектуру модели и гиперпараметры;

• токенизатор и служебные данные;

• веса в квантизированном виде (2–16 бит).​

Задача GGUF — сделать большие модели:

• компактными;

• быстро загружаемыми;

• совместимыми с высокопроизводительными C/C++ рантаймами (llama.cpp и его форки).​

Квантизация — это понижение точности весов:

• с float32/float16 → до 8, 6, 5, 4 или даже 2 бит;

• взамен теряется чуть-чуть точности, но сильно выигрываются размер и скорость.​

Практический эффект:

• вместо 30–40 ГБ FP16‑чекпойнта можно получить 6–8 ГБ GGUF q4;

• модель начинает работать на видеокарте с 8–12 ГБ VRAM или даже чисто на CPU (если набраться терпения).​

AWQ: модели уже в INT4

Отдельная история — модели в формате AWQ (Activation-aware Weight Quantization).​

Что происходит:

• многие LLM выкладывают в виде уже квантизированных INT4 AWQ‑чекпойнтов (особенно оптимизированных под GPU);

• такие веса не всегда можно «напрямую» конвертировать в GGUF без потери качества или странных артефактов;

• хочется: взять AWQ‑модель → привести её к FP16 → затем аккуратно сконвертировать в привычный GGUF с нужным q‑уровнем.​

Поэтому в gguf-converter добавлена поддержка AWQ model support (automatic INT4 → FP16 dequantization):

• если входная модель — AWQ, утилита автоматически деквантизирует INT4 → FP16;

• дальше уже поверх FP16 выполняется GGUF‑квантизация (например, q4_k / q5_k);

• итог — совместимый GGUF‑файл, который можно запускать в любых llama.cpp‑совместимых фронтендах.​

Что делает gguf-converter

Репозиторий: https://github.com/mnbabeshko/gguf-converter.​

Задача утилиты — превратить «зоопарк» форматов в единый, удобный GGUF:

• вход: обычный Hugging Face чекпойнт (FP16/FP32) или AWQ INT4‑модель;

• процесс: при необходимости деквантизация AWQ → FP16, затем квантизация в выбранный GGUF‑формат;

• выход: один или несколько .gguf файлов, готовых к запуску.​

Фокус:

• удобство для локального запуска (Windows/Linux, GPU от 8–12 ГБ);

• минимальное число ручных шагов;

• предсказуемые профили квантизации (q2, q3, q4, q5, q6, q8 — в зависимости от того, что реализовано на момент чтения).

Установка

Пример минимальной установки под Python (универсально для Windows/Linux).

1. Клонирование репозитория

bashgit clone https://github.com/mnbabeshko/gguf-converter.git
cd gguf-converter

git clone https://github.com/mnbabeshko/gguf-converter.git cd gguf-converter

2. Виртуальное окружение и зависимости

bashpython -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows
# .venv\Scripts\activate

pip install -r requirements.txt

python -m venv .venv # Linux/macOS source .venv/bin/activate # Windows # .venv\Scripts\activate pip install -r requirements.txt

Если вы планируете дополнительно использовать PyTorch с GPU — заранее поставьте нужную сборку torch под вашу версию CUDA (например, 2.1.1 + cu121).​

Пример: конвертация обычной FP16‑модели в GGUF

Допустим, у нас есть модель на Hugging Face:

bashgit lfs install
git clone https://huggingface.co/ORG/MODEL\_NAME

git lfs install git clone https://huggingface.co/ORG/MODEL\_NAME

Папка MODEL_NAME — это наш --model-dir.

Запускаем конвертацию:

bashpython gguf_converter.py \
  --model-dir /path/to/MODEL_NAME \
  --output ./out \
  --quant q4_k_m

python gguf_converter.py \ --model-dir /path/to/MODEL_NAME \ --output ./out \ --quant q4_k_m

Где:

• --model-dir — путь к папке с моделью;

• --output — куда складывать результат;

• --quant — целевой GGUF‑профиль квантизации (конкретные названия зависят от реализации: q2_k, q3_k, q4_k_m, q5_k_m, q6_k, q8_0 и т.п.).​

На выходе получаем, например:

textMODEL_NAME-q4_k_m.gguf

MODEL_NAME-q4_k_m.gguf

Его можно сразу запускать через llama.cpp:

bash./main -m MODEL_NAME-q4_k_m.gguf -p "Hello, GGUF!"

./main -m MODEL_NAME-q4_k_m.gguf -p "Hello, GGUF!"

Пример: AWQ INT4 → FP16 → GGUF

Теперь пример для AWQ‑модели.

Примем, что у нас есть AWQ‑чекпойнт в папке /path/to/awq_model. Тогда:

bashpython gguf_converter.py \
  --model-dir /path/to/awq_model \
  --output ./out \
  --awq \
  --quant q4_k_m

python gguf_converter.py \ --model-dir /path/to/awq_model \ --output ./out \ --awq \ --quant q4_k_m

Здесь:

• --awq говорит утилите: «на входе AWQ INT4, сначала деквантизируй до FP16»;

• --quant q4_k_m — привычный GGUF‑квант поверх восстановленных FP16‑весов.​

Пайплайн выглядит так:

textAWQ INT4 → [авто деквантизация в FP16] → GGUF q4_k_m → llama.cpp

AWQ INT4 → [авто деквантизация в FP16] → GGUF q4_k_m → llama.cpp

Это удобно, если:

• авторы выложили только AWQ‑вариант;

• вам нужно привести модель к единому GGUF‑формату с остальными;

• вы хотите сравнить качество/скорость AWQ INT4 vs GGUF q4/q5/q6 на одной и той же модели.​

Как выбрать квантизацию

Условная «шпаргалка» по уровню квантизации:

Типовые сценарии:

• «Запустить что‑то живое на 8–12 ГБ VRAM» → q4.

• «Чат‑бот с минимальными ошибками, есть запас по памяти» → q5–q6.

• «Отладка/сравнение с оригиналом» → q8 или f16.

Планы развития

В ближайших версиях логично развивать утилиту в сторону:

• поддержки новых схем квантизации и форматов GGUF по мере их появления;

• большего набора пресетов (набор заранее подобранных профилей под 8/12/24 ГБ);

• мини‑GUI (web или desktop), где конвертация будет делаться в пару кликов;

• примеров пайплайнов «от Hugging Face до llama.cpp/webui» для разных ОС.​

Если вы уже используете GGUF или AWQ‑модели — буду рад фидбеку, баг‑репортам и идеям по улучшению. Репозиторий открыт, PR приветствуются.

Контакты:

thepuppeteer@internet.ru

GGUF Converter v1.91