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

Importar um chatflow do Flowise

Este guia 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 compilam o Flowise com o chatflow para Docker Compose tal como estão escritos, depois compila-os e executa o resultado. Cada ficheiro e cada bloco de saída abaixo provêm de uma execução real; o chatflow e cada etapa do guia estão no exemplo import-flowise, onde um script de verificação volta a executar a importação, compara o que ela escreve, o que ela imprime e os blocos que esta página cita com os ficheiros aí guardados, e valida e compila o que a importação escreveu.

Gerar o exemplo

É possível executar esta importação com os comandos desta página ou pedir ao seu assistente de IA que a execute.

Escreva o exemplo numa nova pasta com o nome dele:

Terminal window
aggrega scaffold --example import-flowise

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta; o seguinte, abaixo, entra na pasta source da nova pasta, onde a importação é executada. Essa pasta contém o ficheiro 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, a mostrar a exportação do chatflow do Flowise de um chat de suporte, aberta no seu nó ChatOpenAI.

O chatflow

support-chat.json, escrito para este guia 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 ambos e responde com uma mensagem de sistema curta. O nó ChatOpenAI não seleciona nenhuma credencial armazenada e deixa o seu Base Path vazio, pelo que o cliente OpenAI no qual o Flowise o executa lê o seu endereço e a sua chave do ambiente do Flowise.

Ao lado do chatflow, um .aggrega-config.yaml faz da 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 a partir de um ficheiro no arranque, pelo que a compilação o insere através da própria API do Flowise, sob uma conta de proprietário, e nenhuma exportação indica essa conta: o seu e-mail é a única resposta de que uma importação para Docker Compose precisa. Uma importação para Kubernetes precisa também do nome do Secret do Kubernetes que guarda cada segredo — a palavra-passe do proprietário e a chave da OpenAI —, pelo que o ficheiro indica também esses dois Secrets (consulte 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 próprio. Sem o ficheiro, uma importação num terminal pede cada valor, uma pergunta de cada vez, redigida a partir da descrição acima da respetiva chave, e escreve as respostas num novo ficheiro de respostas; onde nada pode ser perguntado, escreve esse ficheiro com as chaves e respostas vazias, lista-as e termina com o estado 1. O ficheiro de respostas da importação descreve o ficheiro 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, pelo que a importação lê o catálogo da biblioteca padrão a partir do registry de onde obtém o seu importador: um snapshot assinado do catálogo publicado, que a primeira importação obtém, verifica e guarda na cache de conteúdo do espaço de trabalho, e que o registo que a importação escreve junto aos seus rascunhos indica pelo seu digest. Um espaço de trabalho que indique as suas próprias pastas de catálogo — em AGGREGA_CATALOG_DIRS, ou em workspace.catalog_dirs — importa antes com base nessas pastas. 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, lista o que escreveu:

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

Na saída de erro padrão, com <workspace> a representar a pasta em que 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 a partir do 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 associado e os ficheiros escritos, e uma notificação indica que a importação gerou 3 ficheiros em rascunho, reconhecidos como flowise.

  • A linha mapped indica que o nó ChatOpenAI se tornou o modelo OpenAI da biblioteca-padrão, core/ai-model/openai, referenciado em vez de rascunhado, uma vez que correspondeu no escalão alto, com 0,9: um componente próprio, ligado ao socket model da plataforma.
  • A linha warn indica como o chatflow chega a esse modelo: o nó lê o endereço e a chave que a plataforma entrega para a ligação do modelo, pelo que a chave que a Release anexa à ligação é a que o chatflow utiliza.
  • A linha info diz respeito ao ficheiro de respostas. Este respondeu ao e-mail do proprietário, que os rascunhos deixaram vazio; os seus dois nomes de Secret respondem ao que só uma importação para Kubernetes deixa vazio, pelo que permanecem no ficheiro, sem utilização aqui.
  • As linhas made no choice indicam 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 obteve as dependências da Release rascunhada, como faz aggrega pull, e escreveu release.lock; a compilação abaixo não precisa de mais nada. A linha warning é uma que a compilação também imprime, e Validar e compilar explica-a.

O que a importação escreve

O Aggregate, a Release e o Manifest chamam-se imported/support-chat, a partir do ficheiro, support-chat.json, uma vez que uma exportação do Flowise não tem nome próprio, no namespace que a definição target_namespace do importador estabelece, imported, salvo se definir outro (Definiçõ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 indica outro Component do catálogo com que o nó se assemelha, com a respetiva pontuação.
  • Os dois segredos — a palavra-passe 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 ao 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 indica de onde vem cada um.
  • chatflow_id é derivado do chatflow, uma vez que uma exportação do editor do Flowise não traz nenhum identificador próprio, pelo que um chatflow produz sempre o mesmo identificador. Um chatflow do Flowise escreve {{<node id>.data.instance}} para cada ligação entre dois nós, e o texto de um Aggregate é lido como um template, pelo que o rascunho escreve cada {{ como {{"{{"}}, que a compilação converte de novo nas duas chavetas.

release.yaml — a Release, que implementa 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, uma predefinição que o comentário acima indica que se deve alterar para o ambiente em que a Release é implementada.
  • 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 serve, pelo que responde em http://127.0.0.1:3000 na sua máquina. Como diz o respetivo comentário, qualquer processo nesta máquina o pode alcançar aí e nada mais pode; elimine a linha para manter o Flowise apenas na rede da stack.
  • owner_email é a resposta do ficheiro de respostas. O comentário acima dele explica por que razão a importação não o pôde rascunhar.
  • Os dois segredos são referências a variáveis, ${FLOWISE_OWNER_PASSWORD} e ${OPENAI_API_KEY}, que o Docker Compose preenche a partir da sua shell quando a stack arranca, pelo que nenhum ficheiro contém qualquer um dos 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 ficheiro Compose tal como está 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 registo 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 a indicar que não foram encontrados problemas.

A compilação da Release em rascunho: aparece uma pasta dist no Explorador, a saída do Aggrega lista o ficheiro do Docker Compose escrito e uma notificação indica que foi escrito 1 ficheiro.

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 a compilação, com <workspace> a representar 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 diz respeito à parte do ficheiro Compose que transporta o chatflow, uma entrada configs de nível superior, que não tem nenhum serviço onde colocar as etiquetas da compilação. A linha notice é informativa: a Feature de segredo aceita o seu origin dos values do Aggregate ou do infra da Release, e o aviso indica que uma folha está declarada em ambos. Nenhuma das duas altera o veredicto.

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 indica estar saudável e depois 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

Regista a conta de proprietário num Flowise novo, ou inicia sessão com ela, e escreve o chatflow em chatflow_id. A chave e a palavra-passe são referências de variável, preenchidas a partir da sua shell quando a stack arranca. 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 apenas 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 nele este prompt.

Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por si. 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`: escreve o exemplo numa 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`: lê as respostas de que precisa de `import-answers.yaml`, ao lado de `support-chat.json`, escreve os seus rascunhos em `import-flowise/source` e obtém aquilo de que 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 que ficheiros a compilação escreveu; ficam em `import-flowise/source/dist/`.

Abrir 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 escreveu os seus rascunhos. A pasta contém uma única Release, o release.yaml em rascunho, pelo que o editor a seleciona automaticamente e verifica os rascunhos face a essa Release à medida que são editados, assinalando o que encontra no ficheiro e no painel Problemas. Aggrega: Show topology graph, na Paleta de Comandos, desenha os componentes da Release e as ligaçõ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 vista Aggrega na barra de atividades; Build escreve os seus ficheiros no dist/ da pasta. Utilizar o Aggrega no Visual Studio Code cobre o resto.

Execução

Defina a chave e a palavra-passe do proprietário na 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 o passo de execução de Como decorre uma importação. --wait regressa assim que o Flowise reporta estar saudável; indica apenas flowise porque conta como falha qualquer contentor que tenha terminado, e o serviço de carga inicial termina por conceção. O segundo comando executa o serviço de carga inicial, imprime o seu registo e regressa quando este 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

Se outro programa na sua máquina já estiver a escutar 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 volte a compilar. A execução abaixo fê-lo, com 3002, e usou essa porta no lugar de 3000.

Testar

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

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

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 marcador de posição para a chave da OpenAI, pelo que a resposta é a recusa da mesma pela OpenAI, o que mostra que o chatflow foi executado até à 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 a compilação que No Kubernetes descreve aplicada e o respetivo Job de carga inicial concluído, encaminhe uma porta local para o Service do Flowise, flowise-default, no namespace a que aplicou, e deixe o comando em execução:

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

Noutro terminal, a pergunta acima chega ao chatflow no mesmo endereço, sem alterações; a execução recebeu a mesma recusa da chave de marcador de posição.

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 importa-se para o Kubernetes com o destino helm. Os rascunhos para o Docker Compose já estão em source, e a importação nunca substitui um Aggregate aí presente, pelo que deve gerar estes rascunhos numa pasta própria com --output-dir e depois validar e compilar 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 palavra-passe do proprietário e a chave da OpenAI como core/referenced-secret, cada uma indicando o seu Secret, e obtém as três respostas do ficheiro de respostas: o e-mail do proprietário, flowise-owner e openai-api-key.

A compilação 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 a que aplica, cada um com o seu valor sob a chave de dados value, e depois aplique a pasta como explica o passo de execução de Como decorre uma importação.