Как устроена фабрика шаблонов ComfyUI изнутри

Если вы работали с ComfyUI, то наверняка помните ощущение, когда открываешь чужой workflow, а он рассыпается красными узлами. Не хватает пары нод, модель лежит не в той папке, да и вообще непонятно, с какого бока к схеме подступиться. Чтобы решить эту проблему для всех пользователей, команда ComfyUI создала репозиторий workflow_templates.

Это не просто свалка JSON-файлов со схемами. Разработчики собрали монорепозиторий, который превращает готовые сценарии и сабграфы в библиотеку Python-пакетов, автоматически обновляет витрину шаблонов и подтягивает нужные нейросети с Hugging Face прямо в интерфейс приложения.

Что внутри репозитория

Официальный репозиторий Comfy-Org/workflow_templates решает две задачи: поставляет готовые шаблоны генерации (изображения, видео, аудио) и предоставляет переиспользуемые блоки нод, так называемые Subgraph Blueprints.

Архитектура проекта устроена по принципу отдельного пакета под каждый тип медиа:

templates/ и packages/media_* содержит файлы воркфлоу в формате JSON и превью для интерфейса выборки.
blueprints/ и packages/blueprints хранят готовые составные узлы (субграфы), которые появляются в палитре нод.
packages/core предоставляет вспомогательный лоадер comfyui-workflow-templates-core.
site/ содержит веб-сайт на Astro (templates.comfy.org) с поиском, поддержкой 11 языков и генерацией описаний.

Весь проект распространяется через PyPI под именем comfyui-workflow-templates. Когда вы обновляете ComfyUI, новые шаблоны попадают в интерфейс именно отсюда.

Анатомия правильного шаблона ComfyUI

Самое интересное в проекте, это требования к сборке шаблонов. Разработчики не просто выкладывают экспортированный граф, а превращают его в самодостаточный бандл.

Возьмем пример добавления шаблона генерации видео на базе модели Wan 2.1. Чтобы воркфлоу стал официальным шаблоном, авторы проходят несколько обязательных этапов.

Сначала очищают схему. ComfyUI запускают с флагом --disable-all-custom-nodes. Это гарантирует, что сторонние расширения не замусорят JSON лишними метаданными.

Затем готовят превью. Для шаблона создается картинка, WebP-анимация или видео. Размеры подгоняют так, чтобы файл весил как можно меньше. Обычно используют сжатие со снижением качества до 65%.

Дальше вшивают привязку моделей прямо в ноды. Пользователю не приходится искать, какую VAE или CLIP-модель скачивать вручную. Прямо в свойства ноды (properties.models) добавляют прямой URL с Hugging Face, SHA256-хэш и целевую директорию.

Вот как выглядит внедрение метаданных модели VAE внутрь JSON-файла воркфлоу:

{
  "id": 39,
  "type": "VAELoader",
  "properties": {
    "Node name for S&R": "VAELoader",
    "models": [
      {
        "name": "wan_2.1_vae.safetensors",
        "url": "https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/resolve/main/split_files/vae/wan_2.1_vae.safetensors?download=true",
        "hash": "2fc39d31359a4b0a64f55876d8ff7fa8d780956ae2cb13463b0223e15148976b",
        "hash_type": "SHA256",
        "directory": "vae"
      }
    ]
  },
  "widgets_values": ["wan_2.1_vae.safetensors"]
}

Благодаря такой записи ComfyUI понимает, какого файла не хватает, проверяет его контрольную сумму и автоматически скачивает веса в папку models/vae.

Хэши и ссылки берут прямо со страницы файла на Hugging Face.

Кроме моделей в свойства нод можно зашить минимальную версию ядра ComfyUI или конкретного кастомного узла. Например, ноде SaveWEBM прописывают "ver": "0.3.26", чтобы пользователь увидел предупреждение, если его клиент устарел.

Все шаблоны регистрируют в едином файле конфигурации index.json.

Что за звери эти Subgraph Blueprints

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

В репозитории чертежи таких блоков хранятся в папке blueprints/. Файл блюпринта содержит описание интерфейса и структуру внутренних связей:

{
  "id": "workflow-uuid",
  "nodes": [{"id": -1, "type": "subgraph-uuid"}],
  "definitions": {
    "subgraphs": [{
      "id": "subgraph-uuid",
      "name": "Text to Image (Flux.1 Dev)",
      "inputs": [
        {"name": "text", "type": "STRING"},
        {"name": "width", "type": "INT"}
      ],
      "outputs": [
        {"name": "IMAGE", "type": "IMAGE"}
      ],
      "nodes": [],
      "links": []
    }]
  }
}

Разработчик создает такую ноду в графическом интерфейсе через "Create Subgraph", экспортирует JSON и запускает скрипт нормализации import_blueprints.py. После этого блок становится доступен в стандартной палитре нод ComfyUI у всех пользователей.

Автоматизация сборки и локализации

Любопытно устроена работа с контентом. Каждое изменение в шаблонах требует синхронизации манифестов и перевода на 11 языков.

За синхронизацию отвечают Python-скрипты из каталога scripts/sync/:

sync_bundles.py распределяет шаблоны по медиа-пакетам и собирает общий манифест.
sync_data.py подтягивает измененные строки в единый файл перевода i18n.json и раскладывает локализованные файлы вроде index.zh.json или index.ja.json.

Сайт каталога в папке site/ собран на Astro. При сборке он обращается к API хаба шаблонов. Переменная окружения PUBLIC_APPROVED_ONLY отсекает не утвержденные сообществом воркфлоу для продакшна, но оставляет их в тестовых превью-стендах.

Деплой завязан на GitHub Actions. Каждые сутки в 00:00 UTC запускается автоматическая пересборка тестовых окружений. При поднятии версии в корневом pyproject.toml CI определяет, какие субпакеты изменились, и публикует свежие релизы в PyPI.

Варианты интерактивных превью

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

Стандартное изображение или гифка.
Слайдер сравнения "до и после" для оценок обработок вроде ControlNet.
Плеер для демонстрации сгенерированного видео или аудио.
Эффекты наведения с зумом или плавной сменой кадра.

Кому пригодится этот репозиторий

Если вы пишете кастомные ноды для ComfyUI или собираете пайплайны под генеративные задачи, заглянуть в workflow_templates однозначно стоит.

Во-первых, это эталонная шпаргалка по спецификации JSON-формата ComfyUI. Из кода репозитория видно, как правильно оформлять манифесты, связывать зависимости моделей и прописывать хэши весов.

Во-вторых, вы можете отправить собственный Pull Request со своим воркфлоу или субграфом. Если схема пройдет автоматическую валидацию и проверку совместимости нод (npm run validate:comfyui-nodes), она попадет в стандартную поставку ComfyUI.

Чтобы изучить структуру изнутри локально, достаточно склонировать репозиторий и запустить генерацию бандлов командой python scripts/sync/sync_bundles.py.