Come Funziona Internamente la Fabbrica di Template di ComfyUI

Se hai lavorato con ComfyUI, probabilmente ricordi la sensazione di aprire il workflow di qualcun altro solo per vederlo andare in pezzi con nodi rossi. Ti mancano un paio di nodi, il modello è nella cartella sbagliata, e non hai idea da dove iniziare con lo schema. Per risolvere questo problema per tutti gli utenti, il team di ComfyUI ha creato il repository workflow_templates.

Non è solo un ammasso di file JSON di schema. Gli sviluppatori hanno costruito un monorepo che trasforma scenari pronti all'uso e sottografi in una libreria di pacchetti Python, aggiorna automaticamente la vetrina dei template, e scarica le reti neurali richieste da Hugging Face direttamente nell'interfaccia dell'applicazione.

Cosa C'è all'Interno del Repository

Il repository ufficiale Comfy-Org/workflow_templates soddisfa due esigenze: fornisce template di generazione pronti all'uso (immagini, video, audio) e offre blocchi di nodi riutilizzabili, noti come Subgraph Blueprints.

L'architettura del progetto segue un approccio con pacchetto separato per tipo di media:

• templates/ e packages/media_* contengono file workflow in formato JSON e anteprime per l'interfaccia di selezione.
• blueprints/ e packages/blueprints memorizzano nodi compositi pronti all'uso (sottografi) che appaiono nella palette dei nodi.
• packages/core fornisce il loader helper comfyui-workflow-templates-core.
• site/ contiene il sito web basato su Astro (templates. comfy.org) con ricerca, supporto per 11 lingue e generazione delle descrizioni.

L'intero progetto è distribuito tramite PyPI con il nome comfyui-workflow-templates. Quando aggiorni ComfyUI, i nuovi template arrivano nell'interfaccia da qui.

Anatomia di un Template ComfyUI Corretto

La parte più interessante del progetto sono i requisiti di assemblaggio del template. Gli sviluppatori non si limitano a scaricare un grafo esportato—lo trasformano in un bundle autosufficiente.

Prendiamo l'esempio di aggiungere un template di generazione video basato sul modello Wan 2.1. Perché un workflow diventi un template ufficiale, gli autori attraversano diversi passaggi obbligatori.

Innanzitutto, puliscono lo schema. ComfyUI viene eseguito con il flag --disable-all-custom-nodes. Questo assicura che le estensioni di terze parti non inquinino il JSON con metadati extra.

Quindi preparano le anteprime. Per il template, creano un'immagine, un'animazione WebP o un video. Le dimensioni vengono regolate in modo che il file pesi il meno possibile. Tipicamente usano compressione con qualità ridotta al 65%.

Successivamente, incorporano le associazioni dei modelli direttamente nei nodi. Gli utenti non devono cercare quale modello VAE o CLIP scaricare manualmente. Un URL diretto da Hugging Face, l'hash SHA256 e la directory di destinazione vengono aggiunti direttamente alle proprietà del nodo (properties.models).

Ecco come appare l'incorporamento dei metadati del modello VAE in un file JSON di 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"]
}

Grazie a questa voce, ComfyUI sa quale file manca, verifica il suo checksum e scarica automaticamente i pesi nella cartella models/vae.

Gli hash e i link sono presi direttamente dalla pagina del file su Hugging Face.

Oltre ai modelli, puoi incorporare la versione minima del core di ComfyUI o una versione specifica di un nodo personalizzato nelle proprietà del nodo. Ad esempio, al nodo SaveWEBM viene assegnato "ver": "0.3.26" così l'utente vede un avviso se il suo client è obsoleto.

Tutti i template sono registrati in un singolo file di configurazione index.json.

Cosa Sono Questi Subgraph Blueprints

Oltre agli scenari completi, ComfyUI utilizza sottografi. Una combinazione complessa di una dozzina di nodi viene compattata in un singolo blocco con ingressi e uscite chiari.

Nel repository, i blueprint per tali blocchi sono memorizzati nella cartella blueprints/. Un file blueprint contiene una descrizione dell'interfaccia e la struttura delle connessioni interne:

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

Lo sviluppatore crea un tale nodo nell'interfaccia grafica attraverso "Create Subgraph", esporta il JSON ed esegue lo script di normalizzazione import_blueprints.py. Dopodiché, il blocco diventa disponibile nella palette dei nodi standard di ComfyUI per tutti gli utenti.

Automazione della Build e della Localizzazione

Il flusso di lavoro dei contenuti è interessante. Ogni modifica ai template richiede la sincronizzazione del manifest e la traduzione in 11 lingue.

Gli script Python dalla directory scripts/sync/ gestiscono la sincronizzazione:

• sync_bundles.py distribuisce i template tra i pacchetti multimediali e assembla il manifest comune.
• sync_data.py estrae le stringhe modificate in un singolo file di traduzione i18n.json e distribuisce i file localizzati come index.zh.json o index.ja.json.

Il sito del catalogo nella cartella site/ è costruito con Astro. Durante la build, interroga l'API dell'hub dei template. La variabile d'ambiente PUBLIC_APPROVED_ONLY filtra i workflow della community non approvati per la produzione, ma li lascia negli ambienti di anteprima di test.

Il deployment è collegato a GitHub Actions. Ogni giorno alle 00:00 UTC, vengono attivati rebuild automatici degli ambienti di test. Quando viene incrementata una versione nella pyproject.toml root, CI determina quali sottopacchetti sono cambiati e pubblica nuove release su PyPI.

Opzioni di Anteprima Interattiva

Per ogni template nel catalogo, invece di una semplice immagine statica, viene definito un elemento interattivo. Il repository supporta diverse opzioni di visualizzazione delle schede:

• Immagine standard o GIF.
• Comparazione prima e dopo con slider per valutazioni di elaborazione come ControlNet.
• Lettore per la dimostrazione di video o audio generati.
• Effetti al passaggio del mouse con zoom o transizioni fluide dei frame.

A Chi Sarà Utile Questo Repository

Se scrivi nodi personalizzati per ComfyUI o costruisci pipeline per attività generative, dovresti assolutamente dare un'occhiata a workflow_templates.

Innanzitutto, è una guida di riferimento per la specifica del formato JSON di ComfyUI. Dal codice del repository, puoi vedere come formattare correttamente i manifest, collegare le dipendenze dei modelli e specificare gli hash dei pesi.

In secondo luogo, puoi inviare la tua Pull Request con il tuo workflow o sottografo. Se lo schema supera la validazione automatizzata e i controlli di compatibilità dei nodi (npm run validate:comfyui-nodes), verrà incluso nella distribuzione standard di ComfyUI.

Per esplorare la struttura localmente, basta clonare il repository ed eseguire il comando di generazione del bundle python scripts/sync/sync_bundles.py.