Cómo funciona internamente la fábrica de plantillas de ComfyUI

Si has trabajado con ComfyUI, probablemente recuerdes la sensación de abrir el flujo de trabajo de otra persona y ver cómo se desmorona con nodos rojos. Te faltan un par de nodos, el modelo está en la carpeta equivocada y no tienes ni idea de por dónde empezar con el esquema. Para resolver este problema para todos los usuarios, el equipo de ComfyUI creó el repositorio workflow_templates.

Esto no es solo un volcado de archivos JSON de esquemas. Los desarrolladores construyeron un monorepo que transforma escenarios listos para usar y subgrafos en una biblioteca de paquetes de Python, actualiza automáticamente la vitrina de plantillas y extrae las redes neuronales necesarias de Hugging Face directamente a la interfaz de la aplicación.

Qué hay dentro del repositorio

El repositorio oficial Comfy-Org/workflow_templates aborda dos necesidades: proporciona plantillas de generación listas para usar (imágenes, video, audio) y ofrece bloques de nodos reutilizables, conocidos como Subgraph Blueprints.

La arquitectura del proyecto sigue un enfoque de paquete separado por tipo de medio:

• templates/ y packages/media_* contienen archivos de flujo de trabajo en formato JSON y vistas previas para la interfaz de selección.
• blueprints/ y packages/blueprints almacenan nodos compuestos listos para usar (subgrafos) que aparecen en la paleta de nodos.
• packages/core proporciona el cargador auxiliar comfyui-workflow-templates-core.
• site/ contiene el sitio web basado en Astro (templates.comfy.org) con búsqueda, soporte de 11 idiomas y generación de descripciones.

Todo el proyecto se distribuye a través de PyPI bajo el nombre comfyui-workflow-templates. Cuando actualizas ComfyUI, las nuevas plantillas llegan a la interfaz desde aquí.

Anatomía de una plantilla de ComfyUI correcta

La parte más interesante del proyecto son los requisitos de ensamblaje de plantillas. Los desarrolladores no solo vuelcan un gráfico exportado: lo transforman en un paquete autocontenido.

Tomemos el ejemplo de agregar una plantilla de generación de video basada en el modelo Wan 2.1. Para que un flujo de trabajo se convierta en una plantilla oficial, los autores pasan por varios pasos obligatorios.

Primero, limpian el esquema. ComfyUI se ejecuta con el indicador --disable-all-custom-nodes. Esto asegura que las extensiones de terceros no contaminen el JSON con metadatos extra.

Luego preparan las vistas previas. Para la plantilla, crean una imagen, animación WebP o video. Las dimensiones se ajustan para que el archivo pese lo menos posible. Típicamente usan compresión con calidad reducida al 65%.

A continuación, incrustan los enlaces de modelos directamente en los nodos. Los usuarios no tienen que buscar qué modelo VAE o CLIP descargar manualmente. Una URL directa de Hugging Face, hash SHA256 y el directorio de destino se agregan directamente a las propiedades del nodo (properties.models).

Así se ve incrustar metadatos del modelo VAE en un archivo JSON de flujo de trabajo:

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

Gracias a esta entrada, ComfyUI sabe qué archivo falta, verifica su suma de verificación y descarga automáticamente los pesos en la carpeta models/vae.

Los hashes y enlaces se toman directamente de la página del archivo en Hugging Face.

Más allá de los modelos, puedes incrustar la versión mínima del núcleo de ComfyUI o una versión específica de un nodo personalizado en las propiedades del nodo. Por ejemplo, al nodo SaveWEBM se le asigna "ver": "0.3.26" para que el usuario vea una advertencia si su cliente está desactualizado.

Todas las plantillas se registran en un único archivo de configuración index.json.

Qué son estos Subgraph Blueprints

Más allá de escenarios completos, ComfyUI utiliza subgrafos. Una combinación compleja de una docena de nodos se empaqueta en un único bloque con entradas y salidas claras.

En el repositorio, los planos para tales bloques se almacenan en la carpeta blueprints/. Un archivo de plano contiene una descripción de la interfaz y la estructura de las conexiones 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": []
    }]
  }
}

El desarrollador crea tal nodo en la interfaz gráfica a través de "Create Subgraph", exporta JSON y ejecuta el script de normalización import_blueprints.py. Después de eso, el bloque está disponible en la paleta de nodos estándar de ComfyUI para todos los usuarios.

Automatización de compilación y localización

El flujo de trabajo del contenido es interesante. Cada cambio en las plantillas requiere sincronización del manifiesto y traducción a 11 idiomas.

Los scripts de Python del directorio scripts/sync/ manejan la sincronización:

• sync_bundles.py distribuye las plantillas entre los paquetes de medios y ensambla el manifiesto común.
• sync_data.py extrae las cadenas modificadas a un único archivo de traducción i18n.json y distribuye archivos localizados como index.zh.json o index.ja.json.

El sitio del catálogo en la carpeta site/ se construye con Astro. Durante la compilación, consulta la API del hub de plantillas. La variable de entorno PUBLIC_APPROVED_ONLY filtra los flujos de trabajo de la comunidad no aprobados para producción, pero los deja en entornos de vista previa de prueba.

El despliegue está vinculado a GitHub Actions. Todos los días a las 00:00 UTC, se activan reconstrucciones automáticas de los entornos de prueba. Cuando se incrementa una versión en el pyproject.toml raíz, CI determina qué subpaquetes cambiaron y publica nuevas versiones a PyPI.

Opciones de vista previa interactiva

Para cada plantilla en el catálogo, en lugar de solo una imagen estática, se define un elemento interactivo. El repositorio soporta varias opciones de visualización de tarjetas:

• Imagen estándar o GIF.
• Control deslizante de comparación antes y después para evaluaciones de procesamiento como ControlNet.
• Reproductor para demostrar video o audio generado.
• Efectos al pasar el cursor con zoom o transiciones suaves de fotogramas.

A quién le será útil este repositorio

Si escribes nodos personalizados para ComfyUI o construyes pipelines para tareas generativas, definitivamente deberías echar un vistazo a workflow_templates.

Primero, es una guía de referencia para la especificación del formato JSON de ComfyUI. Del código del repositorio, puedes ver cómo formatear correctamente los manifiestos, enlazar dependencias de modelos y especificar hashes de pesos.

Segundo, puedes enviar tu propio Pull Request con tu flujo de trabajo o subgrafo. Si el esquema pasa la validación automatizada y las comprobaciones de compatibilidad de nodos (npm run validate:comfyui-nodes), se incluirá en la distribución estándar de ComfyUI.

Para explorar la estructura localmente, simplemente clona el repositorio y ejecuta el comando de generación de paquetes python scripts/sync/sync_bundles.py.