34 Bundles und CI/CD (Vorschau)

Bundles definieren, wie Oracle AI Data Platform Workbench-Ressourcen in Workspaces und Umgebungen gepackt, versioniert, gemeinsam genutzt und bereitgestellt werden.

Sie können Bundles für Jobs und Agents erstellen. Ein Bundle wird in einem Git-Ordner erstellt, sodass die Bundle-Dateien festgeschrieben und in ein Git-Repository übertragen werden können. Die Ressourcen, die Sie in das Bundle aufnehmen, können von einem beliebigen Speicherort im Workspace stammen. Wenn die ausgewählten Ressourcen unterstützende Dateien oder Abhängigkeiten wie Notizbücher, Skripte oder Compute referenzieren, sind diese Referenzen im Bundle enthalten, sodass die Ressourcen in einer anderen Umgebung bereitgestellt werden können, ohne dieselben Komponenten manuell neu zu erstellen.

Sie erstellen Bundles aus Ihrem Workspace und wählen die Oracle AI Data Platform Workbench-Ressourcen aus, die zum Zeitpunkt der Erstellung aufgenommen werden sollen. Vorhandene Bundles können geändert werden, um Ressourcen hinzuzufügen oder zu entfernen. Durch das Zusammenfassen von Ressourcen können Sie zugehörige Jobs und Agents zusammenfassen und in anderen Umgebungen bereitstellen, wobei deren Abhängigkeiten intakt sind.

Sie können Bundles über Ihre Git-Ordner festschreiben und in Ihr Git-Repository pushen. Anschließend können Benutzer die Bundles in ihre eigenen Umgebungen ziehen und bereitstellen. Änderungen an Bundle-Dateien sind in anderen Umgebungen verfügbar, nachdem die Änderungen festgeschrieben und an das Git-Repository übertragen wurden. Wenn Benutzer das aktualisierte Bundle aus dem Git-Repository abrufen, erhalten sie die neuesten festgeschriebenen Ressourcendateien.

Bundle-Konzepte

Konzept Bedeutung Benutzeraktion
Git-Ordner Ein AI Data Platform-Ordner, der mit einem Git-Repository und einer Verzweigung verbunden ist. Bundles können nur in Git-Ordnern erstellt werden. Erstellen oder öffnen Sie einen Git-Ordner, bevor Sie ein Bundle erstellen.
Bündel Ein bereitstellbares Package, das die ausgewählten Ressourcen und ihre Abhängigkeiten definiert. Erstellen Sie das Bundle aus dem Workspace, und wählen Sie dann Ressourcen wie Jobs oder Agent-Abläufe aus.
Bundle-Inhalt Generierte Dateien, die Ressourcen, Variablen, Zieleinstellungen und Artefakte beschreiben, die für das Deployment erforderlich sind. Prüfen Sie generierten Inhalt nach dem Erstellen oder Synchronisieren. Schreiben Sie das Bundle fest, und pushen Sie es, wenn Sie bereit sind.
Target Eine Umgebung oder Workspace-Konfiguration, die beim Deployment des Bundles außerhalb der Quellumgebung verwendet wird. Geben Sie Werte an, die sich nach Umgebung ändern müssen, wie Workspace-Schlüssel, Zugangsdatenname, Tokenschlüssel oder Parameterstandardwerte.
Bereitgestelltes Element Eine Ressource, die von einem Bundle-Deployment im Ziel-Workspace erstellt oder aktualisiert wurde. In der Registerkarte "Deployment" können Sie bereitgestellte Elemente bereitstellen, prüfen, Jobs ausführen und bereitgestellte Ressourcen bei Bedarf löschen.
Synchronisierung Eine Bundle-Aktion, die Bundle-Ressourcen und -Abhängigkeiten aus den neuesten Quellressourcen aktualisiert. Führen Sie die Synchronisierung aus, nachdem Sie gebündelte Ressourcen geändert haben, und schreiben Sie die aktualisierten Bundle-Dateien dann in Git fest.

Bevor Sie beginnen

Aktivieren Sie diese Liste, um sicherzustellen, dass Sie alles haben, was Sie für die Verwendung von Git-Bundles in Ihrem AI Data Platform-Workspace benötigen:
  • Erstellen Sie Git-Zugangsdaten und einen Git-Ordner, der auf das Repository und die Verzweigung verweist, die für Bundle-Dateien verwendet werden.
  • Bestätigen Sie, dass sich die Quellressourcen im Workspace befinden und gespeichert werden, bevor Sie das Bundle erstellen oder synchronisieren.
  • Stellen Sie bei einem umgebungsübergreifenden Deployment sicher, dass der Ziel-Workspace über die erforderlichen Berechtigungen und Compute-Kapazität verfügt.
  • Erstellen Sie für Jobs oder Notizbücher, die Secrets verwenden, die erforderlichen benannten Zugangsdaten im Zielzugangsdatenspeicher. Bundle-Dateien müssen Zugangsdaten nach Name oder Variable referenzieren und keine Secret-Werte enthalten.
  • Speichern und übertragen Sie Änderungen an Bundle-Dateien, nachdem Sie ein Bundle erstellt oder synchronisiert haben, damit andere Umgebungen die neueste Bundle-Definition abrufen können.

Veröffentlichungspfade für Bundle

Bundles können Laufzeitartefakte in einem Workspace-Ordner veröffentlichen, den Benutzer prüfen können. Laufzeitartefakte umfassen Dateien wie Notizbücher, Skripte, Librarys und Agent-Flowdateien, die von bereitgestellten Bundle-Ressourcen benötigt werden. Der Ordner, in dem Artefakte veröffentlicht werden, wird als Veröffentlichungspfad bezeichnet. Artefakte werden unter einem Artefaktordner im Veröffentlichungspfad gespeichert.

Beispiel: Wenn der Veröffentlichungspfad /Workspace/Shared/customer_churn_bundle lautet, werden die Bundle-Artefakte unter /Workspace/Shared/customer_churn_bundle/artifacts veröffentlicht.

Der Veröffentlichungspfad ist nicht die Quelle der Wahrheit für das Bundle. Die Bundle-Quelldateien verbleiben im Bundle-Ordner und sollten in Git festgeschrieben werden. Dateien unter dem Veröffentlichungspfad sind Laufzeitdateien, die von bereitgestellten Ressourcen verwendet werden. Wenn Sie Dateien unter dem Veröffentlichungspfad manuell bearbeiten, werden diese Änderungen nicht in die Bundle-Quelle zurückgeschrieben. Bei einem späteren Deployment können die veröffentlichten Artefakte durch Dateien aus dem Bundle ersetzt werden.

Bundle erstellen (Vorschau)

Sie können Oracle AI Data Platform-Job- und Agent-Ressourcen bündeln, um ein Package zu erstellen, das in einem anderen Git-Ordner bereitgestellt werden kann.

  1. Navigieren Sie zu Ihrem Workspace.
  2. Klicken Sie auf Aktionen und dann auf Bundle erstellen.
  3. Geben Sie einen Namen und die Beschreibung für das Bundle an.
  4. Klicken Sie auf Durchsuchen, und wählen Sie den Git-Ordner in Ihrem Workspace aus, in dem Sie das Bundle erstellen möchten.
  5. Wählen Sie die Ressourcen aus, die Sie in das Bundle aufnehmen möchten.
  6. Klicken Sie auf Create.

    Hinweis:

    Bundles werden in Git-Ordnern erstellt. Wenn sich der ausgewählte Speicherort nicht in einem Git-Ordner befindet, können Sie Git nicht verwenden, um die generierten Bundle-Dateien in eine andere Umgebung zu verschieben.

    Hinweis:

    Wenn ein Bundle erstellt wird, kann AI Data Platform eine Standardveröffentlichungskonfiguration im Bundle-Manifest enthalten. Die Veröffentlichungskonfiguration steuert, wo Laufzeitartefakte platziert werden, wenn das Bundle bereitgestellt wird.

Was wird nach der Bundle-Erstellung generiert (Vorschau)

Nach der Bundle-Erstellung schreibt Oracle AI Data Platform Ihre generierten Dateien in den Bundle-Ordner.

Die genauen Dateinamen variieren je nach Ressourcentyp, aber das erstellte Bundle enthält normalerweise ein Bundle-Manifest der obersten Ebene, Ressourcendefinitionen, Artefaktordner und optionale Override-Dateien.

Generierter Artikel Beschreibung
aidp_workbench.yaml Bundle-Manifest. Identifiziert das Bundle, enthaltene Ressourcen, Variablen und Zielabschnitte, die beim Deployment verwendet werden.
.aidp/resource_origins.yaml Ressourcendefinitionen Beschreiben Sie Ressourcen wie Jobs, Notizbuchaufgaben, Compute-Referenzen oder Agent-Abläufe.
.aidp/overrides.yaml Dateien oder Zielabschnitte überschreiben Halten Sie Werte fest, die sich je nach Umgebung unterscheiden, wie Workspace-IDs, Parameterstandardwerte, Zugangsdatennamen oder Tokenschlüssel.
.aidp/aidp.state.json Verfolgt die aus dem Bundle bereitgestellten Ressourcen. Wird von zukünftigen Bereitstellungs- und Löschvorgängen verwendet.
jobs/ Jobdeskriptoren und Jobabhängigkeiten.
agentflows/ Agent-Deskriptoren und Agent-Abhängigkeiten.
artifacts/ Artefaktordner. Code, Notizbücher und unterstützende Dateiartefakte kopiert.

Pfadkonfiguration veröffentlichen (Vorschau)

Sie können den Veröffentlichungspfad für ein Bundle in der Bundle-Manifestdatei aidp_workbench.yaml konfigurieren.

Um den Veröffentlichungspfad für eine Bundle-Datei zu konfigurieren, fügen Sie einen Veröffentlichungsblock unter defaults in der Manifestdatei aidp_workbench.yaml hinzu, wie in diesem Beispiel: 

bundle:
  name: customer_churn_bundle
  description: Customer churn model workflow

resources:
  jobs:
    - train_churn_model
  agentflows:
    - explain_churn_predictions

defaults:
  publish:
    path: "/Workspace/Shared/customer_churn_bundle"
    overwrite_publish_artifacts: false

Wenn das Bundle bereitgestellt wird, werden Artefakte in diesem Beispiel unter /Workspace/Shared/customer_churn_bundle/artifacts veröffentlicht.

Tabelle 34-1: Felder für Veröffentlichungspfadkonfiguration

Feld Beschreibung
path Workspace-Ordner, der als Veröffentlichungshauptverzeichnis verwendet wird. Artefakte werden unter <path>/artifacts gespeichert.
overwrite_publish_artifacts Gibt an, ob das Deployment vorhandene veröffentlichte Artefakte im konfigurierten Veröffentlichungspfad ersetzen kann.

Pfadkonfiguration für verschiedene Umgebungen veröffentlichen

Sie können verschiedene Veröffentlichungspfade für verschiedene Deployment-Ziele konfigurieren, wie in diesem Beispiel:

bundle:
  name: customer_churn_bundle

resources:
  jobs:
    - train_churn_model

defaults:
  publish:
    path: "/Workspace/Shared/customer_churn_bundle"
    overwrite_publish_artifacts: false

targets:
  prod:
    - aidp_ocid: "ocid1.aidataplatform.oc1..example"
      workspace_key: "workspace-prod"
      publish:
        path: "/Workspace/Production/customer_churn_bundle"
        overwrite_publish_artifacts: true

Alternativ können Sie den Veröffentlichungspfad mit .aidp/overrides.yaml lokal außer Kraft setzen: 

publish:
  path: "/Workspace/Users/me/customer_churn_bundle"
  overwrite_publish_artifacts: true
Wenn mehrere Veröffentlichungspfade konfiguriert sind, löst Oracle AI Data Platform den Veröffentlichungspfad in der folgenden Reihenfolge auf:
  1. defaults.publish.path in aidp_workbench.yaml
  2. Pfad für übereinstimmende Zielveröffentlichung
  3. .aidp/overrides.yaml Veröffentlichungspfad

Veröffentlichung von Bundle-Artefakten (Vorschau)

Wenn Sie ein Bundle bereitstellen, kopiert Oracle AI Data Platform die Bundle-Artefakte aus der Bundle-Quelle in den aufgelösten Veröffentlichungspfad.

Das Standardartefaktlayout ist <publish.path>/artifacts. Beispiel: 

/Workspace/Shared/customer_churn_bundle/artifacts

Bundle-Deskriptordateien können veröffentlichte Artefakte mit ${publish.path}/artifacts/... referenzieren. Beispiel: 

${publish.path}/artifacts/Notebooks/train_model.ipynb

Während des Deployments wird ${publish.path} in den konfigurierten Veröffentlichungspfad aufgelöst.

Bundle bereitstellen (Vorschau)

Sie können Bundles aus einem Git-Ordner bereitstellen, um Ressourcen und Abhängigkeiten über Workspaces und Umgebungen hinweg gemeinsam zu nutzen.

  1. Navigieren Sie zu dem Bundle, das Sie in Ihrem Workspace bereitstellen möchten.
  2. Klicken Sie auf die Registerkarte "Deployment".
  3. Optional: Prüfen Sie ggf. Zielwerte und Überschreibungen.
  4. Klicken Sie auf Bereitstellen. Sie werden benachrichtigt, wenn das Deployment abgeschlossen ist.

    Hinweis:

    Beim ersten Deployment kann die Registerkarte Deployment keine bereitgestellten Elemente anzeigen, bis das Deployment erfolgreich ist. Prüfen Sie nach einem erfolgreichen Deployment die bereitgestellten Ressourcen, führen Sie Jobs oder Agents nach Bedarf aus, und bestätigen Sie die Laufzeitausgabe.

    Hinweis:

    Beim Deployment werden Bundle-Artefakte im konfigurierten Veröffentlichungspfad veröffentlicht, bevor Ressourcen bereitgestellt werden. Wenn kein benutzerdefinierter Veröffentlichungspfad konfiguriert ist, verwendet Oracle AI Data Platform den Standardveröffentlichungsspeicherort für das Bundle.

Bereitstellen von Bundles für veröffentlichte Pfade (Vorschau)

Wenn für ein Bundle ein Veröffentlichungspfad konfiguriert ist, führt das Deployment eine feste Gruppe von Aktionen aus.

Die Aktionen, die Oracle AI Data Platform beim Deployment eines Bundles mit einem konfigurierten Veröffentlichungspfad ausführt, finden in der folgenden Reihenfolge statt:

  1. Prüfen Sie den Veröffentlichungspfad.
  2. Bundle-Artefakte in <publish.path>/artifacts veröffentlichen.
  3. Stellen Sie Bundle-Ressourcen wie Jobs und Agent-Abläufe mithilfe der veröffentlichten Artefaktpfade bereit.
  4. Aktualisieren Sie den Deployment-Status nach Abschluss des Deployments.

Verschiedene Aktionen können stattfinden, wenn AI Data Platform Probleme mit dem Veröffentlichungspfad erkennt:

  • Wenn der Veröffentlichungspfad nicht vorhanden ist, kann AI Data Platform ihn während des Deployments erstellen.
  • Wenn der Veröffentlichungspfad vorhanden ist und leer ist, kann er vom Deployment verwendet werden.
  • Wenn der Veröffentlichungspfad Artefakte enthält, die von demselben Bundle verwaltet werden, kann das Deployment sie aktualisieren.
  • Wenn der Veröffentlichungspfad Daten enthält, die nicht zum Bundle gehören, kann das Deployment fehlschlagen, es sei denn, das Überschreiben ist aktiviert.

Bundle synchronisieren (Vorschau)

Sie können ein Bundle synchronisieren, um die Ressourcen und Abhängigkeiten im Bundle mit den neuesten Änderungen zu aktualisieren.

Sync verwendet die aufgezeichneten Ursprungsmetadaten des Bundles, um das Bundle aus den Quelljobs und Agentflüssen neu zu erstellen, die beim Erstellen des Bundles erfasst wurden. Die Quellmetadaten werden in .aidp/resource_origins.yaml gespeichert und müssen mit der angeforderten Instanz und dem angeforderten Workspace übereinstimmen. Der Vorgang aktualisiert quellkontrollierten Bundle-Inhalt, während die Bundle-Identität und Laufzeitmetadaten beibehalten werden.

Während der Synchronisierung stellt der Service einen aktualisierten Bundle Snapshot unter dem Bundle-Verzeichnis .aidp bereit, vergleicht vorhandene und zwischengespeicherte Deskriptoren, behält vorhandene Variablenaliasnamen bei und setzt Referenzen nach Möglichkeit außer Kraft, führt vorhandene Manifeststandardvariablen zusammen und stuft dann die aktualisierten quellkontrollierten Dateien wieder in der Bundle Root hoch.

Durch die Synchronisierung werden umgebungsspezifische und Deployment-Laufzeitdateien wie .aidp/overrides.yaml und .aidp/aidp.state.json beibehalten. Diese Dateien werden nicht durch den aktualisierten Quell-Snapshot ersetzt.

Synchronisieren Sie Ihre Bundles in folgenden Situationen:
  • Ein gebündeltes Notizbuch, ein Job, ein Agent-Ablauf, eine Compute-Referenz, ein Parameter oder eine Abhängigkeit im Quell-Workspace geändert.
  • Ein gebündelter Job verweist jetzt auf ein anderes Notizbuch oder hat aktualisierte Aufgabenparameter.
  • Agent-Konfiguration, Prompt-Parameter, Modelleinstellung oder AI-Compute-Abhängigkeit geändert.
  • Sie müssen den Git-Ordner mit den zuletzt generierten Bundle-Dateien vor dem Push in eine andere Umgebung verwenden.
  1. Navigieren Sie zu dem Bundle, das Sie in Ihrem Workspace synchronisieren möchten.
  2. Klicken Sie auf Aktionen.
  3. Klicken Sie auf Synchronisieren. Sie werden benachrichtigt, wenn die Synchronisierung abgeschlossen ist.

Empfohlener Promotionworkflow für Bundles (Vorschau)

Wir empfehlen die Befolgung eines Workflows für Entwicklung, Package, Versionierung, Pull, Konfiguration, Bereitstellung und Validierung für Bundles in Oracle AI Data Platform.

Phase Aktion Ergebnis
Entwickeln Erstellen oder aktualisieren Sie Notizbücher, Jobs, Compute-Einstellungen oder Agent-Abläufe im Quell-Workspace. Die Quellressourcen enthalten das neueste beabsichtigte Verhalten.
Package Erstellen Sie das Bundle, oder führen Sie Sync für ein vorhandenes Bundle aus. Generierte Bundle-Dateien spiegeln die aktuellen Quellressourcen und Abhängigkeiten wider.
Version Prüfen, festschreiben und pushen Sie den Bundle-Ordner über den Git-Ordner. Das Remote Repository enthält die Definition des bereitstellbaren Bundles.
Pull Rufen Sie im Zielarbeitsbereich die Änderungen des Git-Ordners ab. Der Ziel-Workspace enthält die neuesten Bundle-Dateien.
Konfigurieren Legen Sie zielspezifische Werte fest, wie Workspace-Schlüssel, Parameterstandardwerte, Zugangsdatenname, Tokenschlüssel oder Laufzeiteinstellungen. Das Bundle ist bereit für die Zielumgebung.
Stellen Sie Öffnen Sie die Registerkarte "Deployment" des Bundles, und klicken Sie auf "Bereitstellen". Workbench erstellt oder aktualisiert die bereitgestellten Ressourcen.
Validieren Führen Sie bereitgestellte Jobs aus, oder testen Sie bereitgestellte Agent-Abläufe, und prüfen Sie Logs oder Ausgaben. Die Zielumgebung wird geprüft, bevor die Hochstufung fortgesetzt wird.

Bundle-Variablen (Vorschau)

Verwenden Sie Bundle-Variablen, wenn ein Bundle Deployment-Zeitwerte benötigt, die sich für jede Zielumgebung ändern können, ohne die Ressourcendefinition zu bearbeiten.

Um Variablen mit Bundles zu verwenden, müssen Sie die Variablennamen in der Datei aidp_workbench.yaml des Bundles mit Standardwerten und bei Bedarf umgebungsspezifischen Überschreibungen definieren. Anschließend referenzieren Sie diese Variablen aus generierten Definitionsdateien.

Beispiel für einen Variablenworkflow

  1. Definieren Sie Variablennamen unter defaults > variables in aidp_workbench.yaml.
  2. Definieren Sie optional umgebungsspezifische Werte unter targets > <environment> > variables in derselben Datei aidp_workbench.yaml.
  3. Verwenden Sie Ziel-Overrides, um Deployment-Zeitwerte festzulegen, wie Entwicklungsregion, QS-Region, Produktionsregion, Schemaname, Zugangsdatenname, Tokenschlüssel oder Parameterstandard.
  4. Wenn keine übereinstimmende Zielumgebung gefunden wird, verwendet Oracle AI Data Platform den Standardwert der Variablen aus aidp_workbench.yaml.
  5. Verwenden Sie die Variable in einer generierten Definitionsdatei, z.B. einer Jobdefinition, Compute-Definition, Aufgabendefinition oder einer anderen YAML-Definitionsdatei.
  6. Referenzieren Sie die Variable mit ${var.<<variable_name>>}, und ersetzen Sie <<variable_name>> durch den tatsächlichen Variablennamen, der in aidp_workbench.yaml definiert ist.
  7. Verwenden Sie ressourcenspezifische Platzhaltersyntax an Stellen wie Agent-Prompts oder Tooldefinitionen, wenn die UI einen benannten Platzhalter erwartet.
  8. Erstellen Sie .aidp/overrides.yaml, und definieren Sie dort Variablenwerte für temporäre Änderungen, die nur für das Deployment gelten.

Bundle-Variablensyntax

Variablendefinitionen müssen in aidp_workbench.yaml geschrieben werden. Andere Bundle-Definitionsdateien dürfen nur den Variablennamen referenzieren.

Definition Syntax Beispiel
Variablendefinition in aidp_workbench.yaml 
defaults: 
  variables: 
    <<variable_name>>: <<default_value>> 
defaults: 
  variables: 
    deployment_region: "us-ashburn-1"
Zielspezifisches Override inaidp_workbench.yaml 
targets: 
  <<target_name>>: 
    variables: 
      <<variable_name>>: <<target_value>> 
targets: 
  qa: 

   “workbenchid”: “ocid” 
   “workspaceKey”: “key” 

    variables: 
      deployment_region: "us-phoenix-1"
Variablenreferenz in einer Definitionsdatei ${var.<<variable_name>>} value: "${var.deployment_region}"
Benannter Platzhalter in einem Agent-Prompt oder Toolfeld {{variable_name}} Generate a summary about {{topic}}.

Beispiel: Jobparametervariable

Im folgenden Beispiel wird eine Variable definiert und an einen Jobparameter übergeben. Die Ressource kann unverändert bleiben, während sich der Variablenwert in der Bundle-Konfiguration ändert.
bundle: 
  name: namedVariableJobDemo 
resources: 
  jobs: 
    - namedVariableJobDemo 
defaults: 
  variables: 
    job_param_value_default: "cloud data governance" 

jobs: 
  namedVariableJobDemo: 
    tasks: 
      - taskKey: Task_956691 
        parameters: 
          - name: param_key 
            value: "${var.job_param_value_default}"

Eine Notizbuchaufgabe kann den aufgelösten Wert über den vom Job verwendeten Parameternamen lesen:

param_value = odiUtils.parameters.getParameter("param_key", "fallback value") 
print(param_value)

Beispiel: Variablendefinition aidp_workbench.yaml

In diesem Beispiel wird die Variable agent_topic_default in aidp_workbench.yaml definiert. Der Standardwert wird angewendet, wenn keine übereinstimmende Zielumgebung gefunden wird oder wenn keine ausgewählte Umgebung oder kein temporäres Override die Variable bereitstellt. Jedes Ziel kann denselben Variablennamen für diesen Workspace außer Kraft setzen.
defaults: 
  variables: 
    agent_topic_default: "Oracle AI Data Platform" 

targets: 
  dev: 
    - aidp_ocid: "ocid1.aidataplatformdev.oc1.iad.exampledev" 
      workspace_key: "6271b138-6f2c-4e8c-a9e5-013e17079955" 
      variables: 
        agent_topic_default: "AIDP Dev Workspace" 
  qa: 
    - aidp_ocid: "ocid1.aidataplatformdev.oc1.iad.exampleqa" 
      workspace_key: "daa0e9b5-f8d7-4ae8-b728-2984e68a74c0" 
      variables: 
        agent_topic_default: "AIDP QA Workspace" 
  prod: 
    - aidp_ocid: "ocid1.aidataplatform.oc1.iad.exampleprod" 
      workspace_key: "83be5b8c-bb8d-4ec4-a8fb-16b50b0e4d4c" 
      variables: 
        agent_topic_default: "AIDP Production Workspace"

Jede Bundle-Definitionsdatei, die Bundle-Variablen unterstützt, kann dann denselben Variablennamen referenzieren. Beispiel:

tasks/agentTopic.task.yaml 

parameters: 
  - name: topic 
    value: "${var.agent_topic_default}"

Beispiel: Dateinamen und Auflösung

In einem generierten Bundle können sich die Variablendefinition und die Ressource, die diese Variable verwendet, in verschiedenen Dateien befinden. Wenn Sie das Beispiel über Git hochstufen oder kopieren, schließen Sie den gesamten Bundle-Ordner ein, damit Manifest, Jobdefinition und Artefakte zusammen bleiben. 
testNamedVarBundleJob/ 
  aidp_workbench.yaml 
  jobs/ 
    namedVariableJobDemo.job.json 
  artifacts/ 
    namedVarNotebookDemo.ipynb
Datei Was es enthält Variablen- oder Lösungswert
aidp_workbench.yaml Definiert die Variable unter Standardwerte > Variablen und optionale Zielüberschreibungen. Variable: job_param_value_default.
jobs/namedVariableJobDemo.job.json Verwendet die Variable als Wert für den Jobparameter param_key. Referenz: ${var.job_param_value_default}.
artifacts/namedVarNotebookDemo.ipynb Liest den aufgelösten Jobparameter zur Laufzeit. Das Notizbuch liest param_key nach der Auflösung.
Beispiel: Das Bundle-Manifest kann die Standard- und Zielüberschreibungen in aidp_workbench.yaml definieren:
defaults: 
  variables: 
    job_param_value_default: "cloud data governance" 
targets: 
  dev: 
    variables: 
      job_param_value_default: "space tourism" 
  qa: 
    variables: 
      job_param_value_default: "data quality validation" 
  prod: 
    variables: 
      job_param_value_default: "customer operations"

Die Jobdefinition kann dann denselben Variablennamen in jobs/namedVariableJobDemo.job.json verwenden. Die gleiche Syntax kann in Jobdefinitionen, Compute-Definitionen, Aufgabendefinitionen und anderen generierten YAML-Definitionsdateien verwendet werden, die Bundle-Variablen unterstützen:

"parameters": [ 
  { 
    "name": "param_key", 
    "value": "${var.job_param_value_default}" 
  } 
]
Deployment-Ziel Variablenauflösung Notebook-Empfänger
Kein übereinstimmendes Ziel Verwendet den Standardwert aus aidp_workbench.yaml. param_key = cloud data governance
Dev Verwendet Dev-Zielüberschreibung. param_key = space tourism
QA Verwendet QA-Zielüberschreibung. param_key = data quality validation
Produkt Verwendet Prod-Zielüberschreibung. param_key = customer operations

Lösungsreihenfolge

Wenn .aidp/overrides.yaml einen Variablenwert angibt, verwendet AI Data Platform diesen temporären Wert für das nächste Deployment. Andernfalls löst AI Data Platform die Variable zuerst aus dem ausgewählten Ziel auf. Wenn keine übereinstimmende Zielumgebung gefunden wird oder das ausgewählte Ziel die Variable nicht außer Kraft setzt, wird AI Data Platform in aidp_workbench.yaml auf defaults > variables zurückgesetzt. Wenn kein Wert für die referenzierte Variable verfügbar ist, kann das Deployment oder die Jobausführung fehlschlagen, bevor der Notizbuch-Fallback-Wert verwendet wird.

Temporäre Überschreibungen für das nächste Deployment

Die Definitionen in aidp_workbench.yaml reichen für die normale Bundle-Promotion aus. Wenn ein Benutzer eine Variable vorübergehend außer Kraft setzen muss, erstellen Sie .aidp/overrides.yaml im Bundle-Ordner und definieren die Variablenwerte dort. AI Data Platform verwendet diese Werte beim nächsten Deployment. 

.aidp/ 
  overrides.yaml
variables: 
  agent_topic_default: "tuesday"
Datei Beispielwert Verwendung
aidp_workbench.yaml defaults Oracle AI Data Platform Wird verwendet, wenn keine übereinstimmende Ziel- oder Override-Datei die Variable bereitstellt.
aidp_workbench.yaml target dev AIDP-Entwicklungsarbeitsbereich Wird beim Deployment in Entwicklungsumgebung verwendet, und es ist keine temporäre Überschreibung vorhanden.
.aidp/overrides.yaml Dienstag Wird als temporärer Wert beim nächsten Deployment verwendet.

Hinweis:

Verwenden Sie .aidp/overrides.yaml für temporäre Deployment-Werte. Behalten Sie dauerhafte Standardwerte und umgebungsspezifische Werte in aidp_workbench.yaml bei, damit das Bundle über Git reproduzierbar bleibt.

Beispiel: Agent Prompt-Variable

Verwenden Sie für Prompt-Text oder Tooldefinitionen des Agent-Ablaufs, die benannte Platzhalter unterstützen, doppelte Klammern um den Variablennamen.

Prompt text: 
You are a demo assistant. For the given {{topic}}, generate 3 short bullet points explaining why it matters. 

Tool parameter: 
Name: /{{topic}} 
Default value: sunday

Hinweis:

Als Best Practice sollten Sie Variablen für Werte verwenden, die sich voraussichtlich zwischen Deployments ändern. Vermeiden Sie es, umgebungsspezifische Werte direkt in Notizbücher, Jobs oder Agent-Flow-Text einzubetten, wenn eine Variable den Wert stattdessen übernehmen kann.

Beispiel: Workflow ohne Compute

Sie können ein Bundle für einen Workflow erstellen, der im Rahmen des Deployments nicht automatisch ein Compute-Cluster erstellt. Erstellen Sie zunächst eine Variable in aidp_workbench.yaml: 

defaults:
 variables:
  job_compute_key: "select_compute"
Suchen Sie als Nächstes im Ordner jobs/ die Jobdatei <JobName>.job.json. Bearbeiten Sie die Jobdatei, und ersetzen Sie den Wert "clusterKey" durch die neu erstellte Variable:
"clusterKey" : "${var.job_compute_key}",

Benannte Variablen in Umgebungen (Vorschau)

Mit benannten Umgebungsvariablen kann Ihr Git-Bundle dieselben logischen Variablennamen beibehalten, während jede Umgebung ihre eigenen Bereitstellungszeitwerte bereitstellt.

Verwenden Sie dieses Muster, wenn eine Entwicklungsregion, eine QS-Region und eine Produktionsumgebung dieselben Ressourcendefinitionen mit unterschiedlichen Werten bereitstellen sollen.

Beispielworkflow mit benannter Variable

  1. Definieren Sie die Variable einmal unter defaults > variables in aidp_workbench.yaml.
  2. Überschreiben Sie denselben Variablennamen unter jeder Zielumgebung.
  3. Mit dem Ziel bereitstellen, dessen Variablenwerte mit dem Ziel-Workspace übereinstimmen
  4. Verwenden Sie Standardwerte für sichere Fallback-Werte, nicht für Production Secrets oder Workspace-spezifische IDs.

Beispiel: Dev-, QS- und Produktüberschreibungen

Im folgenden Beispiel werden dieselben Variablennamen über drei Ziele hinweg verwendet. Der Job referenziert die Variablen weiterhin einmal, während die Entwicklungsregion, die QS-Region und die Produktionsumgebung unterschiedliche Bereitstellungszeitwerte bereitstellen. 

bundle: 
  name: environmentVariableDemoBundle 
resources: 
  jobs: 
    - namedVariableJobDemo 
defaults: 
  variables: 
    job_param_value_default: "cloud data governance" 
    deployment_region: "us-ashburn-1" 
targets: 
  dev: 
    aidp_ocid: "ocid1.aidataplatformdev.oc1.iad.exampledev" 
    workspace_key: dev_workspace 
    variables: 
      job_param_value_default: "space tourism" 
      deployment_region: "us-ashburn-1" 
  qa: 
    aidp_ocid: "ocid1.aidataplatformdev.oc1.iad.exampleqa" 
    workspace_key: qa_workspace 
    variables: 
      job_param_value_default: "data quality validation" 
      deployment_region: "us-phoenix-1" 
  prod: 
    aidp_ocid: "ocid1.aidataplatformdev.oc1.iad.exampleprod" 
    workspace_key: prod_workspace 
    variables: 
      job_param_value_default: "customer operations" 
      deployment_region: "eu-frankfurt-1"
Target Deployment-Region job_param_value_default Laufzeitergebnis
Dev us-ashburn-1 Weltraumtourismus Jobläufe mit Entwicklungsregion und Parameterwerten.
QA us-phoenix-1 Datenqualitätsvalidierung Jobläufe mit QS-Teilsektor und Parameterwerten.
Produkt eu-frankfurt-1 Kundenvorgänge Job wird mit Produktionsumgebungswerten ausgeführt.

Hinweis:

Wenn keine übereinstimmende Zielumgebung gefunden wird oder wenn ein Ziel keinen Override definiert, verwendet Workbench den konfigurierten Standardvariablenwert, sofern vorhanden. Wenn weder ein Override noch ein gültiger Standardwert verfügbar ist, kann die Deployment- oder Laufzeitausführung fehlschlagen, je nachdem, wo die fehlende Variable verwendet wird.

Bundle-Variablen und Zugangsdatenspeicher (Vorschau)

Sie können Variablen mit dem Zugangsdatenspeicher verwenden, wenn ein gebündelter Job oder Notizbuch zur Laufzeit ein Secret suchen muss.

Ihre Variablen müssen den Zugangsdatennamen und den Tokenschlüssel enthalten. Der tatsächliche Secret-Wert muss im Zielzugangsdatenspeicher verbleiben und darf nicht in Git festgeschrieben werden.

Beispielworkflow: Variablen mit Zugangsdatenspeicher verwenden

  1. Erstellen Sie Zugangsdaten und den Tokenschlüssel im Zugangsdatenspeicher.
  2. Definieren Sie Variablen für den Zugangsdatennamen und den Tokenschlüssel.
  3. Übergeben Sie diese Variablen als Parameter an den Job oder das Notizbuch.
  4. Zur Laufzeit liest das Notizbuch die Parameter und ruft die Zugangsdaten-API auf, um das Secret abzurufen. Wenn der Zugangsdatenname, der Tokenschlüssel oder die Berechtigungen falsch sind, kann der Job mit einem Fehler bei der Zugangsdatensuche nicht erfolgreich ausgeführt werden.

Hinweis:

Dokumentieren oder speichern Sie keine Secret-Werte in Bundle-Dateien. Die Bundle-Konfiguration muss Zugangsdatennamen, Tokenschlüssel und Zielvariablen referenzieren. Der Zugangsdatenspeicher bleibt die Quelle des geheimen Materials.

Beispiel: Zugangsdatenname und Tokenschlüsselvariablen

bundle: 
  name: credentialVariableDemoBundle 
resources: 
  jobs: 
    - credentialLookupJob 
defaults: 
  variables: 
    cred_key: default_credential_name 
    token_key: default_token_key 
targets: 
  dev: 
    workspace_key: dev_workspace 
    variables: 
      cred_key: dev_credential_store_entry 
      token_key: dev_token 
  qa: 
    workspace_key: qa_workspace 
    variables: 
      cred_key: qa_credential_store_entry 
      token_key: qa_token 
  prod: 
    workspace_key: prod_workspace 
    variables: 
      cred_key: prod_credential_store_entry 
      token_key: prod_token 

jobs: 
  credentialLookupJob: 
    tasks: 
      - taskKey: Task_854239 
        parameters: 
          - name: cred_key 
            value: "${var.cred_key}" 
          - name: token_key 
            value: "${var.token_key}"

Das Notizbuch liest die Parameterwerte und verwendet sie, um das Secret aus dem Zugangsdatenspeicher zu suchen: 

cred_name = odiUtils.parameters.getParameter("cred_key", "defaultCredValue") 
token_name = odiUtils.parameters.getParameter("token_key", "defaultTokenValue") 

secret = aidpUtils.secrets.get(name=cred_name, key=token_name) 
if secret: 
    print("Credential lookup succeeded") 
else: 
    raise Exception("Credential lookup failed")
Umgebung cred_key-Wert token_key-Wert Zugangsdatenspeicheranforderung
Dev dev_credential_store_entry Dev_Token Erstellen Sie dev_credential_store_entry mit dem Schlüssel dev_token.
QA qa_credential_store_entry QA-Token Erstellen Sie qa_credential_store_entry mit dem Schlüssel qa_token.
Produkt prod_credential_store_entry prod_token Erstellen Sie prod_credential_store_entry mit dem Schlüssel prod_token.

Bundle löschen (Vorschau)

Sie können ein bereitgestelltes Bundle löschen, um die Bundle-Ressourcen aus Ihrem Workspace zu entfernen.

  1. Navigieren Sie zu dem Bundle, für das Sie Ressourcen in Ihrem Workspace löschen möchten.
  2. Klicken Sie auf die Registerkarte "Deployment".
  3. Klicken Sie auf Löschen.
  4. Geben Sie in der Eingabeaufforderung Löschen ein. Klicken Sie auf Löschen.

Hinweis:

Wenn Sie ein Bundle löschen, werden zuerst die bereitgestellten Ressourcen entfernt. Wenn das Bundle einen Veröffentlichungspfad verwendet, entfernt Oracle AI Data Platform den Ordner "Verwaltete Artefakte" unter dem Veröffentlichungspfad. Andere Dateien unter dem Veröffentlichungspfad werden beibehalten.

Löschverhalten für veröffentlichte Artefakte (Vorschau)

Wenn Sie ein bereitgestelltes Bundle löschen, entfernt Oracle AI Data Platform zuerst die bereitgestellten Ressourcen.

Nachdem die Ressourcen entfernt wurden, entfernt AI Data Platform nur den verwalteten Artefaktordner: <publish.path>/artifacts.

Andere Dateien oder Ordner unter dem Veröffentlichungspfad werden beibehalten. Beispiel: Wenn der Veröffentlichungspfad /Workspace/Shared/customer_churn_bundle lautet, wird durch Löschen /Workspace/Shared/customer_churn_bundle/artifacts entfernt, andere Dateien oder Ordner werden jedoch unter /Workspace/Shared/customer_churn_bundle beibehalten.

Wenn die Artefaktbereinigung aufgrund von Berechtigungen oder Pfadzugriff nicht abgeschlossen werden kann, kann das Löschen der Ressource weiterhin abgeschlossen werden.

Vorhandene Bundles und Veröffentlichungspfade (Vorschau)

Vorhandene Bundles, die keinen Veröffentlichungsblock aufweisen, verwenden das vorherige Artefaktverhalten weiter, bis sie synchronisiert oder manuell aktualisiert werden.

Wenn Sie einem vorhandenen Bundle manuell einen Veröffentlichungsblock hinzufügen, verwendet das Deployment den konfigurierten Veröffentlichungspfad. Vorhandene Deskriptordateien werden jedoch beim Deployment nicht automatisch geändert. Wenn vorhandene Deskriptoren weiterhin den vorherigen Artefaktspeicherort referenzieren, verwenden diese Ressourcen möglicherweise weiterhin den vorherigen Speicherort.

Wenn vorhandene Ressourcen den Veröffentlichungspfad verwenden sollen, aktualisieren Sie die Deskriptorreferenzen, oder synchronisieren Sie das Bundle, bevor Sie manuell einen benutzerdefinierten Veröffentlichungsblock hinzufügen. Beispiel:

Old:
${bundle.root}/.aidp/artifacts/Shared/task1.py

New:
${publish.path}/artifacts/Shared/task1.py

Wenn die Synchronisierung neuen oder aktualisierten Deskriptorinhalt für ein Bundle hinzufügt, das bereits einen Veröffentlichungsblock enthält, verwenden die neuen Deskriptorreferenzen das Veröffentlichungspfadformat.

Fehlerbehebung für Bundles (Vorschau)

Wenn beim Erstellen und Verwalten von Git-Bundles Probleme auftreten, prüfen Sie die folgende Liste der Probleme auf mögliche Lösungen.

Symptom Wahrscheinliche Ursachen Empfohlene Aktion
Bundle-Erstellung ist nicht verfügbar, oder das Bundle kann nicht erstellt werden. Der Benutzer befindet sich nicht in einem Git-Ordner oder hat keine erforderlichen Workspace-Berechtigungen. Navigieren Sie zu einem Git-Ordner, und bestätigen Sie, dass der Benutzer Workspace-Ressourcen erstellen kann.
Die Synchronisierung ist abgeschlossen, aber die Aktualisierung wird in einer anderen Umgebung nicht angezeigt. Die aktualisierten Bundle-Dateien wurden nicht festgeschrieben, übertragen oder in den Ziel-Git-Ordner abgerufen. Commit und Push aus dem Quell-Git-Ordner ausführen und dann den Ziel-Workspace vor dem Deployment abrufen.
Auf der Registerkarte "Deployment" werden keine bereitgestellten Elemente angezeigt. Das Bundle wurde noch nicht bereitgestellt, oder das Deployment wurde nicht erfolgreich abgeschlossen. Klicken Sie auf "Bereitstellen", und warten Sie auf die Abschlussbenachrichtigung. Prüfen Sie die Logs, wenn das Deployment nicht erfolgreich verläuft.
Bereitgestellter Job nicht erfolgreich. Fehler bei Zugangsdatensuche. Der Zielzugangsdatenname, der Tokenschlüssel oder die Zugriffsberechtigung stimmen nicht mit der Bundle-Konfiguration überein. Erstellen Sie die Zugangsdaten im Zielzugangsdatenspeicher, oder aktualisieren Sie die Zielvariablen, bevor Sie sie erneut bereitstellen.
Agent-Flow-Deployment ist nicht erfolgreich oder wird mit inaktivem Compute gestartet. Die Zielumgebung weist möglicherweise keine kompatiblen AI-Compute-, Regions-, Modell- oder Abhängigkeitseinstellungen auf. Prüfen Sie Ziel-Overrides, Compute-Status, Modellverfügbarkeit und Deployment-Logs.
Änderungen an einem Quellnotizbuch oder Agent-Fluss werden nach dem Deployment nicht wiedergegeben. Das Bundle wurde ohne erste Synchronisierung aus der aktualisierten Quellressource bereitgestellt. Führen Sie Sync für das Bundle aus, schreiben Sie die aktualisierten Bundle-Dateien fest, übertragen Sie sie, ziehen Sie sie in das Ziel, und stellen Sie sie dann erneut bereit.