GGUF
GGUF — это однофайловый формат, который llama.cpp использует для хранения весов LLM, токенизатора и метаданных, часто квантованных до 4–8 бит для локального оборудования.
GGUF — это двоичный формат файла для хранения моделей, работающих на GGML — библиотеке тензоров на C, лежащей в основе llama.cpp, — и созданных на ее основе инструментов. Один файл GGUF содержит все необходимое для запуска большой языковой модели (LLM): архитектуру и гиперпараметры, словарь токенизатора, шаблон чата и веса модели, обычно сжатые с помощью квантования модели до 2–8 бит на вес. Проект llama.cpp представил GGUF в августе 2023 года на замену более ранним форматам GGML, GGMF и GGJT. GGUF стал стандартным способом распространять модели с открытыми весами для локального инференса на ноутбучном CPU, Mac с Apple Silicon или потребительском GPU; на Hugging Face размещены тысячи репозиториев GGUF.
Структура файла GGUF#
В спецификации GGUF в заданном порядке определены четыре части. Заголовок содержит магические байты GGUF, версию формата (сейчас 3), а также количество тензоров и записей метаданных. Далее идут типизированные пары «ключ-значение» с метаданными, например general.architecture, llama.context_length, tokenizer.ggml.tokens и tokenizer.chat_template, в которые встроены токенизация модели и формат промпта. Затем таблица перечисляет имя, форму, тип данных и смещение каждого тензора, а в конце располагаются данные тензоров. По умолчанию они дополняются до выравнивания в 32 байта, чтобы среда выполнения могла отобразить файл в память и почти мгновенно загрузить его. Читатели находят метаданные по ключу, поэтому новые архитектуры и поля можно добавлять, не нарушая совместимость со старыми файлами.
У каждого тензора свой тип, поэтому в одном файле могут сочетаться разные точности. Пакет Python gguf, поддерживаемый в репозитории llama.cpp, записывает данные в этом формате, читает их и реализует несколько типов квантования:
import numpy as np
from gguf import GGMLQuantizationType, GGUFReader, GGUFWriter
from gguf.quants import dequantize, quantize
weights = np.random.default_rng(0).standard_normal((1024, 1024)).astype(np.float32)
# A GGUF file holds metadata key-value pairs plus named tensors, each with its own type
writer = GGUFWriter("tiny.gguf", arch="llama")
writer.add_context_length(4096)
for qtype in [GGMLQuantizationType.F16, GGMLQuantizationType.Q8_0, GGMLQuantizationType.Q4_0]:
writer.add_tensor(f"weight.{qtype.name}", quantize(weights, qtype), raw_dtype=qtype)
writer.write_header_to_file()
writer.write_kv_data_to_file()
writer.write_tensors_to_file()
writer.close()
# Read the file back: metadata keys, then each tensor's bits per weight and rounding error
reader = GGUFReader("tiny.gguf")
print([name for name in reader.fields if not name.startswith("GGUF.")])
for tensor in reader.tensors:
error = np.abs(dequantize(tensor.data, tensor.tensor_type).reshape(weights.shape) - weights).mean()
print(f"{tensor.tensor_type.name}: {8 * tensor.n_bytes / weights.size:.1f} bits per weight, mean error {error:.4f}")Он перечисляет два ключа метаданных — general.architecture и llama.context_length, — а затем указывает 16,0 бита на вес и среднюю ошибку 0,0001 для F16, 8,5 бита и 0,0045 для Q8_0, а также 4,5 бита и 0,0719 для Q4_0. Q8_0 и Q4_0 хранят блоки из 32 весов и один масштаб FP16 для каждого блока; именно поэтому на вес приходится дополнительные полбита.
Типы квантования#
Типы квантования GGUF относятся к трем поколениям. В исходных блочных форматах, например Q4_0 и Q8_0, для каждых 32 весов используется один масштаб. Форматы K-quants, например Q4_K и Q6_K, объединяют блоки в суперблоки по 256 весов с квантованными масштабами, а имена файлов, такие как Q4_K_M, обозначают сочетание типов, в котором наиболее чувствительные тензоры сохраняются с большей точностью. Форматы I-quants, например IQ2_XXS и IQ4_XS, позволяют получить около 2–4 бит на вес, обычно используя матрицу важности, которую llama-imatrix вычисляет по текстовым примерам, чтобы сохранить максимальную точность для наиболее значимых весов. Среди более новых вариантов — MXFP4, формат плавающей точки с точностью 4 бита, который OpenAI использовала для выпуска gpt-oss. Большинство опубликованных файлов GGUF создают одним и тем же способом:
GGUF и другие форматы моделей#
- GGML, GGMF и GGJT: В более ранних форматах llama.cpp гиперпараметры хранились в не типизированном списке без поля архитектуры, поэтому добавление параметра нарушало работу существующих файлов.
- Safetensors: Формат Hugging Face для безопасного хранения необработанных тензоров, обычно в полной или половинной точности; конфигурация и токенизатор при этом хранятся в отдельных файлах.
- ONNX: Хранит полный граф вычислений вместе с весами, поэтому любая совместимая с ONNX среда выполнения может исполнять модель без кода, специфичного для ее архитектуры.
Запуск моделей GGUF#
llama.cpp запускает файлы GGUF из командной строки или как llama-server, предоставляя API, совместимый с OpenAI. Программа может передать любое количество слоев на GPU, оставив остальные на CPU, что позволяет запускать модели, размер которых превышает объем памяти GPU. Ollama и LM Studio запускают модели GGUF через библиотеку моделей и интерфейс чата, а Hugging Face Hub показывает метаданные и типы тензоров каждого файла GGUF в браузере. Локальный инференс не отправляет промпты с устройства, что важно для конфиденциальности данных и автономного использования ИИ на периферии. Интерфейс LLM Ultralytics может обращаться к модели GGUF, запущенной через llama-server или Ollama, используя их совместимые с OpenAI конечные точки Chat Completions. Поэтому конвейер YOLO26 может попросить локальную модель описать обнаруженные объекты, не отправляя данные в облачный API. Формат используется не только для языковых моделей: пользовательские узлы ComfyUI-GGUF загружают квантованные диффузионные модели, например FLUX.1, из файлов GGUF, чтобы они помещались в память потребительских GPU.










