Конвертация модели в GGUF
Коротко:
convert_hf_to_gguf.pyпревращает HF-репозиторий (safetensors) в GGUF f16/bf16 — исходник для квантования. Часто конвертация не нужна: готовые GGUF есть на Hugging Face, а llama.cpp умеет скачивать их сам (-hf).
Когда конвертировать
- Своя/свежая модель, GGUF которой ещё нет.
- Нужен нестандартный outtype или экспорт отдельных частей (mmproj, PLE).
В остальных случаях берите готовый GGUF сообщества (GGUF-фильтр на HF) или позвольте
llama.cpp скачать: llama-cli -hf <user>/<model>[:quant] — см. llama-cli.
Альтернатива без локальной установки — HF-спейс GGUF-my-repo (docs/models.md).
Конвертация
# зависимости
pip install -r requirements.txt
# из локальной папки модели
python convert_hf_to_gguf.py /path/to/model --outfile model-bf16.gguf --outtype bf16
# прямо с Hugging Face (скачивает сам)
python convert_hf_to_gguf.py --outfile model-bf16.gguf --outtype bf16 --remote user/model
Факты из tools/quantize/README.md v1.0.0:
--outtype auto(или omit) подходит, когда модель распространена в 16-бит — конвертер возьмёт её тип как есть.- requirements тянут transformers 4; свежим моделям (например Gemma 4) нужен
transformers 5 — безопасно обновить:
pip install -U transformers. - Мультимодальной модели нужен отдельный mmproj-файл (см. ниже).
Выбор outtype
| outtype | Когда |
|---|---|
auto / omit |
обычный случай для 16-битных моделей |
bf16 |
явное требование bf16 (лучше устойчивость к выбросам, чем f16) |
f16 |
классика; чуть меньше bf16 |
Квантование выполняется отдельным шагом llama-quantize из этого f16/bf16 файла —
см. Квантование. Квантовать «из кванта» можно только с
--allow-requantize и заметной потерей качества — избегайте.
Мультимодальность (mmproj)
python convert_hf_to_gguf.py --mmproj --outfile mmproj-q8_0.gguf --outtype q8_0 --remote user/model
mmproj (проектор/энкодеры) хранят отдельно и обычно не квантуют агрессивно
(bf16/q8_0): их качество напрямую влияет на входы LLM, а размер мал
(tools/quantize/README.md). Запуск с mmproj — parking lot (lcp.mmproj).
Отдельные экспорты (PLE)
Модели с per-layer embedding (PLE) экспортируются двумя файлами
(--no-ple / --ple-only), подключаются через --shard; детали —
docs/models.md и GGUF.
Типичные ошибки конвертации
| Ошибка | Причина/решение |
|---|---|
| «Architecture not supported» | конвертер не знает архитектуру → обновите llama.cpp (скрипты в conversion/ растут с релизами) |
| transformers-ошибки загрузки | модель требует transformers 5 → pip install -U transformers |
| Нехватка RAM при конвертации | большой outtype; конвертация грузит модель целиком — освободите память или используйте машину побольше |
| Получился HTML вместо GGUF | скачивание обвалилось на веб-страницу → проверьте URL/загрузчик; «bad magic» при запуске — diag-load |