11 Notebook

In questo capitolo vengono fornite informazioni sull'uso e la gestione dei notebook nell'area di lavoro.

Argomenti:

Sviluppare codice nei notebook

I data engineer e i data scientist possono utilizzare i notebook nel loro Oracle AI Data Platform Workbench come strumento comune per lo sviluppo interattivo di codice ed l'esplorazione dei dati.

Oracle AI Data Platform Workbench attualmente supporta i linguaggi Python, SQL e Scala nei notebook. I notebook possono essere pianificati o configurati per essere eseguiti come parte di un workflow. Per eseguire i notebook, è necessario collegare un cluster di computazione.

Il tuo workbench AI Data Platform è dotato di notebook gestiti integrati per un'esperienza intuitiva per gli sviluppatori.

È possibile utilizzare il codice di esempio nel repository Git Oracle AI Data Platform Workbench Samples per esempi di codice che è possibile utilizzare con il notebook.

Salvataggio automatico

I notebook vengono salvati automaticamente ogni due minuti.

Importazione ed esportazione di notebook

È attualmente possibile importare un file notebook (*.ipynb) dal computer locale all'area di lavoro.

L'esportazione dei notebook non è attualmente supportata.

Crea un notebook

È possibile creare un notebook in qualsiasi area di lavoro che si dispone delle autorizzazioni di amministratore.

  1. Nella home page, andare all'area di lavoro.
  2. Fare clic su Crea, quindi su Notebook.
  3. Compilare il nome e una descrizione, quindi fare clic su Crea.

Collega un cluster esistente a un notebook

I notebook richiedono un cluster collegato per fornire potenza di calcolo per il codice sviluppato.

  1. Nella home page, accedere all'area di lavoro e aprire il notebook.
  2. Fare clic su Azioni, quindi su Collega un cluster esistente.
  3. Fare clic sul cluster che si desidera utilizzare dalla lista.
    Il notebook mostrerà Cluster: (ClusterName) in esecuzione quando è stato collegato correttamente. Questa operazione può richiedere fino a diversi minuti.

Creare un cluster per un notebook

È possibile creare un nuovo cluster direttamente dall'interfaccia notebook e collegarlo immediatamente.

Per ulteriori informazioni, vedere Informazioni sui cluster di computazione.
  1. Nella home page, accedere all'area di lavoro e aprire il notebook.
  2. Fare clic su Azioni, quindi su Crea cluster.
  3. Selezionare Versione runtime.
  4. Selezionare le opzioni del driver per il cluster.
  5. Selezionare le opzioni del worker per il cluster. Queste opzioni si applicano a tutti i lavoratori del cluster.
  6. Selezionare se il numero di lavoratori è statico o scala automaticamente.
    • Se Importo statico, specificare il numero di fasi processo.
    • Se Scalabilità automatica, specificare il numero minimo e massimo di worker su cui il cluster può eseguire lo scale.
  7. Per Durata esecuzione, selezionare se l'esecuzione del cluster verrà interrotta dopo una durata di inattività impostata. Se l'opzione Timeout inattività è selezionata, specificare il tempo di inattività, in minuti, prima del timeout del cluster.
  8. Fare clic su Crea.

Lingua predefinita

È possibile utilizzare i notebook per sviluppare ed eseguire codice Apache Spark in Python, SQL o Scala.

Il linguaggio predefinito per i notebook è Python. È possibile modificare la lingua predefinita per l'intero notebook o per singole celle in SQL, Scala, Markdown o testo raw. È possibile combinare codice Python, SQL e Scala in celle diverse all'interno dello stesso notebook.

I notebook dispongono di evidenziazione della sintassi per Python, SQL e Scala. Le nuove celle notebook verranno create in base alla lingua predefinita del notebook.

Gestisci notebook

È possibile rinominare ed eliminare i notebook personali. È inoltre possibile clonare i notebook per copiarne il contenuto e utilizzarne il codice in un nuovo notebook.

È possibile rinominare ed eliminare i notebook dal relativo menu azioni nell'area di lavoro. Per duplicare il blocco appunti, aprirlo e selezionare l'opzione Duplica dal menu File.

Rinomina un notebook

Se il nome del notebook non è più utile o pertinente, è possibile modificarlo in qualsiasi momento.

  1. Nella home page, andare all'area di lavoro.
  2. Accanto al blocco note che si desidera rinominare, fare clic su Azioni, quindi su Rinomina.
  3. Immettere un nuovo nome e scegliere Salva.
  4. Facoltativo: è inoltre possibile modificare il nome di un blocco appunti aperto facendo clic sul nome e immettendone uno nuovo.

Elimina blocco note

È possibile eliminare i notebook per i quali si dispone delle autorizzazioni di amministratore.

  1. Passare all'area di lavoro.
  2. Accanto al blocco note che si desidera eliminare, fare clic su Azioni, quindi su Elimina.
  3. Fare clic su Elimina.

Duplica un notebook

È possibile clonare un notebook esistente per creare una copia del contenuto del notebook che è possibile modificare conservando l'originale.

  1. Aprire il notebook da duplicare.
  2. Nella barra degli strumenti del blocco appunti, fare clic su File, quindi su Duplica.
  3. Immettere un nuovo nome per il blocco note duplicato.
  4. Fare clic su Sfoglia per selezionare la cartella dell'area di lavoro in cui salvare il blocco appunti duplicato. Se non è selezionata alcuna cartella, il blocco appunti clonato viene creato nella stessa cartella del blocco appunti che si sta clonando.
  5. Selezionare se includere o escludere gli output. Gli output sono inclusi per impostazione predefinita. Cancellare la selezione per escludere gli output.
  6. Fare clic su Duplica. Il blocco note clonato viene creato nella cartella dell'area di lavoro specificata.

Sfoglia risorse durante la modifica del notebook

Quando ci si trova in un notebook, è possibile sfogliare il catalogo o gli oggetti dell'area di lavoro sul lato sinistro senza uscire dal notebook.

Se si trascina un oggetto dal riquadro di sinistra al blocco appunti, il nome dell'oggetto o il percorso completo viene copiato e incollato nella cella del blocco appunti (a seconda del contesto).


Un notebook aperto con un oggetto trascinato e rilasciato nel notebook

Sono inoltre disponibili opzioni di pulsante e menu di scelta rapida per ogni oggetto catalogo o area di lavoro nel riquadro di sinistra. Il menu di scelta rapida nella navigazione a sinistra contiene opzioni per copiare il codice di esempio, il nome della copia o il percorso della copia e quindi incollarlo nella cella del notebook.


Opzioni del menu di scelta rapida visualizzate nel riquadro sinistro di un blocco appunti

Esegui blocchi note

È possibile eseguire il codice nei notebook di proprietà dell'utente o da quelli condivisi con l'utente.

Il codice può essere eseguito da un blocco note utilizzando tre metodi: esecuzione su richiesta, esecuzione manuale una tantum o creazione di un processo blocco note pianificato. I job eseguiti su richiesta vengono eseguiti una sola volta.

Esecuzione dei comandi del terminale all'interno di un notebook

È possibile eseguire comandi di base del terminale o comandi della shell all'interno di un notebook premendo un prefisso '!'. Ad esempio, è possibile utilizzare il comando unzip per estrarre i file ZIP dall'area di lavoro.


Esempio di comando unzip in uso

È inoltre possibile utilizzare il modulo subprocess in Python per l'esecuzione degli script shell.


Esempio di comando del sottoprocesso in uso

È inoltre possibile utilizzare moduli Python nativi come zipfile per task quali la decompressione dei file in alternativa ai comandi della shell.

Limitazioni

Al momento, Oracle AI Data Platform Workbench non dispone del supporto nativo per sistemi di installazione di pipeline, CI/CD, Git o controllo delle versioni.

Opzioni di esecuzione per celle notebook

Il menu Esegui nei notebook offre opzioni per l'esecuzione di celle in un notebook.

<Immettere il titolo della sezione qui>

È possibile trovare tutte le opzioni per l'esecuzione delle celle nel notebook dal menu Esegui nella parte superiore del notebook.


Il menu Esegui in un notebook apre e visualizza le opzioni per eseguire le celle in un notebook

Tabella 11-1 Opzioni di esecuzione per le celle notebook

Opzione Descrizione
Esegui tutto Esegue tutte le celle del notebook in sequenza.
Esegui celle selezionate Esegue la cella o le celle attualmente selezionate.
Esegui tutto quanto sopra Esegue la cella attualmente selezionata e qualsiasi cella visualizzata sopra la cella attualmente selezionata nel notebook.
Esegui tutto di seguito Esegue la cella attualmente selezionata e qualsiasi cella visualizzata sotto la cella attualmente selezionata nel notebook.
Esegui il testo selezionato Esegue il segmento di codice selezionato in una cella.
Vai alla cella dell'ultima esecuzione Consente di passare alla cella eseguita più di recente nel notebook.
Cancella tutti gli output cella Rimuove gli output da tutte le celle del notebook.

Esegui codice da blocco note

È possibile scegliere di eseguire tutto il codice sviluppato in un notebook contemporaneamente o una cella alla volta.

Di seguito sono riportati i tasti di scelta rapida per l'esecuzione del codice in un notebook.
  • MacOS: Cmd + Return
  • Windows: Ctrl + Invio

È possibile eseguire il codice in una singola cella facendo clic sul pulsante Pulsante di riproduzione notebook Esegui oppure eseguire l'intero blocco appunti facendo clic su Esegui tutto.

  1. Nella home page, fare clic su Area di lavoro.
  2. Passare al notebook.
  3. Fare clic su Esegui tutto.
  4. Controllare lo stato dell'esecuzione del job notebook facendo clic su Flusso di lavoro, quindi su Esecuzioni job.

Esegui codice da un altro notebook

È possibile utilizzare il comando magic %run in un notebook per includere codice da un altro notebook.

Nell'esempio riportato di seguito, è possibile trasferire il codice da un notebook denominato notebook.ipynb a un notebook caller-notebook.ipynb.
  1. Installare la libreria Python nbconvert.
  2. Utilizzare il comando %run in una cella, come nell'esempio seguente:
    %run /Workspace/folder1/called-notebook.ipynb

Dopo aver seguito questi passaggi, il blocco appunti denominato detto-notebook.ipynb viene eseguito immediatamente utilizzando il principal utente (ad esempio caller-notebook.ipynb) e utilizzando il cluster collegato di caller-notebook.ipynb. Tutte le funzioni e le variabili definite in detto-notebook.ipynb diventano immediatamente disponibili nel notebook denominato caller-notebook.ipynb.

Condividi output notebook con oidlUtils

È possibile acquisire e condividere l'output del contenuto in base ai task del notebook utilizzando le utility disponibili in oidlUtils.

oidlUtils è un set di utility disponibili per tutti gli utenti di Oracle AI Data Platform Workbench. Quando si condivide il contenuto tra i notebook, è possibile chiamare oidlUtils per passare gli argomenti a un notebook e passare l'output al notebook del chiamante, che può essere richiamato in un task di job in un notebook per passare l'output al task padre, ovvero il task che richiama il notebook. Usato in questo modo, è possibile acquisire e utilizzare l'output strutturato restituito dai task del notebook.

Questi moduli oidlUtils sono disponibili per l'uso con i notebook:

Modulo Descrizione Esempio
quaderno Orchestra le esecuzioni dei task notebook e restituisce un singolo risultato strutturato (in genere una stringa JSON) al chiamante. 
oidlUtils.notebook.run(
    notebook_path: str,
    timeout_seconds: int = 0, (Optional)
    parameters: dict (Optional)
) -> str
quaderno Consente a un notebook di uscire dall'esecuzione di un task e di restituire un singolo risultato stringa (in genere un payload JSON) al notebook del chiamante o all'API di output job/task. 
oidlUtils.notebook.exit(value: str)

Esempio 1: Condivisione da blocco note a blocco note

In questo esempio viene utilizzato il notebook A per richiamare il notebook B. Notebook B restituisce un payload dei risultati impostato per l'acquisizione e l'uso del notebook A.

Notebook A

result = oidlUtils.notebook.run("NotebookB", 0)
print("Output from Notebook B:", result)
Notebook 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))

Output del notebook B

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

Esempio 2: passaggio dell'output tramite task job

In questo esempio, viene restituito un file JSON quando il notebook viene eseguito come task: oidlUtils.notebook.exit(json.dumps(payload)). 

import json

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

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

Successivamente si esegue il job con il task notebook e si ottiene l'output del task tramite la chiamata 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()

Infine, si acquisisce l'output restituito dal notebook con 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

Navigazione notebook

È possibile creare e gestire un sommario che può essere utilizzato per organizzare e navigare nel notebook.

È possibile fare clic sull'icona dell'indice nella parte superiore sinistra del blocco appunti per visualizzare un profilo del blocco appunti. L'indice viene generato automaticamente in base alle intestazioni di ribasso che è possibile creare, consentendo una facile organizzazione e navigazione.

È possibile aggiungere testo, intestazioni, elenchi e documentazione formattati come markdown per organizzare e spiegare il contenuto del blocco appunti per se stessi e per altri utenti.

Crea cella ribasso

È possibile creare celle di markdown per fornire intestazioni nel sommario del notebook per facilitare l'organizzazione e la navigazione.

  1. Dalla home page, passare al notebook.
  2. Dall'elenco a discesa Tipo di cella selezionare Contrassegno.
  3. Aggiungere il markdown alla cella.
    • Le celle di ribasso possono includere testo formattato, intestazioni, elenchi e altra documentazione.
    • Per creare un'intestazione, iniziare una riga con # seguita da uno spazio. L'intestazione 1 utilizza un solo #, mentre l'intestazione 2 utilizza ##. Aggiungere # aggiuntivo per ogni livello di intestazione aggiuntivo.

Output e risultati notebook

È possibile visualizzare gli output del notebook e i risultati in una nuova cella che viene visualizzata subito dopo la cella con codice.

Durante l'esecuzione di una cella, è possibile annullare l'esecuzione della cella. Se un notebook viene eseguito come job del workflow, l'output non è visibile nello stesso notebook. In tal caso, l'output è visibile nell'area di output dell'esecuzione del job workflow corrispondente.

È possibile scaricare l'output dalla cella di output come file CSV o Excel. È inoltre possibile copiare il contenuto della cella di output direttamente negli appunti.


Cella di output in un notebook visualizzata con i pulsanti Copia e Scarica evidenziati. Il menu Download è aperto e mostra le opzioni Scarica CSV e Scarica Excel.

Scarica output notebook

È possibile scaricare l'output risultante di una cella notebook direttamente dal pannello dei risultati.

  1. Nella parte superiore destra della cella da cui si desidera scaricare l'output, fare clic su Scarica.
  2. Dal menu, selezionare il formato in cui si desidera scaricare l'output.

Copia output notebook

È possibile copiare l'output risultante di una cella notebook direttamente dal pannello dei risultati.

  1. Nella parte superiore destra della cella da cui si desidera scaricare l'output, fare clic su Copia.
  2. Il contenuto della cella di output viene copiato direttamente negli appunti. È possibile incollarlo altrove nel notebook o in una posizione esterna.

Aspetto notebook

È possibile modificare lo spazio disponibile per l'utilizzo nei notebook riducendo al minimo il pannello di navigazione a sinistra o espandendo la vista notebook.

È possibile ridurre al minimo il pannello di navigazione sinistro di Oracle AI Data Platform Workbench mentre si lavora sul notebook per aumentare lo spazio di schermate utilizzabile facendo clic su Riduci pannello in basso a destra nel pannello di navigazione.


Riquadro di navigazione a sinistra di AI Data Platform Workbench con icona Riduci pannello evidenziata

È inoltre possibile espandere il blocco appunti facendo clic su Espandi in alto a destra, espandendo lo spazio disponibile e semplificando la lettura di celle e output più grandi.


Blocco note aperto con icona Espandi evidenziata

Numeri esecuzione cella

Ogni cella notebook visualizza un numero di esecuzione che indica l'ordine di esecuzione delle celle. Questo numero viene aggiornato ogni volta che viene eseguita la cella. È possibile eseguire le celle in qualsiasi ordine, pertanto i numeri di esecuzione potrebbero non corrispondere all'ordine fisico delle celle nel notebook.

Gestire le esecuzioni dei job

È possibile creare esecuzioni di job per gestire le modalità e i tempi di esecuzione del codice dai notebook.

Le esecuzioni manuali dei job possono essere eseguite di nuovo o in seguito impostate per essere eseguite in base a una pianificazione. Le esecuzioni dei job pianificati vengono attivate automaticamente in base alla pianificazione impostata. A meno che non sia configurata una pianificazione, i processi manuali vengono eseguiti una sola volta.

Creare un job di esecuzione manuale da un notebook

È possibile creare un job non pianificato che può essere eseguito manualmente dal codice sviluppato nel notebook.

  1. Nella home page, fare clic su Area di lavoro.
  2. Passare al notebook.
  3. Fare clic su Azioni, quindi su Programma.
  4. Fornire un nome e la descrizione per il job.
  5. Fare clic su Sfoglia e selezionare la posizione in cui memorizzare la mansione. Fare clic su Seleziona.
  6. Selezionare un cluster di computazione dall'elenco a discesa Cluster.
  7. Per Programma, selezionare Esecuzione manuale.
  8. Fare clic su Crea.

Creare un'esecuzione job pianificata da un notebook

È possibile creare un job pianificato che viene eseguito automaticamente dal codice sviluppato nel notebook.

  1. Nella home page, fare clic su Area di lavoro.
  2. Passare al notebook.
  3. Fare clic su Azioni, quindi su Programma.
  4. Fornire un nome e la descrizione per il job.
  5. Fare clic su Sfoglia e selezionare la posizione in cui memorizzare la mansione. Fare clic su Seleziona.
  6. Selezionare un cluster di computazione dall'elenco a discesa Cluster.
  7. Per Programma, selezionare Programma.
  8. Selezionare uno stato della schedulazione.
    • Selezionare Attivo se si desidera che la pianificazione venga abilitata immediatamente.
    • Selezionare Sospeso se si desidera abilitare manualmente l'esecuzione pianificata in un secondo momento.
  9. Fornire un fuso orario su cui basare la pianificazione.
  10. Selezionare Tipo di pianificazione.
    • Per Calendario, è necessario specificare la frequenza e le ore o i giorni di ripetizione della pianificazione.
    • Per Espressione Cron, è necessario fornire la pianificazione sotto forma di espressione cron.
  11. Controlla il tempo di esecuzione elencato in basso per confermare che la tua pianificazione sia corretta. Fare clic su Crea.

Tasti di scelta rapida per notebook

È possibile utilizzare i tasti di scelta rapida per semplificare l'utilizzo dei comandi nel notebook.

Windows macOS Azione
Ctrl + Invio Cmd + reso Esegui celle
Maiusc + Invio Turno + Reso Esegui cella e passa alla cella successiva
Ctrl + S Cmd + S Salva notebook
Ctrl + N Ctrl + N Nuovo notebook
Ctrl + Z Cmd + Z Annulla
Ctrl + Y CMD + Y Ripristina
Ctrl + C Cmd + C Copiare
Ctrl + X Cmd +X Taglia
Ctrl + V Cmd + V Incolla
CTRL + ALT + F Ctrl + Opzione + F Trova e sostituisci
Ctrl + Maiusc + A Ctrl + Maiusc + A Inserisci celle sopra
CTRL + MAIUSC + B CTRL + MAIUSC + B Inserisci celle sotto
Ctrl + Alt + Su Ctrl + Opzione + Su Sposta cella in alto
CTRL + ALT + GIÙ CTRL + opzione + GIÙ Sposta cella in basso
Ctrl + D Ctrl + D Elimina celle
Alt + Maiusc + Invio Opzione + Maiusc + Restituzione Esegui tutto
ALT + MAIUSC + SU Opzione + Maiusc + Su Esegui tutte le celle precedenti

Eseguire la migrazione del codice Apache Spark esistente in Oracle AI Data Platform Workbench

Puoi adattare il tuo codice Apache Spark per eseguirne la migrazione e utilizzarlo nei notebook di Oracle AI Data Platform Workbench.

Se si esegue la migrazione del codice Spark esistente da altre piattaforme, è possibile utilizzare le seguenti linee guida per adattare il codice da utilizzare nei notebook.

Tabella 11-2 Linee guida per la migrazione da Apache Spark ad AI Data Platform

Istruzione Dettagli
Rimuovi comandi di creazione SparkSession AI Data Platform Workbench crea automaticamente uno SparkContext per ogni cluster di computazione. Si consiglia di rimuovere i comandi di creazione della sessione o di sostituirli con SparkSession.builder().getOrCreate().
Rimuovere i comandi di interruzione della sessione, ad esempio sys.exit() o spark.stop() I cluster di computazione per tutti gli scopi sono cluster condivisi, pertanto se uno qualsiasi degli utenti interrompe SparkSession, ad esempio utilizzando sys.exit() o spark.stop(), il cluster deve essere riavviato per tutti. Per evitare interruzioni, si consiglia di evitare tali comandi nei notebook.