7 筆記本
本章提供有關使用和管理工作區中記事本的資訊。
在記事本中開發程式碼
資料工程師和資料科學家可以在他們的 Oracle AI Data Platform 中使用筆記型電腦,作為互動開發程式碼和探索資料的通用工具。
Oracle AI Data Platform 目前在筆記型電腦中支援 Python、SQL 和 Scala 語言。您可以排定記事本,或將記事本設定為在工作流程中執行。若要執行記事本,您必須連附運算叢集。
您的 AI Data Platform 隨附整合式受管理筆記型電腦,提供直觀的開發人員體驗。
您可以使用 Oracle AI Data Platform 範例 Git 儲存區域中的範例程式碼,取得可與您的筆記型電腦搭配使用的程式碼範例。
自動節省
記事本每兩分鐘會自動儲存一次。
匯入和匯出記事本
您目前可以從本機機器將記事本檔案 (*.ipynb) 匯入您的工作區。
目前不支援匯出記事本。
建立記事本的叢集
您可以直接從記事本介面建立新叢集,然後立即附加。
- 在首頁上,瀏覽至您的工作區並開啟您的記事本。
- 按一下「動作」,然後按一下「建立叢集」。
- 選取程式實際執行版本。
- 選取叢集的驅動程式選項。
- 選取叢集的工作者選項。這些選項適用於所有叢集工作者。
- 選取職工人數為靜態或自動調整。
- 如果是靜態金額,請指定工作程式的數目。
- 如果是自動調整,請指定叢集可調整的工作程式數目下限和上限。
- 在執行持續時間中,選取叢集是否將在設定的無活動持續時間後停止執行。如果選取閒置逾時,請指定叢集逾時之前的閒置時間 (分鐘)。
- 按一下建立。
預設語言
您可以使用筆記本來開發及執行 Python、SQL 或 Scala 中的 Apache Spark 程式碼。
記事本的預設語言為 Python。您可以將整個記事本或個別儲存格的預設語言變更為 SQL、Scala、Markdown 或 raw 文字。您可以在同一記事本內的不同儲存格中結合 Python、SQL 和 Scala 程式碼。
記事本包含 Python、SQL 和 Scala 的語法突顯功能。將根據記事本的預設語言建立新的記事本儲存格。
筆記本中的小工具
小工具可讓您在記事本中定義輸入值。
您可以在以互動方式執行記事本時提供值。工作、工作流程任務或上階記事本也可以在執行階段提供值。
當相同的記事本必須以不同的值 (例如處理日期、環境、區域或資料集名稱) 執行時,您可以使用小工具。以小工具定義輸入可讓您重複使用記事本,而不需編輯每次執行的程式碼。
記事本可以包含下列小工具類型
| 小工具型態 | 描述 |
|---|---|
text |
已接受任何字串值。 |
dropdown |
使用者可從已定義的清單中選取一個值。 |
combobox |
使用者可選取已定義的值或輸入自訂值。 |
multiselect |
使用者可從已定義的清單中選取一或多個值。 |
小工具名稱在記事本中必須是唯一的。所有小工具值都會以字串傳回。複選元件傳回選取的值,以逗號分隔的字串 。
附註:
您至少需有記事本的 USE 權限,才能變更互動式記事本執行的小工具值。您需要 MANAGE 權限才能建立或移除小工具。筆記本小工具範例
下列範例示範您記事本中不同的小工具使用案例。
當您以互動方式執行記事本時,小工具會顯示在小工具面板中。您可以在執行記事本之前變更其值。
文字元件 Comment
此範例會建立單一 text 小工具,採用提供的字串值,在此情況下,處理日期為:
aidputils.widgets.text(
name="date",
defaultValue="2026-01-01",
label="Processing date"
)下拉式清單小工具
此範例會建立單一 dropdown 小工具,讓使用者從定義的清單中選取一個值:
aidputils.widgets.dropdown(
name="environment",
defaultValue="dev",
choices=["dev", "test", "prod"],
label="Environment"
)
Combobox 元件 Name
此範例會建立單一 combobox 小工具,為使用者提供定義的值以從清單中進行選取,以及輸入自訂值的欄位:
aidputils.widgets.combobox(
name="campaign",
defaultValue="renewal_outreach",
choices=["renewal_outreach", "win_back", "loyalty_offer"],
label="Campaign"
)複選元件
此範例會建立單一 multiselect 小工具,為使用者提供定義的值,以從下列項目中選取多個選項:
aidputils.widgets.multiselect(
name="regions",
defaultValue="North America",
choices=["North America", "Europe", "Asia Pacific", "Latin America"],
label="Regions"
)
regions = aidputils.widgets.get("regions")多重元件
aidputils.widgets 在您的筆記型電腦中建立多個小工具。此範例會建立處理日期為字串的文字小工具,以及從已定義清單中選取環境的下拉式小工具,然後輸出結果。 aidputils.widgets.text(
name="date",
defaultValue="2026-01-01",
label="Processing date"
)
aidputils.widgets.dropdown(
name="environment",
defaultValue="dev",
choices=["dev", "test", "prod"],
label="Environment"
)
date = aidputils.widgets.get("date")
environment = aidputils.widgets.get("environment")
print(date)
print(environment)小工具值修訂
未提供其他值時,記事本會使用預設值。若要對工作流程工作執行使用不同的值,您可以新增參數至覆寫原始值的記事本工作。
附註:
參數鍵值必須符合小工具名稱。dev 之 environment 小工具的記事本,可以接收下列工作參數: environment = prod當作業執行時,記事本會使用 prod 而不是 dev。
aidputils.notebook.run() 中的 parameters 引數: aidputils.notebook.run(
"process_data",
parameters={
"date": "2026-03-01",
"environment": "test"
}
)當呼叫的記事本包含名為 date 和 environment 的小工具時,父項記事本傳送的值會覆寫該執行的小工具預設值。如需有關設定工作流程參數的詳細資訊,請參閱參數化。
管理記事本
您可以自行重新命名和刪除記事本。您也可以複製記事本以複製其內容,並在新的記事本中使用其程式碼。
您可以重新命名並刪除工作區中記事本的動作功能表。若要複製記事本,請開啟記事本,然後從「檔案」功能表中選取複製選項。
重新命名記事簿
如果您的筆記型電腦名稱不再有幫助或相關,您可以隨時進行變更。
- 在首頁上,瀏覽至您的工作區。
- 在您要重新命名的記事本旁邊,按一下動作,然後按一下重新命名。
- 輸入新名稱,然後按一下「儲存」。
- 選擇性:您也可以按一下名稱並輸入新記事本,來變更已開啟記事本的名稱。
執行記事簿
您可以在您擁有的筆記型電腦或與您共用的筆記型電腦中執行程式碼。
程式碼可以使用下列三種方法從記事本執行:視需要執行、以單次手動執行方式執行,或建立排定的記事本工作。隨選執行的工作只會執行一次。
在記事本內執行終端機命令
您可以在記事本中執行基本終端機命令或 Shell 命令,方法是在前面加上 '!'。例如,您可以使用 unzip 指令從工作區的 ZIP 檔案中擷取。

您也可以使用 Python 中的 subprocess 模組來執行 Shell 命令檔。

您也可以將原生 Python 模組 (例如 zipfile) 用於將檔案解壓縮為 Shell 指令替代的作業。
限制
Oracle AI Data Platform 目前無法原生支援管線安裝、CI/CD、Git 或版本控制系統。
記事本儲存格的執行選項
記事本中的「執行」功能表提供在記事本中執行儲存格的選項。
您可以從記事本頂端的執行功能表,找到記事本中執行儲存格的所有選項。

表格 7-1 記事本儲存格的執行選項
| 選項 | 描述 |
|---|---|
| 全部執行 | 依序執行記事本中的所有儲存格。 |
| 執行選取的儲存格 | 執行目前選取的儲存格或儲存格 。 |
| 執行以上所有項目 | 執行目前選取的儲存格以及記事本中目前所選儲存格上方的任何儲存格。 |
| 執行下方所有項目 | 執行目前選取的儲存格以及記事本中目前所選儲存格下方的任何儲存格。 |
| 執行選取的內容 | 在儲存格中執行選取的程式碼區段。 |
| 跳到最後執行的儲存格 | 導覽至記事本中最近執行的儲存格。 |
| 清除所有的儲存格輸出 | 移除記事本中所有儲存格的輸出。 |
從記事本執行代碼
您可以選擇一次執行所有在記事本中開發的程式碼,或一次執行一個儲存格。
- MacOS : Cmd + Return
- Windows : Ctrl + Enter
您可以按一下
播放按鈕以在單一儲存格中執行程式碼,或按一下全部執行以執行整個記事本。
- 在「首頁」上,按一下工作區。
- 導覽至您的筆記型電腦。
- 按一下「全部執行」。
- 依序按一下工作流程和工作執行,以檢查記事本工作執行的狀態。
從其他記事本執行代碼
您可以在記事本中使用 %run 魔術命令來包含來自其他記事本的程式碼。
遵循這些步驟之後,名為 called-notebook.ipynb 的筆記型電腦會立即使用您的使用者委派人 (即 caller-notebook.ipynb) 執行,並且使用附加的 caller-notebook.ipynb 叢集。called-notebook.ipynb 中定義的所有函式和變數都會立即出現在名為 caller-notebook.ipynb 的筆記型電腦中。
使用 oidlUtils 共用記事本輸出
您可以使用 oidlUtils 中可用的公用程式,擷取及共用筆記型電腦作業的內容輸出。
oidlUtils 是一組可供 Oracle AI Data Platform 所有使用者使用的公用程式。在記事本之間共用內容時,可以呼叫 oidlUtils 將引數傳送給一個記事本,然後將輸出傳回給呼叫者記事本,也可以在記事本的工作工作中呼叫 oidlUtils,以將輸出傳回給父項工作,也就是呼叫記事本的工作。使用這種方式,您可以擷取及使用由筆記型電腦任務傳回的結構化輸出。
這些 oidlUtils 模組可用於記事本:
| 模組 | 描述 | 範例 |
|---|---|---|
| 筆記本 | 協調記事本作業會執行,並將單一結構化結果 (通常是 JSON 字串) 傳回給呼叫者。 | |
| 筆記本 | 允許記事本結束作業執行,並將單一字串結果 (通常只有 JSON 有效負載) 傳回給呼叫端記事本或工作 / 作業輸出 API。 | |
範例 1:記事本共用記事本
在此範例中,您可以使用記事本 A 來呼叫記事本 B。記事本 B 會傳回將記事本 A 設定為擷取與使用的結果有效負載。
筆記本 A
result = oidlUtils.notebook.run("NotebookB", 0)
print("Output from Notebook B:", result)
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))
記事本 B 的輸出
{"status": "SUCCESS", "rows_processed": 1234, "output_table": "sales_gold", "run_id": "run_2026_02_11"}範例 2:透過工作任務傳送輸出
在此範例中,當您的記事本以工作方式執行時,會傳回 JSON 檔案:oidlUtils.notebook.exit(json.dumps(payload))。
import json
payload = {
"status": "SUCCESS",
"output_table": "sales_gold",
"rows_processed": 1234
}
oidlUtils.notebook.exit(json.dumps(payload))
接下來,您使用記事本工作執行工作,並透過 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()
最後,您可以使用 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
筆記本導覽
您可以建立並維護可用來組織及瀏覽記事本的目錄。
您可以按一下記事本左上方的目錄圖示,以顯示記事本大綱。系統會根據您可建立的減價標題自動產生目錄,讓您輕鬆進行組織與瀏覽。
您可以將格式化文字、標題、清單和文件新增為 Markdown,以組織和說明您自己和其他使用者的筆記型電腦內容。
Python 滾輪檔案
您可以使用 Python 操控盤檔案,快速輕鬆地將 Python 程式碼新增至工作區中的記事本。
Python 滾輪檔案 (.WHL 檔案) 可讓您在單一檔案中封裝和分送 Python 程式碼。這樣一來,將現有的 Python 程式碼安裝到筆記本上就變得更簡單了。
您必須安裝 Python wheel 和 setuptool 套裝軟體。您可以使用 pip 從您的筆記型電腦安裝這些套裝軟體。舉例而言:
%pip install wheel setuptools您的 Python 操控盤檔案應遵循類似以下的格式:
/Workspace/<project>/
setup.py
customer_churn/
__init__.py
analytics.py
predictor.py
utils.py
data/
samples_customers.csv在您的操控盤檔案中,您應該:
- 將
setup.py保持在專案根目錄 - 將可匯入的包裹代碼保留在包裹資料夾內。在提供的範例中,套裝軟體資料夾為
customer_churn/ - 將可重複使用的邏輯程式庫放置在 .PY 檔案中,而不是在 中。IPYNB 檔案。
setup.py 檔案如下所示:
from setuptools import setup, find_packages
setup(
name="customer_churn",
version="1.0.0",
author="admin",
author_email="admin@corporation.com",
description="A package for customer churn analysis and prediction",
packages=find_packages(),
classifiers=[
"Development Status :: 4 - Beta",
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
],
python_requires=">=3.6",
install_requires=[
"pyspark>=3.0.0",
],
package_data={
'customer_churn': [
'data/*.csv',
'*.ipynb', # Include notebook files
],
},
include_package_data=True,
)customer_churn/__init__.py 檔案如下所示:
"""
Customer Churn Analysis Package
Provides tools for calculating and predicting customer churn
"""
__version__= "1.0.0"
__author__ = "admin"
from .analytics import ChurnAnalyzer
from .utils import load_customer_data, calculate_churn_rate
__all__= [
'ChurnAnalyzer',
'load_customer_data',
'calculate_churn_rate'
]__init__.py 中的每個匯入都必須指向套件中的真實 .PY 檔案。例如,utils.py 和 analytics.py 都應該位於 customer_churn 資料夾中。
建立並安裝操控盤
若要建立操控盤,您可以從記事本執行這些命令:
%%bash
cd <project_folder_location> python setup.py bdist_wheel
ls -lh dist #wheel file is created inside dist/ folder例如,對於我們的客戶流失模型,我們的建置看起來如下:
%%bash
cd /Workspace/<projectName>/customer_churn_whl
python setup.py bdist_wheel
ls -lh dist若要安裝客戶輪流檔案,請執行下列指令:
pip install /Workspace/<project>/dist/customer_churn-1.0.0-py3-none-any.whl安裝之後,您可以使用下列方法驗證安裝:
pip show customer_churn最後,您可以使用下列程式碼來測試安裝:
import customer_churn
from customer_churn import ChurnAnalyzer, load_customer_data
print("Package imported successfully!")
print(f"Version: {customer_churn.__version__}")記事本輸出與結果
您可以看到記事本輸出,結果會出現在含有程式碼的儲存格後方的新儲存格。
儲存格正在進行時,您可以取消儲存格的執行。如果記事本是以工作流程工作的方式執行,則相同的記事本中不會顯示輸出。在這種情況下,輸出會顯示在對應的工作流程工作執行的輸出區域中。
您可以將輸出儲存格的輸出下載為 CSV 或 Excel 檔案。您也可以將輸出儲存格的內容直接複製到剪貼簿。

筆記本外觀
您可以將左側的導覽面板最小化或展開記事本檢視,以更改可在記事本中使用的畫面空間。
您可以按一下導覽面板右下方的最小化面板,將 Oracle AI Data Platform 左側導覽面板最小化,同時使用筆記型電腦來增加可用的畫面空間。

您也可以按一下記事本右上方的展開來展開記事本,展開可用空間,讓較大的儲存格和輸出更容易閱讀。

儲存格執行編號
每個記事本儲存格都會顯示一個執行編號,指示儲存格的執行順序。此數字會在每次執行儲存格時更新。您可以依任何順序執行儲存格,因此執行編號可能不符合筆記型電腦中儲存格的實體順序。
管理工作批次
您可以建立工作執行,以管理從筆記型電腦執行程式碼的方式與時間。
手動工作執行可以再次執行,或稍後設定為在排程上執行。排定的工作執行會根據您設定的排程自動觸發。除非有設定排程,否則手動工作只會執行一次。
從記事本建立手動執行工作
您可以建立未排定的工作,從您在筆記型電腦中開發的程式碼手動執行。
- 在「首頁」上,按一下工作區。
- 導覽至您的筆記型電腦。
- 按一下動作,然後按一下排程。
- 提供工作的名稱與描述。
- 按一下瀏覽,然後選取儲存工作的位置。按一下「選取」。
- 從「叢集」下拉式清單中選取運算叢集。
- 若為排程,請選取手動執行。
- 按一下建立。
從記事本建立排定的工作執行
您可以建立從您已在筆記型電腦中開發的程式碼自動執行的排定工作。
- 在「首頁」上,按一下工作區。
- 導覽至您的筆記型電腦。
- 按一下動作,然後按一下排程。
- 提供工作的名稱與描述。
- 按一下瀏覽,然後選取儲存工作的位置。按一下「選取」。
- 從「叢集」下拉式清單中選取運算叢集。
- 在排程中,選取排程。
- 選取排程狀態。
- 若要立即啟用排程,請選取作用中。
- 如果您想要稍後手動啟用排定的執行,請選取已暫停。
- 提供排程所依據的時區。
- 選取排程類型。
- 對於行事曆,您必須指定排程將重複的頻率和時數或天數。
- 對於 Cron 表示式,您必須以 cron 表示式的形式提供排程。
- 請檢查底部列出的執行時間,確認您的排程是否正確。按一下建立。
筆記本鍵盤快速鍵
您可以使用鍵盤快速鍵,在記事本中使用指令來簡化。
| Windows | macOS | 動作 |
|---|---|---|
| Ctrl + Enter | 控制 + 退貨 | 執行單元 |
| Shift + Enter | 班次 + 退回 | 執行儲存格並前進到下一個儲存格 |
| Ctrl + S | Cmd + S | 儲存筆記本 |
| Ctrl + N | Ctrl + N | 新建記事本 |
| Ctrl + Z | 控制 + Z | 還原 |
| Ctrl + Y | 控制 + Y | 重做 |
| Ctrl + C | 控制 + C | 複製 |
| Ctrl + X | 控制 +X | 剪下 |
| Ctrl + V | 控制 + V | 貼上 |
| Ctrl + Alt + F | Ctrl + 選項 + F | 尋找並取代 |
| Ctrl + Shift + A | Ctrl + Shift + A | 在上方插入儲存格 |
| Ctrl + Shift + B | Ctrl + Shift + B | 在下方插入儲存格 |
| Ctrl + Alt + 向上 | Ctrl + 選項 + 上移 | 將儲存格上移 |
| Ctrl + Alt + 向下 | Ctrl + 選項 + 向下鍵 | 將儲存格下移 |
| Ctrl + D | Ctrl + D | 刪除單元 |
| Alt + Shift + Enter | 選項 + 班次 + 退回 | 全部執行 |
| Alt + Shift + 向上 | 選項 + 班次 + 向上 | 執行以上所有儲存格 |
將現有的 Apache Spark 程式碼移轉至 Oracle AI Data Platform
您可以調整 Apache Spark 程式碼以移轉它以用於 Oracle AI Data Platform 筆記型電腦。
如果您要從其他平台移轉現有的 Spark 程式碼,可以使用下列準則來調整程式碼,以在筆記型電腦中使用。
表格 7-2 Apache Spark 與 AI Data Platform 移轉準則
| 準則 | 詳細資訊 |
|---|---|
| 移除 SparkSession 建立命令 | AI 資料平台會自動為每個運算叢集建立 SparkContext。建議您移除階段作業建立命令,或以 SparkSession.builder().getOrCreate() 取代它們。
|
移除階段作業終止命令,例如 sys.exit() 或 spark.stop() |
所有目的運算叢集都是共用叢集,因此如果任何使用者都停止 SparkSession (例如使用 sys.exit() 或 spark.stop()),就必須為所有人重新啟動叢集。為了避免發生中斷的情況,建議您避免筆記型電腦中的指令。
|

