Форматы файлов моделей

Релиз модели — не один файл: это чекпоинт, который перепаковывают под каждый движок. Эта страница картографирует форматы, которые вы реально встретите локально: GGUF для мира llama.cpp, safetensors для стека PyTorch/HF, нативные GPU-кванты движков и ONNX для edge-рантаймов. Сначала выбирайте движок; формат последует.

GGUF: один файл, всё внутри

Файл .gguf упаковывает веса модели, словарь токенизатора, чат-шаблон и метаданные по тензорам в один бинарник. Одна загрузка, нулевая настройка, и любое приложение, говорящее на GGUF, запускает тот же файл: llama.cpp и llama-server, Ollama, LM Studio, Jan, KoboldCpp. Формат поддерживает mmap, поэтому веса стримятся с диска страница за страницей — старт быстрый, а кэширование страниц ОС делает бесплатно.

Анатомия имени файла, поле за полем, для Qwen3-8B-Q4_K_M.gguf:

Осмотрите любой GGUF, не загружая его:

python gguf-py/gguf/scripts/gguf_dump.py model.gguf

general.architecture     : qwen3
general.name             : Qwen3 8B
qwen3.context_length     : 32768
tokenizer.ggml.model     : gpt2 (BPE)
tokenizer.chat_template  : {%- ... шаблон Jinja ... }

Этот блок метаданных — причина, почему GGUF «просто работает» в пяти разных приложениях: движок читает архитектуру, строит граф, грузит токенизатор, а чат-фронтенды применяют встроенный шаблон. Никакой охоты за конфигами, никакого несовпадения словарей, никакой отдельной загрузки токенизатора.

Safetensors: нативный формат Hugging Face

Safetensors — нарочито скучный контейнер: JSON-заголовок с именами тензоров, формами и dtype, за которым сырые байты. Он хранит только тензоры — без исполняемого кода, в отличие от пахнущих pickle .bin-чекпоинтов, которые опасно загружать вслепую, — и поддерживает zero-copy mmap, поэтому старт PyTorch быстрый. Transformers, vLLM, SGLang, TRL и вся экосистема дообучения говорят на нём нативно.

Поскольку он хранит только тензоры, работающая модель — это весь каталог репозитория:

model-00001-of-00004.safetensors   ← шарды весов (~5 GB каждый)
model-00002-of-00004.safetensors
model-00003-of-00004.safetensors
model-00004-of-00004.safetensors
model.safetensors.index.json        ← карта шардов: имя тензора → файл шарда
config.json                         ← архитектура + гиперпараметры
generation_config.json              ← настройки сэмплирования по умолчанию
tokenizer.json                      ← сам токенизатор
tokenizer_config.json               ← чат-шаблон живёт здесь

Шардирование существует, потому что чекпоинт 70B FP16 — это ~140 GB; один файл был бы неуправляем. Если вы обслуживаете vLLM-ом, вы скачиваете все шарды; никакого ярлыка «только 4-битный файл» внутри safetensors-релиза нет. Квантованное обслуживание — отдельный репозиторий (AWQ- или GPTQ-вариант той же модели).

Нативные GPU-кванты движков: AWQ, GPTQ, EXL2

Эти форматы существуют для GPU-серверов инференса, где пропускная способность важнее удобства файла:

• AWQ — квантизация с учётом активаций. Калибровочные промпты находят ~1% каналов весов, от которых сильнее всего зависят активации; им достаётся защищённое масштабирование, всё остальное идёт в 4 бита. Качество около оригинала при 4 битах с быстрыми ядрами; выбор 4 бит по умолчанию в vLLM.
• GPTQ — классический GPU-квант, потомок optimal brain quantization: квантует слой за слоем, компенсируя ошибку каждого слоя против ещё не квантованных весов. 4 бита, только GPU-ядра, до сих пор повсюду в конфигах обслуживания.
• EXL2 — формат exllamav2 с переменным числом бит на вес. Один репозиторий может стоять на, скажем, 4.65 bpw, смешивая тензоры 2–8 бит, чтобы суммарно попасть точно под ваш потолок VRAM. Инструмент для случая, когда Q4 не влезает, а Q3 будет больно.

Всем трём нужны калибровочные данные и разовый конверсионный прогон, и ни один не работает на CPU.

ONNX, MLX, сырые FP16/BF16

ONNX — переносимый формат графа вычислений: экспортируйте модель transformers один раз и запускайте везде, где работает onnxruntime — Windows-машины без CUDA, телефоны, браузерные WebGPU-демо. onnxruntime умеет квантовать граф в INT8 для CPU. Вы платите трением настройки и часто пиковой скоростью; получаете переносимость на машины без стека PyTorch. Edge и встроенные системы — его дом, а не десктопный чат.

MLX — фреймворк массивов Apple для Apple Silicon; организация mlx-community перепаковывает большинство крупных релизов в формат MLX, включая 4- и 8-битные. На Mac серии M с mlx-lm это ваш формат — см. Apple Silicon.

Сырые FP16/BF16-чекпоинты важны, когда нужен эталон без потерь, база для дообучения или источник конверсии. BF16 сохраняет 8-битный диапазон экспоненты FP32 и меняет на него биты мантиссы — куда стабильнее FP16 для обучения при тех же 2 байтах на вес. Модель 7–8B в FP16/BF16 — ~16 GB одних весов, до всякого контекста.

Какой формат для какого движка

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

Пути конверсии

Стандартный путь из репозитория Hugging Face в локальный файл — два шага: конвертировать чекпоинт в 16-битный GGUF, затем квантовать вниз:

git clone https://github.com/ggerganov/llama.cpp
pip install -r llama.cpp/requirements.txt

# 1. конвертировать HF-чекпоинт (safetensors) в GGUF
python llama.cpp/convert_hf_to_gguf.py ./Qwen3-8B --outtype bf16 --outfile qwen3-8b-bf16.gguf

# 2. квантовать до целевого размера
llama-quantize qwen3-8b-bf16.gguf qwen3-8b-Q4_K_M.gguf Q4_K_M

На практике вы редко конвертируете сами: квантизаторы вроде bartowski и mradermacher публикуют каждый размер каждого заметного релиза в течение часов. Конвертируйте сами, когда у вас приватное дообучение, нужен I-квант с калибровкой imatrix или нестандартная битовая цель — детали в квантизации.

Модели эмбеддингов — вторая, поисковая половина RAG — поставляются в тех же форматах: GGUF для эмбеддинг-эндпоинта llama.cpp, safetensors для sentence-transformers. То же правило, что и везде выше: подбирайте формат под движок, которым реально будете пользоваться.

Связанные разделы: квантизация · семейства моделей · движки · RAG