Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Importowanie aplikacji Dify

Ten przewodnik krok po kroku importuje aplikację wyeksportowaną z Dify — asystenta czatu opartego na modelu OpenAI — do encji Aggregate, Release i Manifest, które w postaci, w jakiej zostały zapisane, budują dla Kubernetes instalację Dify z biblioteki standardowej, zawierającą tę aplikację; następnie je buduje i uruchamia wynik. Każdy plik i każdy blok wyjścia poniżej pochodzi z rzeczywistego uruchomienia; aplikacja i każdy etap przewodnika znajdują się w przykładzie import-dify, gdzie skrypt kontrolny ponownie uruchamia import, porównuje to, co zapisuje, to, co wypisuje, oraz bloki cytowane na tej stronie z przechowywanymi tam plikami, a także waliduje i buduje to, co zapisał import.

Generowanie przykładu

Ten import można uruchomić poleceniami z tej strony albo zlecić to asystentowi AI.

Należy zapisać przykład w nowym folderze nazwanym tak jak on:

Terminal window
aggrega scaffold --example import-dify

Następnie wypisuje polecenia do uruchomienia w dalszej kolejności. Pierwsze przechodzi do nowego folderu; kolejne, poniżej, przechodzi do folderu source w nowym folderze, który zawiera to, co importuje ta strona, i w którym uruchamia się import:

Terminal window
cd import-dify

Folder source wygenerowanego przykładu otwarty w Visual Studio Code, z eksportem aplikacji Dify asystenta wsparcia w trybie czatu.

Aplikacja

support-assistant.yml, napisany na potrzeby tego przewodnika, to aplikacja czatu w DSL Dify, czyli YAML, który Dify eksportuje dla aplikacji, w wersji DSL 0.7.0: wiadomość otwierająca, krótki prompt oraz model, którym aplikacja odpowiada, wskazany przez swojego dostawcę:

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

Obok niego plik .aggrega-config.yaml czyni folder obszarem roboczym:

# 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

a import-answers.yaml zawiera odpowiedzi na to, czego żadna aplikacja nie może zawierać: sekret aplikacji instalacji, czyli klucz, którym Dify podpisuje sesje i którym szyfruje przechowywane klucze dostawców modeli; oraz konto właściciela, w ramach którego aplikacja jest importowana, z jego adresem e-mail i hasłem. Na Kubernetes każdy sekret jest odczytywany z obiektu Secret Kubernetes, więc odpowiedzią jest nazwa tego obiektu Secret; ten sam plik służy też do importu dla Docker Compose, jak pokazuje W 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 oznacza własny adres e-mail; dify-credentials i dify-owner to obiekty Secret tworzone w sekcji Uruchomienie. Bez tego pliku import w terminalu pyta o każdą z trzech wartości, po jednym pytaniu naraz, i zapisuje odpowiedzi w nowym pliku odpowiedzi; tam, gdzie nie można o nic zapytać, zapisuje ten plik z trzema kluczami i pustymi odpowiedziami, wymienia je i kończy działanie ze statusem 1. Plik odpowiedzi importu opisuje ten plik w całości.

Obszar roboczy nie wskazuje żadnego folderu katalogu, więc import odczytuje katalog biblioteki standardowej z rejestru, z którego pobiera swój importer: podpisaną migawkę opublikowanego katalogu, którą pierwszy import pobiera, weryfikuje i przechowuje w pamięci podręcznej treści obszaru roboczego i którą rekord zapisywany przez import obok jego szkiców wskazuje za pomocą jej skrótu. Obszar roboczy, który wskazuje własne foldery katalogu — w AGGREGA_CATALOG_DIRS lub pod workspace.catalog_dirs — importuje zamiast tego względem nich. Należy przejść do source:

Terminal window
cd source

Uruchomienie importu

Instalacja Dify z biblioteki standardowej jest realizowana na Kubernetes i na Docker Compose. Ten przewodnik wskazuje cel helm:

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

Na standardowym wyjściu wymienia to, co zapisał:

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

Na standardowym wyjściu błędów, gdzie <workspace> oznacza folder, w którym go uruchomiono:

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

Import uruchomiony z edytora: szkice encji Aggregate, Release i Manifest pojawiają się obok eksportu aplikacji, wyjście Aggrega wymienia to, co łączy szkic, oraz zapisane pliki, a powiadomienie mówi, że import utworzył szkice 3 plików, rozpoznane jako dify.

  • Wiersz warn mówi, że model pozostaje wewnątrz Dify: Dify samo konfiguruje swoich dostawców modeli i ich klucze, więc szkic nie podłącza żadnego modelu. Gdy Dify już działa, instaluje się jego dostawcę OpenAI i ustawia klucz dostawcy, jak pokazuje Testowanie.
  • Wiersz Pull complete to pull. Ponieważ każda wartość miała odpowiedź w pliku odpowiedzi, import pobrał zależności szkicowanej encji Release, tak jak robi to aggrega pull, i zapisał release.lock; poniższa kompilacja nie potrzebuje niczego więcej.

Co zapisuje import

Encje Aggregate, Release i Manifest otrzymują nazwę imported/support-assistant od nazwy aplikacji, Support assistant w app, sprowadzonej do support-assistant — aplikacja bez nazwy otrzymuje nazwę od swojego pliku — w przestrzeni nazw określonej przez ustawienie target_namespace importera, imported, o ile nie ustawi się innej (Ustawienia).

aggregate.yaml — instalacja Dify z biblioteki standardowej, core/dify, encja Aggregate, którą szkic składa w aggregates, z aplikacją przeniesioną dosłownie do jej parametru app_definition, tutaj w większości pominiętą, oraz z secret_key instalacji przekazywanym z parametru, który deklaruje szkic:

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

Instalacja to dziesięć komponentów — serwer API, worker, scheduler, frontend webowy, piaskownica kodu i środowisko uruchomieniowe wtyczek Dify, proxy ruchu wychodzącego, PostgreSQL, pamięć podręczna zgodna z Redis i Weaviate — połączonych ze sobą, a import aplikacji to krok, który generuje encja Recipe serwera API instalacji. Jej sekret aplikacji nie ma wartości domyślnej w core/dify, dlatego szkic deklaruje secret_key jako własny parametr, bez wartości domyślnej, i przekazuje go dalej, aby encja Release go wypełniła. Pozostałe dane uwierzytelniające instalacji zachowują wartości domyślne nadane im przez core/dify, jak opisuje Uruchomienie.

release.yaml — encja Release, która kieruje instalację do granicy, platform, i wypełnia z pliku odpowiedzi to, czego aplikacja nie może dostarczyć:

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 ma wartość development, domyślną, którą według komentarza nad nią należy zmienić na środowisko, w którym wdrażana jest encja Release.
  • secret_key to nazwa obiektu Secret przechowującego sekret aplikacji, dify-credentials, pod kluczem danych wskazanym przez instalację, secret-key: encja Manifest odczytuje wszystkie dane uwierzytelniające z obiektu Secret już istniejącego w przestrzeni nazw.
  • Konto właściciela ustawia się na komponencie api instalacji, we wpisie routingu, który umieszcza instalację w jej granicy: jego adres e-mail oraz hasło dołączone jako core/referenced-secret wskazujący obiekt Secret, który je przechowuje, dify-owner, pod kluczem danych value. Komentarze nad wartościami podanymi w odpowiedziach wyjaśniają, dlaczego import nie mógł ich przygotować.
  • marketplace_enabled ma wartość true na serwerze API, api, jego workerze i jego harmonogramie, na każdym celu: instalacja nie sięga do niczego u dostawcy Dify, chyba że encja Release na to zezwala, a dostawca OpenAI, którym odpowiada aplikacja, to wtyczka instalowana przez Dify z jego rynku wtyczek, jak pokazuje sekcja Testowanie. Każdy z tych trzech odczytuje własne ustawienie.

manifest.yaml — encja Recipe Helm dla każdego komponentu, z którego składa się instalacja, oraz realizacja odczytująca dane uwierzytelniające z obiektu Secret już istniejącego w przestrzeni nazw:

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 mapuje typy komponentów instalacji, którą składa szkic, a także jego własne. Tam, gdzie katalog oferuje kilka encji Recipes Helm dla jednego typu, jak w przypadku PostgreSQL, mapuje tę nazwaną od typu, helm/postgres.

.aggrega-import.json to zapis tego, co zapisał import, odczytywany przez późniejsze aggrega import --sync, a release.lock przypina każdą encję katalogu, na którą rozwiązuje się encja Release, według wersji i skrótu (digest).

Walidacja i kompilacja

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

Szkic encji Release otwarty w edytorze po walidacji, a wyjście Aggrega i powiadomienie zgłaszają, że nie znaleziono problemów.

Kompilacja szkicu encji Release: w Eksploratorze pojawia się folder dist, wyjście Aggrega wymienia manifesty Kubernetes instalacji Dify, a powiadomienie mówi, że zapisano 24 pliki.

Walidacja wypisuje:

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)

a kompilacja, gdzie <workspace> oznacza folder zawierający szkice:

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

Wiersz notice ma charakter informacyjny: encja Feature sekretu przyjmuje swoje origin z values encji Aggregate lub z infra encji Release, a komunikat informuje, że jeden liść jest zadeklarowany w obu miejscach. Nie zmienia żadnego werdyktu.

Budowanie zapisuje manifesty Kubernetes instalacji w dist/boundaries/platform/helm/. Wśród nich jest Job, który importuje aplikację, dify.api/dify-app-import.job.yaml. Czeka on, aż serwer API Dify odpowie, wykonuje pierwszą konfigurację Dify jako konto właściciela wskazane przez encję Release, tam gdzie ta konfiguracja jeszcze się nie odbyła, i importuje aplikację:

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

Sama aplikacja znajduje się w obiekcie ConfigMap obok. Gdy Dify odrzuca to, co wysyła mu krok, odpowiedzią z błędem klienta innym niż przekroczenie czasu żądania lub limit częstotliwości albo zgłaszając, że import się nie powiódł, krok wypisuje komunikat zawarty w odpowiedzi Dify i kończy działanie ze statusem 2, tak jak wtedy, gdy definicja nie wskazuje żadnej aplikacji w app.name; podFailurePolicy obiektu Job powoduje niepowodzenie tego obiektu przy tej próbie, ponieważ ponowna próba zostałaby odrzucona w ten sam sposób; każde inne niepowodzenie, na przykład gdy serwer nie odpowiada w ciągu około dziesięciu minut, jest ponawiane.

Z asystentem AI

Asystent AI skonfigurowany z narzędziami Aggrega może zrobić to samo: wystarczy wkleić do niego ten prompt.

Używaj wyłącznie narzędzi Aggrega i nie twórz samodzielnie żadnego folderu. Jeśli folder Workspace nie zawiera jeszcze folderu `import-dify`, wywołaj raz narzędzie `scaffold` z `example` ustawionym na `import-dify` i bez `dir`: zapisze ono przykład w nowym folderze `import-dify`, którego folder `source` zawiera to, co importuje ta strona. Następnie wywołaj narzędzie `import` z `workspace_root` ustawionym na `import-dify/source`, `source` ustawionym na `support-assistant.yml` i `target` ustawionym na `helm`: odczyta ono potrzebne odpowiedzi z `import-answers.yaml` obok `support-assistant.yml`, zapisze szkice w `import-dify/source` i pobierze to, czego potrzebują. Następnie wywołaj narzędzie `validate` z `workspace_root` ustawionym na `import-dify/source` i `release` ustawionym na `release.yaml`, a potem narzędzie `build` z `workspace_root` ustawionym na `import-dify/source`, `release` ustawionym na `release.yaml` i `write` ustawionym na true. Powiedz mi, które pliki zapisała kompilacja; znajdują się w `import-dify/source/dist/`.

Otwieranie w VS Code

Po zainstalowaniu rozszerzenia Aggrega dla Visual Studio Code należy otworzyć w VS Code folder import-dify/source, w którym import zapisał wersje robocze. Folder zawiera jedną encję Release, wersję roboczą release.yaml, więc edytor sam ją wybiera; gdy sekcja W Docker Compose przygotuje drugą encję Release w compose, Aggrega: Select Release… wybiera tę, na której pracuje edytor. Edytor sprawdza wersje robocze względem wybranej encji Release podczas edycji, oznaczając znalezione problemy w pliku i w panelu Problemy. Aggrega: Show topology graph w palecie poleceń rysuje komponenty wybranej encji Release i połączenia między nimi. Aggrega: Build, Aggrega: Preview build i Aggrega: Pull działają na tej samej encji Release, a każde z nich jest też przyciskiem w panelu Commands widoku Aggrega na pasku działań; Build zapisuje swoje pliki w dist/ folderu. Resztę omawia Używanie Aggrega w Visual Studio Code.

Uruchomienie

Przed zastosowaniem manifestów należy utworzyć obiekty Secret, które one odczytują. Obciążenie robocze wskazujące nieistniejący Secret nie uruchamia się. Dwa z nich przechowują to, co wskazał plik odpowiedzi: dify-owner, przechowujący hasło właściciela pod kluczem value, oraz dify-credentials, przechowujący sekret aplikacji pod kluczem secret-key. Pozostałe cztery poświadczenia instalacji — hasło do bazy danych i trzy klucze, które jej komponenty przedstawiają sobie nawzajem — zachowują wartości domyślne nadane im przez core/dify, a w Kubernetes każda wartość domyślna jest nazwą obiektu Secret, z którego manifesty ją odczytują: dify-db-password-for-evaluation-only pod kluczem db-password, dify-code-execution-key-for-evaluation-only pod kluczem code-execution-key, dify-plugin-daemon-key-for-evaluation-only pod kluczem plugin-daemon-key oraz dify-inner-api-key-for-evaluation-only pod kluczem inner-api-key. Należy utworzyć również te cztery, każdy z własną wartością; aby odczytywać je z obiektów Secret o innych nazwach, należy przekazać nazwy do core/dify we wpisie dify encji Aggregate, pod parameters, jako db_password, code_execution_key, plugin_daemon_key i inner_api_key.

Hasło właściciela należy ustawić w powłoce jako DIFY_OWNER_PASSWORD, ponieważ poniżej służy ono do logowania. Dify przyjmuje hasło właściciela o długości co najmniej ośmiu znaków, zawierające literę i cyfrę: przy każdym innym Job importu kończy się niepowodzeniem, gdy tylko Dify odrzuci konfigurację początkową, a jego log zawiera first-time setup was refused with HTTP 422: Validation error for parameter 'payload', czyli odpowiedź, jaką Dify daje na konto właściciela, które odrzuca. Oczekiwanie poniżej czeka na ukończenie obiektu Job, a obiekt Job zakończony niepowodzeniem nigdy nie zostaje ukończony, więc oczekiwanie trwa wtedy aż do upływu limitu czasu; należy uruchomić kubectl wait --for=condition=failed job/dify-zdapi-app-import --timeout=15m obok, w drugim terminalu, a to oczekiwanie kończy się, gdy tylko Job zakończy się niepowodzeniem. Należy usunąć obiekt Job i obiekt Secret dify-owner, ponownie utworzyć obiekt Secret z hasłem, które Dify przyjmuje, i ponownie zastosować manifesty.

Dla każdego z pozostałych pięciu obiektów Secret należy zapisać plik zawierający jeden wiersz: klucz danych, = i własną wartość — dify-credentials.env z secret-key=, db-password.env z db-password=, code-execution-key.env z code-execution-key=, plugin-daemon-key.env z plugin-daemon-key= oraz inner-api-key.env z inner-api-key=. Następnie należy utworzyć sześć obiektów Secret. Od tej chwili wartości przechowuje klaster, więc należy usunąć pliki:

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

Należy zastosować manifesty, jak wyjaśnia krok uruchomienia w Jak przebiega import — -R sięga do obiektu Job i dwóch obiektów ConfigMap w dify.api/ i dify.proxy/ — a następnie poczekać na Job importu i odczytać jego log oraz poczekać na środowisko uruchomieniowe wtyczek:

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

Log podaje identyfikator aplikacji, potrzebny w Testowanie.

Testowanie

API Dify odpowiada pod http://127.0.0.1:5001. Na Kubernetes należy przekierować port lokalny do obiektu Service serwera API, dify-zdapi-default, w przestrzeni nazw, do której zastosowano manifesty, i pozostawić polecenie działające w drugim terminalu:

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

W Docker Compose, uruchomionym tak, jak pokazuje W Docker Compose, encja Release już publikuje API pod tym adresem, a konsolę pod http://127.0.0.1:3001. Należy otworzyć http://127.0.0.1:3001/signin, stronę logowania konsoli; / przekierowuje właśnie tam. Strona wysyła żądania do API pod http://127.0.0.1:5001, a API Dify odpowiada przeglądarce tylko dla stron serwowanych z adresu, który wskazuje szkic console_url, http://127.0.0.1:3001, więc należy zalogować się tam jako właściciel. Po otwarciu konsoli pod jakimkolwiek innym adresem jej żądania nie dostają takiej odpowiedzi, a przeglądarka odrzuca każdą odpowiedź; aby opublikować konsolę na innym porcie, należy razem z nim zmienić console_url.

Aplikacja odpowiada także przez API, bez udziału przeglądarki. W terminalu, w którym ustawiono DIFY_OWNER_PASSWORD, należy zalogować się jako właściciel. API konsoli przyjmuje hasło zakodowane w Base64, a logowanie zostawia sesję w cookies.txt. Każde późniejsze żądanie do konsoli odsyła sesję wraz z tokenem CSRF z tego samego pliku w nagłówku X-CSRF-Token; żądanie bez niego zostaje odrzucone z komunikatem 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"}

Dostawcy modeli w Dify są wtyczkami, a nowa instalacja nie zawiera żadnego. Należy zainstalować dostawcę OpenAI dla Dify w wersji 1.1.0, tej, którą zainstalowało uruchomienie; środowisko uruchomieniowe wtyczek pobiera go z marketplace Dify, do którego szkic marketplace_enabled daje instalacji dostęp, więc instalacja musi mieć dostęp do internetu:

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}

Gdy marketplace_enabled zostanie usunięte z encji Release, Dify zamiast tego odrzuca żądanie z {"code":"invalid_param","message":"marketplace is not enabled","status":400}. Instalacja działa w tle. Należy odpytywać o jej zadanie, z task_id podanym w odpowiedzi, dopóki jego status nie będzie 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]}]}}

Należy zapisać klucz dostawcy w openai.json jako {"credentials": {"openai_api_key": "your OpenAI key"}}, ustawić go i usunąć plik:

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 sprawdza klucz jednym żądaniem do dostawcy, zanim go zachowa, i odpowiada {"result":"success"} dla klucza, który dostawca akceptuje. Uruchomienie ustawiło wartość zastępczą, a Dify odrzuciło ją z odpowiedzią 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}

Aplikacja odpowiada na żądania wysyłane z jej własnym kluczem API. Należy utworzyć taki klucz, podając identyfikator aplikacji z logu kroku, który ją importuje — w 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}

i wysłać do aplikacji wiadomość z kluczem, czyli token z odpowiedzi:

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

Po odrzuceniu wartości zastępczej model nie ma klucza, a Dify to zgłasza:

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

Uruchomienia na Kubernetes i w Docker Compose otrzymały te same odpowiedzi. Z kluczem, który dostawca akceptuje, odpowiedź zawiera odpowiedź modelu w answer.

Na Kubernetes należy zatrzymać przekierowanie portu, a następnie usunąć to, co zostało zastosowane, obiekty Secret i plik sesji:

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 zachowuje żądania woluminów utworzone przez StatefulSet, gdy StatefulSet zostaje usunięty, dlatego trzecie polecenie usuwa je, a wraz z nimi bazę danych, zainstalowaną wtyczkę i magazyn wektorów. W Docker Compose docker compose -p support-assistant -f ../dist/boundaries/platform/compose/docker-compose.yaml down -v usuwa stos i jego woluminy.

W Docker Compose

Tę samą aplikację importuje się dla Docker Compose z celem compose, z tego samego pliku odpowiedzi. Szkice dla Kubernetes są już w source, więc szkice dla Compose należy zapisać w osobnym folderze za pomocą --output-dir; import i tak odczytuje plik odpowiedzi leżący obok aplikacji:

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

Docker Compose nie ma obiektu Secret, który można by wskazać, więc dla compose szkic sam zapisuje sekret aplikacji i hasło właściciela, każde jako odwołanie do zmiennej, które Docker Compose wypełnia ze środowiska osoby uruchamiającej stos. Wymagany jest tam tylko adres e-mail właściciela. Import zachowuje dwie nazwy obiektów Secret w pliku odpowiedzi, nie stosując ich, i informuje o tym na standardowym wyjściu błędów:

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

Szkic encji Release odczytuje sekret aplikacji z DIFY_SECRET_KEY, a hasło właściciela z DIFY_OWNER_PASSWORD, i publikuje API na porcie 5001, a frontend, console, na porcie 3001 adresu pętli zwrotnej:

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

Każdy port jest osiągalny tylko z własnego komputera, jak mówi jego komentarz, a usunięcie wiersza pozostawia tę usługę wyłącznie w sieci stosu. Frontend nasłuchuje na 3000 wewnątrz swojego kontenera i jest publikowany na 3001, więc może działać obok innego przykładu publikującego 3000. console_url serwera API to adres, pod którym publikowany jest frontend, więc port zmieniony dla frontendu zmienia się także tam.

Encja Manifest mapuje każdy komponent na jego encję Recipe dla Compose, a core/referenced-secret na compose/dotenv-referenced-secret, który zapisuje każde odwołanie do pliku Compose w niezmienionej postaci. Należy zwalidować i skompilować z nowego folderu:

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

Kompilacja zapisuje w dist w katalogu głównym obszaru roboczego, a obszarem roboczym nadal jest source, folder zawierający .aggrega-config.yaml: plik Compose to source/dist/boundaries/platform/compose/docker-compose.yaml, czyli z compose jest to ../dist/boundaries/platform/compose/docker-compose.yaml, a wewnątrz compose nie powstaje żaden folder dist. Plik zawiera SECRET_KEY: ${DIFY_SECRET_KEY} i OWNER_PASSWORD: ${DIFY_OWNER_PASSWORD} zamiast którejkolwiek z wartości. Przed uruchomieniem stosu należy ustawić obie zmienne w powłoce lub w pliku .env obok pliku Compose.

Cztery pozostałe dane uwierzytelniające instalacji zachowują wartości domyślne nadane im przez core/dify, a w Docker Compose każda wartość domyślna jest samą wartością, zapisaną do pliku Compose w niezmienionej postaci: DB_PASSWORD: dify-db-password-for-evaluation-only, z takim samym POSTGRES_PASSWORD w bazie danych, i podobnie dify-code-execution-key-for-evaluation-only, dify-plugin-daemon-key-for-evaluation-only oraz dify-inner-api-key-for-evaluation-only. Każdy czytelnik katalogu zna te wartości domyślne, więc służą one wyłącznie do ewaluacji. Aby zastąpić jedną z nich, należy zadeklarować dla niej parametr typu string w szkicu encji Aggregate, przekazać go w parameters wpisu dify pod nazwą, jaką nadaje mu core/dify — db_password, code_execution_key, plugin_daemon_key lub inner_api_key — tak jak szkic przekazuje secret_key, i wypełnić go w parameters encji Release. Encja Release zapisująca db_password: "${DIFY_DB_PASSWORD}" buduje plik Compose zawierający DB_PASSWORD: ${DIFY_DB_PASSWORD} i POSTGRES_PASSWORD: ${DIFY_DB_PASSWORD}, wypełniane ze środowiska tak jak dwie powyższe.

Należy uruchomić stos z compose, z hasłem właściciela akceptowanym przez Dify, jak opisuje Uruchomienie:

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

W tym uruchomieniu --wait zakończyło się po około minucie, gdy każdy serwer zgłosił, że jest zdrowy. Krok importujący aplikację działa obok nich i kończy się po wykonaniu importu; jego log brzmi wtedy:

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

Testowanie łączy się z instalacją przez dwa opublikowane porty.