Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

Importar um chatflow do Flowise

Este passo a passo importa um chatflow exportado do Flowise — uma cadeia de conversa com um modelo de chat e uma memória — para um Aggregate, uma Release e um Manifest que fazem o build do Flowise com o chatflow para Docker Compose tal como estão escritos, depois faz o build deles e executa o resultado. Cada arquivo e cada bloco de saída abaixo vêm de uma execução real; o chatflow e cada etapa do passo a passo estão no exemplo import-flowise, onde um script de verificação executa a importação novamente, compara o que ela escreve, o que ela imprime e os blocos que esta página cita com os arquivos mantidos lá, e valida e faz o build do que a importação escreveu.

Gerar o exemplo

Você pode executar esta importação com os comandos desta página ou pedir ao seu assistente de IA que a execute para você.

Escreva o exemplo em uma nova pasta com o nome dele:

Terminal window
aggrega scaffold --example import-flowise

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova; o seguinte, abaixo, entra na pasta source da pasta nova, onde a importação é executada. Essa pasta contém o arquivo do chatflow, support-chat.json, que esta página descreve em vez de citar:

Terminal window
cd import-flowise

A pasta source do exemplo gerado aberta no Visual Studio Code, mostrando a exportação do chatflow do Flowise de um chat de suporte, aberta no nó ChatOpenAI.

O chatflow

support-chat.json, escrito para este passo a passo no formato em que o editor do Flowise exporta um chatflow, contém três nós e as duas arestas entre eles: um nó ChatOpenAI que seleciona gpt-4o-mini, um nó Buffer Memory e um nó Conversation Chain que recebe os dois e responde com uma mensagem de sistema curta. O nó ChatOpenAI não seleciona nenhuma credencial armazenada e deixa seu Base Path vazio, então o cliente OpenAI no qual o Flowise o executa lê seu endereço e sua chave do ambiente do Flowise.

Ao lado do chatflow, um .aggrega-config.yaml torna a pasta um espaço de trabalho:

# 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

e import-answers.yaml contém as respostas ao que nenhum chatflow pode conter. O Flowise não carrega nenhum chatflow de um arquivo na inicialização, então o build o insere pela própria API do Flowise, sob uma conta de proprietário, e nenhuma exportação nomeia essa conta: o e-mail dela é a única resposta de que uma importação para Docker Compose precisa. Uma importação para Kubernetes também precisa do nome do Secret do Kubernetes que guarda cada segredo — a senha do proprietário e a chave da OpenAI —, então o arquivo também nomeia esses dois Secrets (veja No 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 um e-mail seu. Sem o arquivo, uma importação em um terminal pede cada valor, uma pergunta de cada vez, redigida a partir da descrição acima da sua chave, e grava suas respostas em um novo arquivo de respostas; onde nada pode ser perguntado, ela grava esse arquivo com as chaves e respostas vazias, lista-as e sai com status 1. O arquivo de respostas da importação descreve o arquivo por completo.

A importação compara cada nó com os Components do catálogo do espaço de trabalho, e --target rascunha um Manifest a partir das Recipes desse catálogo. O espaço de trabalho não indica nenhuma pasta de catálogo, então a importação lê o catálogo da biblioteca padrão a partir do registro do qual obtém o seu importador: um snapshot assinado do catálogo publicado, que a primeira importação busca, verifica e guarda no cache de conteúdo do espaço de trabalho, e que o histórico que a importação escreve ao lado dos seus rascunhos indica pelo seu digest. Um espaço de trabalho que indica suas próprias pastas de catálogo — em AGGREGA_CATALOG_DIRS, ou em workspace.catalog_dirs — importa a partir delas em vez disso. Entre em source:

Terminal window
cd source

Executar a importação

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

Na saída padrão, ela lista o que gravou:

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

Na saída de erro padrão, com <workspace> representando a pasta em que você a executou:

[… 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)

A importação executada pelo editor: o Aggregate, a Release e o Manifest em rascunho aparecem ao lado da exportação do chatflow, a saída do Aggrega lista como cada nó foi mapeado e os arquivos escritos, e uma notificação diz que a importação gerou 3 arquivos em rascunho, reconhecidos como flowise.

  • A linha mapped diz que o nó ChatOpenAI se tornou o modelo OpenAI da biblioteca padrão, core/ai-model/openai, referenciado em vez de rascunhado, já que correspondeu na faixa alta, com 0,9: um componente próprio, ligado ao socket model da plataforma.
  • A linha warn diz como o chatflow alcança esse modelo: o nó lê o endereço e a chave que a plataforma entrega para a conexão do modelo, então a chave que a Release anexa à conexão é a que o chatflow usa.
  • A linha info trata do arquivo de respostas. Ele respondeu o e-mail do proprietário, que os rascunhos deixaram vazio; seus dois nomes de Secret respondem ao que só uma importação para Kubernetes deixa vazio, então permanecem no arquivo, sem uso aqui.
  • As linhas made no choice dizem que a memória e a cadeia ficam dentro do chatflow: nenhum socket da plataforma as recebe.
  • As duas últimas linhas são o pull. Com todos os valores respondidos, a importação baixou as dependências da Release rascunhada, como faz aggrega pull, e gravou release.lock; o build abaixo não precisa de mais nada. A linha warning é uma que o build também imprime, e Validar e fazer o build a explica.

O que a importação grava

O Aggregate, a Release e o Manifest se chamam imported/support-chat, a partir do arquivo, support-chat.json, já que uma exportação do Flowise não carrega nome próprio, sob o namespace definido pela configuração target_namespace do importador, imported, a menos que você defina outro (Configurações).

aggregate.yaml — uma instância da plataforma Flowise da biblioteca padrão, core/ai-agent/flowise, com o chatflow tal como foi exportado, a maior parte dele omitida aqui, e o modelo ligado ao seu 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
  • O modelo é core/ai-model/openai, com o modelo que o nó seleciona, gpt-4o-mini. O comentário acima dele nomeia outro Component do catálogo com que o nó se parece, com sua pontuação.
  • Os dois segredos — a senha da conta de proprietário sob a qual o chatflow é inserido e a chave da OpenAI que a plataforma apresenta ao modelo — são declarados aqui com a variável sob a qual cada um chega no ambiente do Flowise, OWNER_PASSWORD e OPENAI_API_KEY. No Docker Compose, um segredo anexado apenas pela Release chegaria sob a chave value, e os dois colidiriam; declarados aqui, cada um tem uma chave própria. A Release diz de onde cada um vem.
  • chatflow_id é derivado do chatflow, já que uma exportação do editor do Flowise não traz nenhum identificador próprio, de modo que um chatflow sempre produz o mesmo identificador. Um chatflow do Flowise escreve {{<node id>.data.instance}} para cada conexão entre dois nós, e o texto de um Aggregate é lido como um template, então o rascunho escreve cada {{ como {{"{{"}}, que o build converte de volta nas duas chaves.

release.yaml — a Release, que implanta o Aggregate com o 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 é development, um padrão que o comentário acima dele diz para trocar pelo ambiente em que a Release é implantada.
  • A imagem é o Flowise 3.1.3, a versão que as Recipes do catálogo para o Flowise executam.
  • published_port é 3000, a porta em que o Flowise atende, então ele responde em http://127.0.0.1:3000 na sua máquina. Como diz o comentário, qualquer processo nesta máquina pode alcançá-lo ali e nada mais pode; exclua a linha para manter o Flowise apenas na rede da stack.
  • owner_email é a resposta do arquivo de respostas. O comentário acima dele diz por que a importação não pôde rascunhá-lo.
  • Os dois segredos são referências a variáveis, ${FLOWISE_OWNER_PASSWORD} e ${OPENAI_API_KEY}, que o Docker Compose preenche a partir do seu shell quando a stack é iniciada, de modo que nenhum arquivo contém nenhum dos dois valores.

manifest.yaml — as Recipes de Compose da plataforma e do modelo, e a realização que escreve a referência de variável de um segredo no arquivo Compose tal como foi escrita:

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 é o registro do que a importação escreveu, que um aggrega import --sync posterior lê, e release.lock fixa cada entidade do catálogo para a qual a Release se resolve, por versão e digest.

Validar e compilar

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

A Release em rascunho aberta no editor depois de validada, com a saída do Aggrega e uma notificação informando que nenhum problema foi encontrado.

O build da Release em rascunho: uma pasta dist aparece no Explorer, a saída do Aggrega lista o arquivo do Docker Compose gravado, e uma notificação informa que 1 arquivo foi gravado.

A validação 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)

e o build, com <workspace> representando a pasta que contém os rascunhos:

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

A linha warning trata da parte do arquivo Compose que carrega o chatflow, uma entrada configs de nível superior, que não tem nenhum serviço onde colocar os rótulos do build. A linha notice é informativa: a Feature de segredo aceita seu origin dos values do Aggregate ou do infra da Release, e o aviso informa que uma folha está declarada em ambos. Nenhuma das duas altera o veredito.

dist/compose/docker-compose.yaml contém dois serviços. O próprio 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]

e o serviço que insere o chatflow assim que o Flowise reporta estar saudável e, em seguida, encerra:

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

Ele registra a conta de proprietário em um Flowise novo, ou entra com ela, e grava o chatflow em chatflow_id. A chave e a senha são referências de variável, preenchidas a partir do seu shell quando a stack é iniciada. A Recipe do Compose do Flowise publica uma porta na sua máquina apenas onde a Release define published_port no infra do Flowise, e nesse caso somente no endereço de loopback, 127.0.0.1; sem isso, o serviço só é acessível na rede da stack.

Com um assistente de IA

Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.

Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta Workspace ainda não contiver uma pasta `import-flowise`, chame uma vez a ferramenta `scaffold` com `example` definido como `import-flowise` e sem `dir`: ela grava o exemplo em uma nova pasta `import-flowise`, cuja pasta `source` contém o que esta página importa. Depois chame a ferramenta `import` com `workspace_root` definido como `import-flowise/source`, `source` definido como `support-chat.json` e `target` definido como `compose`: ela lê as respostas de que precisa em `import-answers.yaml`, ao lado de `support-chat.json`, grava seus rascunhos em `import-flowise/source` e faz o pull do que eles precisam. Depois chame a ferramenta `validate` com `workspace_root` definido como `import-flowise/source` e `release` definido como `release.yaml`, e a ferramenta `build` com `workspace_root` definido como `import-flowise/source`, `release` definido como `release.yaml` e `write` definido como true. Diga-me quais arquivos o build gravou; eles ficam em `import-flowise/source/dist/`.

Abra no VS Code

Com a extensão do Aggrega para o Visual Studio Code instalada, abra no VS Code a pasta import-flowise/source, onde a importação gravou seus rascunhos. A pasta contém uma única Release, o release.yaml em rascunho, então o editor a seleciona para você e verifica os rascunhos em relação a essa Release enquanto você os edita, marcando o que encontra no arquivo e no painel Problemas. Aggrega: Show topology graph, na Paleta de Comandos, desenha os componentes da Release e as conexões entre eles. Aggrega: Build, Aggrega: Preview build e Aggrega: Pull atuam sobre a mesma Release, e cada um também é um botão no painel Commands da visualização Aggrega na barra de atividades; Build grava seus arquivos no dist/ da pasta. Usar o Aggrega no Visual Studio Code cobre o restante.

Execução

Defina a chave e a senha do proprietário no seu shell, inicie o Flowise e depois execute o serviço 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 dá nome ao projeto, como explica a etapa de execução de Como uma importação é executada. --wait retorna assim que o Flowise reporta estar saudável; ele nomeia apenas flowise porque conta como falha qualquer contêiner que tenha encerrado, e o serviço de carga inicial encerra por design. O segundo comando executa o serviço de carga inicial, imprime seu log e retorna quando ele encerra:

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

Se outro programa na sua máquina já escuta em 127.0.0.1:3000, o primeiro comando para com failed to bind host port 127.0.0.1:3000/tcp: address already in use: defina published_port como uma porta livre e faça o build novamente. A execução abaixo fez isso, com 3002, e usou essa porta no lugar de 3000.

Teste

Abra http://127.0.0.1:3000, o endereço que published_port publica, e entre com o e-mail e a senha do proprietário: o chatflow da carga inicial está no Flowise.

Um chatflow que não define uma chave de API própria responde em seu endpoint de previsão sem nenhuma. Faça uma pergunta a ele:

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?"}'

A execução usou um placeholder para a chave da OpenAI, então a resposta é a recusa dela pela OpenAI, o que mostra que o chatflow foi executado até a chamada ao modelo:

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

Com a sua chave, a resposta traz o resultado em text.

No Kubernetes, com o build que No Kubernetes descreve aplicado e seu Job de carga inicial concluído, encaminhe uma porta local para o Service do Flowise, flowise-default, no namespace em que você aplicou, e deixe o comando em execução:

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

De outro terminal, a pergunta acima chega ao chatflow no mesmo endereço, sem alterações; a execução recebeu a mesma recusa da chave placeholder.

Pare a stack com o comando abaixo. -v também remove o volume de dados do Flowise e, com ele, a conta do proprietário e o chatflow que o serviço de carga inicial escreveu:

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

No Kubernetes

O mesmo chatflow é importado para o Kubernetes com o destino helm. Os rascunhos para o Docker Compose já estão em source, e a importação nunca sobrescreve um Aggregate ali, então gere estes rascunhos em uma pasta própria com --output-dir e depois valide e faça o build a partir dela:

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

Os rascunhos diferem onde o destino difere. O Manifest mapeia a plataforma para helm/flowise, o modelo para helm/openai e cada segredo para helm/k8s-existing-secret, que o lê de um Secret já existente no namespace. A Release anexa a senha do proprietário e a chave da OpenAI como core/referenced-secret, cada uma nomeando seu Secret, e obtém as três respostas do arquivo de respostas: o e-mail do proprietário, flowise-owner e openai-api-key.

O build escreve manifestos Kubernetes simples em dist/helm/ na raiz do workspace, source, que a partir de helm é ../dist/helm/, entre eles o seed do chatflow como um Job. Crie os dois Secrets no namespace ao qual você aplica, cada um contendo seu valor sob a chave de dados value, e então aplique a pasta como explica a etapa de execução de Como uma importação é executada.