Лицензия YOLO
Назад к глоссарию Ultralytics

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.

Изучи решения

Компьютерное зрение в спорте

Компьютерное зрение в спорте

Узнай, как Ultralytics YOLO обеспечивает компьютерное зрение в спорте: отслеживание игроков и мяча, аналитика результатов, полезные выводы для тренеров и реабилитация спортсменов.
Подробнее
Компьютерное зрение для аэросъёмки

Компьютерное зрение для аэросъёмки

Превращай снимки с дронов и аэрофотоснимки в полезные данные в реальном времени для сельского хозяйства, аквакультуры, охраны природы и геопространственного анализа с Ultralytics YOLO.
Подробнее
Компьютерное зрение в аэрокосмической отрасли

Компьютерное зрение в аэрокосмической отрасли

Применяй компьютерное зрение в аэрокосмической отрасли с Ultralytics YOLO: для осмотра самолётов, обнаружения посторонних предметов на взлётно-посадочных полосах, наземного обслуживания аэропортов и выявления дефектов композитных материалов.
Подробнее
Компьютерное зрение в сфере безопасности

Компьютерное зрение в сфере безопасности

Защити любой объект с помощью моделей Ultralytics YOLO. ИИ на базе компьютерного зрения обеспечивает мониторинг периметра, обнаружение угроз, распознавание номерных знаков и безопасность на рабочем месте.
Подробнее
Компьютерное зрение в робототехнике

Компьютерное зрение в робототехнике

Создавай более интеллектуальные машины с моделями Ultralytics YOLO. ИИ на базе компьютерного зрения в робототехнике обеспечивает автономную навигацию, восприятие, отслеживание объектов и управление в реальном времени.
Подробнее
Компьютерное зрение в логистике

Компьютерное зрение в логистике

Оптимизируй логистику с моделями Ultralytics YOLO. Визуальный AI обеспечивает проверку посылок, сортировку, отслеживание транспорта и мониторинг безопасности на складе в реальном времени.
Подробнее
Компьютерное зрение в розничной торговле

Компьютерное зрение в розничной торговле

Переосмысли розничную торговлю с моделями Ultralytics YOLO. Визуальный AI обеспечивает отслеживание запасов, мониторинг полок, управление очередями и более глубокое понимание поведения покупателей.
Подробнее
Компьютерное зрение в здравоохранении

Компьютерное зрение в здравоохранении

Создавай решения для здравоохранения с моделями Ultralytics YOLO. Визуальный AI в здравоохранении ускоряет медицинскую визуализацию, улучшает диагностику и мониторинг пациентов.
Подробнее
Компьютерное зрение в производстве

Компьютерное зрение в производстве

Оптимизируй производство с моделями Ultralytics YOLO. Компьютерное зрение на базе ИИ обеспечивает контроль качества, обнаружение дефектов, контроль использования СИЗ и автоматизацию сборочных линий.
Подробнее
Компьютерное зрение в автомобильной отрасли

Компьютерное зрение в автомобильной отрасли

Применяй компьютерное зрение в автомобильной отрасли с моделями Ultralytics YOLO. Компьютерное зрение на базе ИИ повышает безопасность дорожного движения, улучшает помощь водителю и автоматизацию автомобилей, делая дороги умнее.
Подробнее
Компьютерное зрение в сельском хозяйстве

Компьютерное зрение в сельском хозяйстве

Внедряй ИИ для компьютерного зрения в умное сельское хозяйство с моделями Ultralytics YOLO. Используй их для мониторинга посевов, отслеживания скота и точного земледелия, чтобы повысить урожайность и эффективность.
Подробнее

Давай вместе строить будущее ИИ!

Начни свой путь в будущее машинного обучения