Экспорт Llama 3 в GGUF с Unsloth: как обойти RuntimeError

Статья о сбое Unsloth при экспорте Llama 3 в формат GGUF: симптомы на AzureML, причины и надежный обход через сборку llama.cpp и convert_lora_to_gguf.py.

При экспорте дообученной модели Llama 3 в формат GGUF с помощью Unsloth все выглядит штатно почти до самого конца: слои квантуются, проставляется метадата — и затем процесс падает с ошибкой времени выполнения. Если вы работаете на виртуальной машине AzureML Standard_NC24ads_A100_v4 с моделью unsloth/Meta-Llama-3.1-8B-Instruct на Unsloth 2025.5.6, описанные ниже симптомы будут знакомы. Хорошая новость: это известная проблема, над исправлением уже работают, а пока есть надежный обходной путь, позволяющий получить GGUF‑артефакт прямо сейчас.

Минимальный пример, который воспроизводит сбой

Вызов API экспорта предельно простой. После дообучения достаточно одной строки, чтобы запустить конвертацию и квантизацию:

learner.save_pretrained_gguf("model", spm, quantization_method="q4_k_m")

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

RuntimeError: Unsloth: Не удалось выполнить квантизацию для .../model/unsloth.BF16.gguf
Возможно, вам потребуется самостоятельно собрать llama.cpp, затем повторно запустить процесс.
Закрывать этот Python-процесс не нужно. Выполните следующие команды в новом терминале:
Запускайте их в той же папке, куда сохраняете модель.
git clone --recursive https://github.com/ggerganov/llama.cpp
cd llama.cpp && make clean && make all -j
После этого повторите квантизацию.

Что происходит на самом деле

Сбой не связан ни с вашей ВМ, ни с флагами сборки, ни с выбором модели. Он обусловлен проблемой, которую сейчас устраняют в Unsloth. Мейнтейнеры ведут открытое отслеживание, и обсуждения доступны здесь: #2581, #2580 и #2604. До выхода исправления экспорт может завершаться неудачей даже если вы уже собрали llama.cpp и поместили его бинарники рядом с чекпойнтом.

Практическое обходное решение, которое работает уже сегодня

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

git clone --recursive https://github.com/ggerganov/llama.cpp
cd llama.cpp && make clean && make all -j

После сборки создайте GGUF‑файл явно. Запускайте из каталога, где сохранена ваша модель:

python3 llama.cpp/convert_lora_to_gguf.py my_model

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

Почему это важно

Экспорт в GGUF — ключевой этап, если вы планируете обслуживать дообученную модель через llama.cpp или совместимые рантаймы. Зная, что текущий релиз Unsloth может «споткнуться» на финишной прямой, вы сэкономите время: вместо перебора флагов сборки или перекладывания бинарников можно сразу перейти к ручной конверсии и продолжать выстраивать конвейер деплоя. Когда апстрим‑исправление выйдет, вернетесь к встроенному вызову экспорта для более гладкого процесса.

Рекомендуемый план действий

Если экспорт в GGUF падает с описанным RuntimeError, считайте это известной проблемой из трекера Unsloth. Сейчас используйте ручную конверсию, чтобы получить финальный файл, а к нативному экспорту вернитесь после закрытия связанных задач. Держите окружение актуальным: обновите Unsloth, когда выйдет новый релиз, и затем повторите встроенный экспорт.