11 Carnets

Ce chapitre fournit des informations sur l'utilisation et la gestion des carnets dans votre espace de travail.

Rubriques :

Développer du code dans les carnets

Les ingénieurs et les scientifiques de données peuvent utiliser des calepins électroniques dans leur atelier de plateforme de données Oracle AI comme outil commun pour développer interactivement du code et explorer des données.

L'atelier Plate-forme de données Oracle AI prend actuellement en charge les langages Python, SQL et Scala dans les carnets. Les carnets peuvent être programmés ou configurés pour s'exécuter dans le cadre d'un flux de travail. Pour exécuter des carnets, vous devez attacher une grappe de calcul.

Votre atelier de plate-forme de données IA est fourni avec des blocs-notes gérés intégrés pour une expérience de développement intuitive.

Vous pouvez utiliser l'exemple de code dans le référentiel Git Exemples de l'atelier Plate-forme de données d'Oracle AI pour obtenir des exemples de code que vous pouvez utiliser avec votre carnet.

Enregistrement automatique

Les carnets sont automatiquement enregistrés toutes les deux minutes.

Importation et exportation de carnets

Vous pouvez actuellement importer un fichier de carnet (*.ipynb) depuis votre ordinateur local vers votre espace de travail.

L'exportation de carnets n'est pas prise en charge actuellement.

Créer un carnet

Vous pouvez créer un carnet dans n'importe quel espace de travail pour lequel vous disposez des autorisations d'administrateur.

  1. Dans la page d'accueil, accédez à votre espace de travail.
  2. Cliquez sur Créer et cliquez sur Carnet.
  3. Entrez le nom et la description, puis cliquez sur Créer.

Attacher une grappe existante à un carnet

Les carnets nécessitent une grappe attachée pour fournir la puissance de calcul du code développé.

  1. Dans la page d'accueil, accédez à votre espace de travail et ouvrez votre carnet.
  2. Cliquez sur Actions, puis sur Attacher une grappe existante.
  3. Cliquez sur le cluster que vous souhaitez utiliser dans la liste.
    Votre carnet affiche Grappe : (ClusterName) en cours d'exécution lorsqu'il a été attaché. Cela peut prendre quelques minutes.

Créer une grappe pour un carnet

Vous pouvez créer une nouvelle grappe directement à partir de l'interface de carnet et l'attacher immédiatement.

Pour plus d'informations, voir À propos des grappes de calcul.
  1. Dans la page d'accueil, accédez à votre espace de travail et ouvrez votre carnet.
  2. Cliquez sur Actions, puis sur Créer une grappe.
  3. Sélectionnez Version d'exécution.
  4. Sélectionnez les options de pilote pour votre grappe.
  5. Sélectionnez les options de traitement de votre grappe. Ces options s'appliquent à tous les travailleurs de grappe.
  6. Indiquez si le nombre de travailleurs est statique ou s'il est mis à l'échelle automatiquement.
    • Si Montant statique, indiquez le nombre de travailleurs.
    • Si vous sélectionnez Ajustement automatique, spécifiez le nombre minimal et maximal de travailleurs auxquels la grappe peut s'adapter.
  7. Pour Durée d'exécution, indiquez si la grappe s'arrêtera après une durée définie d'inactivité. Si l'option Temporisation d'inactivité est sélectionnée, spécifiez la durée d'inactivité, en minutes, avant la temporisation de la grappe.
  8. Cliquez sur Créer.

Langue par défaut

Vous pouvez utiliser des carnets pour développer et exécuter du code Apache Spark en Python, SQL ou Scala.

Le langage par défaut pour les carnets est Python. Vous pouvez modifier la langue par défaut pour l'ensemble du carnet ou pour les cellules individuelles en SQL, Scala, Markdown ou en texte brut. Vous pouvez combiner du code Python, SQL et Scala dans différentes cellules du même carnet.

Les carnets ont une mise en surbrillance syntaxique pour Python, SQL et Scala. De nouvelles cellules de carnet seront créées en fonction de la langue par défaut du carnet.

Gérer les carnets

Vous pouvez renommer et supprimer vos propres carnets. Vous pouvez également cloner des carnets pour copier leur contenu et utiliser son code dans un nouveau carnet.

Vous renommez et supprimez vos carnets à partir de leur menu d'actions dans votre espace de travail. Vous clonez votre carnet en l'ouvrant et en sélectionnant l'option Cloner dans le menu Fichier.

Renommer un carnet

Si le nom de votre ordinateur portable n'est plus utile ou pertinent, vous pouvez le modifier à tout moment.

  1. Dans la page d'accueil, accédez à votre espace de travail.
  2. À côté du carnet à renommer, cliquez sur Actions, puis sur Renommer.
  3. Entrez un nouveau nom et cliquez sur Enregistrer.
  4. Facultatif : Vous pouvez également modifier le nom d'un carnet ouvert en cliquant sur son nom et en entrant un nouveau.

Supprimer un carnet

Vous pouvez supprimer des carnets pour lesquels vous disposez des autorisations d'administrateur.

  1. Accédez à votre espace de travail.
  2. À côté du carnet à supprimer, cliquez sur Actions, puis sur Supprimer.
  3. Cliquez sur Supprimer.

Cloner un carnet

Vous pouvez cloner un carnet existant pour créer une copie du contenu de ce carnet que vous pouvez modifier tout en conservant l'original.

  1. Ouvrez le carnet à cloner.
  2. Dans la barre d'outils du carnet, cliquez sur Fichier, puis sur Cloner.
  3. Entrez un nouveau nom pour le carnet cloné.
  4. Cliquez sur Parcourir pour sélectionner le dossier de l'espace de travail dans lequel enregistrer le carnet cloné. Si aucun dossier n'est sélectionné, le carnet cloné est créé dans le même dossier que le carnet que vous clonez.
  5. Sélectionnez si les sorties doivent être incluses ou exclues. Les sorties sont incluses par défaut. Effacez la sélection pour exclure les sorties.
  6. Cliquez sur Cloner. Le carnet cloné est créé dans le dossier d'espace de travail que vous avez spécifié.

Parcourir les ressources lors de la modification du carnet

Lorsque vous êtes dans un carnet, vous pouvez parcourir les objets du catalogue ou de l'espace de travail sur le côté gauche sans quitter votre carnet.

Si vous glissez-déposez un objet du volet de gauche vers le carnet, le nom de l'objet ou le chemin complet est copié et collé dans la cellule du carnet (selon le contexte).


Carnet ouvert avec un objet glissé et déposé dans le carnet

Vous disposez également d'un bouton et d'options de menu contextuel pour chaque objet de catalogue ou d'espace de travail dans le volet de gauche. Le menu contextuel de la navigation de gauche contient des options pour copier un exemple de code, un nom de copie ou un chemin de copie, et vous pouvez le coller dans la cellule de votre carnet.


Options du menu contextuel affichées dans le volet gauche d'un carnet

Exécuter les carnets

Vous pouvez exécuter du code dans les carnets que vous possédez ou à partir de carnets partagés avec vous.

Le code peut être exécuté à partir d'un carnet à l'aide de trois méthodes : exécution sur demande, exécution manuelle ponctuelle ou création d'une tâche de carnet programmée. Les tâches exécutées sur demande ne sont exécutées qu'une seule fois.

Exécution de commandes de terminal dans un carnet

Vous pouvez exécuter des commandes de terminal de base ou des commandes shell dans un carnet en ajoutant un préfixe '!'. Par exemple, vous pouvez utiliser la commande unzip pour extraire des fichiers ZIP dans l'espace de travail.


Exemple de la commande décompresser en cours d'utilisation

Vous pouvez également utiliser le module de sous-processus dans Python pour l'exécution du script d'interpréteur de commandes.


Exemple de commande de sous-processus utilisée

Vous pouvez également utiliser des modules Python natifs tels que zipfile pour des tâches telles que la décompression de fichiers en tant qu'alternative aux commandes d'interpréteur de commandes.

Limitations

Actuellement, Oracle AI Data Platform Workbench n'a pas de prise en charge native des systèmes d'installation par pip, d'intégration et de développement en continu, de Git ou de contrôle des versions.

Options d'exécution pour les cellules de carnet

Le menu Exécuter des carnets vous offre des options pour exécuter des cellules dans un carnet.

<Entrer le titre de section ici>

Vous pouvez trouver toutes les options pour exécuter des cellules dans votre carnet à partir du menu Exécuter en haut de votre carnet.


Le menu Exécuter dans un carnet s'ouvre et affiche les options permettant d'exécuter des cellules dans un carnet

Tableau 11-1 : Options d'exécution pour les cellules de carnet

Option Description
Tout exécuter Exécute toutes les cellules du carnet de façon séquentielle.
Exécuter les cellules sélectionnées Exécute la ou les cellules actuellement sélectionnées.
Exécuter tous les éléments ci-dessus Exécute la cellule actuellement sélectionnée et toutes les cellules qui apparaissent au-dessus de la cellule actuellement sélectionnée dans le carnet.
Exécuter tout ce qui suit Exécute la cellule actuellement sélectionnée et toutes les cellules qui apparaissent sous la cellule actuellement sélectionnée dans le carnet.
Exécuter le texte sélectionné Exécute le segment de code sélectionné dans une cellule.
Aller à la cellule de la dernière exécution Permet d'accéder à la cellule d'exécution la plus récente du carnet.
Effacer toutes les sorties de cellule Supprime les sorties de toutes les cellules du carnet.

Exécuter le code à partir d'un carnet

Vous pouvez choisir d'exécuter tout le code développé dans un carnet à la fois, ou une cellule à la fois.

Les raccourcis clavier pour exécuter du code dans un carnet sont les suivants :
  • MacOS : Cmd + Retour
  • Windows : Ctrl + Entrée

Vous pouvez exécuter du code dans une seule cellule en cliquant sur le bouton Bouton de lecture de carnet Lire ou sur l'ensemble du carnet en cliquant sur Tout exécuter.

  1. Dans la page d'accueil, cliquez sur Espace de travail.
  2. Naviguez jusqu'à votre carnet.
  3. Cliquez sur Tout exécuter.
  4. Vérifiez le statut de l'exécution de votre tâche de carnet en cliquant sur Flux de travail, puis sur Exécutions de travail.

Code d'exécution d'un autre carnet

Vous pouvez utiliser la commande magique %run dans un carnet pour inclure le code d'un autre carnet.

Dans l'exemple suivant, vous apportez du code à partir d'un carnet nommé appelé-notebook.ipynb, vers un carnet caller-notebook.ipynb.
  1. Installez la bibliothèque Python nbconvert.
  2. Utilisez la commande %run dans une cellule, comme dans l'exemple suivant :
    %run /Workspace/folder1/called-notebook.ipynb

Après avoir suivi ces étapes, le carnet nommé appelé-notebook.ipynb est exécuté immédiatement à l'aide de votre principal d'utilisateur (caller-notebook.ipynb) et de la grappe associée à caller-notebook.ipynb. Toutes les fonctions et variables définies dans appelé-notebook.ipynb deviennent immédiatement disponibles dans le carnet nommé caller-notebook.ipynb.

Partager la sortie du carnet avec oidlUtils

Vous pouvez capturer et partager le contenu généré par vos tâches de carnet à l'aide des utilitaires disponibles dans oidlUtils.

oidlUtils est un ensemble d'utilitaires disponibles pour tous les utilisateurs d'Oracle AI Data Platform Workbench. Lors du partage de contenu entre des carnets, oidlUtils peut être appelé pour transmettre des arguments à un carnet et transmettre la sortie au carnet de l'appelant, et il peut être appelé dans une tâche d'un carnet pour transmettre la sortie à la tâche parent, ce qui signifie que la tâche appelle sur le carnet. De cette façon, vous pouvez capturer et utiliser la sortie structurée retournée par vos tâches de carnet.

Ces modules oidlUtils peuvent être utilisés avec des carnets :

Module Description Exemple
carnet Orchestrer les exécutions de tâche de carnet et retourner un seul résultat structuré (généralement une chaîne JSON) à l'appelant. 
oidlUtils.notebook.run(
    notebook_path: str,
    timeout_seconds: int = 0, (Optional)
    parameters: dict (Optional)
) -> str
carnet Autoriser un carnet à quitter une exécution de tâche et retourner un résultat de chaîne unique (généralement des données utiles JSON) au carnet de l'appelant ou à l'API de sortie de tâche/tâche. 
oidlUtils.notebook.exit(value: str)

Exemple 1 : Partage d'un carnet vers un autre

Dans cet exemple, vous utilisez le carnet A pour appeler le carnet B. Le carnet B retourne les données utiles de résultat que le carnet A est configuré pour la capture et l'utilisation.

Carnet A

result = oidlUtils.notebook.run("NotebookB", 0)
print("Output from Notebook B:", result)
Carnet B
import json

payload = {
"status": "SUCCESS",
"rows_processed": 1234,
"output_table": "sales_gold",
"run_id": "run_2026_02_11"
}

json_payload = json.dumps(payload)
oidlUtils.notebook.exit(str(json_payload))

Sortie du carnet B

{"status": "SUCCESS", "rows_processed": 1234, "output_table": "sales_gold", "run_id": "run_2026_02_11"}

Exemple 2 : Transmission de la sortie par des tâches

Dans cet exemple, vous retournez un fichier JSON lorsque votre carnet est exécuté en tant que tâche : oidlUtils.notebook.exit(json.dumps(payload)). 

import json

payload = {
    "status": "SUCCESS",
    "output_table": "sales_gold",
    "rows_processed": 1234
}

oidlUtils.notebook.exit(json.dumps(payload))

Ensuite, vous exécutez la tâche avec votre tâche de carnet et obtenez la sortie de la tâche au moyen de l'appel d'API : endpoint = f"https://<workspace-url>/jobs/runs/get-output?run_id={task_run_id}" and response = requests.get(endpoint, headers=headers).json(). 

import requests

task_run_id = "<task_run_id>"

endpoint = f"https://<workspace-url>/jobs/runs/get-output?run_id={task_run_id}"
response = requests.get(endpoint, headers=headers).json()

Enfin, vous saisissez la sortie retournée par le carnet avec job_result = response['notebook_output']['result']. 

job_result = response["notebook_output"]["result"]
payload = json.loads(job_result)

print(payload["output_table"])   # Output : sales_gold
print(payload["rows_processed"]) # Output : 1234

Navigation dans le carnet

Vous pouvez créer et tenir à jour une table des matières qui peut être utilisée pour organiser et naviguer dans votre carnet.

Vous pouvez cliquer sur l'icône de table des matières en haut à gauche de votre carnet pour afficher une structure de carnet. La table des matières est générée automatiquement en fonction des en-têtes de démarque que vous pouvez créer, ce qui facilite l'organisation et la navigation.

Vous pouvez ajouter du texte formaté, des en-têtes, des listes et de la documentation sous forme de balisage pour organiser et expliquer le contenu des carnets pour vous-même et les autres utilisateurs.

Créer une cellule Markdown

Vous pouvez créer des cellules de démarque pour fournir des en-têtes dans la table des matières de votre carnet pour faciliter l'organisation et la navigation.

  1. Dans la page d'accueil, accédez à votre carnet.
  2. Dans la liste déroulante des types de cellule, sélectionnez Marquer.
  3. Ajoutez votre marque à la cellule.
    • Les cellules Markdown peuvent inclure du texte formaté, des en-têtes, des listes et d'autres documents.
    • Pour créer un en-tête, commencez une ligne par # suivi d'un espace. L'en-tête 1 utilise un #, l'en-tête 2 utilise ##. Ajoutez # supplémentaire pour chaque niveau d'en-tête supplémentaire.

Résultats et sortie du carnet

Vous pouvez voir les sorties du carnet et les résultats dans une nouvelle cellule qui apparaît juste après la cellule avec du code.

Pendant qu'une cellule est en cours, vous pouvez annuler son exécution. Si un carnet est exécuté en tant que tâche de flux de travail, la sortie n'est pas visible dans le même carnet. Dans ce cas, la sortie est visible dans la zone de sortie de l'exécution de travail de flux de travail correspondante.

Vous pouvez télécharger la sortie de la cellule de sortie sous forme de fichier CSV ou Excel. Vous pouvez également copier le contenu de la cellule de sortie directement dans votre presse-papiers.


Cellule de sortie dans un carnet affiché avec les boutons Copier et Télécharger mis en surbrillance. Le menu de téléchargement est ouvert et affiche les options Télécharger CSV et Télécharger Excel.

Télécharger la sortie du carnet

Vous pouvez télécharger la sortie résultante d'une cellule de carnet directement à partir du panneau des résultats.

  1. Dans le coin supérieur droit de la cellule à partir de laquelle vous voulez télécharger la sortie, cliquez sur Télécharger.
  2. Dans le menu, sélectionnez le format sous lequel vous souhaitez télécharger la sortie.

Copier la sortie du carnet

Vous pouvez copier la sortie résultante d'une cellule de carnet directement à partir du panneau des résultats.

  1. Dans le coin supérieur droit de la cellule à partir de laquelle vous voulez télécharger la sortie, cliquez sur Copier.
  2. Le contenu de la cellule de sortie est copié directement dans le presse-papiers. Vous pouvez le coller ailleurs dans votre carnet ou dans un emplacement externe.

Apparence du carnet

Vous pouvez modifier l'espace d'écran disponible pour travailler dans les carnets en réduisant au minimum le panneau de navigation de gauche ou en développant la vue du carnet.

Vous pouvez réduire le panneau de navigation de gauche de l'atelier Plate-forme de données d'Oracle AI pendant que vous travaillez sur votre carnet pour augmenter l'espace d'écran utilisable en cliquant sur Minimiser le panneau en bas à droite du panneau de navigation.


Volet de navigation de gauche de l'atelier Plate-forme de données d'intelligence artificielle avec icône Réduire le panneau en surbrillance

Vous pouvez également développer le carnet en cliquant sur Développer en haut à droite du carnet, en développant l'espace disponible et en facilitant la lecture des cellules et des sorties plus volumineuses.


Carnet ouvert avec l'icône Développer en surbrillance

Numéros d'exécution de cellule

Chaque cellule de carnet affiche un numéro d'exécution qui indique l'ordre dans lequel les cellules ont été exécutées. Ce nombre est mis à jour chaque fois que la cellule est exécutée. Vous pouvez exécuter des cellules dans n'importe quel ordre, de sorte que les numéros d'exécution peuvent ne pas correspondre à l'ordre physique des cellules de votre carnet.

Gérer les exécutions de tâche

Vous pouvez créer des exécutions de travail pour gérer comment et quand le code est exécuté à partir de vos carnets.

Les exécutions manuelles de travail peuvent être exécutées à nouveau ou ultérieurement pour être exécutées selon un programme. Les exécutions de tâche programmées sont déclenchées automatiquement en fonction du programme que vous avez défini. À moins qu'un programme ne soit configuré, les tâches manuelles ne sont exécutées qu'une seule fois.

Créer une tâche d'exécution manuelle à partir d'un carnet

Vous pouvez créer une tâche non programmée que vous pouvez exécuter manuellement à partir du code que vous avez développé dans votre carnet.

  1. Sur la page d'accueil, cliquez sur Espace de travail.
  2. Naviguez jusqu'à votre carnet.
  3. Cliquez sur Actions, puis sur Programmer.
  4. Entrer un nom et une description pour la tâche.
  5. Cliquez sur Parcourir et sélectionnez l'emplacement où stocker votre travail. Cliquez sur Sélectionner.
  6. Sélectionnez une grappe de calcul dans la liste déroulante Grappe.
  7. Pour Programmer, sélectionnez Exécution manuelle.
  8. Cliquez sur Créer.

Créer une exécution de tâche programmée à partir d'un carnet

Vous pouvez créer une tâche programmée qui s'exécute automatiquement à partir du code que vous avez développé dans votre carnet.

  1. Sur la page d'accueil, cliquez sur Espace de travail.
  2. Naviguez jusqu'à votre carnet.
  3. Cliquez sur Actions, puis sur Programmer.
  4. Entrez un nom et une description pour la tâche.
  5. Cliquez sur Parcourir et sélectionnez l'emplacement où stocker votre travail. Cliquez sur Sélectionner.
  6. Sélectionnez une grappe de calcul dans la liste déroulante Grappe.
  7. Pour Programme, sélectionnez Programme.
  8. Sélectionnez un statut de programmation.
    • Sélectionnez Actif si vous voulez que le programme soit activé immédiatement.
    • Sélectionnez Paused (Pausé) pour activer manuellement l'exécution programmée ultérieurement.
  9. Indiquez le fuseau horaire sur lequel le programme doit être basé.
  10. Sélectionnez le type de programmation.
    • Pour Calendrier, vous devez spécifier la fréquence et les heures ou les jours de répétition du programme.
    • Pour Expression cron, vous devez fournir la programmation sous la forme d'une expression cron.
  11. Vérifiez l'heure d'exécution indiquée en bas pour vérifier que votre programme est correct. Cliquez sur Créer.

Raccourcis clavier de carnet

Vous pouvez utiliser des raccourcis clavier pour simplifier l'utilisation des commandes de votre carnet.

Windows macOS Action
Ctrl + Entrer Code + retour Exécuter la cellule
Maj+Entrée Quart + retour Exécuter la cellule et passer à la cellule suivante
Ctrl + S Cmd + S Enregistrer le carnet
Ctrl+N Ctrl+N Nouveau carnet
Ctrl + Z Code + Z Annulé
Ctrl + Y Code + Y Rétablir
Ctrl + C Cmd + C Copier
Ctrl + X Code +X Couper
Ctrl + V Cmd + V Coller
Ctrl + Alt + F Ctrl + Option + F Recherche et remplacement
Ctrl + Maj + A Ctrl + Maj + A Insérer des cellules au-dessus
Ctrl + Maj + B Ctrl + Maj + B Insérer des cellules ci-dessous
Ctrl + Alt + Haut Ctrl + Option + Haut Déplacer la cellule vers le haut
Ctrl + Alt + Bas Ctrl + Option + Bas Déplacer la cellule vers le bas
Ctrl+D Ctrl+D Supprimer la cellule
Alt + Maj + Entrée Option + quart + retour Tout exécuter
Alt + Maj + Haut Option + Maj + haut Exécuter toutes les cellules ci-dessus

Migrer un code Apache Spark existant vers l'atelier de plate-forme de données d'Oracle AI

Vous pouvez adapter votre code Apache Spark pour le migrer en vue de son utilisation dans des blocs-notes Oracle AI Data Platform Workbench.

Si vous migrez du code Spark existant à partir d'autres plates-formes, vous pouvez utiliser les directives suivantes pour adapter votre code pour l'utiliser dans les carnets.

Tableau 11-2 : Directives de migration d'Apache Spark vers AI Data Platform

Instruction Détails
Supprimer les commandes de création SparkSession AI Data Platform Workbench crée automatiquement un contexte SparkContext pour chaque grappe de calcul. Nous vous recommandons de supprimer les commandes de création de session ou de les remplacer par SparkSession.builder().getOrCreate().
Supprimer les commandes d'arrêt de session, telles que sys.exit() ou spark.stop() Toutes les grappes de calcul sont des grappes partagées. Par conséquent, si des utilisateurs arrêtent SparkSession, à l'aide de sys.exit() ou de spark.stop(), par exemple, la grappe doit être redémarrée pour tous. Pour éviter les interruptions, nous vous recommandons d'éviter ces commandes dans les carnets.