GGUF

GGUF — это формат одного файла, используемый для хранения моделей для инференса с помощью GGML, содержащий метаданные модели и тензоры. Он поддерживает множество квантованных типов данных (см. таблицу типов квантования), что позволяет существенно экономить память.

Загрузка моделей GGUF

Установите kernels, иначе при загрузке сжатый путь откатится к полной деквантизации.

pip install kernels

Веса остаются упакованными, если доступно ядро Hub ggml-org/ggml-quantization. Загрузчик по умолчанию использует MPS, когда это ядро присутствует, и выполняет матричные умножения непосредственно на упакованных блоках. Если ядро недоступно, модель деквантуется при загрузке.

from transformers import AutoModelForCausalLM, AutoTokenizer

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

model = AutoModelForCausalLM.from_pretrained(model_id, gguf_file=filename)
tokenizer = AutoTokenizer.from_pretrained(model_id, gguf_file=filename)

Такая же загрузка работает и для Qwen3.5 MoE.

moe_model_id = "unsloth/Qwen3.5-35B-A3B-GGUF"
moe_filename = "Qwen3.5-35B-A3B-Q4_K_M.gguf"

moe_model = AutoModelForCausalLM.from_pretrained(moe_model_id, gguf_file=moe_filename)
moe_tokenizer = AutoTokenizer.from_pretrained(moe_model_id, gguf_file=moe_filename)

Сжатый путь загрузки в настоящее время поддерживает Qwen3.5 и Qwen3.5 MoE. Загрузка в сжатом формате автоматически использует float32, так как это быстрее на MPS. Если вы зададите другой dtype, загрузчик вернёт предупреждение. Другие архитектуры обрабатываются через устаревший загрузчик.

Внимание

На MPS при установленных ядрах ggml-attn является реализацией внимания по умолчанию при загрузке файла GGUF: это то же самое ядро flash-attention, которое llama.cpp использует для decode и prefill. Если ядро не удалось получить, модель сохраняет свою исходную реализацию внимания. Передача параметра attn_implementation (например, "sdpa") всегда имеет приоритет.

Вы также можете передать его явно:

model = AutoModelForCausalLM.from_pretrained(
    model_id, gguf_file=filename, attn_implementation="ggml-org/ggml-attn"
)

Декуантизация

Dequantizing распаковывает каждый вес при загрузке и возвращает обычную плотную модель. Это запасной вариант, когда быстрый сжатый путь неприменим. Вы также можете явно запросить его с помощью GgufConfig.

import torch

from transformers import AutoModelForCausalLM, GgufConfig

quantization_config = GgufConfig(dequantize=True)
model = AutoModelForCausalLM.from_pretrained(
    model_id, gguf_file=filename, quantization_config=quantization_config, dtype=torch.bfloat16
)

Вы получаете обычную плотную модель в dtype, который вы передали.

Архитектуры, отличные от Qwen3.5 и Qwen3.5 MoE, обрабатываются устаревшим загрузчиком, который всегда выполняет деквантование.

Устаревший загрузчик поддерживает Llama, Mistral, Qwen2, Qwen2Moe, Phi3, Bloom, Falcon, StableLM, GPT2, Starcoder2 и другие.

Развертывание

transformers serve отображает каждый файл .gguf в репозитории как отдельную модель. Имя модели GGUF имеет вид <repo>:<file>.gguf, поскольку в репозитории хранится несколько квантованных версий, и идентификатор должен указывать, какую именно загрузить. Запросы используют то же самое имя.

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