跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

导入 Flowise 聊天流

本演练将一个从 Flowise 导出的聊天流——一条带有聊天模型和记忆的对话链——导入为一个 Aggregate、一个 Release 和一个 Manifest,它们按原样即可为 Docker Compose 构建承载该聊天流的 Flowise;随后构建它们并运行结果。下文的每个文件和每段输出都来自一次真实运行;聊天流和演练的每个阶段都位于 import-flowise 示例中,那里的检查脚本会再次运行导入,将它写入的内容、打印的内容以及本页引用的代码块与保存在那里的文件进行比较,并验证和构建导入所写出的内容。

生成示例

你可以使用本页的命令运行此导入,也可以让你的 AI 助手替你运行。

将示例写入一个以其命名的新文件夹:

Terminal window
aggrega scaffold --example import-flowise

然后它会打印接下来要运行的命令。第一条命令进入新文件夹;其后的一条命令见下文,它进入新文件夹的 source 文件夹,导入就在这里运行。该文件夹包含 chatflow 文件 support-chat.json,本页对其进行描述而不是引用:

Terminal window
cd import-flowise

在 Visual Studio Code 中打开的已生成示例的 source 文件夹,显示一个支持聊天的 Flowise chatflow 导出,定位在其 ChatOpenAI 节点上。

聊天流

support-chat.json 是为本演练编写的,采用 Flowise 编辑器导出聊天流的格式,包含三个节点及它们之间的两条边:一个选择 gpt-4o-mini 的 ChatOpenAI 节点、一个 Buffer Memory 节点,以及一个接收前两者并以简短系统消息作答的 Conversation Chain 节点。ChatOpenAI 节点未选择任何已存储的凭据,且其 Base Path 留空,因此 Flowise 运行它所用的 OpenAI 客户端会从 Flowise 的环境中读取其地址和密钥。

在聊天流旁边,一个 .aggrega-config.yaml 使该文件夹成为工作区:

# 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

而 import-answers.yaml 保存的是任何聊天流都无法承载的内容的答案。Flowise 启动时不会从文件加载聊天流,因此构建会通过 Flowise 自身的 API,以一个所有者账户预置聊天流,而任何导出都不会指明该账户:它的电子邮件地址是面向 Docker Compose 的导入唯一需要的答案。面向 Kubernetes 的导入还需要保存每个机密的 Kubernetes Secret 的名称(即所有者的密码和 OpenAI 密钥),因此该文件也指明了这两个 Secret(参见在 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 代表你自己的电子邮件地址。没有该文件时,在终端中运行的导入会逐个询问每个值,每次一个问题,问题依据其键上方的描述措辞,并将你的答案写入一个新的答案文件;在无法提问的情况下,它会写入该文件,其中包含各个键和空的答案,列出这些键,并以状态 1 退出。导入答案文件完整描述了该文件。

导入会将每个节点与工作区目录中的 Components 进行比对评估,而 --target 会根据该目录的 Recipes 起草一个 Manifest。工作区没有指定目录文件夹,因此导入会从获取其导入器的注册表中读取标准库目录:这是已发布目录的一个签名快照,由第一次导入获取、验证并保存在工作区的内容缓存中,并在导入写在其草稿旁的记录中以其摘要标明。指定了自己的目录文件夹的工作区——在 AGGREGA_CATALOG_DIRS 中,或在 workspace.catalog_dirs 下——则改为针对这些文件夹进行导入。进入 source:

Terminal window
cd source

运行导入

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

它在标准输出上列出所写的内容:

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

在标准错误上,其中 <workspace> 代表你运行它的文件夹:

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

从编辑器运行的导入:起草的 Aggregate、Release 和 Manifest 出现在 chatflow 导出文件旁边,Aggrega 输出列出了每个节点的映射方式和写入的文件,一条通知说明导入起草了 3 个文件,识别为 flowise。

  • mapped 行表示 ChatOpenAI 节点成为了标准库的 OpenAI 模型 core/ai-model/openai,以引用而非起草的方式出现,因为它以 0.9 的分数在高档位匹配:一个独立的组件,连接到平台的 model 插槽。
  • warn 行说明聊天流如何到达该模型:该节点读取平台为模型连接提供的地址和密钥,因此 Release 附加到该连接上的密钥就是聊天流所使用的密钥。
  • info 行与答案文件有关。该文件回答了所有者的电子邮件地址,这一项在草稿中留空;它的两个 Secret 名称回答的是只有面向 Kubernetes 的导入才会留空的内容,因此它们保留在文件中,在此处未被使用。
  • made no choice 行表示记忆和链保留在聊天流内部:平台没有任何插槽接收它们。
  • 最后两行是拉取。由于每个值都已回答,导入像 aggrega pull 那样拉取了所起草 Release 的依赖项,并写入了 release.lock;下面的构建无需其他任何东西。warning 行是构建同样会打印的一行,验证并构建对此作了解释。

它写出的内容

该 Aggregate、Release 和 Manifest 命名为 imported/support-chat,取自文件名 support-chat.json,因为 Flowise 导出的内容不带自己的名称,位于导入器的 target_namespace 设置所设定的命名空间下,除非你另行设置,否则该命名空间为 imported(设置)。

aggregate.yaml——标准库 Flowise 平台 core/ai-agent/flowise 的一个实例,按导出时的原样承载聊天流(此处省略了其大部分内容),以及连接到其 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
  • 该模型为 core/ai-model/openai,并带有节点所选的模型 gpt-4o-mini。其上方的注释指明了目录中与该节点相似的另一个 Component,并附有其分数。
  • 这两个机密(预置聊天流时所用所有者账户的密码,以及平台提供给模型的 OpenAI 密钥)在此处声明,并带有各自在 Flowise 环境中到达时所用的变量:OWNER_PASSWORD 和 OPENAI_API_KEY。在 Docker Compose 上,仅由 Release 附加的机密会以键 value 到达,两者就会冲突;在此处声明后,每个机密都有自己的键。Release 说明每个机密的来源。
  • chatflow_id 由聊天流推导而来,因为从 Flowise 编辑器导出的内容不带有自身的标识符,因此同一个聊天流始终产生同一个标识符。Flowise 聊天流会为两个节点之间的每个连接写入 {{<node id>.data.instance}},而 Aggregate 的文本会被当作模板读取,因此草稿将每个 {{ 写成 {{"{{"}},构建时会将其还原为两个花括号。

release.yaml——该 Release,它使用该 Manifest 部署该 Aggregate:

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,这是一个默认值,其上方的注释说明应将其改为该 Release 所部署到的环境。
  • 镜像为 Flowise 3.1.3,即目录中面向 Flowise 的 Recipes 所运行的版本。
  • published_port 为 3000,即 Flowise 提供服务的端口,因此它在你的机器上通过 http://127.0.0.1:3000 响应。如注释所述,这台机器上的任何进程都可以在那里访问它,其他任何东西都不能;删除该行即可让 Flowise 只留在栈的网络中。
  • owner_email 是来自答案文件的答案。其上方的注释说明了导入为何无法起草它。
  • 这两个机密是变量引用 ${FLOWISE_OWNER_PASSWORD} 和 ${OPENAI_API_KEY},Docker Compose 会在栈启动时从你的 shell 中填入它们,因此任何文件都不携带其中任何一个值。

manifest.yaml——平台和模型的 Compose Recipes,以及将机密的变量引用原样写入 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 记录了导入所写入的内容,供之后的 aggrega import --sync 读取;release.lock 按版本和摘要锁定该 Release 所解析到的每个目录实体。

验证并构建

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

验证后在编辑器中打开的草拟 Release,Aggrega 输出和一条通知都报告未发现问题。

草拟 Release 的构建:资源管理器中出现一个 dist 文件夹,Aggrega 输出列出了写入的 Docker Compose 文件,一条通知说明已写入 1 个文件。

验证打印:

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)

以及构建,其中 <workspace> 代表包含草稿的文件夹:

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

warning 行涉及 Compose 文件中承载聊天流的部分,即一个顶层 configs 条目,它没有可供放置构建标签的服务。notice 行仅供参考:机密 Feature 从 Aggregate 的 values 或 Release 的 infra 接收其 origin,该通知报告有一个叶子节点在两处都有声明。两者都不会改变判定结果。

dist/compose/docker-compose.yaml 包含两个服务。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]

以及在 Flowise 报告健康后预置聊天流、随后退出的服务:

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

它会在全新的 Flowise 上注册所有者账户,或以该账户登录,然后将聊天流写入 chatflow_id 处。密钥和密码都是变量引用,在栈启动时从你的 shell 中填入。只有当 Release 在 Flowise 的 infra 中设置了 published_port 时,Flowise 的 Compose Recipe 才会在你的机器上发布端口,并且只发布在环回地址 127.0.0.1 上;没有该设置时,只能在栈的网络上访问该服务。

借助 AI 助手

配置了 Aggrega 工具的 AI 助手也可以完成同样的操作:将下面的提示词粘贴给它。

只使用 Aggrega 工具,不要自己创建任何文件夹。如果 Workspace 文件夹中还没有 `import-flowise` 文件夹,请调用一次 `scaffold` 工具,将 `example` 设置为 `import-flowise`,且不设置 `dir`:它会将示例写入一个新的 `import-flowise` 文件夹,其中的 `source` 文件夹包含本页导入的内容。然后调用 `import` 工具,将 `workspace_root` 设置为 `import-flowise/source`,`source` 设置为 `support-chat.json`,`target` 设置为 `compose`:它会从 `support-chat.json` 旁边的 `import-answers.yaml` 中读取所需的答案,将草稿写入 `import-flowise/source`,并拉取草稿所需的内容。然后调用 `validate` 工具,将 `workspace_root` 设置为 `import-flowise/source`,`release` 设置为 `release.yaml`;再调用 `build` 工具,将 `workspace_root` 设置为 `import-flowise/source`,`release` 设置为 `release.yaml`,`write` 设置为 true。告诉我构建写入了哪些文件;它们位于 `import-flowise/source/dist/` 下。

在 VS Code 中打开

安装 适用于 Visual Studio Code 的 Aggrega 扩展 后,在 VS Code 中打开导入写入草稿的文件夹 import-flowise/source。该文件夹只包含一个 Release,即草拟的 release.yaml,因此编辑器会为你选中它,并在你编辑草稿时根据该 Release 检查草稿,将发现的问题标记在文件中和“问题”面板中。命令面板中的 Aggrega: Show topology graph 会绘制该 Release 的组件及其之间的连接。Aggrega: Build、Aggrega: Preview build 和 Aggrega: Pull 作用于同一个 Release,并且每个命令也是活动栏中 Aggrega 视图的 Commands 面板上的一个按钮;Build 会将文件写入该文件夹的 dist/。在 Visual Studio Code 中使用 Aggrega 介绍了其余内容。

运行

在你的 shell 中设置密钥和所有者的密码,启动 Flowise,然后运行初始化服务:

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 为项目命名,正如 导入如何运行 中的运行步骤所解释的。--wait 会在 Flowise 报告健康后返回;它只指定 flowise,因为它会把任何已退出的容器都算作失败,而初始化服务按设计会退出。第二条命令运行初始化服务,打印其日志,并在其退出时返回:

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

如果你机器上的另一个程序已在监听 127.0.0.1:3000,第一条命令会以 failed to bind host port 127.0.0.1:3000/tcp: address already in use 停止:将 published_port 设置为一个空闲端口,然后重新构建。下面的运行就是这样做的,使用了 3002,并用该端口代替了 3000。

测试

打开 http://127.0.0.1:3000,即 published_port 发布的地址,并使用所有者的电子邮件和密码登录:初始化服务写入的聊天流已在 Flowise 中。

没有设置自身 API 密钥的聊天流,其预测端点无需密钥即可响应。向它提一个问题:

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

本次运行为 OpenAI 密钥使用了占位符,因此得到的回答是 OpenAI 对该密钥的拒绝,这表明聊天流一直运行到了对模型的调用:

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

使用你自己的密钥时,回复会在 text 中携带答案。

在 Kubernetes 上,应用 在 Kubernetes 上 所述的构建并等其初始化 Job 完成后,在你应用到的命名空间中将一个本地端口转发到 Flowise 的 Service flowise-default,并让该命令保持运行:

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

从另一个终端发出上面的问题,会原样在同一地址到达聊天流;本次运行得到了对占位符密钥的同样拒绝。

使用下面的命令停止该栈。-v 还会删除 Flowise 的数据卷,连同初始化服务写入的所有者账户和 chatflow 一起删除:

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

在 Kubernetes 上

同一个聊天流可以使用 helm 目标为 Kubernetes 导入。Docker Compose 的草稿已经位于 source 中,而导入绝不会覆盖那里的 Aggregate,因此请使用 --output-dir 将这些草稿写入单独的文件夹,然后从该文件夹进行验证和构建:

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

草稿在目标不同之处有所不同。Manifest 将平台映射到 helm/flowise,将模型映射到 helm/openai,并将每个密钥映射到 helm/k8s-existing-secret,后者从命名空间中已有的 Secret 读取该密钥。Release 将所有者的密码和 OpenAI 密钥作为 core/referenced-secret 附加,每个都指明其 Secret,并从答案文件中获取全部三个答案:所有者的电子邮件、flowise-owner 和 openai-api-key。

构建会在工作区根目录 source 的 dist/helm/ 下写出普通的 Kubernetes 清单(从 helm 来看即 ../dist/helm/),其中包括作为 Job 的 chatflow 种子。在你要应用到的命名空间中创建这两个 Secret,每个都在数据键 value 下保存其值,然后按照 导入如何运行 的运行步骤所述应用该文件夹。