18 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
- 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.
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.
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. |
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.
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é.
- 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
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 Git 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 > variablesdansaidp_workbench.yaml. - Définissez éventuellement des valeurs propres à l'environnement sous
targets > <environment> > variablesdans le même fichieraidp_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
|
|
|
Remplacement spécifique à la cible dansaidp_workbench.yaml |
|
|
| 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
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
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
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.
|
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.yamlvariables:
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"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 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.
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. |