Bundles et CI/CD (aperçu)

34 Bundles et CI/CD (aperçu)

Les bundles définissent la façon dont les ressources Oracle AI Data Platform Workbench sont packagées, gérées par version, partagées et déployées dans les espaces de travail et les environnements.

Vous pouvez créer des lots d'offres pour les emplois et les agents. Un bundle est créé dans un dossier Git afin que les fichiers du bundle puissent être validés et propagés vers un référentiel Git. Les ressources que vous incluez dans le groupe peuvent provenir de n'importe quel emplacement dans l'espace de travail. Si les ressources sélectionnées référencent des fichiers ou des dépendances de prise en charge, tels que des blocs-notes, des scripts ou des calculs, ces références sont incluses dans le groupe afin que les ressources puissent être déployées dans un autre environnement sans recréer manuellement les mêmes composants.

Vous créez des bundles à partir de votre espace de travail et sélectionnez les ressources Oracle AI Data Platform Workbench à inclure au moment de la création. Les bundles existants peuvent être modifiés pour ajouter ou supprimer des ressources. Les ressources de regroupement vous permettent de regrouper des travaux et des agents associés et de les déployer dans d'autres environnements avec leurs dépendances intactes.

Vous pouvez valider et propager des bundles vers votre référentiel Git via vos dossiers Git. Les utilisateurs peuvent ensuite extraire les lots dans leurs propres environnements et les déployer. Les modifications apportées aux fichiers de groupe sont disponibles pour d'autres environnements une fois les modifications validées et propagées vers le référentiel Git. Chaque fois que les utilisateurs extraient le bundle mis à jour du référentiel Git, ils reçoivent les derniers fichiers de ressources validés.

Concepts relatifs au bundle

Concept	Signification	Action utilisateur
Dossier Git	Dossier AI Data Platform connecté à un référentiel et à un branchement Git. Les bundles ne peuvent être créés que dans les dossiers Git.	Créez ou ouvrez un dossier Git avant de créer un bundle.
Regroupement	Package déployable qui définit les ressources sélectionnées et leurs dépendances.	Créez le groupe à partir de l'espace de travail, puis sélectionnez des ressources telles que des travaux ou des flux d'agent.
Contenu du bundle	Fichiers générés décrivant les ressources, les variables, les paramètres de cible et les artefacts requis pour le déploiement.	Vérifier le contenu généré après la création ou la synchronisation. Validez et poussez le bundle via Git lorsque vous êtes prêt.
Target	Configuration d'environnement ou d'espace de travail utilisée lors du déploiement du lot en dehors de l'environnement source.	Indiquez les valeurs qui doivent être modifiées par environnement, telles que la clé d'espace de travail, le nom des informations d'identification, la clé de jeton ou les paramètres par défaut.
Elément déployé	Ressource créée ou mise à jour par un déploiement de groupe dans l'espace de travail cible.	Utilisez l'onglet Déploiement pour déployer, vérifier les éléments déployés, exécuter des travaux et purger les ressources déployées si nécessaire.
Synchronisation	Action de groupe qui actualise les ressources de groupe et les dépendances à partir des dernières ressources source.	Exécutez la synchronisation après la modification des ressources groupées, puis validez les fichiers groupés actualisés dans Git.

Avant de commencer

Consultez cette liste pour vous assurer que vous disposez de tout ce dont vous avez besoin pour commencer à utiliser les bundles Git dans votre espace de travail AI Data Platform :

Créez les informations d'identification Git et un dossier Git qui pointe vers le référentiel et le branchement utilisés pour les fichiers de groupe.
Vérifiez que les ressources source se trouvent dans l'espace de travail et sont enregistrées avant de créer ou de synchroniser le groupe.
Pour un déploiement inter-environnement, vérifiez que l'espace de travail cible dispose des droits d'accès et de la capacité de calcul requis.
Pour les travaux ou les blocs-notes qui utilisent des clés secrètes, créez les informations d'identification nommées requises dans la banque d'informations d'identification cible. Les fichiers de groupe doivent référencer les informations d'identification par nom ou variable, et ne doivent pas contenir de valeurs secrètes.
Validez et propagez les modifications de fichier de groupe après avoir créé ou synchronisé un groupe afin que d'autres environnements puissent extraire la dernière définition de groupe.

Chemins de publication du bundle

Les bundles peuvent publier des artefacts d'exécution dans un dossier d'espace de travail que les utilisateurs peuvent inspecter. Les artefacts d'exécution incluent des fichiers tels que des blocs-notes, des scripts, des bibliothèques et des fichiers de flux d'agent nécessaires aux ressources de groupe déployées. Le dossier dans lequel les artefacts sont publiés est appelé chemin de publication. Les artefacts sont stockés dans un dossier d'artefacts dans le chemin de publication.

Par exemple, si le chemin de publication est /Workspace/Shared/customer_churn_bundle, les artefacts de groupe sont publiés sous /Workspace/Shared/customer_churn_bundle/artifacts.

Le chemin de publication n'est pas la source de vérité du groupe. Les fichiers source du bundle restent dans le dossier du bundle et doivent être validés dans Git. Les fichiers sous le chemin de publication sont des fichiers d'exécution utilisés par les ressources déployées. Si vous modifiez manuellement des fichiers sous le chemin de publication, ces modifications ne sont pas réécrites dans la source du bundle. Un déploiement ultérieur peut remplacer les artefacts publiés par des fichiers du groupe.

Créer un groupe de propriétés (aperçu)

Vous pouvez regrouper des ressources de travail et d'agent Oracle AI Data Platform pour créer un package qui peut être déployé dans un autre dossier Git.

Accédez à votre espace de travail.
Cliquez sur Actions, puis sur Créer un groupe.
Indiquez un nom et un descriptif pour le groupe.
Cliquez sur Parcourir et sélectionnez le dossier Git dans l'espace de travail dans lequel créer le bundle.
Sélectionnez les ressources à inclure dans le groupe dans les options répertoriées.
Cliquez sur Créer.

Remarques :
Les bundles sont créés dans les dossiers Git. Si l'emplacement sélectionné ne se trouve pas dans un dossier Git, vous ne pouvez pas utiliser Git pour déplacer les fichiers de bundle générés vers un autre environnement.

Remarques :
Lorsqu'un bundle est créé, AI Data Platform peut inclure une configuration de publication par défaut dans le manifeste du bundle. La configuration de publication contrôle l'emplacement des artefacts d'exécution lors du déploiement du groupe.

Eléments générés après la création du bundle (aperçu)

Après la création du bundle, Oracle AI Data Platform écrit les fichiers générés dans le dossier du bundle.

Les noms de fichier exacts varient selon le type de ressource, mais le groupe créé contient généralement un manifeste de groupe de niveau supérieur, des définitions de ressource, des dossiers d'artefacts et des fichiers de remplacement facultatifs.

Article généré	Description
`aidp_workbench.yaml`	Manifeste de groupe. Identifie le groupe, les ressources incluses, les variables et les sections cible utilisés lors du déploiement.
`.aidp/resource_origins.yaml`	Définitions des ressources. Décrire les ressources telles que les travaux, les tâches de bloc-notes, les références de calcul ou les flux d'agent.
`.aidp/overrides.yaml`	Remplacez les fichiers ou les sections cible. Contient des valeurs qui diffèrent selon l'environnement, telles que les identificateurs d'espace de travail, les valeurs par défaut des paramètres, les noms d'informations d'identification ou les clés de jeton.
`.aidp/aidp.state.json`	Effectue le suivi des ressources déployées à partir du groupe. Utilisé par les opérations de déploiement et de purge futures.
`jobs/`	Descripteurs de travail et dépendances de travail.
`agentflows/`	Descripteurs d'agent et dépendances d'agent.
`artifacts/`	Dossiers d'artefacts. Code copié, blocs-notes et artefacts de fichier de prise en charge.

Configuration du chemin de publication (aperçu)

Vous pouvez configurer le chemin de publication d'un groupe dans le fichier manifeste du groupe, aidp_workbench.yaml.

Pour configurer le chemin de publication d'un fichier de groupe, ajoutez un bloc de publication sous defaults dans le fichier manifeste aidp_workbench.yaml, comme dans l'exemple suivant :

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

Dans cet exemple, lorsque le groupe est déployé, les artefacts sont publiés sous /Workspace/Shared/customer_churn_bundle/artifacts.

Tableau 34-1 Champs de configuration du chemin de publication

Champ	Description
`path`	Dossier d'espace de travail utilisé comme racine de publication. Les artefacts sont stockés sous `<path>/artifacts`.
`overwrite_publish_artifacts`	Indique si le déploiement peut remplacer les artefacts publiés existants au niveau du chemin de publication configuré.

Configuration du chemin de publication pour différents environnements

Vous pouvez configurer différents chemins de publication pour différentes cibles de déploiement, comme dans l'exemple suivant :

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

Vous pouvez également utiliser .aidp/overrides.yaml pour remplacer le chemin de publication localement :

publish:
  path: "/Workspace/Users/me/customer_churn_bundle"
  overwrite_publish_artifacts: true

Lorsque plusieurs chemins de publication sont configurés, Oracle AI Data Platform résout le chemin de publication dans l'ordre suivant :

defaults.publish.path dans aidp_workbench.yaml
Chemin de publication cible correspondant
.aidp/overrides.yaml chemin de publication

Publication des artefacts de groupe (aperçu)

Lorsque vous déployez un bundle, Oracle AI Data Platform copie les artefacts du bundle de la source du bundle dans le chemin de publication résolu.

La présentation d'artefact par défaut est <publish.path>/artifacts. Exemple :

/Workspace/Shared/customer_churn_bundle/artifacts

Les fichiers de descripteur de groupe peuvent référencer des artefacts publiés à l'aide de ${publish.path}/artifacts/.... Exemple :

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

Au cours du déploiement, ${publish.path} est résolu en chemin de publication configuré.

Déployer un bundle (aperçu)

Vous pouvez déployer des bundles à partir d'un dossier Git pour partager des ressources et des dépendances entre des espaces de travail et des environnements.

Accédez au groupe à déployer dans votre espace de travail.
Cliquez sur l'onglet Déploiement.
Facultatif : vérifiez les valeurs cible et les remplacements, le cas échéant.
Cliquez sur Déployer. Vous êtes averti de la fin du déploiement.

Remarques :
Lors du premier déploiement, l'onglet Déploiement peut n'afficher aucun élément déployé tant que le déploiement n'a pas abouti. Après un déploiement réussi, vérifiez les ressources déployées, exécutez des travaux ou des agents selon vos besoins et confirmez la sortie d'exécution.

Remarques :
Pendant le déploiement, les artefacts de groupe sont publiés sur le chemin de publication configuré avant le déploiement des ressources. Si aucun chemin de publication personnalisé n'est configuré, Oracle AI Data Platform utilise l'emplacement de publication par défaut du groupe.

Mode de déploiement des bundles vers les chemins publiés (aperçu)

Lorsqu'un chemin de publication est configuré pour un groupe, le déploiement exécute un ensemble fixe d'actions.

Les actions effectuées par Oracle AI Data Platform lors du déploiement d'un bundle avec un chemin de publication configuré ont lieu dans l'ordre suivant :

Validez le chemin de publication.
Publiez les artefacts de groupe dans <publish.path>/artifacts.
Déployez des ressources de groupe, telles que des travaux et des flux d'agent, à l'aide des chemins d'artefact publiés.
Mettre à jour le statut de déploiement une fois le déploiement terminé.

Différentes actions peuvent être effectuées si la plate-forme de données AI rencontre des problèmes avec le chemin de publication :

Si le chemin de publication n'existe pas, AI Data Platform peut le créer pendant le déploiement.
Si le chemin de publication existe et est vide, le déploiement peut l'utiliser.
Si le chemin de publication contient des artefacts gérés par le même groupe, le déploiement peut les mettre à jour.
Si le chemin de publication contient des données qui ne sont pas détenues par le groupe, le déploiement peut échouer, sauf si l'écrasement est activé.

Synchroniser un bundle (aperçu)

Vous pouvez synchroniser un bundle pour mettre à jour les ressources et les dépendances du bundle avec les dernières modifications.

Sync utilise les métadonnées d'origine enregistrées du groupe pour reconstruire le groupe à partir des travaux source et des flux d'agent capturés lors de la création du groupe. Les métadonnées source sont stockées dans .aidp/resource_origins.yaml et doivent correspondre à l'instance et à l'espace de travail demandés. L'opération actualise le contenu du lot contrôlé par la source tout en conservant l'identité du lot et les métadonnées d'exécution.

Au cours de la synchronisation, le service prépare un cliché de groupe actualisé sous le répertoire .aidp du groupe, compare les descripteurs existants et intermédiaires, conserve les alias de variable existants et remplace les références si possible, fusionne les variables par défaut de manifeste existantes, puis promeut les fichiers contrôlés par la source actualisés dans la racine du groupe.

Sync conserve les fichiers d'exécution propres à l'environnement et au déploiement, tels que .aidp/overrides.yaml et .aidp/aidp.state.json. Ces fichiers ne sont pas remplacés par l'instantané source actualisé.

Vous devez synchroniser vos bundles lorsque :

Bloc-notes, travail, flux d'agent, référence de calcul, paramètre ou dépendance groupés modifiés dans l'espace de travail source.
Un travail groupé pointe désormais vers un bloc-notes différent ou comporte des paramètres de tâche mis à jour.
Une configuration d'agent, un paramètre d'invite, un paramètre de modèle ou une dépendance de calcul AI ont été modifiés.
Le dossier Git doit contenir les derniers fichiers de groupe générés avant d'être transféré vers un autre environnement.

Accédez au bundle à synchroniser dans votre espace de travail.
Cliquez sur Actions.
Cliquez sur Synchroniser. Vous êtes informé de la fin de la synchronisation.

Workflow de promotion recommandé pour les bundles (aperçu)

Nous vous recommandons de suivre un workflow de développement, de package, de version, d'extraction, de configuration, de déploiement et de validation pour les bundles dans Oracle AI Data Platform.

Phase	Action	Résultat
Développement	Créez ou mettez à jour des blocs-notes, des travaux, des paramètres de calcul ou des flux d'agent dans l'espace de travail source.	Les ressources source contiennent le comportement prévu le plus récent.
Package	Créez le bundle ou exécutez Sync sur un bundle existant.	Les fichiers de groupe générés reflètent les ressources et dépendances source actuelles.
Version	Vérifiez, validez et propagez le dossier du bundle à travers le dossier Git.	Le référentiel distant contient la définition de groupe déployable.
PULL	Dans l'espace de travail cible, extrayez les modifications du dossier Git.	L'espace de travail cible contient les derniers fichiers de groupe.
Configurer	Définissez des valeurs spécifiques à la cible, telles que la clé d'espace de travail, les paramètres par défaut, le nom des informations d'identification, la clé de jeton ou les paramètres d'exécution.	Le groupe est prêt pour l'environnement cible.
Déployez	Ouvrez l'onglet Déploiement du bundle et cliquez sur Déployer.	Workbench crée ou met à jour les ressources déployées.
Valider	Exécutez des travaux déployés ou testez les flux d'agents déployés et examinez les journaux ou la sortie.	L'environnement cible est vérifié avant la poursuite de la promotion.

Variables de groupe (aperçu)

Utilisez des variables de groupe lorsqu'un groupe a besoin de valeurs de déploiement qui peuvent changer pour chaque environnement cible sans modifier la définition de ressource.

Pour commencer à utiliser des variables avec des groupes, vous devez définir les noms des variables dans le fichier aidp_workbench.yaml du groupe avec des valeurs par défaut et, si nécessaire, des remplacements propres à l'environnement. Vous référencez ensuite ces variables à partir des fichiers de définition générés.

Exemple de workflow de variable

Définissez des noms de variable sous defaults > variables dans aidp_workbench.yaml.
Définissez éventuellement des valeurs propres à l'environnement sous targets > <environment> > variables dans le même fichier aidp_workbench.yaml.
Utilisez les remplacements de cible pour définir des valeurs de déploiement telles qu'une région de développement, une région d'assurance qualité, une région de production, un nom de schéma, un nom d'informations d'identification, une clé de jeton ou une valeur par défaut de paramètre.
Lorsqu'aucun environnement cible correspondant n'est trouvé, Oracle AI Data Platform utilise la valeur de variable par défaut provenant de aidp_workbench.yaml.
Utilisez la variable dans un fichier de définition généré, tel qu'une définition de travail, une définition de calcul, une définition de tâche ou un autre fichier de définition YAML.
Référencez la variable avec ${var.<<nom_variable>>}, en remplaçant <<nom_variable>> par le nom de variable réel défini dans aidp_workbench.yaml.
Utilisez la syntaxe d'espace réservé propre à la ressource à des emplacements tels que des invites d'agent ou des définitions d'outil lorsque l'interface utilisateur attend un espace réservé nommé.
Pour les modifications temporaires de déploiement uniquement, créez le fichier .aidp/overrides.yaml et définissez-y des valeurs de variable.

Syntaxe des variables de groupe

Les définitions de variable doivent être écrites dans aidp_workbench.yaml. Les autres fichiers de définition de groupe ne doivent référencer que le nom de la variable.

Définition	Syntaxe	Exemple
Définition de variable dans `aidp_workbench.yaml`	`defaults: variables: <<variable_name>>: <<default_value>>`	`defaults: variables: deployment_region: "us-ashburn-1"`
Remplacement spécifique à la cible dans`aidp_workbench.yaml`	`targets: <<target_name>>: variables: <<variable_name>>: <<target_value>>`	`targets: qa: “workbenchid”: “ocid” “workspaceKey”: “key” variables: deployment_region: "us-phoenix-1"`
Référence de variable dans un fichier de définition	`${var.<<variable_name>>}`	`value: "${var.deployment_region}"`
Espace réservé nommé dans une invite d'agent ou un champ d'outil	`{{variable_name}}`	`Generate a summary about {{topic}}.`

Exemple : variable de paramètre de travail

L'exemple suivant définit une variable et la transmet à un paramètre de travail. La ressource peut rester inchangée pendant que la valeur de la variable change dans la configuration du groupe.

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

Une tâche de bloc-notes peut lire la valeur résolue via le nom de paramètre utilisé par le travail :

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

Exemple : définition de variable aidp_workbench.yaml

Cet exemple définit la variable agent_topic_default dans aidp_workbench.yaml. La valeur par défaut s'applique lorsqu'aucun environnement cible correspondant n'est trouvé ou lorsqu'aucun environnement sélectionné ou remplacement temporaire ne fournit la variable. Chaque cible peut remplacer le même nom de variable pour cet espace de travail.

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"

Tout fichier de définition de groupe prenant en charge les variables de groupe peut alors référencer le même nom de variable. Exemple :

tasks/agentTopic.task.yaml 

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

Exemple : noms de fichier et résolution

Dans un groupe généré, la définition de variable et la ressource qui utilise la variable peuvent se trouver dans différents fichiers. Lorsque vous promouvez ou copiez l'exemple via Git, incluez l'ensemble du dossier du bundle afin que le manifeste, la définition de travail et les artefacts restent ensemble.

testNamedVarBundleJob/ 
  aidp_workbench.yaml 
  jobs/ 
    namedVariableJobDemo.job.json 
  artifacts/ 
    namedVarNotebookDemo.ipynb

Fichier	Contenu	Variable ou valeur résolue
`aidp_workbench.yaml`	Définit la variable sous default > variables et remplacements de cible facultatifs.	Variable : `job_param_value_default`.
`jobs/namedVariableJobDemo.job.json`	Utilise la variable comme valeur pour le paramètre de travail param_key.	Référence : `${var.job_param_value_default}`.
`artifacts/namedVarNotebookDemo.ipynb`	Lit le paramètre de travail résolu lors de l'exécution.	Le bloc-notes lit `param_key` après la résolution.

Par exemple, le manifeste du bundle peut définir les remplacements par défaut et cible dans aidp_workbench.yaml :

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"

La définition de travail peut ensuite utiliser le même nom de variable dans jobs/namedVariableJobDemo.job.json. La même syntaxe peut être utilisée dans les définitions de travail, les définitions de calcul, les définitions de tâche et les autres fichiers de définition YAML générés qui prennent en charge les variables de groupe :

"parameters": [ 
  { 
    "name": "param_key", 
    "value": "${var.job_param_value_default}" 
  } 
]

Cible de déploiement	Résolution de variable	Reçus de bloc-notes
Aucune cible correspondante	Utilise la valeur par défaut du fichier helpp_workbench.yaml.	`param_key = cloud data governance`
dév	Utilise le remplacement de l'objectif de développement.	`param_key = space tourism`
qa	Utilise le remplacement de cible QA.	`param_key = data quality validation`
prod	Utilise le remplacement de cible de produit.	`param_key = customer operations`

Ordre de résolution

Lorsque .aidp/overrides.yaml fournit une valeur de variable, AI Data Platform utilise cette valeur temporaire pour le déploiement suivant. Sinon, AI Data Platform résout d'abord la variable à partir de la cible sélectionnée. Si aucun environnement cible correspondant n'est trouvé ou si la cible sélectionnée ne remplace pas la variable, AI Data Platform revient à defaults > variables dans aidp_workbench.yaml. Si aucune valeur n'est disponible pour la variable référencée, le déploiement ou l'exécution du travail peut échouer avant l'utilisation de la valeur de restauration du bloc-notes.

Remplacements temporaires pour le prochain déploiement

Les définitions du fichier aidp_workbench.yaml sont suffisantes pour une promotion groupée normale. Si un utilisateur doit remplacer temporairement une variable, créez le fichier .aidp/overrides.yaml dans le dossier du bundle et définissez-y les valeurs de variable. AI Data Platform utilise ces valeurs lors du prochain déploiement.

.aidp/ 
  overrides.yaml

variables: 
  agent_topic_default: "tuesday"

Fichier	Exemple de valeur	Quand utilisé
`aidp_workbench.yaml defaults`	Oracle AI Data Platform	Utilisé lorsqu'aucun fichier cible ou de remplacement ne correspond à la variable.
`aidp_workbench.yaml target dev`	Espace de travail de développement AIDP	Utilisé lors du déploiement vers le développement et aucun remplacement temporaire n'est présent.
`.aidp/overrides.yaml`	Mardi	Utilisé comme valeur temporaire lors du déploiement suivant.

Remarques :

Utilisez .aidp/overrides.yaml pour les valeurs de déploiement temporaire. Conservez les valeurs par défaut durables et les valeurs propres à l'environnement dans aidp_workbench.yaml afin que le groupe reste reproductible via Git.

Exemple : variable d'invite d'agent

Pour les définitions de texte ou d'outil d'invite de flux d'agent qui prennent en charge les espaces réservés nommés, utilisez des accolades doubles autour du nom de la variable.

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

Remarques :

Il est recommandé d'utiliser des variables pour les valeurs qui doivent changer d'un déploiement à l'autre. Evitez d'incorporer des valeurs propres à l'environnement directement dans les blocs-notes, les travaux ou le texte de flux d'agent lorsqu'une variable peut transférer la valeur.

Exemple : Workflow sans calcul

Vous pouvez créer un groupe pour un workflow qui ne crée pas automatiquement un cluster de calcul dans le cadre du déploiement. Commencez par créer une variable dans aidp_workbench.yaml :

defaults:
 variables:
  job_compute_key: "select_compute"

Ensuite, dans le dossier jobs/, localisez le fichier de travail <JobName>.job.json. Modifiez le fichier de travail pour remplacer la valeur "clusterKey" par la nouvelle variable créée :

"clusterKey" : "${var.job_compute_key}",

Variables nommées dans les environnements (aperçu)

Les variables d'environnement nommées permettent à votre groupe Git de conserver les mêmes noms de variable logique tandis que chaque environnement fournit ses propres valeurs de déploiement.

Utilisez ce modèle lorsqu'une région de développement, une région d'assurance qualité et un environnement de production doivent déployer les mêmes définitions de ressource avec des valeurs différentes.

Exemple de workflow de variable nommée

Définissez la variable une fois sous defaults > variables dans aidp_workbench.yaml.
Remplacez le même nom de variable sous chaque environnement cible.
Déployer avec la cible dont les valeurs de variable correspondent à l'espace de travail de destination.
Utilisez les valeurs par défaut pour les valeurs de restauration sécurisées, et non pour les clés secrètes de production uniquement ou les identificateurs propres à l'espace de travail.

Exemple : remplacements de développement, d'assurance qualité et de production

L'exemple suivant utilise les mêmes noms de variable sur trois cibles. Le travail référence toujours les variables une fois, tandis que la région de développement, la région d'assurance qualité et l'environnement de production fournissent des valeurs de temps de déploiement différentes.

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	déploiement_région	job_param_value_default	Résultat d'exécution
dév	us-ashburn-1	tourisme spatial	Exécutions de travail avec des valeurs de région et de paramètre de développement.
qa	us-phoenix-1	validation de la qualité des données	Exécutions de travail avec des valeurs de région et de paramètre d'assurance qualité.
prod	eu-frankfurt-1	opérations client	Exécutions de travail avec des valeurs d'environnement de production.

Remarques :

Si aucun environnement cible correspondant n'est trouvé ou si une cible ne définit pas de remplacement, Workbench utilise la valeur de variable par défaut configurée lorsqu'elle existe. Si aucun remplacement ni aucune valeur par défaut valide n'est disponible, l'exécution du déploiement ou de l'exécution peut échouer en fonction de l'emplacement où la variable manquante est utilisée.

Variables de groupe et banque d'informations d'identification (aperçu)

Vous pouvez utiliser des variables avec la banque d'informations d'identification lorsqu'un travail groupé ou un bloc-notes doit rechercher une clé secrète lors de l'exécution.

Vos variables doivent porter le nom des informations d'identification et la clé de jeton. La valeur de clé secrète réelle doit rester dans la banque d'informations d'identification cible et ne doit pas être validée dans Git.

Exemple de workflow : utilisation de variables avec la banque d'informations d'identification

Créez les informations d'identification et la clé de jeton dans la banque d'informations d'identité.
Définissez des variables pour le nom des informations d'identification et la clé de jeton.
Transmettez ces variables dans le travail ou le bloc-notes en tant que paramètres.
Au moment de l'exécution, le bloc-notes lit les paramètres et appelle l'API d'informations d'identification pour extraire la clé secrète. Si le nom des informations d'identification, la clé de jeton ou les droits d'accès sont incorrects, le travail peut échouer avec une erreur de recherche d'informations d'identification.

Remarques :

Ne documentez pas ou ne validez pas les valeurs de clé secrète dans les fichiers de groupe. La configuration du groupe doit référencer les noms d'informations d'identification, les clés de jeton et les variables cible ; la banque d'informations d'identification reste la source des informations d'identification.

Exemple : nom d'informations d'identification et variables de clé de jeton

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

Le bloc-notes lit les valeurs de paramètre et les utilise pour rechercher la clé secrète dans la banque d'informations d'identification :

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")

Environnement	Valeur cred_key	Valeur token_key	Exigence de stockage des informations d'identification
dév	dev_credential_store_entry	jeton_de_développement	Créez dev_credential_store_entry avec la clé dev_token.
qa	qa_credential_store_entry	Jeton qa	Créez qa_credential_store_entry avec la clé qa_token.
prod	prod_credential_store_entry	jeton_prod	Créez prod_credential_store_entry avec la clé prod_token.

Purger un bundle (aperçu)

Vous pouvez purger un groupe déployé pour enlever les ressources du groupe de votre espace de travail.

Accédez au groupe pour lequel vous voulez purger les ressources dans votre espace de travail.
Cliquez sur l'onglet Déploiement.
Cliquez sur Purger.
Entrez Purger dans l'invite. Cliquez sur Purger.

Remarques :

La purge d'un groupe supprime d'abord les ressources déployées. Si le groupe utilise un chemin de publication, Oracle AI Data Platform enlève ensuite le dossier d'artefacts gérés sous le chemin de publication. Les autres fichiers situés sous le chemin de publication sont conservés.

Comportement de purge pour les artefacts publiés (aperçu)

Lorsque vous purgez un lot déployé, Oracle AI Data Platform enlève d'abord les ressources déployées.

Une fois les ressources enlevées, AI Data Platform enlève uniquement le dossier d'artefact géré : <publish.path>/artifacts.

Les autres fichiers ou dossiers sous le chemin de publication sont conservés. Par exemple, si le chemin de publication est /Workspace/Shared/customer_churn_bundle, la purge enlève /Workspace/Shared/customer_churn_bundle/artifacts mais conserve les autres fichiers ou dossiers sous /Workspace/Shared/customer_churn_bundle.

Si le nettoyage de l'artefact ne peut pas être effectué en raison de droits d'accès ou d'un accès par chemin, la suppression de la ressource peut toujours se terminer.

Bundles existants et chemins de publication (aperçu)

Les groupes existants qui n'ont pas de bloc de publication continuent d'utiliser le comportement de l'artefact précédent jusqu'à ce qu'ils soient synchronisés ou mis à jour manuellement.

Si vous ajoutez manuellement un bloc de publication à un groupe existant, le déploiement utilise le chemin de publication configuré. Toutefois, les fichiers descripteurs existants ne sont pas modifiés automatiquement au cours du déploiement. Si des descripteurs existants font toujours référence à l'emplacement d'artefact précédent, ces ressources peuvent continuer à utiliser l'emplacement précédent.

Si vous voulez que les ressources existantes utilisent le chemin de publication, mettez à jour les références du descripteur ou synchronisez le groupe avant d'ajouter manuellement un bloc de publication personnalisé. Exemple :

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

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

Lorsque la synchronisation ajoute du contenu de descripteur nouveau ou actualisé pour un groupe qui a déjà un bloc de publication, les références de nouveau descripteur utilisent le format de chemin de publication.

Dépannage des bundles (aperçu)

Si vous rencontrez des problèmes lors de la création et de la gestion de groupes Git, consultez la liste suivante de problèmes pour trouver des solutions potentielles.

Symptôme	Cause probable	Action recommandée
L'option Créer un bundle n'est pas disponible ou le bundle ne peut pas être créé.	L'utilisateur ne se trouve pas dans un dossier Git ou ne dispose pas des autorisations d'espace de travail requises.	Accédez à un dossier Git et vérifiez que l'utilisateur peut créer des ressources d'espace de travail.
La synchronisation est terminée, mais aucun autre environnement ne voit la mise à jour.	Les fichiers de groupe actualisés n'ont pas été validés, poussés ou extraits dans le dossier Git cible.	Validez et propagez à partir du dossier Git source, puis extrayez l'espace de travail cible avant de le déployer.
L'onglet Déploiement n'affiche aucun élément déployé.	Le groupe n'a pas encore été déployé ou le déploiement n'a pas abouti.	Cliquez sur Déployer et attendez la notification de fin. Consultez les journaux en cas d'échec du déploiement.
Echec du travail déployé avec une erreur de recherche d'informations d'identification.	Le nom des informations d'identification cible, la clé de jeton ou le droit d'accès ne correspond pas à la configuration du groupe.	Créez les informations d'identification dans la banque d'informations d'identification cible ou mettez à jour les variables cible avant le redéploiement.
Le déploiement de flux d'agent échoue ou démarre avec un calcul inactif.	L'environnement cible peut ne pas avoir de paramètres de calcul, de région, de modèle ou de dépendance AI compatibles.	Passez en revue les remplacements de cible, le statut du calcul, la disponibilité du modèle et les journaux de déploiement.
Les modifications apportées à un bloc-notes ou à un flux d'agent source ne sont pas reflétées après le déploiement.	Le groupe a été déployé sans synchronisation préalable à partir de la ressource source mise à jour.	Exécutez Sync sur le bundle, validez et propagez les fichiers du bundle actualisé, extrayez-les dans la cible, puis déployez à nouveau.