Fonctionnement interne de la Fabrique de Modèles ComfyUI

Si vous avez utilisé ComfyUI, vous vous souvenez probablement de ce sentiment de frustration en ouvrant le workflow de quelqu'un d'autre pour découvrir qu'il s'effondre avec des nœuds rouges. Il manque quelques nœuds, le modèle est dans le mauvais dossier, et vous ne savez pas par où commencer avec le schéma. Pour résoudre ce problème pour tous les utilisateurs, l'équipe ComfyUI a créé le dépôt workflow_emplates.

Ce n'est pas simplement un dépôt de fichiers JSON. Les développeurs ont construit un monorepo qui transforme des scénarios prêts à l'emploi et des sous-graphes en une bibliothèque de packages Python, met automatiquement à jour la vitrine des modèles, et récupère les réseaux neuronaux requis depuis Hugging Face directement dans l'interface de l'application.

Ce qu'il y a à l'intérieur du dépôt

Le dépôt officiel Comfy-Org/workflow_emplates répond à deux besoins : il fournit des modèles de génération prêts à l'emploi (images, vidéo, audio) et propose des blocs de nœuds réutilisables, connus sous le nom de Subgraph Blueprints.

L'architecture du projet suit une approche avec un package séparé par type de média :

• templates/ et packages/media_* contiennent les fichiers de workflow au format JSON et les aperçus pour l'interface de sélection.
• blueprints/ et packages/blueprints stockent les nœuds composites prêts à l'emploi (sous-graphes) qui apparaissent dans la palette de nœuds.
• packages/core fournit le chargeur d'aide comfyui-workflow-templates-core.
• site/ contient le site web basé sur Astro (templates.comfy. org) avec recherche, support de 11 langues et génération de descriptions.

L'ensemble du projet est distribué via PyPI sous le nom comfyui-workflow-templates. Lorsque vous mettez à jour ComfyUI, les nouveaux modèles sont intégrés à l'interface depuis ce dépôt.

Anatomie d'un modèle ComfyUI correct

La partie la plus intéressante du projet concerne les exigences d'assemblage des modèles. Les développeurs ne se contentent pas de déposer un graphe exporté—ils le transforment en un bundle autonome.

Prenons l'exemple de l'ajout d'un modèle de génération vidéo basé sur le modèle Wan 2.1. Pour qu'un workflow devienne un modèle officiel, les auteurs passent par plusieurs étapes obligatoires.

D'abord, ils nettoyent le schéma. ComfyUI est exécuté avec l'indicateur --disable-all-custom-nodes. Cela garantit que les extensions tierces ne polluent pas le JSON avec des métadonnées supplémentaires.

Puis ils préparent les aperçus. Pour le modèle, ils créent une image, une animation WebP ou une vidéo. Les dimensions sont ajustées de sorte que le fichier pèse le moins possible. Ils utilisent généralement une compression avec une qualité réduite à 65%.

Ensuite, ils intègrent les liaisons de modèles directement dans les nœuds. Les utilisateurs n'ont pas à chercher quel modèle VAE ou CLIP télécharger manuellement. Une URL directe depuis Hugging Face, le hash SHA256 et le répertoire cible sont ajoutés directement aux propriétés du nœud (properties.models).

Voici à quoi ressemble l'intégration des métadonnées du modèle VAE dans un fichier 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"]
}

Grâce à cette entrée, ComfyUI sait quel fichier manque, vérifie sa somme de contrôle, et télécharge automatiquement les poids dans le dossier models/vae.

Les hashs et les liens sont pris directement depuis la page du fichier sur Hugging Face.

Au-delà des modèles, vous pouvez intégrer la version minimale du cœur ComfyUI ou une version spécifique d'un nœud personnalisé dans les propriétés du nœud. Par exemple, le nœud SaveWEBM se voit attribuer "ver": "0.3.26" afin que l'utilisateur voie un avertissement si son client est obsolète.

Tous les modèles sont enregistrés dans un seul fichier de configuration index.json.

Que sont ces Subgraph Blueprints

Au-delà des scénarios complets, ComfyUI utilise des sous-graphes. Une combinaison complexe d'une douzaine de nœuds est regroupée en un seul bloc avec des entrées et des sorties claires.

Dans le dépôt, les blueprints pour ces blocs sont stockés dans le dossier blueprints/. Un fichier blueprint contient une description d'interface et la structure des connexions internes :

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

Le développeur crée un tel nœud dans l'interface graphique via « Create Subgraph », exporte le JSON, et exécute le script de normalisation import_blueprints.py. Après cela, le bloc devient disponible dans la palette de nœuds standard ComfyUI pour tous les utilisateurs.

Automatisation de la construction et de la localisation

Le workflow de contenu est intéressant. Chaque modification des modèles nécessite une synchronisation du manifeste et une traduction dans 11 langues.

Les scripts Python du répertoire scripts/sync/ gèrent la synchronisation :

• sync_bundles.py distribue les modèles entre les packages médias et assemble le manifeste commun.
• sync_data.py extrait les chaînes modifiées dans un seul fichier de traduction i18n.json et distribue les fichiers localisés comme index.zh.json ou index.ja.json.

Le site catalogue dans le dossier site/ est construit avec Astro. Pendant la construction, il interroge l'API du hub de modèles. La variable d'environnement PUBLIC_APPROVED_ONLY filtre les workflows communautaires non approuvés pour la production, mais les laisse dans les environnements de prévisualisation de test.

Le déploiement est lié à GitHub Actions. Chaque jour à 00h00 UTC, des reconstructions automatiques des environnements de test sont déclenchées. Lorsqu'une version est incrémentée dans pyproject.toml à la racine, CI détermine quels sous-packages ont changé et publie de nouvelles versions sur PyPI.

Options d'aperçu interactif

Pour chaque modèle du catalogue, au lieu d'une simple image statique, un élément interactif est défini. Le dépôt prend en charge plusieurs options d'affichage des cartes :

• Image standard ou GIF.
• Comparaison avant-après avec curseur pour les évaluations de traitement comme ControlNet.
• Lecteur pour démontrer la vidéo ou l'audio généré.
• Effets au survol avec zoom ou transitions d'images fluides.

À qui ce dépôt sera utile

Si vous écrivez des nœuds personnalisés pour ComfyUI ou construisez des pipelines pour des tâches génératives, vous devriez absolument jeter un œil à workflow_emplates.

Premièrement, c'est un guide de référence pour la spécification du format JSON de ComfyUI. À partir du code du dépôt, vous pouvez voir comment formater correctement les manifestes, lier les dépendances de modèles et spécifier les hashs des poids.

Deuxièmement, vous pouvez soumettre votre propre Pull Request avec votre workflow ou sous-graphe. Si le schéma passe la validation automatisée et les vérifications de compatibilité des nœuds (npm run validate:comfyui-nodes), il sera inclus dans la distribution standard de ComfyUI.

Pour explorer la structure localement, il suffit de cloner le dépôt et d'exécuter la commande de génération de bundle python scripts/sync/sync_bundles.py.