Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Importare un’applicazione Dify

Questa guida passo passo importa un’applicazione esportata da Dify — un assistente di chat basato su un modello OpenAI — in un Aggregate, una Release e un Manifest che, così come sono scritti, eseguono la build per Kubernetes dell’installazione Dify della libreria standard, che contiene l’applicazione; poi ne esegue la build ed esegue il risultato. Ogni file e ogni blocco di output riportati di seguito provengono da un’esecuzione reale; l’applicazione e ogni fase della guida si trovano nell’esempio import-dify, dove uno script di controllo esegue di nuovo l’importazione, confronta ciò che scrive, ciò che stampa e i blocchi citati in questa pagina con i file conservati lì, e convalida ed esegue la build di ciò che l’importazione ha scritto.

Generare l’esempio

Puoi eseguire questa importazione con i comandi di questa pagina, oppure farla eseguire al tuo assistente AI.

Scrivi l’esempio in una nuova cartella che porta il suo nome:

Terminal window
aggrega scaffold --example import-dify

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella; quello successivo, qui sotto, ti porta nella cartella source della nuova cartella, che contiene ciò che questa pagina importa ed è dove viene eseguita l’importazione:

Terminal window
cd import-dify

La cartella source dell’esempio generato aperta in Visual Studio Code, con l’esportazione dell’app Dify di un assistente di supporto in modalità chat.

L’applicazione

support-assistant.yml, scritto per questa guida, è un’applicazione di chat nel DSL di Dify, lo YAML che Dify esporta per un’applicazione, alla versione DSL 0.7.0: un messaggio di apertura, un breve prompt e il modello con cui risponde, indicato tramite il suo fornitore:

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

Accanto a esso, un file .aggrega-config.yaml rende la cartella un’area di lavoro:

# 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 contiene le risposte a ciò che nessuna applicazione può contenere: il segreto applicativo dell’installazione, la chiave con cui Dify firma le sessioni e con cui cifra le chiavi dei provider di modelli che memorizza; e l’account proprietario con cui l’applicazione viene importata, con la sua email e la sua password. Su Kubernetes ogni segreto viene letto da un Secret di Kubernetes, quindi la sua risposta è il nome di quel Secret; lo stesso file serve anche a un’importazione per Docker Compose, come mostra Su 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 sta per un tuo indirizzo email; dify-credentials e dify-owner sono i Secret creati in Eseguilo. Senza il file, un’importazione in un terminale chiede ciascuno dei tre valori, una domanda alla volta, e scrive le tue risposte in un nuovo file di risposte; dove non è possibile chiedere nulla, scrive quel file con le tre chiavi e risposte vuote, le elenca ed esce con stato 1. Il file delle risposte dell’importazione descrive il file per intero.

Lo spazio di lavoro non indica alcuna cartella di catalogo, quindi l’importazione legge il catalogo della libreria standard dal registry da cui recupera il proprio importer: uno snapshot firmato del catalogo pubblicato, che la prima importazione recupera, verifica e conserva nella cache dei contenuti dello spazio di lavoro, e che il record scritto dall’importazione accanto alle sue bozze indica tramite il suo digest. Uno spazio di lavoro che indica le proprie cartelle di catalogo — in AGGREGA_CATALOG_DIRS, oppure sotto workspace.catalog_dirs — importa invece rispetto a quelle. Entra in source:

Terminal window
cd source

Eseguire l’importazione

L’installazione Dify della libreria standard è realizzata su Kubernetes e su Docker Compose. Questa guida indica il target helm:

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

Sullo standard output elenca ciò che ha scritto:

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

Sullo standard error, dove <workspace> sta per la cartella in cui l’hai eseguita:

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

L’importazione eseguita dall’editor: l’Aggregate, la Release e il Manifest in bozza compaiono accanto all’esportazione dell’app, l’output di Aggrega elenca ciò che la bozza collega e i file scritti, e una notifica dice che l’importazione ha prodotto 3 file in bozza, riconosciuti come dify.

  • La riga warn dice che il modello resta dentro Dify: Dify configura da sé i propri fornitori di modelli e le relative chiavi, quindi la bozza non collega alcun modello. Una volta avviato Dify, installi il suo fornitore OpenAI e imposti la chiave del fornitore, come mostra Verifica.
  • La riga Pull complete è il pull. Con ogni valore risposto dal file delle risposte, l’importazione ha eseguito il pull delle dipendenze della Release abbozzata, come fa aggrega pull, e ha scritto release.lock; la build seguente non richiede altro.

Cosa scrive

L’Aggregate, la Release e il Manifest si chiamano imported/support-assistant, dal nome dell’applicazione, Support assistant sotto app, ridotto a support-assistant — un’applicazione senza nome prende il nome dal suo file — nel namespace definito dall’impostazione target_namespace dell’importatore, imported a meno che tu non ne imposti un altro (Impostazioni).

aggregate.yaml — l’installazione Dify della libreria standard, core/dify, un Aggregate che la bozza compone sotto aggregates, con l’applicazione riportata così com’è scritta nel suo parametro app_definition, qui in gran parte omessa, e il secret_key dell’installazione passato da un parametro che la bozza dichiara:

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

L’installazione è composta da dieci componenti — il server API di Dify, il suo worker, lo scheduler, il front end web, la sandbox per il codice, il runtime dei plugin, un proxy di uscita, PostgreSQL, una cache compatibile con Redis e Weaviate — collegati tra loro, e l’importazione dell’applicazione è un passaggio generato dalla Recipe del suo server API. Il segreto dell’applicazione non ha un valore predefinito in core/dify, perciò la bozza dichiara secret_key come parametro proprio, senza valore predefinito, e lo passa affinché la Release lo soddisfi. Le altre credenziali dell’installazione mantengono i valori predefiniti che core/dify assegna loro, come descrive Eseguilo.

release.yaml — la Release, che instrada l’installazione in un confine, platform, e soddisfa a partire dal file delle risposte ciò che l’applicazione non può fornire:

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, un valore predefinito che il commento sopra di esso indica di cambiare con l’ambiente in cui la Release viene distribuita.
  • secret_key è il nome del Secret che contiene il segreto dell’applicazione, dify-credentials, sotto la chiave dati indicata dall’installazione, secret-key: il Manifest legge ogni credenziale da un Secret già presente nel namespace.
  • L’account proprietario è impostato sul componente api dell’installazione, nella voce di instradamento che colloca l’installazione nel suo confine: la sua email, e la sua password allegata come core/referenced-secret che nomina il Secret che la contiene, dify-owner, sotto la chiave dati value. I commenti sopra i valori forniti spiegano perché l’importazione non ha potuto redigerli.
  • marketplace_enabled è true sul server API, api, sul suo worker e sul suo scheduler, per ogni target: l’installazione non raggiunge nulla del fornitore di Dify a meno che la Release non lo consenta, e il provider OpenAI con cui risponde l’applicazione è un plugin che Dify installa dal suo marketplace di plugin, come mostra Provarlo. Ciascuno dei tre legge la propria impostazione.

manifest.yaml — una Recipe Helm per ogni componente che l’installazione compone, e la realizzazione che legge una credenziale da un Secret già presente nel 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 mappa i tipi di componente dell’installazione che la bozza compone, oltre ai propri. Dove il catalogo offre più Recipes Helm per un tipo, come accade per PostgreSQL, mappa quella che prende il nome dal tipo, helm/postgres.

.aggrega-import.json è il registro di ciò che l’importazione ha scritto, che un successivo aggrega import --sync legge, e release.lock fissa ogni entità del catalogo a cui la Release si risolve, per versione e digest.

Convalidare e compilare

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

La Release in bozza aperta nell’editor dopo la validazione, con l’output di Aggrega e una notifica che riportano entrambi che non sono stati trovati problemi.

La build della Release in bozza: nell’Explorer compare una cartella dist, l’output di Aggrega elenca i manifest Kubernetes dell’installazione di Dify e una notifica dice che sono stati scritti 24 file.

La convalida stampa:

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 la build, dove <workspace> sta per la cartella che contiene le bozze:

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

La riga notice è informativa: la Feature del segreto accetta il suo origin dai values dell’Aggregate o dall’infra della Release, e l’avviso segnala che una foglia è dichiarata in entrambi. Non cambia alcun verdetto.

La build scrive i manifest Kubernetes dell’installazione in dist/boundaries/platform/helm/. Tra questi c’è il Job che importa l’applicazione, dify.api/dify-app-import.job.yaml. Attende che il server API di Dify risponda, esegue la configurazione iniziale di Dify come l’account proprietario indicato dalla Release, dove tale configurazione non è stata eseguita, e importa l’applicazione:

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

L’applicazione stessa si trova nella ConfigMap accanto. Quando Dify rifiuta ciò che il passaggio gli invia, con una risposta di errore del client diversa da un timeout della richiesta o da un limite di frequenza, oppure segnalando che l’importazione è fallita, il passaggio stampa il messaggio contenuto nella risposta di Dify ed esce con stato 2, come fa quando la definizione non indica alcuna applicazione sotto app.name; il podFailurePolicy del Job fa fallire il Job a quel tentativo, poiché un nuovo tentativo verrebbe rifiutato allo stesso modo; qualsiasi altro errore, come il server che non risponde entro circa dieci minuti, viene ritentato.

Con un assistente AI

Un assistente AI configurato con gli strumenti di Aggrega può fare lo stesso: incollaci questo prompt.

Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Se la cartella del Workspace non contiene ancora una cartella `import-dify`, chiama una volta lo strumento `scaffold` con `example` impostato a `import-dify` e senza `dir`: scrive l’esempio in una nuova cartella `import-dify`, la cui cartella `source` contiene ciò che questa pagina importa. Poi chiama lo strumento `import` con `workspace_root` impostato a `import-dify/source`, `source` impostato a `support-assistant.yml` e `target` impostato a `helm`: legge le risposte che gli servono da `import-answers.yaml` accanto a `support-assistant.yml`, scrive le sue bozze in `import-dify/source` e scarica ciò di cui hanno bisogno. Poi chiama lo strumento `validate` con `workspace_root` impostato a `import-dify/source` e `release` impostato a `release.yaml`, e lo strumento `build` con `workspace_root` impostato a `import-dify/source`, `release` impostato a `release.yaml` e `write` impostato a true. Dimmi quali file ha scritto la build; si trovano in `import-dify/source/dist/`.

Aprilo in VS Code

Con l’estensione Aggrega per Visual Studio Code installata, apri in VS Code la cartella import-dify/source, dove l’importazione ha scritto le sue bozze. La cartella contiene una sola Release, il release.yaml in bozza, quindi l’editor la seleziona per te; quando Su Docker Compose avrà redatto una seconda Release in compose, Aggrega: Select Release… sceglie quella su cui lavora l’editor. L’editor controlla le bozze rispetto alla Release selezionata mentre le modifichi, segnalando ciò che trova nel file e nel pannello Problemi. Aggrega: Show topology graph, nel riquadro comandi, disegna i componenti della Release selezionata e le connessioni tra di essi. Aggrega: Build, Aggrega: Preview build e Aggrega: Pull agiscono sulla stessa Release, e ciascuno è anche un pulsante nel pannello Commands della vista Aggrega nella barra delle attività; Build scrive i suoi file in dist/ all’interno della cartella. Usare Aggrega in Visual Studio Code tratta il resto.

Esecuzione

Prima di applicare i manifest, crea i Secret che leggono. Un carico di lavoro che nomina un Secret inesistente non si avvia. Due contengono ciò che il file delle risposte ha indicato: dify-owner, che contiene la password del proprietario sotto value, e dify-credentials, che contiene il segreto dell’applicazione sotto secret-key. Le altre quattro credenziali dell’installazione — la password del database e tre chiavi che i suoi componenti si presentano a vicenda — mantengono i valori predefiniti che core/dify assegna loro, e su Kubernetes ogni valore predefinito è il nome del Secret da cui i manifest lo leggono: dify-db-password-for-evaluation-only sotto db-password, dify-code-execution-key-for-evaluation-only sotto code-execution-key, dify-plugin-daemon-key-for-evaluation-only sotto plugin-daemon-key e dify-inner-api-key-for-evaluation-only sotto inner-api-key. Crea anche questi quattro, ciascuno con un valore tuo; per leggerli da Secret con nomi diversi, passa i nomi a core/dify nella voce dify dell’Aggregate, sotto parameters, come db_password, code_execution_key, plugin_daemon_key e inner_api_key.

Imposta la password del proprietario nella tua shell, come DIFY_OWNER_PASSWORD, perché più sotto la usi per accedere. Dify accetta una password del proprietario di almeno otto caratteri che contenga una lettera e una cifra: con qualsiasi altra, il Job di importazione fallisce non appena Dify rifiuta la configurazione iniziale, e il suo log riporta first-time setup was refused with HTTP 422: Validation error for parameter 'payload', la risposta che Dify dà a un account proprietario che rifiuta. L’attesa qui sotto aspetta che il Job venga completato, e un Job fallito non viene mai completato, quindi in quel caso prosegue fino al timeout; esegui kubectl wait --for=condition=failed job/dify-zdapi-app-import --timeout=15m in un secondo terminale accanto, e quell’attesa ritorna non appena il Job fallisce. Elimina il Job e il Secret dify-owner, crea di nuovo il Secret con una password che Dify accetta e applica di nuovo.

Scrivi un file per ciascuno degli altri cinque Secret, contenente una riga: la chiave di dati, = e un valore tuo — dify-credentials.env con secret-key=, db-password.env con db-password=, code-execution-key.env con code-execution-key=, plugin-daemon-key.env con plugin-daemon-key= e inner-api-key.env con inner-api-key=. Poi crea i sei Secret. A quel punto i valori li conserva il cluster, quindi elimina i file:

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

Applica i manifest, come spiega il passo di esecuzione di Come si svolge un’importazione — -R raggiunge il Job e le due ConfigMap in dify.api/ e dify.proxy/ — poi attendi il Job di importazione e leggine il log, e attendi il runtime dei plugin:

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

Il log riporta l’identificatore dell’applicazione, che serve in Verifica.

Eseguire il test

L’API di Dify risponde su http://127.0.0.1:5001. Su Kubernetes, inoltra una porta locale al Service del server API, dify-zdapi-default, nel namespace in cui hai applicato i manifest, e lascia il comando in esecuzione in un secondo terminale:

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

Su Docker Compose, avviato come mostra Su Docker Compose, la Release pubblica già l’API a quell’indirizzo, e la console su http://127.0.0.1:3001. Apri http://127.0.0.1:3001/signin, la pagina di accesso della console; / reindirizza lì. La pagina invia le sue richieste all’API su http://127.0.0.1:5001, e l’API di Dify risponde a un browser solo per le pagine servite dall’indirizzo indicato dal console_url della bozza, http://127.0.0.1:3001, quindi accedi lì come proprietario. Se la console viene aperta a qualsiasi altro indirizzo, le sue richieste non ricevono tale risposta e il browser rifiuta ogni risposta; pubblica la console su un’altra porta e cambia console_url di conseguenza.

L’applicazione risponde anche tramite l’API, senza alcun browser coinvolto. In un terminale in cui è impostata DIFY_OWNER_PASSWORD, accedi come proprietario. L’API della console accetta la password codificata in Base64, e l’accesso lascia la sessione in cookies.txt. Ogni richiesta successiva alla console rimanda la sessione, con il token CSRF dello stesso file in un’intestazione X-CSRF-Token; una richiesta che ne è priva viene rifiutata con 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"}

I fornitori di modelli di Dify sono plugin, e una nuova installazione non ne contiene nessuno. Installa il fornitore OpenAI di Dify, alla versione 1.1.0, quella installata dall’esecuzione; il runtime dei plugin lo scarica dal marketplace di Dify, che il marketplace_enabled della bozza consente all’installazione di raggiungere, quindi l’installazione deve raggiungere 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}

Con marketplace_enabled eliminato dalla Release, Dify invece rifiuta la richiesta, con {"code":"invalid_param","message":"marketplace is not enabled","status":400}. L’installazione viene eseguita in background. Interroga il suo task, con il task_id indicato dalla risposta, finché il suo status non è 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]}]}}

Scrivi la chiave del fornitore in openai.json, come {"credentials": {"openai_api_key": "your OpenAI key"}}, impostala ed elimina il file:

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

Dify verifica la chiave con una richiesta al fornitore prima di conservarla, e risponde {"result":"success"} per una chiave che il fornitore accetta. L’esecuzione ha impostato un segnaposto, e Dify lo ha rifiutato con la risposta di 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}

Un’applicazione risponde alle richieste fatte con una propria chiave API. Creane una, con l’identificatore dell’applicazione preso dal log del passo che la importa — su 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 invia all’applicazione un messaggio con la chiave, il token della risposta:

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

Con il segnaposto rifiutato, il modello non ha alcuna chiave, e Dify lo segnala:

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

Le esecuzioni su Kubernetes e su Docker Compose hanno ottenuto le stesse risposte. Con una chiave che il fornitore accetta, la replica contiene la risposta del modello in answer.

Su Kubernetes, interrompi l’inoltro della porta, poi rimuovi ciò che hai applicato, i Secret e il file di sessione:

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

Kubernetes conserva le richieste di volume create da uno StatefulSet quando lo StatefulSet viene eliminato, quindi il terzo comando le rimuove, e con esse il database, il plugin installato e l’archivio vettoriale. Su Docker Compose, docker compose -p support-assistant -f ../dist/boundaries/platform/compose/docker-compose.yaml down -v rimuove lo stack e i suoi volumi.

Su Docker Compose

La stessa applicazione si importa per Docker Compose con il target compose, dallo stesso file delle risposte. Le bozze per Kubernetes si trovano già in source, quindi scrivi quelle per Compose in una cartella a parte con --output-dir; l’importazione legge comunque il file delle risposte accanto all’applicazione:

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

Docker Compose non ha alcun Secret da indicare, quindi per compose la bozza scrive essa stessa il segreto dell’applicazione e la password del proprietario, ciascuno come riferimento a una variabile che Docker Compose valorizza dall’ambiente di chi avvia lo stack. Lì è richiesta solo l’email del proprietario. L’importazione conserva i due nomi dei Secret nel file delle risposte senza applicarli, e lo segnala sullo standard error:

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

La Release in bozza legge il segreto dell’applicazione da DIFY_SECRET_KEY e la password del proprietario da DIFY_OWNER_PASSWORD, e pubblica l’API sulla porta 5001 e il front end, console, sulla 3001 dell’indirizzo di 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

Ogni porta è raggiungibile solo dalla tua macchina, come dice il suo commento, ed eliminando una riga quel servizio resta soltanto sulla rete dello stack. Il front end è in ascolto sulla 3000 all’interno del suo container ed è pubblicato sulla 3001, così può essere eseguito accanto a un altro esempio che pubblica la 3000. Il console_url del server API è l’indirizzo a cui è pubblicato il front end, quindi una porta che cambi per il front end va cambiata anche lì.

Il Manifest associa ogni componente alla sua Recipe Compose e core/referenced-secret a compose/dotenv-referenced-secret, che scrive ogni riferimento nel file Compose così com’è. Valida e compila dalla nuova cartella:

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

La build scrive in dist alla radice del workspace, e il workspace è ancora source, la cartella che contiene .aggrega-config.yaml: il file Compose è source/dist/boundaries/platform/compose/docker-compose.yaml, che da compose è ../dist/boundaries/platform/compose/docker-compose.yaml, e nessuna cartella dist viene scritta dentro compose. Il file contiene SECRET_KEY: ${DIFY_SECRET_KEY} e OWNER_PASSWORD: ${DIFY_OWNER_PASSWORD} anziché l’uno o l’altro valore. Imposta entrambe le variabili nella tua shell, o in un file .env accanto al file Compose, prima di avviare lo stack.

Le altre quattro credenziali dell’installazione mantengono i valori predefiniti che dà loro core/dify, e su Docker Compose ogni valore predefinito è il valore stesso, scritto nel file Compose così com’è: DB_PASSWORD: dify-db-password-for-evaluation-only, con POSTGRES_PASSWORD uguale sul database, e allo stesso modo dify-code-execution-key-for-evaluation-only, dify-plugin-daemon-key-for-evaluation-only e dify-inner-api-key-for-evaluation-only. Chiunque legga il catalogo conosce questi valori predefiniti, quindi servono solo per una valutazione. Per sostituirne uno, dichiara un parametro stringa nell’Aggregate in bozza, passalo nei parameters della voce dify con il nome che gli dà core/dify — db_password, code_execution_key, plugin_daemon_key o inner_api_key — come la bozza passa secret_key, e soddisfalo nei parameters della Release. Una Release che scrive db_password: "${DIFY_DB_PASSWORD}" produce un file Compose che contiene DB_PASSWORD: ${DIFY_DB_PASSWORD} e POSTGRES_PASSWORD: ${DIFY_DB_PASSWORD}, valorizzati dall’ambiente come i due precedenti.

Avvia lo stack da compose, con una password del proprietario che Dify accetti, come descrive Esecuzione:

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

Nell’esecuzione --wait è tornato dopo circa un minuto, una volta che ogni server ha segnalato di essere integro. Il passo che importa l’applicazione viene eseguito accanto a essi e termina una volta completata l’importazione; il suo log riporta allora:

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

Verifica raggiunge l’installazione sulle due porte pubblicate.