7 记事本
本章提供有关在工作区中使用和管理记事本的信息。
在笔记本中开发代码
数据工程师和数据科学家可以在 Oracle AI Data Platform 中使用记事本作为交互式开发代码和浏览数据的通用工具。
Oracle AI Data Platform 当前在笔记本中支持 Python、SQL 和 Scala 语言。记事本可以调度或配置为在工作流中运行。要运行记事本，需要附加计算集群。
您的 AI 数据平台附带集成的托管笔记本，可提供直观的开发人员体验。
您可以将 Oracle AI Data Platform Samples Git 存储库中的示例代码用于记事本中的代码示例。
自动保存的
记事本每两分钟自动保存一次。
导入和导入记事本
您当前可以将记事本文件 (*.ipynb) 从本地计算机导入到工作区。
当前不支持导出笔记本。
为记事本创建集群
您可以直接从记事本界面创建新集群，然后立即将其附加。
- 在主页上，导航到工作区并打开记事本。
- 单击操作，然后单击创建集群。
- 选择运行时版本。
- 为群集选择驱动程序选项。
- 选择集群的 Worker 选项。这些选项适用于所有群集工作进程。
- 选择员工数是静态还是自动缩放。
- 如果是静态金额，则指定员工数。
- 如果为自动缩放，请指定集群可以缩放到的最小和最大工作进程数。
- 对于运行持续时间，选择群集是否会在设置的不活动持续时间后停止运行。如果选择了 Idle timeout（空闲超时），请在群集超时之前指定空闲时间（以分钟为单位）。
- 单击创建。
默认语言
您可以使用笔记本在 Python、SQL 或 Scala 中开发和运行 Apache Spark 代码。
记事本的默认语言是 Python。您可以将整个记事本或单个单元的默认语言更改为 SQL、Scala 或 Markdown 或原始文本。您可以在同一笔记本的不同单元格中组合 Python、SQL 和 Scala 代码。
记事本具有针对 Python、SQL 和 Scala 的语法突出显示。将根据记事本的默认语言创建新的记事本单元格。
记事本中的小部件
通过小部件，您可以在记事本中定义输入值。
可以在交互式运行记事本时提供值。作业、工作流任务或父记事本还可以在运行时提供值。
当同一笔记本必须使用不同的值（例如处理日期、环境、区域或数据集名称）运行时，可以使用小部件。通过使用小部件定义输入，您可以重用记事本，而无需编辑每次运行的代码。
记事本可以包括以下窗口部件类型
| 小组件类型 | 说明 |
|---|---|
text |
接受任何字符串值。 |
dropdown |
用户从定义的列表中选择一个值。 |
combobox |
用户选择定义的值或输入自定义值。 |
multiselect |
用户从定义的列表中选择一个或多个值。 |
小部件名称在记事本中必须唯一。所有小部件值都将作为字符串返回。多选窗口部件将所选值作为逗号分隔的字符串返回。
注意：
您至少需要对记事本具有 USE 权限，才能更改交互式记事本运行的窗口部件值。您需要具有 MANAGE 权限才能创建或删除小部件。记事本小部件示例
以下示例演示了笔记本中小部件的不同用例。
以交互方式运行记事本时，小部件会显示在小部件面板中。您可以在运行记事本之前更改其值。
文本窗口部件
此示例创建单个 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 小部件，该小部件为用户提供从列表中选择的值，以及用于输入定制值的字段：
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 的小部件时，父记事本传递的值将覆盖该执行的窗口部件默认值。有关配置工作流参数的更多信息，请参阅参数化。
管理笔记本
您可以重命名和删除您自己的记事本。您还可以克隆记事本以复制其内容并在新记事本中处理其代码。
可在工作区中的操作菜单中重命名和删除记事本。您可以通过打开记事本并从“文件”菜单中选择克隆选项来克隆记事本。
重命名笔记本
如果您的笔记本名称不再有用或相关，您可以随时更改它。
- 在主页上，导航到您的工作区。
- 在要重命名的记事本旁边，依次单击操作和重命名。
- 输入新名称，然后单击 Save（保存）。
- 可选：您还可以通过单击名称并输入新记事本来更改打开的记事本的名称。
运行记事簿
您可以在您拥有的记事本中或从与您共享的记事本中运行代码。
可以使用三种方法从记事本运行代码：按需运行、作为一次性手动运行运行或创建调度的记事本作业。按需运行的作业仅运行一次。
在记事本中运行终端命令
您可以在记事本中运行基本的终端命令或 shell 命令，方法是将 '!' 作为前缀。例如，您可以使用 unzip 命令从工作区中的 ZIP 文件中提取数据。
您还可以使用 Python 中的 subprocess 模块执行 shell 脚本。
您还可以使用本机 Python 模块（如 zipfile ）执行诸如解压缩文件等任务，作为 shell 命令的替代方法。
限制
目前，Oracle AI Data Platform 对管道安装、CI/CD、Git 或版本控制系统没有原生支持。
记事本单元的运行选项
记事本中的“Run（运行）”菜单提供了用于在记事本中运行单元格的选项。
您可以从记事本顶部的运行菜单中找到用于在记事本中运行单元的所有选项。
表 7-1 笔记本单元的运行选项
| 选项 | 说明 |
|---|---|
| 全部运行 | 按顺序运行记事本中的所有单元格。 |
| 运行所选单元 | 运行当前选定的单元格。 |
| 以上运行 | 运行当前选定单元格以及显示在记事本中当前选定单元格上方的任何单元格。 |
| 运行以下所有项 | 运行当前选定单元格以及显示在记事本中当前选定单元格下方的任何单元格。 |
| 运行选定的文本 | 在单元格中运行选定的代码段。 |
| 转到上次运行单元格 | 导航到记事本中最近运行的单元格。 |
| 清除所有单元格输出 | 从记事本中的所有单元格中删除输出。 |
从记事本运行代码
您可以选择一次运行在记事本中开发的所有代码，也可以一次运行一个单元格。
- MacOS : Cmd + Return
- Windows : Ctrl + Enter
您可以通过单击 
Play（播放）按钮在单个单元格中运行代码，也可以通过单击全部运行运行整个记事本。
- 在主页中，单击工作区。
- 导航到您的笔记本。
- 单击全部运行。
- 通过依次单击工作流和作业运行来检查记事本作业运行的状态。
从其他记事本运行代码
您可以在记事本中使用 %run magic 命令来包含其他记事本中的代码。
执行以下步骤后，将使用您的用户主体（即 caller-notebook.ipynb ）并使用附加的 caller-notebook.ipynb 集群立即运行名为 called-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
记事本导航
您可以创建和维护可用于组织和浏览记事本的内容表。
您可以单击记事本左上角的目录图标以显示记事本大纲。目录是根据您可以创建的减价标题自动生成的，这样可以轻松组织和导航。
您可以添加格式化的文本、标题、列表和文档作为标记，以便自己和其他用户组织和解释记事本内容。
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 左侧导航面板，同时使用笔记本来增加可用的屏幕空间。
您还可以通过单击记事本右上角的展开来展开记事本，扩展可用空间，并使更大的单元格和输出更易于阅读。
单元运行编号
每个记事本单元显示一个运行编号，指示单元格的运行顺序。每次运行单元时，此数字都会更新。您可以按任意顺序运行单元，因此运行编号可能与记事本中单元格的物理顺序不匹配。
管理作业运行时
您可以创建作业运行，以管理如何以及何时从记事本运行代码。
可以再次运行手动作业运行，也可以稍后将手动作业运行设置为按计划运行。系统会根据您设置的计划自动触发计划的作业运行。除非配置了调度，否则手动作业只运行一次。
从记事本创建手动运行作业
您可以根据在笔记本中开发的代码创建可以手动运行的未调度作业。
- 在主页中，单击工作区。
- 导航到您的笔记本。
- 依次单击操作和计划。
- 为作业提供名称和说明。
- 单击浏览并选择要存储作业的位置。单击选择。
- 从 Cluster（集群）下拉列表中选择计算集群。
- 对于调度，选择手动运行。
- 单击创建。
从记事本创建调度的作业运行
您可以创建基于在记事本中开发的代码自动运行的调度作业。
- 在主页中，单击工作区。
- 导航到您的笔记本。
- 依次单击操作和计划。
- 为作业提供名称和说明。
- 单击浏览并选择要存储作业的位置。单击选择。
- 从 Cluster（集群）下拉列表中选择计算集群。
- 对于计划，选择计划。
- 选择计划状态。
- 如果希望立即启用调度，请选择有效。
- 如果要稍后手动启用计划的运行，请选择已暂停。
- 为要基于的计划提供时区。
- 选择计划类型。
- 对于日历，您必须指定频率以及计划将重复的小时数或天数。
- 对于 Cron Expression ，必须以 cron 表达式的形式提供调度。
- 检查底部的列出的运行时间以确认您的计划是否正确。单击创建。
记事本键盘快捷键
您可以使用键盘快捷键在笔记本中使用命令来简化操作。
| Windows | macOS | 操作 |
|---|---|---|
| Ctrl + Enter | Cmd + 退货 | 执行单元格 |
| Shift + Enter | 班次 + 退货 | 执行单元并前进到下一个单元 |
| Ctrl + S | 计量单位 + S | 保存笔记本 |
| Ctrl + N | Ctrl + N | 新建记事本 |
| Ctrl + Z | 计量单位 + Z | 撤消 |
| Ctrl + Y | 计量单位 + Y | 恢复 |
| Ctrl + C | 计量单位 + C | 复制 |
| Ctrl + X | Cmd +X | 剪切 |
| Ctrl + V | Cmd + 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 + Up | 选项 + 班次 + 向上 | 运行以上所有单元格 |
将现有 Apache Spark 代码迁移到 Oracle AI Data Platform
您可以调整 Apache Spark 代码以将其迁移到 Oracle AI Data Platform 记事本中使用。
如果您要从其他平台迁移现有的 Spark 代码，则可以使用以下准则调整代码以用于记事本。
表 7-2 Apache Spark 到 AI Data Platform 的迁移准则
| 准则 | 详细资料 |
|---|---|
| 删除 SparkSession 创建命令 | AI Data Platform 可自动为每个计算集群创建一个 SparkContext。我们建议删除会话创建命令或将其替换为 SparkSession.builder().getOrCreate()。
|
删除会话终止命令，例如 sys.exit() 或 spark.stop() |
所有用途的计算集群都是共享集群，因此，如果任何用户停止 SparkSession，例如使用 sys.exit() 或 spark.stop()，则需要为所有人重新启动集群。为了避免中断，我们建议避免在笔记本中执行这些命令。
|