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 aplicativo Dify

Este passo a passo importa um aplicativo exportado do Dify — um assistente de chat sobre um modelo da OpenAI — para um Aggregate, uma Release e um Manifest que, tal como estão escritos, compilam para Kubernetes a instalação do Dify da biblioteca padrão, que carrega o aplicativo; depois os compila e executa o resultado. Cada arquivo e cada bloco de saída abaixo vêm de uma execução real; o aplicativo e cada etapa do passo a passo estão no exemplo import-dify, onde um script de verificação executa a importação novamente, compara o que ela grava, o que ela imprime e os blocos que esta página cita com os arquivos mantidos ali, e valida e compila o que a importação gravou.

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-dify

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, que contém o que esta página importa e é onde a importação é executada:

Terminal window
cd import-dify

A pasta source do exemplo gerado aberta no Visual Studio Code, mostrando a exportação do aplicativo Dify de um assistente de suporte no modo chat.

O aplicativo

support-assistant.yml, escrito para este passo a passo, é um aplicativo de chat na DSL do Dify, o YAML que o Dify exporta para um aplicativo, na versão de DSL 0.7.0: uma mensagem de abertura, um prompt curto e o modelo com que ele responde, citado pelo seu provedor:

model:
completion_params:
stop: []
temperature: 0.4
mode: chat
name: gpt-4o-mini
provider: langgenius/openai/openai

Ao lado dele, 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-assistant.yml.
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 para o que nenhum aplicativo pode conter: o segredo de aplicativo da instalação, a chave com que o Dify assina as sessões e sob a qual criptografa as chaves dos provedores de modelos que armazena; e a conta proprietária sob a qual o aplicativo é importado, seu e-mail e sua senha. No Kubernetes, cada segredo é lido de um Secret do Kubernetes, então sua resposta é o nome desse Secret; o mesmo arquivo serve também a uma importação para Docker Compose, como mostra No Docker Compose:

# 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:
# Passed down to core/dify's secret_key parameter, which has no default; that parameter's description
# in core/dify says what the value is.
spec.parameters.secret_key: "dify-credentials"
# Email address of the installation's owner account, read only when values.app_definition is set. The
# step that imports the application creates this account when it performs Dify's first-time setup, and
# signs in as it; on an installation whose setup has already run, it names an existing account allowed
# to import applications, and the password attached to the owner_password slot is that account's.
# Required when values.app_definition is set: the build halts when it is empty. It has no default.
spec.boundaries.platform.aggregates.dify.components.api.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.boundaries.platform.aggregates.dify.components.api.features.owner_password.infra.origin: "dify-owner"

owner@example.com representa um e-mail seu; dify-credentials e dify-owner são os Secrets que Execute cria. Sem o arquivo, uma importação em um terminal pede cada um dos três valores, uma pergunta por vez, e grava suas respostas em um novo arquivo de respostas; onde nada pode ser perguntado, ela grava esse arquivo com as três chaves e respostas vazias, lista-as e sai com status 1. O arquivo de respostas da importação descreve o arquivo por completo.

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

A instalação do Dify da biblioteca padrão é realizada no Kubernetes e no Docker Compose. Este passo a passo cita o destino helm:

Terminal window
aggrega import support-assistant.yml --target helm

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 dify format, with drafted paths relative to <workspace>
warn: node model_config.model (model) names the model "gpt-4o-mini" of the model provider "langgenius/openai/openai", whose credentials are set inside Dify, and core/ai-agent/dify configures that for itself rather than reaching it through a socket, so the draft wires no part for it
made no choice for model_config.model (model)
Pull complete: <workspace>/release.lock (entities=25, 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 aplicativo, a saída do Aggrega lista o que o rascunho conecta e os arquivos escritos, e uma notificação diz que a importação gerou 3 arquivos em rascunho, reconhecidos como dify.

  • A linha warn diz que o modelo permanece dentro do Dify: o Dify configura seus provedores de modelo, e as chaves deles, por conta própria, então o rascunho não conecta nenhum modelo. Quando o Dify estiver em execução, você instala o provedor OpenAI dele e define a chave do provedor, como mostra Teste.
  • A linha Pull complete é o pull. Com cada valor respondido pelo arquivo de respostas, a importação fez o pull das dependências da Release rascunhada, como faz aggrega pull, e gravou release.lock; o build abaixo não precisa de mais nada.

O que a importação grava

O Aggregate, a Release e o Manifest se chamam imported/support-assistant, a partir do nome do aplicativo, Support assistant em app, reduzido a support-assistant — um aplicativo sem nome recebe o nome do seu arquivo — sob o namespace definido pela configuração target_namespace do importador, imported, a menos que você defina outro (Configurações).

aggregate.yaml — a instalação do Dify da biblioteca padrão, core/dify, um Aggregate que o rascunho compõe em aggregates, com o aplicativo levado tal como escrito em seu parâmetro app_definition, em grande parte omitido aqui, e o secret_key da instalação repassado a partir de um parâmetro que o rascunho declara:

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/support-assistant
version: 0.1.0
description: Draft Aggregate imported from a source in the dify format.
spec:
parameters:
secret_key:
type: string
required: true
minLength: 1
description: "Passed down to core/dify's secret_key parameter, which has no default; that parameter's description in core/dify says what the value is."
aggregates:
# An import sees the Components of the workspace's catalog and none of its Aggregates, so it does not check that the catalog holds core/dify.
dify:
type: core/dify
parameters:
secret_key: "{{ .parameters.secret_key }}"
app_definition: |
app:
description: Answers questions about the support plans of a small software company.
[… omitted: the rest of the application, as exported]
version: 0.7.0

A instalação tem dez componentes — o servidor de API do Dify, seu worker, seu agendador, seu front-end web, seu sandbox de código, seu runtime de plugins, um proxy de saída, PostgreSQL, um cache compatível com Redis e Weaviate —, ligados entre si, e a importação do aplicativo é uma etapa que a Recipe do servidor de API renderiza. O segredo do aplicativo não tem padrão em core/dify, então o rascunho declara secret_key como um parâmetro próprio, sem padrão, e o repassa para que a Release o preencha. As demais credenciais da instalação mantêm os padrões que core/dify lhes dá, como descreve Execute.

release.yaml — a Release, que roteia a instalação para uma fronteira, platform, e preenche, a partir do arquivo de respostas, o que o aplicativo não pode fornecer:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: imported/support-assistant
# 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 dify format.
spec:
aggregate: imported/support-assistant
manifest: imported/support-assistant
parameters:
# Left for the Release, since the source cannot supply it: secret_key, which the drafted Aggregate declares and passes down to core/dify; that parameter's description there says what the value is
secret_key: "dify-credentials"
boundaries:
platform:
aggregates:
dify:
components:
api:
infra:
# Lets the installation reach Dify's plugin marketplace, which the plugin serving the application's model, such as OpenAI's, is installed from.
marketplace_enabled: true
# Left for the Release, since the source cannot supply it: components.api.infra.owner_email, the email of the installation's owner account the application is imported under, on the api component of core/dify
owner_email: "owner@example.com"
features:
owner_password:
type: core/referenced-secret
infra:
# Left for the Release, since the source cannot supply it: the name of a Kubernetes Secret already in the namespace holding, under the data key value, the owner account's password.
origin: "dify-owner"
worker:
infra:
# Lets the installation reach Dify's plugin marketplace, which the plugin serving the application's model, such as OpenAI's, is installed from.
marketplace_enabled: true
scheduler:
infra:
# Lets the installation reach Dify's plugin marketplace, which the plugin serving the application's model, such as OpenAI's, is installed from.
marketplace_enabled: true
  • environment é development, um padrão que o comentário acima dele diz para trocar pelo ambiente em que a Release é implantada.
  • secret_key é o nome do Secret que contém o segredo do aplicativo, dify-credentials, sob a chave de dados que a instalação nomeia, secret-key: o Manifest lê cada credencial de um Secret que já existe no namespace.
  • A conta de proprietário é definida no componente api da instalação, na entrada de roteamento que coloca a instalação em sua fronteira: o e-mail dela e a senha dela, anexada como um core/referenced-secret que cita o Secret que a contém, dify-owner, sob a chave de dados value. Os comentários acima dos valores respondidos dizem por que a importação não pôde redigi-los.
  • marketplace_enabled é true no servidor da API, api, no seu worker e no seu agendador, em todos os destinos: a instalação não alcança nada do fornecedor do Dify a menos que a Release o permita, e o provedor da OpenAI com que a aplicação responde é um plugin que o Dify instala a partir do seu marketplace de plugins, como mostra Testar. Cada um dos três lê sua própria configuração.

manifest.yaml — uma Recipe Helm para cada componente que a instalação compõe, e a realização que lê uma credencial de um Secret que já existe no namespace:

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: imported/support-assistant
version: 0.1.0
spec:
mappings:
components:
type:
core/datastore/postgres: helm/postgres
core/datastore/redis: helm/redis
core/datastore/weaviate: helm/weaviate
core/ai-agent/dify-ssrf-proxy: helm/dify-ssrf-proxy
core/ai-agent/dify-sandbox: helm/dify-sandbox
core/ai-agent/dify-plugin-daemon: helm/dify-plugin-daemon
core/ai-agent/dify: helm/dify
core/ai-agent/dify-worker: helm/dify-worker
core/ai-agent/dify-worker-beat: helm/dify-worker-beat
core/ai-agent/dify-web: helm/dify-web
features:
type:
core/referenced-secret: helm/k8s-existing-secret

--target mapeia os tipos de componente da instalação que o rascunho compõe, além dos seus próprios. Quando o catálogo oferece várias Recipes Helm para um tipo, como faz para o PostgreSQL, ele mapeia aquela que leva o nome do tipo, helm/postgres.

.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, ambas, que nenhum problema foi encontrado.

O build da Release em rascunho: uma pasta dist aparece no Explorer, a saída do Aggrega lista os manifestos Kubernetes da instalação do Dify e uma notificação diz que 24 arquivos foram escritos.

A validação imprime:

notice: LINT: Feature "core/referenced-secret" at core/referenced-secret: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:

notice: LINT: Feature "core/referenced-secret" at core/referenced-secret: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: 24 files written to <workspace>/dist

A linha notice é apenas informativa: a Feature de segredo aceita seu origin dos values do Aggregate ou da infra da Release, e a notificação informa que uma folha está declarada em ambos. Ela não altera nenhum veredito.

O build grava os manifestos Kubernetes da instalação em dist/boundaries/platform/helm/. Entre eles está o Job que importa o aplicativo, dify.api/dify-app-import.job.yaml. Ele espera o servidor de API do Dify responder, executa a configuração inicial do Dify como a conta de proprietário que a Release cita, onde essa configuração ainda não foi executada, e importa o aplicativo:

spec:
podFailurePolicy:
rules:
- action: FailJob
onExitCodes:
containerName: import
operator: In
values: [2]
template:
spec:
restartPolicy: Never
containers:
- name: import
image: "langgenius/dify-api:1.17.0"
command: ["python", "/seed/import.py"]
env:
- name: DIFY_API_URL
value: "http://dify-zdapi-default:5001"
- name: OWNER_EMAIL
value: "owner@example.com"
- name: OWNER_PASSWORD
valueFrom:
secretKeyRef:
name: "dify-owner"
key: "value"
volumeMounts:
- name: seed
mountPath: /seed
readOnly: true
volumes:
- name: seed
configMap:
name: dify-zdapi-app

O aplicativo em si está no ConfigMap ao lado. Quando o Dify recusa o que a etapa lhe envia, com uma resposta de erro do cliente que não seja um tempo limite da solicitação nem um limite de taxa, ou informando que a importação falhou, a etapa imprime a mensagem que a resposta do Dify traz e sai com status 2, como faz quando a definição não nomeia nenhum aplicativo em app.name; a podFailurePolicy do Job faz o Job falhar nessa tentativa, já que uma nova tentativa seria recusada da mesma forma; qualquer outra falha, como o servidor não responder em cerca de dez minutos, é tentada novamente.

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 do Workspace ainda não contiver uma pasta `import-dify`, chame a ferramenta `scaffold` uma vez com `example` definido como `import-dify` e sem `dir`: ela escreve o exemplo em uma nova pasta `import-dify`, cuja pasta `source` contém o que esta página importa. Em seguida, chame a ferramenta `import` com `workspace_root` definido como `import-dify/source`, `source` definido como `support-assistant.yml` e `target` definido como `helm`: ela lê as respostas de que precisa em `import-answers.yaml`, ao lado de `support-assistant.yml`, escreve seus rascunhos em `import-dify/source` e baixa o que eles exigem. Em seguida, chame a ferramenta `validate` com `workspace_root` definido como `import-dify/source` e `release` definido como `release.yaml`, e a ferramenta `build` com `workspace_root` definido como `import-dify/source`, `release` definido como `release.yaml` e `write` definido como true. Diga-me quais arquivos o build escreveu; eles ficam em `import-dify/source/dist/`.

Abra no VS Code

Com a extensão do Aggrega para Visual Studio Code instalada, abra no VS Code a pasta import-dify/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ê; depois que No Docker Compose tiver rascunhado uma segunda Release em compose, Aggrega: Select Release… escolhe aquela com que o editor trabalha. O editor verifica os rascunhos em relação à Release selecionada 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 selecionada 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; o Build grava seus arquivos no dist/ da pasta. Usar o Aggrega no Visual Studio Code cobre o restante.

Execução

Antes de aplicar os manifestos, crie os Secrets que eles leem. Uma carga de trabalho que nomeia um Secret inexistente não inicia. Dois guardam o que o arquivo de respostas nomeou: dify-owner, que guarda a senha do proprietário sob value, e dify-credentials, que guarda o segredo da aplicação sob secret-key. As outras quatro credenciais da instalação — a senha do banco de dados e três chaves que seus componentes apresentam uns aos outros — mantêm os valores padrão que core/dify lhes dá, e no Kubernetes cada valor padrão é o nome do Secret do qual os manifestos o leem: dify-db-password-for-evaluation-only sob db-password, dify-code-execution-key-for-evaluation-only sob code-execution-key, dify-plugin-daemon-key-for-evaluation-only sob plugin-daemon-key e dify-inner-api-key-for-evaluation-only sob inner-api-key. Crie esses quatro também, cada um com um valor seu; para lê-los de Secrets com outros nomes, passe os nomes a core/dify na entrada dify do Aggregate, sob parameters, como db_password, code_execution_key, plugin_daemon_key e inner_api_key.

Defina a senha do proprietário no seu shell, como DIFY_OWNER_PASSWORD, já que você faz login com ela mais abaixo. O Dify aceita uma senha de proprietário de pelo menos oito caracteres contendo uma letra e um dígito: com qualquer outra, o Job de importação falha assim que o Dify recusa a configuração inicial, e o log dele diz first-time setup was refused with HTTP 422: Validation error for parameter 'payload', a resposta que o Dify dá a uma conta de proprietário que ele recusa. A espera abaixo aguarda a conclusão do Job, e um Job que falhou nunca é concluído, então ela vai até o tempo limite; execute kubectl wait --for=condition=failed job/dify-zdapi-app-import --timeout=15m em um segundo terminal ao lado, e essa espera retorna assim que o Job falha. Exclua o Job e o Secret dify-owner, crie o Secret de novo com uma senha que o Dify aceite e aplique novamente.

Escreva um arquivo para cada um dos outros cinco Secrets, com uma linha: a chave de dados, = e um valor seu — dify-credentials.env com secret-key=, db-password.env com db-password=, code-execution-key.env com code-execution-key=, plugin-daemon-key.env com plugin-daemon-key= e inner-api-key.env com inner-api-key=. Em seguida, crie os seis Secrets. A partir daí o cluster guarda os valores, então exclua os arquivos:

Terminal window
printf 'value=%s\n' "$DIFY_OWNER_PASSWORD" > dify-owner.env
kubectl create secret generic dify-owner --from-env-file=dify-owner.env
kubectl create secret generic dify-credentials --from-env-file=dify-credentials.env
kubectl create secret generic dify-db-password-for-evaluation-only --from-env-file=db-password.env
kubectl create secret generic dify-code-execution-key-for-evaluation-only --from-env-file=code-execution-key.env
kubectl create secret generic dify-plugin-daemon-key-for-evaluation-only --from-env-file=plugin-daemon-key.env
kubectl create secret generic dify-inner-api-key-for-evaluation-only --from-env-file=inner-api-key.env
rm dify-owner.env dify-credentials.env db-password.env code-execution-key.env plugin-daemon-key.env inner-api-key.env

Aplique os manifestos, como explica a etapa de execução de Como uma importação é executada — -R alcança o Job e os dois ConfigMaps em dify.api/ e dify.proxy/ — e depois aguarde o Job de importação e leia o log dele, e aguarde o runtime de plugins:

Terminal window
kubectl apply -R -f dist/boundaries/platform/helm/
kubectl wait --for=condition=complete job/dify-zdapi-app-import --timeout=15m
kubectl logs job/dify-zdapi-app-import
kubectl rollout status statefulset/dify-zdplugins
service/dify-zdapi-default created
deployment.apps/dify-zdapi created
[… omitted: a line for each of the other Services, Deployments and StatefulSets]
job.batch/dify-zdapi-app-import created
configmap/dify-zdapi-app created
configmap/dify-zdproxy-config created
job.batch/dify-zdapi-app-import condition met
first-time setup done: owner account owner@example.com
imported 'Support assistant' as application 7e03e85c-b13f-4ddc-b539-040470a61d4c
partitioned roll out complete: 1 new pods have been updated...

O log indica o identificador da aplicação, de que Teste precisa.

Teste

A API do Dify responde em http://127.0.0.1:5001. No Kubernetes, encaminhe uma porta local para o Service do servidor de API, dify-zdapi-default, no namespace em que você aplicou os manifestos, e deixe o comando em execução em um segundo terminal:

Terminal window
kubectl port-forward -n <namespace> svc/dify-zdapi-default 5001:5001

No Docker Compose, iniciado como mostra No Docker Compose, a Release já publica a API nesse endereço, e o console em http://127.0.0.1:3001. Abra http://127.0.0.1:3001/signin, a página de login do console; / redireciona para lá. A página envia suas requisições à API em http://127.0.0.1:5001, e a API do Dify só responde a um navegador para páginas servidas a partir do endereço que o console_url do rascunho indica, http://127.0.0.1:3001, então faça login ali como proprietário. Aberto em qualquer outro endereço, as requisições do console não recebem essa resposta e o navegador recusa cada resposta; publique o console em outra porta e altere console_url junto.

A aplicação também responde pela API, sem nenhum navegador envolvido. Em um terminal onde DIFY_OWNER_PASSWORD esteja definida, faça login como proprietário. A API de console recebe a senha codificada em Base64, e o login deixa a sessão em cookies.txt. Cada requisição posterior ao console envia a sessão de volta, com o token CSRF do mesmo arquivo em um cabeçalho X-CSRF-Token; uma requisição sem ele é recusada com CSRF token is missing or invalid.

Terminal window
printf '{"email": "owner@example.com", "password": "%s"}' "$(printf %s "$DIFY_OWNER_PASSWORD" | base64 | tr -d '\n')" |
curl -sS -c cookies.txt http://127.0.0.1:5001/console/api/login -H 'Content-Type: application/json' -d @-
CSRF=$(awk '$6 == "csrf_token" {print $7}' cookies.txt)
{"result":"success"}

Os provedores de modelo do Dify são plugins, e uma instalação nova não contém nenhum. Instale o provedor OpenAI do Dify, na versão 1.1.0, a que a execução instalou; o runtime de plugins o busca no marketplace do Dify, que o marketplace_enabled do rascunho permite à instalação alcançar, então a instalação precisa alcançar a internet:

Terminal window
curl -sS -b cookies.txt -H "X-CSRF-Token: $CSRF" -H 'Content-Type: application/json' \
http://127.0.0.1:5001/console/api/workspaces/current/plugin/install/marketplace \
-d '{"plugin_unique_identifiers": ["langgenius/openai:1.1.0@1ded02acee56efd5788c86fd447d792e4923e959554a4942f440c7859d164340"]}'
{"all_installed":false,"task_id":"01a1dc0a-653d-756b-a104-e5d6d1e43695","task":null}

Com marketplace_enabled removido da Release, o Dify recusa a requisição em vez disso, com {"code":"invalid_param","message":"marketplace is not enabled","status":400}. A instalação é executada em segundo plano. Consulte a tarefa dela, com o task_id que a resposta indica, até que o status dela seja success:

Terminal window
curl -sS -b cookies.txt -H "X-CSRF-Token: $CSRF" \
http://127.0.0.1:5001/console/api/workspaces/current/plugin/tasks/<task id>
{"task":{"id":"01a1dc0a-653d-756b-a104-e5d6d1e43695",[… omitted: when it was created and last updated],"status":"success","total_plugins":1,"completed_plugins":1,"plugins":[{"plugin_unique_identifier":"langgenius\/openai:1.1.0@1ded02acee56efd5788c86fd447d792e4923e959554a4942f440c7859d164340",[… omitted: the plugin's status, its icon and its names in four languages]}]}}

Escreva a chave do provedor em openai.json, como {"credentials": {"openai_api_key": "your OpenAI key"}}, defina-a e exclua o arquivo:

Terminal window
curl -sS -b cookies.txt -H "X-CSRF-Token: $CSRF" -H 'Content-Type: application/json' \
http://127.0.0.1:5001/console/api/workspaces/current/model-providers/langgenius/openai/openai/credentials \
-d @openai.json
rm openai.json

O Dify verifica a chave com uma requisição ao provedor antes de guardá-la, e responde {"result":"success"} para uma chave que o provedor aceita. A execução definiu um valor provisório, e o Dify o recusou com a resposta da OpenAI:

{"code":"invalid_param","message":"Error code: 401 - {'error': {'message': 'Incorrect API key provided: sk-place*****************-key. You can find your API key at https:\/\/platform.openai.com\/account\/api-keys.', 'type': 'invalid_request_error', 'code': 'invalid_api_key', 'param': None}, 'status': 401}","status":400}

Uma aplicação responde a requisições feitas com uma chave de API própria. Crie uma, com o identificador da aplicação do log da etapa que a importa — no Docker Compose, docker compose -p support-assistant -f ../dist/boundaries/platform/compose/docker-compose.yaml logs dify-zdapi-app-import:

Terminal window
curl -sS -X POST -b cookies.txt -H "X-CSRF-Token: $CSRF" \
http://127.0.0.1:5001/console/api/apps/<application id>/api-keys
{"id":"8d6c1eb1-cf61-4825-9b04-f32689ed0489","type":"app","token":"[… omitted: the key]","last_used_at":null,"created_at":1794693042}

e envie à aplicação uma mensagem com a chave, o token da resposta:

Terminal window
curl -sS http://127.0.0.1:5001/v1/chat-messages \
-H 'Authorization: Bearer <app key>' -H 'Content-Type: application/json' \
-d '{"inputs": {}, "query": "In one short sentence: what does a support plan cover?", "response_mode": "blocking", "user": "test-it"}'

Com o valor provisório recusado, o modelo não tem chave, e o Dify informa isso:

{"code":"provider_not_initialize","message":"Model gpt-4o-mini credentials is not initialized.","status":400}

As execuções no Kubernetes e no Docker Compose obtiveram as mesmas respostas. Com uma chave que o provedor aceite, a resposta traz a resposta do modelo em answer.

No Kubernetes, interrompa o encaminhamento de porta e depois remova o que você aplicou, os Secrets e o arquivo de sessão:

Terminal window
kubectl delete -R -f dist/boundaries/platform/helm/
kubectl delete secret dify-owner dify-credentials dify-db-password-for-evaluation-only dify-code-execution-key-for-evaluation-only dify-plugin-daemon-key-for-evaluation-only dify-inner-api-key-for-evaluation-only
kubectl delete pvc data-dify-zddb-0 storage-dify-zdplugins-0 data-dify-zdvector-0
rm cookies.txt

O Kubernetes mantém as reivindicações de volume que um StatefulSet criou quando o StatefulSet é excluído, então o terceiro comando as remove, e com elas o banco de dados, o plugin instalado e o armazenamento de vetores. No Docker Compose, docker compose -p support-assistant -f ../dist/boundaries/platform/compose/docker-compose.yaml down -v remove a stack e seus volumes.

No Docker Compose

A mesma aplicação é importada para Docker Compose com o destino compose, a partir do mesmo arquivo de respostas. Os rascunhos para Kubernetes já estão em source, então gere os de Compose em uma pasta própria com --output-dir; a importação lê do mesmo jeito o arquivo de respostas ao lado da aplicação:

Terminal window
aggrega import support-assistant.yml --target compose --output-dir compose

O Docker Compose não tem Secret para nomear, então, para compose, o próprio rascunho escreve o segredo da aplicação e a senha do proprietário, cada um como uma referência a variável que o Docker Compose preenche a partir do ambiente de quem inicia a stack. Ali só o e-mail do proprietário é exigido. A importação mantém os dois nomes de Secret no arquivo de respostas sem aplicá-los, e informa isso na saída de erro padrão:

info: the answers file <workspace>/import-answers.yaml also answers spec.boundaries.platform.aggregates.dify.components.api.features.owner_password.infra.origin in release.yaml, spec.parameters.secret_key in release.yaml, which these drafts do not leave empty; those answers are kept there and not applied

A Release em rascunho lê o segredo da aplicação de DIFY_SECRET_KEY e a senha do proprietário de DIFY_OWNER_PASSWORD, e publica a API na porta 5001 e o front-end, console, na 3001 do endereço de loopback:

parameters:
# Passed by reference, never as a value: secret_key, which the drafted Aggregate declares and passes down to core/dify; that parameter's description there says what the value is; it is read from the variable DIFY_SECRET_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.
secret_key: "${DIFY_SECRET_KEY}"
[… omitted: the boundary, the marketplace switch, and the owner's email, answered as above]
# 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: 5001
console_url: "http://127.0.0.1:3001"
features:
owner_password:
type: core/referenced-secret
infra:
# Attached by reference, never as a value: the owner account's password, read from the variable DIFY_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: "${DIFY_OWNER_PASSWORD}"
[… omitted: the worker and the scheduler, each with the marketplace switch, as above]
console:
infra:
# 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: 3001

Cada porta só é acessível a partir da sua máquina, como diz o comentário dela, e excluir uma linha mantém esse serviço apenas na rede da stack. O front-end escuta na 3000 dentro do contêiner e é publicado na 3001, então ele roda ao lado de outro exemplo que publique a 3000. O console_url do servidor da API é o endereço em que o front-end é publicado, então uma porta que você altera para o front-end é alterada lá também.

O Manifest mapeia cada componente para sua Recipe de Compose e core/referenced-secret para compose/dotenv-referenced-secret, que escreve cada referência no arquivo Compose tal como está. Valide e faça o build a partir da nova pasta:

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

O build escreve em dist na raiz do workspace, e o workspace continua sendo source, a pasta que contém .aggrega-config.yaml: o arquivo Compose é source/dist/boundaries/platform/compose/docker-compose.yaml, que a partir de compose é ../dist/boundaries/platform/compose/docker-compose.yaml, e nenhuma pasta dist é escrita dentro de compose. O arquivo contém SECRET_KEY: ${DIFY_SECRET_KEY} e OWNER_PASSWORD: ${DIFY_OWNER_PASSWORD} em vez de qualquer um dos valores. Defina as duas variáveis no seu shell, ou em um arquivo .env ao lado do arquivo Compose, antes de iniciar a stack.

As outras quatro credenciais da instalação mantêm os valores padrão que core/dify lhes dá, e no Docker Compose cada valor padrão é o próprio valor, escrito no arquivo Compose tal como está: DB_PASSWORD: dify-db-password-for-evaluation-only, com o mesmo POSTGRES_PASSWORD no banco de dados, e da mesma forma dify-code-execution-key-for-evaluation-only, dify-plugin-daemon-key-for-evaluation-only e dify-inner-api-key-for-evaluation-only. Qualquer leitor do catálogo conhece esses valores padrão, então eles servem apenas para avaliação. Para substituir um, declare um parâmetro de string para ele no Aggregate em rascunho, repasse-o nos parameters da entrada dify com o nome que core/dify dá a ele — db_password, code_execution_key, plugin_daemon_key ou inner_api_key —, assim como o rascunho repassa secret_key, e preencha-o nos parameters da Release. Uma Release que escreve db_password: "${DIFY_DB_PASSWORD}" gera um arquivo Compose contendo DB_PASSWORD: ${DIFY_DB_PASSWORD} e POSTGRES_PASSWORD: ${DIFY_DB_PASSWORD}, preenchidos a partir do ambiente como os dois acima.

Inicie a stack a partir de compose, com uma senha de proprietário que o Dify aceite, como descreve Execução:

Terminal window
export DIFY_SECRET_KEY='a long random value of your own'
export DIFY_OWNER_PASSWORD='a password of your own'
docker compose -p support-assistant -f ../dist/boundaries/platform/compose/docker-compose.yaml up -d --wait

Na execução, --wait retornou em cerca de um minuto, assim que todos os servidores se declararam saudáveis. A etapa que importa a aplicação roda ao lado deles e termina depois de fazê-lo; o log dela diz então:

first-time setup done: owner account owner@example.com
imported 'Support assistant' as application 7fae73f4-826b-4918-a623-a3383aa0da8c

Teste alcança a instalação nas duas portas publicadas.