Como Funciona a Fábrica de Templates do ComfyUI nos Bastidores

Se você já trabalhou com o ComfyUI, provavelmente lembra a sensação de abrir o workflow de outra pessoa e ver tudo desmoronar com nós vermelhos. Faltam alguns nós, o modelo está na pasta errada, e você não tem ideia de por onde começar com o esquema. Para resolver esse problema para todos os usuários, a equipe do ComfyUI criou o repositório workflow_templates.

Isso não é apenas um despejo de arquivos JSON de esquemas. Os desenvolvedores construíram um monorepo que transforma cenários prontos e subgrafos em uma biblioteca de pacotes Python, atualiza automaticamente a vitrine de templates e puxa as redes neurais necessárias do Hugging Face diretamente para a interface do aplicativo.

O Que Está Dentro do Repositório

O repositório oficial Comfy-Org/workflow_templates atende a duas necessidades: fornece templates de geração prontos para uso (imagens, vídeo, áudio) e oferece blocos de nós reutilizáveis, conhecidos como Subgraph Blueprints.

A arquitetura do projeto segue uma abordagem de pacote separado por tipo de mídia:

• templates/ e packages/media_* contêm arquivos de workflow em formato JSON e visualizações para a interface de seleção.
• blueprints/ e packages/blueprints armazenam nós compostos prontos (subgrafos) que aparecem na paleta de nós.
• packages/core fornece o loader auxiliar comfyui-workflow-templates-core.
• site/ contém o site baseado em Astro (templates. comfy. org) com busca, suporte a 11 idiomas e geração de descrições.

Todo o projeto é distribuído via PyPI sob o nome comfyui-workflow-templates. Quando você atualiza o ComfyUI, os novos templates chegam à interface a partir daqui.

Anatomia de um Template ComfyUI Adequado

A parte mais interessante do projeto são os requisitos de montagem do template. Os desenvolvedores não despejam apenas um grafo exportado—eles o transformam em um bundle autocontido.

Vamos usar como exemplo a adição de um template de geração de vídeo baseado no modelo Wan 2.1. Para um workflow se tornar um template oficial, os autores passam por várias etapas obrigatórias.

Primeiro, eles limpam o esquema. O ComfyUI é executado com a flag --disable-all-custom-nodes. Isso garante que extensões de terceiros não poluam o JSON com metadados extras.

Depois, eles preparam as visualizações. Para o template, criam uma imagem, animação WebP ou vídeo. As dimensões são ajustadas para que o arquivo pese o mínimo possível. Geralmente usam compressão com qualidade reduzida para 65%.

Em seguida, eles incorporam vinculações de modelos diretamente nos nós. Os usuários não precisam procurar qual modelo VAE ou CLIP baixar manualmente. Uma URL direta do Hugging Face, hash SHA256 e diretório de destino são adicionados diretamente às propriedades do nó (properties.models).

Aqui está como fica a incorporação de metadados do modelo VAE em um arquivo JSON de workflow:

{
  "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"]
}

Graças a essa entrada, o ComfyUI sabe qual arquivo está faltando, verifica seu checksum e baixa automaticamente os pesos para a pasta models/vae.

Os hashes e links são tirados diretamente da página do arquivo no Hugging Face.

Além dos modelos, você pode incorporar a versão mínima do core do ComfyUI ou uma versão específica de um nó personalizado nas propriedades do nó. Por exemplo, o nó SaveWEBM recebe "ver": "0.3.26" para que o usuário veja um aviso se o cliente estiver desatualizado.

Todos os templates são registrados em um único arquivo de configuração index.json.

O Que São Esses Subgraph Blueprints

Além de cenários completos, o ComfyUI usa subgrafos. Uma combinação complexa de uma dúzia de nós é empacotada em um único bloco com entradas e saídas claras.

No repositório, os blueprints para esses blocos são armazenados na pasta blueprints/. Um arquivo de blueprint contém uma descrição da interface e a estrutura das conexões internas:

{
  "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": []
    }]
  }
}

O desenvolvedor cria tal nó na interface gráfica através de "Create Subgraph", exporta o JSON e executa o script de normalização import_blueprints.py. Depois disso, o bloco fica disponível na paleta de nós padrão do ComfyUI para todos os usuários.

Automação de Build e Localização

O fluxo de trabalho de conteúdo é interessante. Cada alteração nos templates requer sincronização do manifesto e tradução para 11 idiomas.

Scripts Python do diretório scripts/sync/ lidam com a sincronização:

• sync_bundles.py distribui os templates pelos pacotes de mídia e monta o manifesto comum.
• sync_data.py puxa as strings alteradas para um único arquivo de tradução i18n.json e distribui os arquivos localizados como index.zh.json ou index.ja.json.

O site do catálogo na pasta site/ é construído com Astro. Durante o build, ele consulta a API do hub de templates. A variável de ambiente PUBLIC_APPROVED_ONLY filtra workflows da comunidade não aprovados para produção, mas os mantém em ambientes de visualização de teste.

O deploy é vinculado ao GitHub Actions. Todos os dias às 00:00 UTC, reconstruções automáticas dos ambientes de teste são acionadas. Quando uma versão é incrementada no pyproject.toml raiz, o CI determina quais subpacotes foram alterados e publica novas versões no PyPI.

Opções de Pré-visualização Interativa

Para cada template no catálogo, em vez de apenas uma imagem estática, um elemento interativo é definido. O repositório suporta várias opções de exibição de cards:

• Imagem padrão ou GIF.
• Comparador antes-e-depois para avaliações de processamento como o ControlNet.
• Player para demonstrar vídeo ou áudio gerado.
• Efeitos de hover com zoom ou transições suaves de quadros.

Para Quem Este Repositório Será Útil

Se você escreve nós personalizados para o ComfyUI ou constrói pipelines para tarefas generativas, definitivamente deveria dar uma olhada no workflow_templates.

Primeiro, é um guia de referência para a especificação do formato JSON do ComfyUI. A partir do código do repositório, você pode ver como formatar manifests corretamente, vincular dependências de modelos e especificar hashes de pesos.

Segundo, você pode enviar seu próprio Pull Request com seu workflow ou subgrafo. Se o esquema passar na validação automatizada e nas verificações de compatibilidade de nós (npm run validate:comfyui-nodes), ele será incluído na distribuição padrão do ComfyUI.

Para explorar a estrutura localmente, basta clonar o repositório e executar o comando de geração de bundle python scripts/sync/sync_bundles.py.