JSON Workflow

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

Коротко

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

API-формат

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Главное

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

JSON удобно читать и менять программой, но он не переносит все зависимости. Для надёжного архива рядом нужны модели либо ссылки с контрольными суммами, версии 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