JSON Workflow

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

Коротко

JSON Workflow — текстовое представление графа нод. В файле записано, какие ноды участвуют в процессе, какие значения стоят в их полях и как выходы одних нод подключены ко входам других.

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

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

Граф и текст описывают одно и то же

В редакторе workflow выглядит как карточки с портами и проводами. В JSON те же отношения превращаются в объекты, идентификаторы и ссылки.

Упрощённый API-фрагмент выглядит так:

{
  "3": {
    "class_type": "KSampler",
    "inputs": {
      "seed": 42,
      "model": ["4", 0],
      "positive": ["6", 0]
    }
  }
}

Здесь 3, 4 и 6 — идентификаторы нод внутри графа. Пара ["4", 0] означает связь с определённым выходом другой ноды. class_type сообщает backend, какой код должен обработать входы.

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

Два JSON-представления

Официальная документация Workflow API Format разделяет формат сохранения редактора и API-формат.

Формат редактора

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

• координаты и размер карточек;
• группы, цвета и заметки;
• состояние canvas;
• свойства виджетов;
• версия схемы и дополнительные метаданные.

Официальная структура описана через JSON Schema. Схема версионируется, поэтому поле version и ссылка на точную спецификацию надёжнее предположения, что любой workflow имеет одну и ту же структуру навсегда.

API-формат

Backend не нужны координаты карточек и цвет групп. API-представление оставляет исполняемую часть: тип каждой ноды, её входы, значения и ссылки на выходы других нод.

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

На инфографике один граф раскрывается в два листа. Формат редактора сохраняет карту рабочего стола, API-формат — рецепт исполнения. Это два представления одной логики, а не «полная» и «обрезанная» копии одного файла.

Что JSON действительно переносит

Состав зависит от версии схемы и расширений, но обычно workflow хранит:

• типы нод;
• их входные значения;
• связи между входами и выходами;
• названия выбранных моделей и ресурсов;
• seed и параметры sampling, если они находятся в графе;
• визуальную раскладку в формате редактора;
• дополнительные свойства, которые записывает frontend или расширение.

Файл способен описать не только генерацию изображения. Официальное определение workflow относится к любому графу ComfyUI: изображению, видео, аудио, 3D, работе с моделями и другим медиа.

Чего в нём обычно нет

JSON Workflow сам по себе не включает:

• гигабайты весов checkpoint, LoRA, VAE и других моделей;
• исходный код custom nodes;
• Python-пакеты и системные библиотеки;
• точные версии драйверов и вычислительного runtime;
• внешние изображения, видео и аудио, если они не встроены отдельным механизмом;
• секреты для внешних API, которые вообще не стоит публиковать;
• гарантию доступности URL и облачных сервисов.

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

JSON и воспроизводимость

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

workflow + модели + custom nodes + входные файлы
+ версии окружения + seed + режим вычислений

Даже при совпадении компонентов возможны небольшие численные различия между устройствами и backend. А обновление custom node способно изменить значения по умолчанию, порядок обработки или сам алгоритм.

Поэтому «файл открылся» и «результат повторился пиксель в пиксель» — разные уровни совместимости. Первый проверяет структуру графа, второй — весь вычислительный контекст.

Workflow внутри изображения

Встроенная нода SaveImage сохраняет PNG и может включать workflow metadata. Такой файл можно перетащить в ComfyUI или открыть как workflow: интерфейс прочитает вложенный JSON и восстановит граф.

Это удобный способ связать результат с рецептом, но он не является надёжным архивом сам по себе:

• другой saver может не записывать metadata;
• сохранение без metadata отключает вложение;
• пересжатие, экспорт в другой формат или обработка сайтом способны удалить служебные поля;
• изображение всё равно не содержит веса моделей и код нод;
• metadata может раскрыть промпты, пути к файлам и другие нежелательные детали.

Поэтому отдельный JSON остаётся понятным исходником, а встроенный workflow — удобной дополнительной копией. Утверждение «любой PNG восстанавливает граф» неверно: это работает только с файлом, где нужные данные сохранились.

Импорт и отсутствующие зависимости

Когда тип ноды не найден, редактор может показать отсутствующий элемент, но не способен исполнить его без кода. В актуальных сборках ComfyUI Manager встроен в core: в Desktop он включён по умолчанию, а portable- и manual-установкам может потребоваться включение. Официальная инструкция Manager описывает различия между способами установки.

Manager умеет искать отсутствующие пакеты нод в registry. Это не гарантирует восстановление любого старого графа: пакет мог исчезнуть, переименовать класс, не попасть в registry или иметь несовместимые зависимости. Модели и внешние входы тоже проверяются отдельно.

Иными словами, Manager — часть текущей инфраструктуры ComfyUI, а не отдельная нода внутри workflow и не содержимое JSON-файла.

Безопасность чужого workflow

JSON — данные, а не исполняемый Python-код. Само чтение текста обычно безопаснее запуска неизвестного скрипта. Но workflow может ссылаться на сторонние ноды, а их установка добавляет код и зависимости в окружение.

Перед запуском чужого графа имеет смысл посмотреть:

• какие custom nodes ему нужны;
• откуда они устанавливаются;
• обращаются ли ноды к сети или файловой системе;
• нет ли в полях неожиданных путей, URL и команд;
• какие данные уйдут во внешние API.

Встроенный Manager ограничивает часть способов установки и показывает registry-информацию, но оценку доверия к стороннему коду не отменяет.

Версионирование в Git

JSON — текст, поэтому изменения можно хранить в системе контроля версий. На практике diff формата редактора бывает шумным: перемещение карточки меняет координаты, а frontend может переставить поля или обновить служебные данные.

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

• редакторский — для человека;
• API-версия — для автоматизации и тестов.

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

Автоматизация без хрупких номеров

Сценарий часто загружает API-JSON, меняет prompt или seed и отправляет граф на исполнение. Самая простая версия обращается к ноде по ID, но этот ID легко изменяется при пересборке workflow.

Более устойчивый проект добавляет собственный контракт: уникальные названия, manifest с путями к нужным полям или проверку class_type и метаданных перед заменой. Если подходящих нод несколько, скрипт не угадывает, какую из них имел в виду автор.

Перед отправкой полезна валидация: JSON должен разбираться синтаксически, обязательные ноды должны присутствовать, а изменяемые поля — иметь ожидаемый тип. Тогда ошибка появляется до долгой генерации.

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

JSON Workflow содержит модели?

Обычно нет. Он хранит имена или ссылки. В спецификации редакторского workflow могут быть метаданные моделей, включая URL и hash, но бинарные веса от этого не становятся частью JSON.

Можно ли открыть API-формат в интерфейсе?

В актуальной официальной документации — да, но без исходного layout. Старые версии или сторонние frontend могут вести себя иначе.

Любая картинка ComfyUI содержит workflow?

Нет. Всё зависит от saver, настроек metadata и последующей обработки файла. Даже правильно сохранённый PNG может потерять вложение после оптимизации на сайте.

Можно ли редактировать JSON вручную?

Да. Синтаксически это обычный JSON, но смысл полей задаёт schema и типы нод. Валидный JSON всё равно может описывать несуществующую связь или неподходящее значение.

Manager является отдельным custom node?

В старых установках он распространялся отдельно. В актуальном ComfyUI Manager входит в core, хотя способ включения зависит от варианта установки. В самом workflow это не рабочая нода графа.

Почему одинаковый workflow даёт другой результат?

Чаще всего отличаются веса моделей, версии нод, входные файлы, seed, runtime или параметры, которые были вычислены динамически. JSON хранит граф, но не замораживает всё окружение.

Главное

JSON Workflow — переносимое текстовое описание графа. Формат редактора сохраняет и логику, и визуальную раскладку; API-формат оставляет исполняемые типы, входы и связи.

Его сила — в прозрачности и автоматизации, а предел — в зависимостях. Для надёжного архива рядом нужны модели или их hashes, версии custom nodes, внешние файлы и сведения об окружении. Вложенный workflow в PNG удобен как дополнительная копия, но не заменяет исходный JSON и список зависимостей.

Источники

• ComfyUI: Workflow
• ComfyUI Workflow JSON Schema
• ComfyUI Workflow API Format
• ComfyUI SaveImage
• ComfyUI-Manager Installation
• ComfyUI: Custom nodes in the new Manager UI