Safetensors: что за файл, чем открыть и куда класть

Что такое safetensors

Модель нейросети — это большая таблица чисел. Их надо как-то записать в файл, и раньше это делали средствами самого PyTorch. Safetensors — формат, придуманный в Hugging Face специально для того, чтобы хранить те же числа безопасно и при этом быстро.

Собственное описание формата звучит коротко: простой формат для безопасного хранения тензоров, в отличие от pickle, и при этом быстрый за счёт чтения без копирования. Обе половины этой фразы важны, и обе разберём ниже.

Сегодня его читают почти все: библиотеки transformers и diffusers, ComfyUI, сборки Stable Diffusion, InvokeAI, оболочки для текстовых моделей. Для чат-моделей, которые запускают локально, чаще используется другой формат — про него отдельная статья про GGUF.

Чем он безопаснее .ckpt и .bin

Старые файлы весов — .ckpt, .pt, .bin — сделаны на механизме pickle. Это способ Python сохранять объекты в файл, и он же долгое время был форматом весов PyTorch по умолчанию.

Проблема в том, что pickle хранит не данные, а инструкции: что создать и какие функции вызвать при чтении. Документация Hugging Face формулирует это без смягчений — при загрузке pickle-файла возможны атаки с выполнением произвольного кода.

Safetensors устроен наоборот: внутри нет инструкций, только описание чисел и сами числа. Выполнять там нечего.

Сам Хаб при этом не полагается на один формат. Каждый загруженный pickle-файл прогоняется через антивирус и через разбор списка импортов, а сам список показывается рядом с файлом — подозрительные подсвечиваются. При этом в документации честно написано, что проверка не стопроцентна и ответственность остаётся на пользователе.

Отсюда правило выбора, если в репозитории лежат оба варианта.

• Есть safetensors — берём его. Даже если рядом лежит привычный .ckpt с тем же названием.
• Только .ckpt и автор неизвестен — не берём. Популярную модель почти всегда кто-то уже переложил в безопасный формат.
• Расширение .safetensors ничего не говорит о качестве. Оно говорит только о том, что при загрузке файла ничего не выполнится.

Что лежит внутри файла

Устройство описано в спецификации формата и оно нарочито простое. Файл состоит из трёх частей подряд.

1. Восемь байт в начале — длина заголовка, обычное 64-битное число.
2. Заголовок в формате JSON — перечень тензоров: имя, тип чисел, форма и то, с какого по какой байт лежат данные. Есть один служебный ключ для произвольных пометок, и в нём разрешены только строки.
3. Всё остальное — сплошной блок чисел без разрывов.

Из этой конструкции следуют оба обещания формата. Программа читает заголовок, узнаёт, где какой кусок лежит, и обращается к нужным байтам напрямую, не разворачивая файл целиком — отсюда быстрая загрузка. А поскольку данные обязаны быть сплошными, без дырок, спрятать внутрь файла постороннюю нагрузку не выйдет: спецификация прямо говорит, что это условие мешает собрать файл-гибрид.

Почему файлов несколько, а не один

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

Так сделано намеренно, и вам это выгодно.

• Части взаимозаменяемы. Один и тот же кодировщик текста работает с разными моделями, и качать его второй раз не нужно.
• Дообучение весит мало. Стиль или персонаж — это файл на десятки мегабайт вместо новой модели на десять гигабайт.
• Части обновляются по отдельности. Вышла новая версия одного блока — меняете один файл.

Обратная сторона: скачав только основную модель, вы получите ошибку о недостающем файле. Это не поломка, а недособранный конвейер.

Checkpoint, LoRA, VAE, CLIP, ControlNet

У всех этих файлов одно и то же расширение, и различить их по нему нельзя. Различают по названию папки, в которую их кладут, и по узлу, которым загружают.

Формулировки в документации ComfyUI совпадают с этим делением: LoRA там названа лёгким дополнением, настроенным под стиль, персонажа или концепт, а ControlNet — дополнительным управлением по контурам, глубине и позе.

Какие вообще бывают базовые модели и чем отличаются их версии, разобрано в статье про Stable Diffusion. Здесь речь только про файлы.

Что значат fp16, bf16 и fp8 в имени

В именах постоянно встречаются приписки вида fp16, bf16, fp8. Это не версии модели, а разрядность: сколько бит отводится на одно число.

Арифметика тут прямая: каждый шаг вниз примерно вдвое уменьшает размер файла. Поэтому восьмибитные версии крупных моделей выкладывают именно для тех, у кого шестнадцатибитная в память не помещается.

Дополнительные буквы в конце восьмибитных имён — это уточнение того, как биты распределены внутри числа. На выбор файла они почти не влияют: берите тот вариант, который ваша программа и ваша видеокарта понимают, а если оба — тот, что легче.

Куда класть файлы

Общее правило одинаковое во всех программах: у каждого типа модели своя подпапка, и программа ищет файл только в ней. Документация ComfyUI формулирует это буквально — класть в подпапку соответствующего типа внутри папки моделей.

Точные пути, установка и файл с внешними путями для тех, у кого модели уже лежат в другой программе, разобраны в статье про ComfyUI. Второй раз копировать десятки гигабайт не нужно.

Где брать сами файлы

Основной склад — Hugging Face: там лежат и официальные веса, и чужие пересборки. Как устроен сайт, как выбрать нужный файл в репозитории и как выкачать его целиком, разобрано в статье про Hugging Face. Оттуда же качаются файлы для локального запуска текстовых моделей.

Второй склад, но уже целиком про картинки, — Civitai: там у каждой модели видны примеры и настройки, с которыми они получились. Чем он отличается, зачем у него появился второй домен и как выбрать версию файла под свою программу — в статье про Civitai.

Чем открыть safetensors

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

Отдельно про то, зачем вообще держать модели у себя, а не пользоваться сервисом: разбор задач, которые имеет смысл считать локально, есть на портале ИИ-офиса — подборка нейросетей для картинок показывает, где облако удобнее, а где своё железо выигрывает.

Модель скачал, а её нет в списке

Пять причин, которые закрывают почти все случаи.

• Файл в чужой папке. Модель, положенная в loras вместо checkpoints, просто не появится в нужном списке.
• Список не обновлён. Программа читает содержимое папок при запуске. Перезапуск или кнопка обновления решают.
• Файл скачан не полностью. На моделях в несколько гигабайт обрыв соединения даёт файл нормального вида и неверного размера. Сверьте размер с указанным на странице.
• Скачана веб-страница вместо файла. Классика при сохранении по ссылке из браузера: на диске лежит документ в килобайтах с правильным именем.
• Не хватает соседних файлов. Модель есть, а текстового кодировщика или VAE к ней нет — программа сообщит об отсутствующем узле, а не о проблеме с моделью.

Отдельный случай — модель видна, но выдаёт серую или чёрную картинку. Это почти всегда несовпадение частей конвейера: VAE или кодировщик от другой версии модели.

Частые вопросы