Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Importer une application Dify

Ce guide pas à pas importe une application exportée depuis Dify — un assistant de chat sur un modèle OpenAI — dans un Aggregate, une Release et un Manifest qui, tels qu’ils sont écrits, construisent pour Kubernetes l’installation Dify de la bibliothèque standard, qui embarque l’application, puis les construit et exécute le résultat. Chaque fichier et chaque bloc de sortie ci-dessous proviennent d’une exécution réelle ; l’application et chaque étape du guide se trouvent dans l’exemple import-dify, où un script de vérification relance l’importation, compare ce qu’elle écrit, ce qu’elle affiche et les blocs que cite cette page avec les fichiers qui y sont conservés, et valide et construit ce que l’importation a écrit.

Générer l’exemple

Vous pouvez exécuter cette importation avec les commandes de cette page, ou la faire exécuter par votre assistant IA.

Écrivez l’exemple dans un nouveau dossier qui porte son nom :

Terminal window
aggrega scaffold --example import-dify

Elle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier ; la suivante, ci-dessous, vous place dans le dossier source du nouveau dossier, qui contient ce que cette page importe et où s’exécute l’import :

Terminal window
cd import-dify

Le dossier source de l’exemple généré ouvert dans Visual Studio Code, montrant l’export de l’application Dify d’un assistant de support en mode chat.

L’application

support-assistant.yml, écrit pour ce guide, est une application de chat dans le DSL de Dify, le YAML que Dify exporte pour une application, en version DSL 0.7.0 : un message d’ouverture, un court prompt et le modèle avec lequel elle répond, nommé par son fournisseur :

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

À côté, un fichier .aggrega-config.yaml fait du dossier un espace de travail :

# 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

et import-answers.yaml contient les réponses à ce qu’aucune application ne peut contenir : le secret applicatif de l’installation, la clé avec laquelle Dify signe les sessions et sous laquelle il chiffre les clés des fournisseurs de modèles qu’il stocke ; et le compte propriétaire sous lequel l’application est importée, son adresse e-mail et son mot de passe. Sur Kubernetes, chaque secret est lu depuis un Secret Kubernetes, sa réponse est donc le nom de ce Secret ; le même fichier sert aussi à une importation pour Docker Compose, comme le montre Sur 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 représente une adresse e-mail à vous ; dify-credentials et dify-owner sont les Secrets que crée Exécuter. Sans le fichier, une importation dans un terminal demande chacune des trois valeurs, une question à la fois, et écrit vos réponses dans un nouveau fichier de réponses ; là où rien ne peut être demandé, elle écrit ce fichier avec les trois clés et des réponses vides, les liste et se termine avec le statut 1. Le fichier de réponses de l’importation décrit le fichier en détail.

L’espace de travail n’indique aucun dossier de catalogue ; l’importation lit donc le catalogue de la bibliothèque standard depuis le registre dont elle récupère son importateur : un instantané signé du catalogue publié, que la première importation récupère, vérifie et conserve dans le cache de contenu de l’espace de travail, et que l’enregistrement écrit par l’importation à côté de ses brouillons désigne par son condensé. Un espace de travail qui indique ses propres dossiers de catalogue — dans AGGREGA_CATALOG_DIRS, ou sous workspace.catalog_dirs — importe plutôt en s’appuyant sur ceux-ci. Placez-vous dans source :

Terminal window
cd source

Lancer l’importation

L’installation Dify de la bibliothèque standard est réalisée sur Kubernetes et sur Docker Compose. Ce guide nomme la cible helm :

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

Sur la sortie standard, elle liste ce qu’elle a écrit :

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

Sur la sortie d’erreur standard, où <workspace> désigne le dossier dans lequel vous l’avez lancée :

[… 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’importation lancée depuis l’éditeur : l’Aggregate, la Release et le Manifest ébauchés apparaissent à côté de l’export de l’application, la sortie Aggrega liste ce que l’ébauche relie et les fichiers écrits, et une notification indique que l’importation a ébauché 3 fichiers, reconnus comme dify.

  • La ligne warn indique que le modèle reste dans Dify : Dify configure lui-même ses fournisseurs de modèles, et leurs clés, si bien que l’ébauche ne relie aucun modèle. Une fois Dify lancé, vous installez son fournisseur OpenAI et définissez la clé du fournisseur, comme le montre Test.
  • La ligne Pull complete est le pull. Chaque valeur ayant sa réponse dans le fichier de réponses, l’importation a récupéré par pull les dépendances de la Release ébauchée, comme le fait aggrega pull, et a écrit release.lock ; le build ci-dessous n’a besoin de rien de plus.

Ce qu’elle écrit

L’Aggregate, la Release et le Manifest sont nommés imported/support-assistant, d’après le nom de l’application, Support assistant sous app, réduit à support-assistant — une application sans nom est nommée d’après son fichier —, sous le namespace que fixe le paramètre target_namespace de l’importeur, imported sauf si vous en fixez un autre (Paramètres).

aggregate.yaml — l’installation Dify de la bibliothèque standard, core/dify, un Aggregate que l’ébauche compose sous aggregates, avec l’application reprise telle qu’écrite dans son paramètre app_definition, en grande partie omise ici, et le secret_key de l’installation transmis depuis un paramètre que déclare l’ébauche :

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’installation se compose de dix composants — le serveur d’API de Dify, son worker, son ordonnanceur, son front-end web, son bac à sable de code, son runtime de plugins, un proxy de sortie, PostgreSQL, un cache compatible Redis et Weaviate — reliés entre eux, et l’importation de l’application est une étape que rend la Recipe de son serveur d’API. Son secret d’application n’a pas de valeur par défaut dans core/dify ; l’ébauche déclare donc secret_key comme paramètre propre, sans valeur par défaut, et le transmet pour que la Release le renseigne. Les autres identifiants de l’installation conservent les valeurs par défaut que leur donne core/dify, comme le décrit L’exécuter.

release.yaml — la Release, qui achemine l’installation dans une frontière, platform, et renseigne à partir du fichier de réponses ce que l’application ne peut pas fournir :

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 vaut development, une valeur par défaut que le commentaire au-dessus demande de remplacer par l’environnement dans lequel la Release est déployée.
  • secret_key est le nom du Secret qui contient le secret d’application, dify-credentials, sous la clé de données que nomme l’installation, secret-key : le Manifest lit chaque identifiant dans un Secret déjà présent dans le namespace.
  • Le compte propriétaire est défini sur le composant api de l’installation, dans l’entrée de routage qui place l’installation dans sa frontière : son adresse e-mail, et son mot de passe attaché en tant que core/referenced-secret qui nomme le Secret le contenant, dify-owner, sous la clé de données value. Les commentaires au-dessus des valeurs renseignées expliquent pourquoi l’importation n’a pas pu les rédiger.
  • marketplace_enabled vaut true sur le serveur d’API, api, son worker et son planificateur, sur chaque cible : l’installation n’atteint rien de l’éditeur de Dify sans que la Release l’autorise, et le fournisseur OpenAI avec lequel répond l’application est un plugin que Dify installe depuis sa place de marché de plugins, comme le montre Le tester. Chacun des trois lit son propre paramètre.

manifest.yaml — une Recipe Helm pour chaque composant que compose l’installation, et la réalisation qui lit un identifiant dans un Secret déjà présent dans le 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 associe les types de composants de l’installation que compose l’ébauche ainsi que les siens. Lorsque le catalogue propose plusieurs Recipes Helm pour un type, comme c’est le cas pour PostgreSQL, il associe celle qui porte le nom du type, helm/postgres.

.aggrega-import.json est l’enregistrement de ce que l’importation a écrit, que lit un aggrega import --sync ultérieur, et release.lock épingle chaque entité du catalogue vers laquelle la Release se résout, par version et digest.

Valider et compiler

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

La Release ébauchée ouverte dans l’éditeur après sa validation, la sortie Aggrega et une notification indiquant toutes deux qu’aucun problème n’a été trouvé.

La construction de la Release ébauchée : un dossier dist apparaît dans l’Explorateur, la sortie Aggrega liste les manifestes Kubernetes de l’installation Dify, et une notification indique que 24 fichiers ont été écrits.

La validation affiche :

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)

et la compilation, où <workspace> désigne le dossier contenant les ébauches :

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 ligne notice est indicative : la Feature de secret accepte son origin depuis les values de l’Aggregate ou l’infra de la Release, et la notice signale qu’une feuille est déclarée dans les deux. Elle ne change aucun verdict.

Le build écrit les manifestes Kubernetes de l’installation sous dist/boundaries/platform/helm/. Parmi eux se trouve le Job qui importe l’application, dify.api/dify-app-import.job.yaml. Il attend que le serveur d’API de Dify réponde, effectue la configuration initiale de Dify en tant que compte propriétaire que nomme la Release, là où cette configuration n’a pas été faite, et importe l’application :

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’application elle-même se trouve dans la ConfigMap à côté. Lorsque Dify refuse ce que l’étape lui envoie, par une réponse d’erreur client autre qu’un dépassement du délai de la requête ou une limitation de débit, ou en signalant que l’importation a échoué, l’étape affiche le message que porte la réponse de Dify et se termine avec le statut 2, comme elle le fait lorsque la définition ne nomme aucune application sous app.name ; la podFailurePolicy du Job fait échouer le Job à cette tentative, puisqu’une nouvelle tentative serait refusée de la même manière ; tout autre échec, comme un serveur qui ne répond pas dans un délai d’environ dix minutes, donne lieu à une nouvelle tentative.

Avec un assistant IA

Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-y ce prompt.

Utilise uniquement les outils Aggrega et ne crée toi-même aucun dossier. Si le dossier du Workspace ne contient pas encore de dossier `import-dify`, appelle une fois l’outil `scaffold` avec `example` défini à `import-dify` et sans `dir` : il écrit l’exemple dans un nouveau dossier `import-dify`, dont le dossier `source` contient ce que cette page importe. Appelle ensuite l’outil `import` avec `workspace_root` défini à `import-dify/source`, `source` défini à `support-assistant.yml` et `target` défini à `helm` : il lit les réponses dont il a besoin dans `import-answers.yaml` à côté de `support-assistant.yml`, écrit ses ébauches dans `import-dify/source` et tire ce dont elles ont besoin. Appelle ensuite l’outil `validate` avec `workspace_root` défini à `import-dify/source` et `release` défini à `release.yaml`, puis l’outil `build` avec `workspace_root` défini à `import-dify/source`, `release` défini à `release.yaml` et `write` défini à true. Dis-moi quels fichiers la construction a écrits ; ils se trouvent sous `import-dify/source/dist/`.

L’ouvrir dans VS Code

Une fois l’extension Aggrega pour Visual Studio Code installée, ouvrez dans VS Code le dossier import-dify/source, où l’importation a écrit ses brouillons. Le dossier contient une seule Release, le release.yaml rédigé, donc l’éditeur la sélectionne pour vous ; une fois que Sur Docker Compose a rédigé une seconde Release dans compose, Aggrega: Select Release… choisit celle sur laquelle travaille l’éditeur. L’éditeur vérifie les brouillons par rapport à la Release sélectionnée à mesure que vous les modifiez, en signalant ce qu’il trouve dans le fichier et dans le panneau Problèmes. Aggrega: Show topology graph, dans la palette de commandes, dessine les composants de la Release sélectionnée et les connexions entre eux. Aggrega: Build, Aggrega: Preview build et Aggrega: Pull agissent sur la même Release, et chacune est aussi un bouton du panneau Commands de la vue Aggrega dans la barre d’activité ; Build écrit ses fichiers dans le dist/ du dossier. Utiliser Aggrega dans Visual Studio Code couvre le reste.

Exécution

Avant d’appliquer les manifestes, créez les Secrets qu’ils lisent. Une charge de travail qui nomme un Secret inexistant ne démarre pas. Deux contiennent ce que le fichier de réponses a nommé : dify-owner, qui contient le mot de passe du propriétaire sous value, et dify-credentials, qui contient le secret de l’application sous secret-key. Les quatre autres identifiants de l’installation — son mot de passe de base de données et trois clés que ses composants se présentent les uns aux autres — conservent les valeurs par défaut que leur donne core/dify, et sur Kubernetes chaque valeur par défaut est le nom du Secret depuis lequel les manifestes la lisent : dify-db-password-for-evaluation-only sous db-password, dify-code-execution-key-for-evaluation-only sous code-execution-key, dify-plugin-daemon-key-for-evaluation-only sous plugin-daemon-key et dify-inner-api-key-for-evaluation-only sous inner-api-key. Créez aussi ces quatre-là, chacun avec une valeur de votre choix ; pour les lire depuis des Secrets nommés autrement, passez les noms à core/dify dans l’entrée dify de l’Aggregate, sous parameters, en tant que db_password, code_execution_key, plugin_daemon_key et inner_api_key.

Définissez le mot de passe du propriétaire dans votre shell, sous la forme DIFY_OWNER_PASSWORD, car vous vous connectez avec lui plus bas. Dify accepte un mot de passe de propriétaire d’au moins huit caractères contenant une lettre et un chiffre : avec tout autre, le Job d’import échoue dès que Dify refuse la configuration initiale, et son journal indique first-time setup was refused with HTTP 422: Validation error for parameter 'payload', la réponse que Dify donne à un compte propriétaire qu’il refuse. L’attente ci-dessous attend que le Job s’achève, et un Job en échec ne s’achève jamais, si bien qu’elle court alors jusqu’à son délai d’expiration ; exécutez kubectl wait --for=condition=failed job/dify-zdapi-app-import --timeout=15m dans un second terminal à côté, et cette attente rend la main dès que le Job échoue. Supprimez le Job et le Secret dify-owner, recréez le Secret avec un mot de passe que Dify accepte, puis appliquez de nouveau les manifestes.

Écrivez un fichier pour chacun des cinq autres Secrets, contenant une ligne : la clé de données, = et une valeur de votre choix — dify-credentials.env avec secret-key=, db-password.env avec db-password=, code-execution-key.env avec code-execution-key=, plugin-daemon-key.env avec plugin-daemon-key= et inner-api-key.env avec inner-api-key=. Créez ensuite les six Secrets. Le cluster détient alors les valeurs, supprimez donc les fichiers :

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

Appliquez les manifestes, comme l’explique l’étape d’exécution de Déroulement d’une importation — -R atteint le Job et les deux ConfigMaps dans dify.api/ et dify.proxy/ — puis attendez le Job d’import et lisez son journal, et attendez le runtime des 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...

Le journal indique l’identifiant de l’application, dont Test a besoin.

Tester

L’API de Dify répond à http://127.0.0.1:5001. Sur Kubernetes, redirigez un port local vers le Service du serveur d’API, dify-zdapi-default, dans l’espace de noms où vous avez appliqué les manifestes, et laissez la commande s’exécuter dans un second terminal :

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

Sur Docker Compose, démarré comme le montre Sur Docker Compose, la Release publie déjà l’API à cette adresse, et la console à http://127.0.0.1:3001. Ouvrez http://127.0.0.1:3001/signin, la page de connexion de la console ; / y redirige. La page envoie ses requêtes à l’API à http://127.0.0.1:5001, et l’API de Dify ne répond à un navigateur que pour les pages servies depuis l’adresse que nomme le console_url ébauché, http://127.0.0.1:3001 ; connectez-vous donc là en tant que propriétaire. Ouverte à toute autre adresse, la console n’obtient pas cette réponse pour ses requêtes et le navigateur refuse chaque réponse ; publiez la console sur un autre port et modifiez console_url en conséquence.

L’application répond aussi par l’API, sans aucun navigateur. Dans un terminal où DIFY_OWNER_PASSWORD est défini, connectez-vous en tant que propriétaire. L’API de console prend le mot de passe encodé en Base64, et la connexion laisse la session dans cookies.txt. Chaque requête ultérieure à la console renvoie la session, avec le jeton CSRF du même fichier dans un en-tête X-CSRF-Token ; une requête sans lui est refusée avec 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"}

Les fournisseurs de modèles de Dify sont des plugins, et une nouvelle installation n’en contient aucun. Installez le fournisseur OpenAI de Dify, en version 1.1.0, celle que l’exécution a installée ; le runtime des plugins le récupère sur la marketplace de Dify, que le marketplace_enabled ébauché permet à l’installation d’atteindre, si bien que l’installation doit pouvoir atteindre 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}

Si marketplace_enabled est supprimé de la Release, Dify refuse la requête à la place, avec {"code":"invalid_param","message":"marketplace is not enabled","status":400}. L’installation s’exécute en arrière-plan. Interrogez sa tâche, avec le task_id que nomme la réponse, jusqu’à ce que son status soit 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]}]}}

Écrivez la clé du fournisseur dans openai.json, sous la forme {"credentials": {"openai_api_key": "your OpenAI key"}}, définissez-la, puis supprimez le fichier :

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 vérifie la clé par une requête au fournisseur avant de la conserver, et répond {"result":"success"} pour une clé que le fournisseur accepte. L’exécution a défini une valeur fictive, et Dify l’a refusée avec la réponse d’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}

Une application répond aux requêtes faites avec une clé d’API qui lui est propre. Créez-en une, avec l’identifiant de l’application tiré du journal de l’étape qui l’importe — sur 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}

et envoyez un message à l’application avec la clé, le token de la réponse :

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

La valeur fictive ayant été refusée, le modèle n’a pas de clé, et Dify le signale :

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

Les exécutions sur Kubernetes et sur Docker Compose ont obtenu les mêmes réponses. Avec une clé que le fournisseur accepte, la réponse porte celle du modèle dans answer.

Sur Kubernetes, arrêtez la redirection de port, puis supprimez ce que vous avez appliqué, les Secrets et le fichier de session :

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 conserve les demandes de volume qu’un StatefulSet a créées lorsque le StatefulSet est supprimé, si bien que la troisième commande les supprime, et avec elles la base de données, le plugin installé et la base vectorielle. Sur Docker Compose, docker compose -p support-assistant -f ../dist/boundaries/platform/compose/docker-compose.yaml down -v supprime la pile et ses volumes.

Sur Docker Compose

La même application s’importe pour Docker Compose avec la cible compose, à partir du même fichier de réponses. Les ébauches pour Kubernetes se trouvent déjà dans source, ébauchez donc celles pour Compose dans un dossier distinct avec --output-dir ; l’importation lit malgré tout le fichier de réponses situé à côté de l’application :

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

Docker Compose n’a pas de Secret à désigner, si bien que pour compose l’ébauche écrit elle-même le secret de l’application et le mot de passe du propriétaire, chacun sous forme de référence de variable que Docker Compose renseigne depuis l’environnement de la personne qui démarre la pile. Seule l’adresse e-mail du propriétaire y est requise. L’importation conserve les deux noms de Secrets dans le fichier de réponses sans les appliquer, et le signale sur la sortie d’erreur standard :

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 ébauchée lit le secret de l’application dans DIFY_SECRET_KEY et le mot de passe du propriétaire dans DIFY_OWNER_PASSWORD, et publie l’API sur le port 5001 et le front-end, console, sur le port 3001 de l’adresse de bouclage :

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

Chaque port n’est accessible que depuis votre machine, comme l’indique son commentaire, et supprimer une ligne laisse ce service sur le seul réseau de la pile. Le front-end écoute sur 3000 dans son conteneur et est publié sur 3001, il peut donc s’exécuter à côté d’un autre exemple qui publie 3000. Le console_url du serveur d’API est l’adresse à laquelle le front-end est publié, si bien qu’un port que vous changez pour le front-end doit y être changé aussi.

Le Manifest associe chaque composant à sa Recipe Compose et core/referenced-secret à compose/dotenv-referenced-secret, qui écrit chaque référence telle quelle dans le fichier Compose. Validez et construisez depuis le nouveau dossier :

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

La construction écrit sous dist à la racine de l’espace de travail, et l’espace de travail est toujours source, le dossier qui contient .aggrega-config.yaml : le fichier Compose est source/dist/boundaries/platform/compose/docker-compose.yaml, qui depuis compose est ../dist/boundaries/platform/compose/docker-compose.yaml, et aucun dossier dist n’est écrit dans compose. Le fichier contient SECRET_KEY: ${DIFY_SECRET_KEY} et OWNER_PASSWORD: ${DIFY_OWNER_PASSWORD} plutôt que l’une ou l’autre valeur. Définissez les deux variables dans votre shell, ou dans un fichier .env à côté du fichier Compose, avant de démarrer la pile.

Les quatre autres identifiants de l’installation conservent les valeurs par défaut que leur donne core/dify, et sur Docker Compose chaque valeur par défaut est la valeur elle-même, écrite telle quelle dans le fichier Compose : DB_PASSWORD: dify-db-password-for-evaluation-only, avec le même POSTGRES_PASSWORD sur la base de données, et de même dify-code-execution-key-for-evaluation-only, dify-plugin-daemon-key-for-evaluation-only et dify-inner-api-key-for-evaluation-only. Tout lecteur du catalogue connaît ces valeurs par défaut, elles ne servent donc qu’à une évaluation. Pour en remplacer une, déclarez pour elle un paramètre de type chaîne dans l’Aggregate ébauché, transmettez-le dans les parameters de l’entrée dify sous le nom que lui donne core/dify — db_password, code_execution_key, plugin_daemon_key ou inner_api_key — comme l’ébauche transmet secret_key, et renseignez-le dans les parameters de la Release. Une Release qui écrit db_password: "${DIFY_DB_PASSWORD}" construit un fichier Compose contenant DB_PASSWORD: ${DIFY_DB_PASSWORD} et POSTGRES_PASSWORD: ${DIFY_DB_PASSWORD}, renseignés depuis l’environnement comme les deux ci-dessus.

Démarrez la pile depuis compose, avec un mot de passe de propriétaire que Dify accepte, comme le décrit Exécution :

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

--wait a rendu la main au bout d’environ une minute lors de l’exécution, une fois que chaque serveur s’est déclaré en bonne santé. L’étape qui importe l’application s’exécute à côté d’eux et se termine une fois l’importation faite ; son journal indique alors :

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

Test atteint l’installation sur les deux ports publiés.