Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Importar un chatflow de Flowise

Esta guía paso a paso importa un chatflow exportado de Flowise — una cadena de conversación con un modelo de chat y una memoria — en un Aggregate, una Release y un Manifest que compilan Flowise con el chatflow para Docker Compose tal como están escritos, y después los compila y ejecuta el resultado. Cada archivo y cada bloque de salida que aparecen a continuación proceden de una ejecución real; el chatflow y cada etapa de la guía están en el ejemplo import-flowise, donde un script de comprobación vuelve a ejecutar la importación, compara lo que escribe, lo que imprime y los bloques que cita esta página con los archivos que se conservan allí, y valida y compila lo que escribió la importación.

Generar el ejemplo

Puedes ejecutar esta importación con los comandos de esta página o pedir a tu asistente de IA que la ejecute por ti.

Escribe el ejemplo en una carpeta nueva con su nombre:

Terminal window
aggrega scaffold --example import-flowise

Después imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva; el siguiente, más abajo, entra en la carpeta source de la carpeta nueva, donde se ejecuta la importación. Esa carpeta contiene el archivo del chatflow, support-chat.json, que esta página describe en lugar de citar:

Terminal window
cd import-flowise

La carpeta source del ejemplo generado abierta en Visual Studio Code, con la exportación del chatflow de Flowise de un chat de soporte, abierta en su nodo ChatOpenAI.

El chatflow

support-chat.json, escrito para esta guía con la forma en que el editor de Flowise exporta un chatflow, contiene tres nodos y las dos aristas entre ellos: un nodo ChatOpenAI que selecciona gpt-4o-mini, un nodo Buffer Memory y un nodo Conversation Chain que recibe ambos y responde con un breve mensaje de sistema. El nodo ChatOpenAI no selecciona ninguna credencial almacenada y deja vacío su Base Path, de modo que el cliente de OpenAI en el que Flowise lo ejecuta lee su dirección y su clave del entorno de Flowise.

Junto al chatflow, un .aggrega-config.yaml convierte la carpeta en un espacio de trabajo:

# The workspace key marks this directory as the workspace root, so an import run
# here writes its drafts beside support-chat.json.
workspace: {}
# The registry the importer is fetched from the first time an import needs it.
default_registry: hub.aggrega.ai

y import-answers.yaml contiene las respuestas a lo que ningún chatflow puede contener. Flowise no carga ningún chatflow desde un archivo al arrancar, así que la compilación lo precarga a través de la propia API de Flowise con una cuenta de propietario, y ninguna exportación nombra esa cuenta: su correo electrónico es la única respuesta que necesita una importación para Docker Compose. Una importación para Kubernetes necesita además el nombre del Secret de Kubernetes que contiene cada secreto —la contraseña del propietario y la clave de OpenAI—, así que el archivo nombra también esos dos Secrets (consulta En Kubernetes):

# Values the import could not draft from the source, keyed by the drafted file and the key path inside
# it. Write each one beside its key; an import of the same source, and a sync, read them from here and
# ask nothing. A secret is never written here: its key asks where the secret comes from — a variable
# name, ${NAME}, or the name of a Kubernetes Secret.
release.yaml:
# Email address of the platform's owner account, read only when values.flow_definition is set. The
# step that seeds the chatflow registers this account when the instance has no owner yet, which makes
# it the owner, and signs in as it; on an instance that already has one, it names an account allowed
# to import chatflows, and the password attached to the owner_password slot is that account's.
# Required when values.flow_definition is set: the build halts when it is empty. It has no default.
spec.components.flowise.infra.owner_email: "owner@example.com"
# The origin of the secret value, written by the operator in the Release. Read exactly as
# values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes
# from, never the value.
spec.components.flowise.features.owner_password.infra.origin: "flowise-owner"
# The origin of the secret value, written by the operator in the Release. Read exactly as
# values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes
# from, never the value.
spec.components.flowise.uses.model.chatopenai-0.features.credential.infra.origin: "openai-api-key"

owner@example.com representa un correo electrónico tuyo. Sin el archivo, una importación en una terminal pide cada valor, una pregunta cada vez, redactada a partir de la descripción situada sobre su clave, y escribe tus respuestas en un nuevo archivo de respuestas; donde no se puede preguntar nada, escribe ese archivo con las claves y respuestas vacías, las enumera y termina con el estado 1. El archivo de respuestas de importación describe el archivo por completo.

La importación evalúa cada nodo frente a los Components del catálogo del espacio de trabajo, y --target genera un borrador de Manifest a partir de sus Recipes. El espacio de trabajo no indica ninguna carpeta de catálogo, así que la importación lee el catálogo de la biblioteca estándar desde el registro del que obtiene su importador: una instantánea firmada del catálogo publicado, que la primera importación obtiene, verifica y guarda en la caché de contenido del espacio de trabajo, y que el historial que la importación escribe junto a sus borradores nombra por su resumen criptográfico. Un espacio de trabajo que indica sus propias carpetas de catálogo — en AGGREGA_CATALOG_DIRS, o bajo workspace.catalog_dirs — importa en cambio a partir de ellas. Entra en source:

Terminal window
cd source

Ejecutar la importación

Terminal window
aggrega import support-chat.json --target compose

En la salida estándar enumera lo que escribió:

wrote aggregate.yaml
wrote release.yaml
wrote manifest.yaml
wrote .aggrega-import.json

En la salida de error estándar, donde <workspace> representa la carpeta en la que la ejecutaste:

[… omitted: a warning that the importer runs unverified, printed where its module is read from beside its Plugin entity in a catalog folder rather than fetched]
read as the flowise format, with drafted paths relative to <workspace>
warn: node chatOpenAI_0 reaches chatopenai-0 through the model connection chatopenai-0 of core/ai-agent/flowise: its Base Path is empty, so the OpenAI client Flowise runs it on reads the address the platform delivers for this connection, OPENAI_BASE_URL, and, since it selects no credential, the key delivered as OPENAI_API_KEY
info: the answers file <workspace>/import-answers.yaml also answers spec.components.flowise.features.owner_password.infra.origin in release.yaml, spec.components.flowise.uses.model.chatopenai-0.features.credential.infra.origin in release.yaml, which these drafts do not leave empty; those answers are kept there and not applied
mapped chatOpenAI_0 (chatOpenAI) to core/ai-model/openai as a reference, HIGH at 0.9
made no choice for bufferMemory_0 (bufferMemory)
made no choice for conversationChain_0 (conversationChain)
warning: node "flowise" (provider "compose"): artifact "flowise-flow/flowise-flow.yaml": skipped provenance label injection — the fragment declares no compose service. Compose carries build provenance as service labels, so a fragment contributing only top-level networks, volumes or configs carries none; the services this component emits elsewhere carry the full set.
Pull complete: <workspace>/release.lock (entities=8, source_artifacts=0, external_inputs=0)

La importación ejecutada desde el editor: el Aggregate, la Release y el Manifest en borrador aparecen junto a la exportación del chatflow, la salida de Aggrega enumera cómo se asignó cada nodo y los archivos escritos, y una notificación dice que la importación generó 3 archivos en borrador, reconocidos como flowise.

  • La línea mapped indica que el nodo ChatOpenAI se convirtió en el modelo de OpenAI de la biblioteca estándar, core/ai-model/openai, referenciado en lugar de generado como borrador, ya que coincidió en el nivel alto, con 0.9: un componente propio, conectado al socket model de la plataforma.
  • La línea warn indica cómo llega el chatflow a ese modelo: el nodo lee la dirección y la clave que la plataforma entrega para la conexión del modelo, de modo que la clave que la Release adjunta a la conexión es la que usa el chatflow.
  • La línea info trata del archivo de respuestas. Respondió el correo electrónico del propietario, que los borradores dejaban vacío; sus dos nombres de Secret responden a lo que solo una importación para Kubernetes deja vacío, así que permanecen en el archivo, sin usarse aquí.
  • Las líneas made no choice indican que la memoria y la cadena permanecen dentro del chatflow: ningún socket de la plataforma las acoge.
  • Las dos últimas líneas son el pull. Con todos los valores respondidos, la importación descargó las dependencias de la Release generada, como hace aggrega pull, y escribió release.lock; la compilación de abajo no necesita nada más. La línea warning es una que la compilación también imprime, y Validar y compilar la explica.

Lo que escribe

El Aggregate, la Release y el Manifest se llaman imported/support-chat, por el archivo, support-chat.json, ya que una exportación de Flowise no lleva nombre propio, bajo el namespace que fija el ajuste target_namespace del importador, imported salvo que fijes otro (Ajustes).

aggregate.yaml — una instancia de la plataforma Flowise de la biblioteca estándar, core/ai-agent/flowise, que lleva el chatflow tal como se exportó, aquí omitido en su mayor parte, y el modelo conectado a su socket model:

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/support-chat
version: 0.1.0
description: Draft Aggregate imported from a source in the flowise format.
spec:
components:
flowise:
type: core/ai-agent/flowise
features:
# For the compose target, the lines below declare owner_password on flowise: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
owner_password:
type: core/secret-value
values:
key: OWNER_PASSWORD
values:
# chatflow_id is derived from the exported flow, which gives no identifier of its own.
chatflow_id: '40d9f5c5-5187-54c1-a9f5-a8dac92f88bb'
flow_definition: |
{
"nodes": [
[… omitted: the chatflow's nodes, as exported, up to the Conversation Chain's inputs]
"inputs": {
"model": "{{"{{"}}chatOpenAI_0.data.instance}}",
"memory": "{{"{{"}}bufferMemory_0.data.instance}}",
[… omitted: the rest of the chatflow, as exported]
}
uses:
model:
chatopenai-0:
target: chatopenai-0
# For the compose target, the lines below declare credential on chatopenai-0: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
features:
credential:
type: core/secret-value
values:
key: OPENAI_API_KEY
# swap to core/ai-model/azure-openai (score 0.4000) by setting type: core/ai-model/azure-openai
chatopenai-0:
type: core/ai-model/openai
values:
model: |-
gpt-4o-mini
  • El modelo es core/ai-model/openai, con el modelo que selecciona el nodo, gpt-4o-mini. El comentario situado encima nombra otro Component del catálogo al que se parece el nodo, con su puntuación.
  • Los dos secretos —la contraseña de la cuenta de propietario con la que se precarga el chatflow y la clave de OpenAI que la plataforma presenta al modelo— se declaran aquí con la variable con la que cada uno llega al entorno de Flowise, OWNER_PASSWORD y OPENAI_API_KEY. En Docker Compose, un secreto que adjuntara solo la Release llegaría con la clave value, y los dos colisionarían; declarados aquí, cada uno tiene su propia clave. La Release indica de dónde viene cada uno.
  • chatflow_id se deriva del chatflow, ya que una exportación desde el editor de Flowise no lleva ningún identificador propio, de modo que un chatflow siempre produce el mismo identificador. Un chatflow de Flowise escribe {{<node id>.data.instance}} para cada conexión entre dos nodos, y el texto de un Aggregate se lee como plantilla, así que el borrador escribe cada {{ como {{"{{"}}, que la compilación vuelve a convertir en las dos llaves.

release.yaml — la Release, que despliega el Aggregate con el Manifest:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: imported/support-chat
# environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to.
environment: development
version: 0.1.0
description: Draft Release imported from a source in the flowise format.
spec:
aggregate: imported/support-chat
manifest: imported/support-chat
components:
flowise:
infra:
# The image running core/ai-agent/flowise, at the version this importer drafts, which the catalog's Recipes for it are known to run; the import does not raise or lower it to follow the source.
image: "flowiseai/flowise:3.1.3"
# Left for the Release, since the source cannot supply it: infra.owner_email, the email address of the platform's owner account, required while values.flow_definition is set
owner_email: "owner@example.com"
# Published on this machine's loopback address, 127.0.0.1: reachable from this machine only, by any process running on it. Delete this line to keep the service internal.
published_port: 3000
features:
owner_password:
type: core/secret-value
infra:
# Attached by reference, never as a value: the owner account's password, required while values.flow_definition is set, read from the variable FLOWISE_OWNER_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${FLOWISE_OWNER_PASSWORD}"
uses:
model:
chatopenai-0:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential flowise presents to chatopenai-0 on its model connection, read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${OPENAI_API_KEY}"
chatopenai-0: {}
  • environment es development, un valor predeterminado que el comentario de encima indica cambiar por el entorno en el que se despliega la Release.
  • La imagen es Flowise 3.1.3, la versión que ejecutan las Recipes del catálogo para Flowise.
  • published_port es 3000, el puerto en el que sirve Flowise, así que responde en http://127.0.0.1:3000 en tu máquina. Como dice su comentario, cualquier proceso de esta máquina puede llegar a él ahí y nada más puede; elimina la línea para mantener Flowise solo en la red del stack.
  • owner_email es la respuesta del archivo de respuestas. El comentario situado encima explica por qué la importación no pudo generarla.
  • Los dos secretos son referencias a variables, ${FLOWISE_OWNER_PASSWORD} y ${OPENAI_API_KEY}, que Docker Compose rellena desde tu shell cuando arranca el stack, de modo que ningún archivo contiene ninguno de los dos valores.

manifest.yaml — las Recipes de Compose de la plataforma y del modelo, y la realización que escribe tal cual la referencia a variable de un secreto en el archivo Compose:

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: imported/support-chat
version: 0.1.0
spec:
mappings:
components:
type:
core/ai-agent/flowise: compose/flowise
core/ai-model/openai: compose/openai
features:
type:
core/secret-value: compose/dotenv-secret

.aggrega-import.json es el registro de lo que escribió la importación, que lee un aggrega import --sync posterior, y release.lock fija cada entidad del catálogo a la que se resuelve la Release, por versión y digest.

Validar y compilar

Terminal window
aggrega validate --release release.yaml
aggrega build --release release.yaml

La Release en borrador abierta en el editor tras validarla, con la salida de Aggrega y una notificación que indican que no se encontraron problemas.

El build de la Release en borrador: aparece una carpeta dist en el Explorador, la salida de Aggrega enumera el archivo de Docker Compose escrito y una notificación indica que se escribió 1 archivo.

La validación imprime:

notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
release dependency validation passed: release.yaml (schema-pillar + dependency pillars)

y la compilación, donde <workspace> representa la carpeta que contiene los borradores:

warning: node "flowise" (provider "compose"): artifact "flowise-flow/flowise-flow.yaml": skipped provenance label injection — the fragment declares no compose service. Compose carries build provenance as service labels, so a fragment contributing only top-level networks, volumes or configs carries none; the services this component emits elsewhere carry the full set.
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[… omitted: a total build time, which differs per run]
Build completed: 1 file written to <workspace>/dist

La línea warning trata de la parte del archivo Compose que lleva el chatflow, una entrada configs de nivel superior, que no tiene ningún servicio en el que poner las etiquetas de la compilación. La línea notice es informativa: la Feature de secreto acepta su origin de los values del Aggregate o de la infra de la Release, y el aviso informa de que una hoja está declarada en ambos. Ninguna de las dos cambia el veredicto.

dist/compose/docker-compose.yaml contiene dos servicios. El propio Flowise:

flowise:
image: flowiseai/flowise:3.1.3
environment:
DATABASE_PATH: /home/node/.flowise
SECRETKEY_PATH: /home/node/.flowise
OPENAI_BASE_URL: https://api.openai.com/v1
OPENAI_API_KEY: ${OPENAI_API_KEY}
ports:
- 127.0.0.1:3000:3000
[… omitted: the labels the build writes on every service, naming the Aggregate, the component, the environment and the compiler's version]
volumes:
- type: volume
source: flowise--data
target: /home/node
networks:
- compose
[… omitted: the service's health check]

y el servicio que precarga el chatflow en cuanto Flowise informa de que está en buen estado, y luego termina:

flowise-flow-seed:
image: flowiseai/flowise:3.1.3
entrypoint:
- node
- /seed/seed.js
environment:
FLOWISE_URL: http://127.0.0.1:3000
OWNER_EMAIL: owner@example.com
OWNER_PASSWORD: ${FLOWISE_OWNER_PASSWORD}
CHATFLOW_ID: 40d9f5c5-5187-54c1-a9f5-a8dac92f88bb
CHATFLOW_NAME: 40d9f5c5-5187-54c1-a9f5-a8dac92f88bb
[… omitted: the labels the build writes on every service]
network_mode: service:flowise
depends_on:
flowise:
condition: service_healthy
restart: "no"
configs:
- source: flowise-flow
target: /seed/flow.json
- source: flowise-flow-seed
target: /seed/seed.js

Registra la cuenta de propietario en un Flowise recién creado, o inicia sesión con ella, y escribe el chatflow en chatflow_id. La clave y la contraseña son referencias de variables, que se rellenan desde tu shell cuando arranca el stack. La Recipe de Compose de Flowise publica un puerto en tu máquina solo donde la Release establece published_port en el infra de Flowise, y en ese caso solo en la dirección de loopback, 127.0.0.1; sin ello, el servicio solo es accesible en la red del stack.

Con un asistente de IA

Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pega en él este prompt.

Usa solo las herramientas de Aggrega y no crees ninguna carpeta por tu cuenta. Si la carpeta Workspace aún no contiene una carpeta `import-flowise`, llama una vez a la herramienta `scaffold` con `example` establecido en `import-flowise` y sin `dir`: escribe el ejemplo en una nueva carpeta `import-flowise`, cuya carpeta `source` contiene lo que esta página importa. Luego llama a la herramienta `import` con `workspace_root` establecido en `import-flowise/source`, `source` establecido en `support-chat.json` y `target` establecido en `compose`: lee las respuestas que necesita de `import-answers.yaml`, junto a `support-chat.json`, escribe sus borradores en `import-flowise/source` y descarga lo que necesitan. Luego llama a la herramienta `validate` con `workspace_root` establecido en `import-flowise/source` y `release` establecido en `release.yaml`, y a la herramienta `build` con `workspace_root` establecido en `import-flowise/source`, `release` establecido en `release.yaml` y `write` establecido en true. Dime qué archivos escribió el build; están en `import-flowise/source/dist/`.

Ábrelo en VS Code

Con la extensión de Aggrega para Visual Studio Code instalada, abre en VS Code la carpeta import-flowise/source, donde la importación escribió sus borradores. La carpeta contiene una sola Release, el release.yaml en borrador, así que el editor la selecciona por ti y comprueba los borradores con respecto a esa Release mientras los editas, marcando lo que encuentra en el archivo y en el panel Problemas. Aggrega: Show topology graph, en la paleta de comandos, dibuja los componentes de la Release y las conexiones entre ellos. Aggrega: Build, Aggrega: Preview build y Aggrega: Pull actúan sobre la misma Release, y cada uno es también un botón del panel Commands de la vista Aggrega en la barra de actividad; Build escribe sus archivos en el dist/ de la carpeta. Usar Aggrega en Visual Studio Code cubre el resto.

Ejecución

Establece la clave y la contraseña del propietario en tu shell, inicia Flowise y luego ejecuta el servicio de carga inicial:

Terminal window
export OPENAI_API_KEY='your OpenAI key'
export FLOWISE_OWNER_PASSWORD='a password of your own'
docker compose -p support-chat -f dist/compose/docker-compose.yaml up -d --wait flowise
docker compose -p support-chat -f dist/compose/docker-compose.yaml up flowise-flow-seed

-p da nombre al proyecto, como explica el paso de ejecución de Cómo se ejecuta una importación. --wait regresa en cuanto Flowise informa de que está sano; nombra solo flowise porque cuenta como un fallo cualquier contenedor que haya terminado, y el servicio de carga inicial termina por diseño. El segundo comando ejecuta el servicio de carga inicial, imprime su log y regresa cuando termina:

flowise-flow-seed-1 | registered the owner account owner@example.com
flowise-flow-seed-1 | imported chatflow 40d9f5c5-5187-54c1-a9f5-a8dac92f88bb as "40d9f5c5-5187-54c1-a9f5-a8dac92f88bb"
flowise-flow-seed-1 exited with code 0

Si otro programa de tu máquina ya escucha en 127.0.0.1:3000, el primer comando se detiene con failed to bind host port 127.0.0.1:3000/tcp: address already in use: establece published_port en un puerto libre y vuelve a hacer el build. La ejecución de abajo lo hizo, con 3002, y usó ese puerto en lugar de 3000.

Probarlo

Abre http://127.0.0.1:3000, la dirección que publica published_port, e inicia sesión con el correo electrónico y la contraseña del propietario: el chatflow de la carga inicial está en Flowise.

Un chatflow que no establece una clave de API propia responde en su endpoint de predicción sin ninguna. Hazle una pregunta:

Terminal window
curl -sS -X POST http://127.0.0.1:3000/api/v1/prediction/40d9f5c5-5187-54c1-a9f5-a8dac92f88bb \
-H 'Content-Type: application/json' -d '{"question": "In one short sentence: what is Docker Compose?"}'

La ejecución usó un marcador de posición para la clave de OpenAI, así que la respuesta es el rechazo de OpenAI, que muestra que el chatflow se ejecutó hasta su llamada al modelo:

{"statusCode":500,"success":false,"message":"401 Unauthorized – check your API key and ensure it has access to the requested model.","stack":{}}

Con tu clave, la respuesta lleva el resultado en text.

En Kubernetes, con el build que describe En Kubernetes aplicado y su Job de carga inicial completado, reenvía un puerto local al Service de Flowise, flowise-default, en el namespace al que aplicaste, y deja el comando en ejecución:

Terminal window
kubectl port-forward -n <namespace> svc/flowise-default 3000:3000

Desde otra terminal, la pregunta anterior llega al chatflow en la misma dirección, sin cambios; la ejecución obtuvo el mismo rechazo de la clave de marcador de posición.

Detén el stack con el comando siguiente. -v también elimina el volumen de datos de Flowise y, con él, la cuenta del propietario y el chatflow que escribió el servicio de carga inicial:

Terminal window
docker compose -p support-chat -f dist/compose/docker-compose.yaml down -v

En Kubernetes

El mismo chatflow se importa para Kubernetes con el destino helm. Los borradores para Docker Compose ya están en source, y la importación nunca sobrescribe un Aggregate allí, así que genera estos borradores en una carpeta propia con --output-dir y luego valida y haz el build desde ella:

Terminal window
aggrega import support-chat.json --target helm --output-dir helm
cd helm
aggrega validate --release release.yaml
aggrega build --release release.yaml

Los borradores difieren donde difiere el destino. El Manifest asigna la plataforma a helm/flowise, el modelo a helm/openai y cada secreto a helm/k8s-existing-secret, que lo lee de un Secret que ya está en el namespace. La Release adjunta la contraseña del propietario y la clave de OpenAI como core/referenced-secret, cada una nombrando su Secret, y toma las tres respuestas del archivo de respuestas: el correo electrónico del propietario, flowise-owner y openai-api-key.

La compilación escribe manifiestos de Kubernetes simples en dist/helm/, en la raíz del workspace, source, que desde helm es ../dist/helm/, entre ellos el seed del chatflow como un Job. Crea los dos Secrets en el namespace al que aplicas, cada uno con su valor bajo la clave de datos value, y luego aplica la carpeta como explica el paso de ejecución de Cómo se ejecuta una importación.