Transformers теперь запускает кванты llama.cpp

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

Запуск AI‑моделей на ноутбуке стал намного проще, и llama.cpp сыграл большую роль в этом. Его движок инференса используется в локальных AI‑инструментах, таких как Ollama, LM Studio и Jan. Вместе с проектами, как MLX, он помог сделать локальный инференс практичным вариантом для повседневного использования.

Недавний пример того, как может ощущаться локальный AI:

Вот где мы сейчас. И я не буду лгать, это выглядит довольно волшебно 🧙‍♀️Qwen3.6 27B запускается внутри Pi coding agent через Llama.cpp на MacBook ProДля нерегулярных задач на кодовых базах @huggingface, это выглядит очень, очень близко к последнему Opus в Claude… pic.twitter.com/lsIxLoUneU— Julien Chaumond (@julien_c) 24 апреля 2026

Вот где мы сейчас. И я не буду лгать, это выглядит довольно волшебно 🧙‍♀️

Qwen3.6 27B запускается внутри Pi coding agent через Llama.cpp на MacBook Pro

Для нерегулярных задач на кодовых базах @huggingface, это выглядит очень, очень близко к последнему Opus в Claude…

GGUF, разработанный командой llama.cpp, является широко используемым форматом для локального инференса. Команда также публикует квантованные контрольные точки под ggml-org в Hub. Издатели, такие как Unsloth, LM Studio Community и bartowski, также предоставляют готовые к использованию контрольные точки GGUF в различных квантованиях, чтобы пользователи могли выбрать версию, подходящую для их машины. Модели GGUF скачиваются миллионы раз.

Мы хотим сделать проще запуск этих моделей локально с transformers. Совместимость полезна только если модель удобно запускать. Чтобы приблизить производительность к llama.cpp, мы переиспользуем его базовые ядра ggml через библиотеку kernels и уменьшаем накладные расходы в generate. Наш первоначальный фокус — локальный инференс на Apple Silicon, начиная с архитектуры Qwen3.5.

Что такое формат файла GGUF?

GGUF упаковывает веса модели и метаданные, включая информацию о токенизаторе и необязательный шаблон чата, в один файл. Он поддерживает разные уровни квантования, позволяя вам обменивать часть точности на меньший объём памяти. Варианты, такие как Q4_K_M, смешивают точности тензоров, используя в основном 4‑битные веса, сохраняя при этом чувствительные тензоры с более высокой точностью.

Вот как квантование меняет размер файла Unsloth's Qwen3.5-4B:

Мы рекомендуем начинать с Q4_K_M, затем пробовать Q5_K_M или Q6_K, если у вас больше памяти. Более агрессивное квантование может помочь большим моделям поместиться, но компромисс качества зависит от модели и задачи. Оцените его на работе, которую вы действительно хотите, чтобы модель выполняла. Документация GGUF в Hub описывает доступные типы квантования.

Загрузка GGUF с transformers

Для начала вам понадобится:

• Mac с Apple Silicon.
• Версия PyTorch, поддерживаемая опубликованными сборками ядра ggml-quantization, обычно две последние версии PyTorch.
• Последняя версия transformers (на данный момент main, до следующего релиза) и совместимая версия kernels.

Чтобы загрузить модель GGUF, передайте её model_id из Hub и имя файла как gguf_file в from_pretrained.

Дополнительная конфигурация не требуется: когда веса остаются упакованными на Metal, transformers автоматически загружает совместимые ядра ggml/Metal и использует ggml-org/ggml-attn в качестве реализации внимания. Если это ядро не может быть загружено, модель переходит на "sdpa" с предупреждением, и вы всегда можете принудительно задать "sdpa", передав attn_implementation="sdpa" явно. См. документацию GGUF для дополнительных вариантов загрузки.

Это единственный шаг, специфичный для GGUF. Всё после него — стандартный API transformers:

Без совместимого ядра квантования загрузчик переходит к декиантованию модели и использует больше памяти.

Без совместимого ядра квантования загрузчик переходит к декиантованию модели и использует больше памяти.

Служба GGUF с вашим предпочтительным интерфейсом

Вы также можете использовать тот же контрольный пункт с transformers serve, который предоставляет API совместимый с OpenAI:

Аргумент модели использует <model_id>:<filename>.gguf: перед двоеточием находится репозиторий Hub (unsloth/Qwen3.5-4B-GGUF), а после — файл для загрузки (Qwen3.5-4B-Q4_K_M.gguf). Это выбирает конкретное квантование из репозитория, который может содержать несколько вариантов.

Для моделей, чьи шаблоны чата поддерживают размышление, добавьте --reasoning off, чтобы пропустить его, или --reasoning on, чтобы включить. По умолчанию, --reasoning auto, следует за настройками шаблона чата. См. параметры размышления для подробностей.

Вы можете подключить клиента, такой как Jan или Pi, добавив пользовательский провайдер совместимый с OpenAI с этими настройками:

transformers запускает модель на вашем Mac, в то время как клиент предоставляет интерфейс разговора. Тот же конечный пункт может использоваться другими клиентами, поддерживающими этот API.

Сравнение с llama.cpp

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

Колонка llama.cpp берёт данные из инструмента llama-bench (build 5f55650a7, release b10200, Metal backend из ggml 0.18.0), запущенного как llama-bench -m <file> -p 0 -n 128 -r 3, который сообщает tg128: скорость генерации токенов за 128 декодированных токенов, усреднённую по трем повторениям, с исключением обработки подсказки. Колонка transformers использует generate, создавая те же 128 токенов из 12‑токеновой подсказки, лучший из трёх разогретых запусков, и включает prefill.

Измерено на MacBook Pro M2 Max, 32 ГБ объединённой памяти, macOS 26.6, PyTorch 2.12.1, kernels 0.17.0, подключён к сети.

Для другой колонки:

Transformers близок к llama.cpp по всем трём контрольным точкам. Диаграмма использует те же измерения, описанные выше; это не подразумевает идентичных условий бенчмарка, поскольку измерение Transformers включает prefill, тогда как llama-bench сообщает только throughput декодирования.

transformers и llama.cpp

Когда GGML и llama.cpp присоединились к Hugging Face, мы описали их взаимодополняющие роли: llama.cpp обеспечивает основу для локального инференса, а transformers — основу для определения модели. Поддержка GGUF приближает эти два вместе.

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

• Экспериментируйте с GGUF в Python и PyTorch. Анализируйте промежуточные активации с помощью хуков, изменяйте проход модели, или прототипируйте пользовательские слои, используя знакомые инструменты PyTorch.
• Оцените модели GGUF. Используйте существующие рабочие процессы оценки transformers, чтобы измерить качество квантованных контрольных точек.
• Проверьте конвертации GGUF. Для нас, как для разработчиков, загрузка оригинальной контрольной точки и её конвертации GGUF в transformers упрощает проверку того, что веса были корректно преобразованы, учитывая ошибку квантования.
• Попробуйте новые идеи декодирования. Используйте пользовательские процессоры логитов и критерии остановки с помощью функции generate или напишите свой собственный цикл генерации на Python.
• Выполните тонкую настройку модели из контрольной точки GGUF. Деквантуйте веса и продолжайте стандартный процесс обучения трансформеров.

Для последнего случая используйте GgufConfig(dequantize=True):

За пределами GGUF: ядра ggml для большего количества моделей

Более значительная возможность — это привнести производительность ggml к моделям, которые не поддерживаются llama.cpp.

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

Эта возможность выходит за рамки формата GGUF как такового. Ядро работает с тензорами; оно не требует, чтобы вся модель поступала из файла GGUF. Те же строительные блоки могут быть интегрированы в другие модели трансформеров и процессы загрузки. Это также открывает путь к другим модальностям: модели компьютерного зрения, аудиомодели и мультимодальные модели могут повторно использовать совместимые ядра внимания, нормализации и умножения матриц, не имея сначала полной реализации в llama.cpp. Каждая архитектура все равно нуждается в интеграции и валидации; первоначальные примеры GGUF здесь охватывают генерацию текста.

Быстрое локальное инференсное моделирование с помощью Python и PyTorch

Мы также хотели показать, насколько далеко мы можем зайти, сохраняя модель и цикл генерации в Python. С правильными ядрами и эффективным циклом генерации Python и PyTorch могут обеспечить высокую производительность локального инференсного моделирования. Ядра выполняют тяжелые вычисления, а цикл генерации держит GPU занятым, избегая ненужной синхронизации.

Наша цель заключалась в том, чтобы сделать жадное выполнение быстрым, не требуя torch.compile. Для интерактивного использования мы хотели быстрого старта и стабильного потока токенов без пауз компиляции или рекомпиляции при изменении форм входных данных. Двумя основными элементами этой работы являются ядра и функция generate сама по себе.

Повторное использование ядер Metal из ggml

Ядро — это небольшая программа, которая выполняет операцию на GPU. PyTorch предоставляет общие реализации; специализированное ядро может выполнять меньше работы, объединять несколько операций или читать квантированные веса напрямую в их сохраненном формате.

Библиотека ядер позволяет нам распространять совместимые сборки ядер Metal из ggml на Hub и вызывать их из трансформеров. Это привносит работу ggml в модель PyTorch, не заменяя модель отдельным средой выполнения инференсного моделирования.

Первые четыре пакета основаны на ядрах ggml; ядро top-k решает отдельную проблему в маршрутизации MoE. Вместе они снижают объем работы GPU, необходимой для каждого сгенерированного токена.

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

Сохранение совместной работы CPU и GPU

Более быстрые ядра помогают только в том случае, если у GPU есть работа. Во время генерации CPU планирует операции GPU и управляет циклом, который производит следующий токен. Чтение результата обратно из GPU может заставить CPU ждать, пока запланированные операции не завершатся. Повторение даже небольшой паузы для каждого токена может заметно снизить пропускную способность.

Два изменения решают эту проблему в функции generate, что приводит к улучшениям для всех моделей трансформеров (а не только при запуске файлов GGUF):

• Drop an unnecessary attention mask early (#48814). Когда поддерживаемый декодирующий вход не имеет паддинга, его маска паддинга из единиц может быть удалена в начале генерации. Код внимания нижележащего уровня больше не должен проверять эту маску неоднократно, чтобы определить, можно ли ее пропустить. Причинное внимание сохраняется.
• Defer the stopping check (#47975). На поддерживаемых путях функция generate копирует решение об остановке асинхронно и использует его на следующем шаге. CPU может продолжать планировать работу, пока GPU работает. Потоковые токены используют тот же подход, и любой дополнительный шаг после условия остановки удаляется из результата.

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

Эти измерения сохраняют все слоевые ядра включенными; столбцы изолируют изменения в цикле генерации.

Текущие ограничения и следующие шаги

Первоначальная цель — одно интерактивное общение на Apple Silicon. Есть несколько границ, которые нужно учитывать:

• Путь упакованного инференсного моделирования пока доступен только для MPS. Импорт GGUF через деквантизацию остается отдельным вариантом; поддержка формата файла не подразумевает, что упакованныые ядра доступны на каждом устройстве.
• Паддинг и батчинг все еще нуждаются в доработке. Непаддированные входные данные извлекают выгоду из оптимизации маски, описанной выше. Паддированные батчи не могут использовать тот же shortcut и могут иметь более низкую производительность. Мы хотим расширить работу на функцию generate_batch в MPS.
• Охват архитектуры ограничен. Упакованныый загрузчик в настоящее время охватывает плотную и MoE архитектуры Qwen3.5, включая совместимые контрольные точки Qwen3.8. Добавление поддержки других архитектур относительно просто, и мы постепенно расширим охват.

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

Благодарности

Мы хотели бы поблагодарить Артура Цукера за инициирование этой работы и обзор всех моих PR, а также Кирилла Валлея за PR generate. Мы благодарны Саяку Полу, , и Бертрану Шевалье за их помощь в интеграции ядер. Мы также благодарим Аритру Роя Гостипати и Педро Куэнку за обзор этого блога, а также Лисандра Дебюта за руководство проектом.