Safetensors

Safetensors — открытый формат хранения тензоров, в том числе весов нейросетей. Он описывает числовые массивы и не использует механизм pickle, способный запускать произвольный Python-код при загрузке. Архитектура модели задаётся отдельно; совместимость и безопасность всей программы одним расширением файла не определяются.

Коротко

Коротко. Файл Safetensors хранит имена, размеры и числовые данные тензоров. Загрузчику не нужно восстанавливать произвольные Python-объекты, как при работе с pickle. Это устраняет один важный путь исполнения чужого кода, но не отменяет проверку происхождения модели и используемых программ.

Что это такое

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

Safetensors специально ограничивает содержимое тензорами — многомерными массивами чисел — и небольшими текстовыми метаданными. Это удобно для распространения весов: нет необходимости упаковывать вместе с ними произвольные объекты Python.

Формат устроен так:

• в начале записана длина заголовка;
• далее идёт JSON-заголовок с именами тензоров, их типами, формой и смещениями;
• после него лежат байты самих тензоров.

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

Как это работает

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

Формат поддерживает отображение файла в память — memory mapping, или mmap. Оно позволяет работать с данными файла без обязательного предварительного копирования всего содержимого в отдельный буфер. Однако чтение с диска и перенос на видеокарту всё равно занимают время. Поведение зависит от загрузчика, устройства и файлового кэша.

Расширение checkpoint-файла само по себе не определяет безопасность. Контейнеры на основе pickle могут восстанавливать Python-объекты и выполнять связанный с ними код. У PyTorch есть ограниченный режим загрузки weights_only; его возможности и ограничения описаны в документации сериализации. Нельзя без проверки переносить совет о загрузке между версиями и режимами.

Пример на практике

Дизайнер выбирает checkpoint для конкретного рабочего процесса ComfyUI. Сначала он сверяет карточку модели: базовое семейство, необходимые компоненты и рекомендуемый загрузчик. Наличие расширения .safetensors не означает, что любой файл можно положить в models/checkpoints: LoRA, VAE и отдельный диффузионный модуль загружаются иначе.

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

from safetensors import safe_open

with safe_open("model.safetensors", framework="pt", device="cpu") as model:
    print(list(model.keys())[:10])
    print(model.metadata())

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

После загрузки дизайнер проверяет модель на небольшом запросе. Ошибка несовпадения ключей может указывать на неподходящую архитектуру или неполный набор компонентов; она не обязательно означает повреждение формата.

С чем часто путают

• Safetensors и checkpoint. Checkpoint — сохранённое состояние модели или обучения. Safetensors — один из форматов хранения его тензоров; дополнительные состояния могут находиться отдельно.
• Safetensors и GGUF. Оба формата хранят тензоры и метаданные, но рассчитаны на разные соглашения загрузчиков. GGUF часто используется в llama.cpp и связанных инструментах. Разница не сводится к «полные веса против квантизованных»: представление чисел и совместимость нужно проверять отдельно.
• Safetensors и ONNX. ONNX может описывать граф вычислений, а Safetensors хранит массивы без архитектуры.
• Safetensors и pickle. Pickle сериализует Python-объекты общего вида. Safetensors намеренно поддерживает более узкий набор данных.
• Формат и сжатие. Смена контейнера не уменьшает разрядность весов. Квантизация меняет их представление и требует поддержки загрузчика.

Частые ошибки и заблуждения

• «Любой Safetensors подходит любой модели». Имена, формы и назначение тензоров должны совпадать с ожидаемой архитектурой.
• «Достаточно переименовать .ckpt в .safetensors». Расширение не меняет структуру файла. Нужна корректная конвертация.
• «Конвертация неизвестного checkpoint безопасна». Сначала придётся прочитать исходник. Риск возникает на этом шаге, до появления нового файла.
• «При конвертации сохранится абсолютно всё». Поддерживаемые тензоры можно перенести без изменения чисел, но произвольные объекты, связи между ними и состояние обучения могут потребовать другой обработки.
• «Безопасный формат означает безопасную модель». Остаются риски уязвимости загрузчика, чрезмерного расхода памяти, недоверенного дополнительного кода и нежелательного поведения модели.

Связанные термины

• LoRA — адаптер, веса которого могут храниться в Safetensors.
• GGUF — другой формат хранения моделей для совместимых загрузчиков.
• Quantization — уменьшение точности представления весов.
• Model Merge — объединение весов; формат сохранения выбирается отдельно.
• PyTorch — библиотека для работы с тензорами и нейросетями.

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

Чем .safetensors отличается от .bin? Расширение .bin не указывает единственный формат. Нужно смотреть описание файла и способ его загрузки. Safetensors обозначает конкретную структуру тензорного контейнера.

Как конвертировать .ckpt? С помощью инструмента, который понимает структуру исходного checkpoint и ожидаемый результат. Неизвестный файл не стоит открывать в рабочем окружении только ради конвертации. Универсальная однострочная команда не учитывает все варианты содержимого.

Есть ли метаданные? Да. В специальном поле metadata хранятся строковые пары ключ — значение. Там могут быть сведения об авторе и базовой модели, но их наличие не обязательно, а достоверность зависит от источника файла.

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

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

Какие библиотеки поддерживаются? Проект предлагает интеграции с несколькими библиотеками работы с массивами и нейросетями. Точный список и ограничения следует смотреть в документации выбранного загрузчика; поддержка формата не означает поддержку каждой архитектуры.

Главное

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