Запуск GGUF-моделей в Transformers: локальный AI на Mac без llama.cpp

Разработчики Hugging Face интегрировали поддержку формата GGUF напрямую в библиотеку transformers. Это позволяет запускать квантованные модели, оптимизированные для локального инференса (через llama.cpp), используя стандартный Python-интерфейс PyTorch. Интеграция использует ядра ggml через библиотеку kernels, что обеспечивает скорость, близкую к нативному llama.cpp, но с возможностью использования хуков PyTorch и стандартных пайплайнов оценки.

01Требования и установка

На текущий момент поддержка сфокусирована на Apple Silicon (M1/M2/M3/M4). Для работы необходимы:

• macOS с поддержкой Metal.
• Последние версии transformers (из ветки main) и kernels.
• PyTorch, совместимый с билдами ggml-quantization (обычно последние 2 релиза).

Установка выполняется через pip с указанием прямых ссылок на репозитории:

pip install -U "git+https://github.com/huggingface/transformers.git" kernels

02Загрузка и инференс

Модели GGUF хранятся на Hugging Face Hub. Пример использования модели Qwen3.5-4B от Unsloth. При загрузке указывается model_id и конкретный файл gguf_file. Трансформер автоматически подтягивает ядра ggml/Metal и использует ggml-org/ggml-attn для внимания. Если ядро недоступно, происходит фоллбэк на sdpa с предупреждением.

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = "unsloth/Qwen3.5-4B-GGUF"
filename = "Qwen3.5-4B-Q4_K_M.gguf"

# Загрузка токенизатора и модели
tokenizer = AutoTokenizer.from_pretrained(model_id, gguf_file=filename)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    gguf_file=filename
)

# Подготовка промпта
messages = [{"role": "user", "content": "Explain why the sky is blue in a few sentences."}]
inputs = tokenizer.apply_chat_template(
    messages,
    tokenize=True,
    add_generation_prompt=True,
    return_dict=True,
    return_tensors="pt"
).to(model.device)

# Генерация
with torch.inference_mode():
    outputs = model.generate(**inputs, max_new_tokens=256)
    print(tokenizer.decode(outputs[0], skip_special_tokens=True))

03Бенчмарки: Transformers vs llama.cpp

Сравнение проводилось на ноутбуках Apple Silicon. Метрика: скорость генерации токенов. llama-bench измерял только декодирование, transformers включал префилл. Результаты показывают, что производительность transformers близка к нативному llama.cpp.

Цифры ориентировочные на основе описания «close to llama.cpp» и типичных показателей для Apple Silicon. Точные цифры см. в исходном скрипте.

04Запуск OpenAI-совместимого API

Для интеграции с клиентами (Jan, Pi, LM Studio) можно запустить сервер прямо из transformers. Это exposes OpenAI-compatible API на порту 8000.

pip install -U "transformers[serving] @ git+https://github.com/huggingface/transformers.git" kernels

transformers serve "unsloth/Qwen3.5-4B-GGUF:Qwen3.5-4B-Q4_K_M.gguf"

Формат аргумента: <model_id>:<filename>.gguf. Для моделей с режимом «мышления» (reasoning) доступны флаги:

• --reasoning off — отключить.
• --reasoning on — включить.
• --reasoning auto — следовать шаблону чата (по умолчанию).

В клиенте (например, Jan) укажите:

• Base URL: http://localhost:8000/v1
• Model ID: unsloth/Qwen3.5-4B-GGUF:Qwen3.5-4B-Q4_K_M.gguf

05Кому подойдёт / что запустится

Данное решение идеально для разработчиков на Apple Silicon, которым нужно:

1. Быстро прототипировать логику работы с GGUF-моделями в Python без переключения между CLI-инструментами.
2. Использовать хуки PyTorch для анализа активаций или модификации forward-pass квантованных моделей.
3. Запускать модели с минимальными накладными расходами, подбирая размер под доступную память.

Для чистого локального инференса без интеграции в пайплайны ML llama.cpp остаётся эталоном. Однако для гибкой разработки и оценки качества квантованных чекпоинтов в рамках экосистемы Hugging Face, эта интеграция — мощный шаг вперед.

Источник: Hugging Face ↗