LLM-GUIDELLM × llama.cpp Конфигуратор …
Главная / llama.cpp Handbook / Конвертация модели в GGUF

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