11 记事本

本章提供有关在工作区中使用和管理记事本的信息。

主题：

在笔记本中开发代码

数据工程师和数据科学家可以在 Oracle AI Data Platform 工作台中使用记事本作为交互式开发代码和浏览数据的通用工具。

Oracle AI Data Platform Workbench 当前在笔记本中支持 Python、SQL 和 Scala 语言。记事本可以调度或配置为在工作流中运行。要运行记事本，需要附加计算集群。

您的 AI Data Platform Workbench 附带集成的托管式笔记本，可提供直观的开发人员体验。

您可以将 Oracle AI Data Platform Workbench Samples Git 存储库中的示例代码用于记事本中的代码。

自动保存的

记事本每两分钟自动保存一次。

导入和导入记事本

您当前可以将记事本文件 (*.ipynb) 从本地计算机导入到工作区。

当前不支持导出笔记本。

创建记事本

您可以在您具有管理员权限的任何工作区中创建记事本。

  1. 在主页上，导航到您的工作区。
  2. 单击创建，然后单击记事本。
  3. 填写名称和说明，然后单击创建。

将现有集群附加到记事本

记事本需要连接的集群来为开发的代码提供计算能力。

  1. 在主页上，导航到工作区并打开记事本。
  2. 单击操作，然后单击附加现有集群。
  3. 从列表中单击要使用的集群。
    您的记事本将在成功连接后显示 Cluster：(ClusterName) running 。这最多可能需要几分钟时间。

为记事本创建集群

您可以直接从记事本界面创建新集群，然后立即将其附加。

有关更多信息，请参阅关于计算集群。
  1. 在主页上，导航到工作区并打开记事本。
  2. 单击操作，然后单击创建集群。
  3. 选择运行时版本。
  4. 为群集选择驱动程序选项。
  5. 选择集群的 Worker 选项。这些选项适用于所有群集工作进程。
  6. 选择员工数是静态还是自动缩放。
    • 如果是静态金额，则指定员工数。
    • 如果为自动缩放，请指定集群可以缩放到的最小和最大工作进程数。
  7. 对于运行持续时间，选择群集是否会在设置的不活动持续时间后停止运行。如果选择了 Idle timeout（空闲超时），请在群集超时之前指定空闲时间（以分钟为单位）。
  8. 单击创建。

默认语言

您可以使用笔记本在 Python、SQL 或 Scala 中开发和运行 Apache Spark 代码。

记事本的默认语言是 Python。您可以将整个记事本或单个单元的默认语言更改为 SQL、Scala 或 Markdown 或原始文本。您可以在同一笔记本的不同单元格中组合 Python、SQL 和 Scala 代码。

记事本具有针对 Python、SQL 和 Scala 的语法突出显示。将根据记事本的默认语言创建新的记事本单元格。

管理笔记本

您可以重命名和删除您自己的记事本。您还可以克隆记事本以复制其内容并在新记事本中处理其代码。

可在工作区中的操作菜单中重命名和删除记事本。您可以通过打开记事本并从“文件”菜单中选择克隆选项来克隆记事本。

重命名笔记本

如果您的笔记本名称不再有用或相关，您可以随时更改它。

  1. 在主页上，导航到您的工作区。
  2. 在要重命名的记事本旁边，依次单击操作和重命名。
  3. 输入新名称，然后单击 Save（保存）。
  4. 可选：您还可以通过单击名称并输入新记事本来更改打开的记事本的名称。

删除记事簿

您可以删除您具有管理员权限的记事本。

  1. 定位至工作区。
  2. 在要删除的记事本旁边，依次单击操作和删除。
  3. 单击删除。

克隆笔记本

您可以克隆现有记事本以创建该记事本内容的副本，您可以在保留原始记事本时对其进行修改。

  1. 打开要克隆的记事本。
  2. 在记事本工具栏中，单击文件，然后单击克隆。
  3. 为克隆的记事本输入新名称。
  4. 单击浏览以选择工作区文件夹以将克隆的记事本保存到其中。如果未选择文件夹，克隆的记事本将与要克隆的记事本在同一文件夹中创建。
  5. 选择是包括输出还是排除输出。缺省情况下会包括输出。清除选择以排除输出。
  6. 单击克隆。克隆的记事本是在您指定的工作区文件夹中创建的。

编辑记事本时浏览资源

在记事本中时，您可以浏览左侧的目录或工作区对象，而无需离开记事本。

如果将左侧窗格中的任何对象拖放到记事本中，则对象名称或完整路径将被复制并粘贴到记事本单元格（具体取决于上下文）。


打开的记事本中拖放到记事本中的对象

您还可以在左侧窗格中为每个目录或工作区对象提供按钮和上下文菜单选项。左侧导航的上下文菜单具有复制示例代码、复制名称或复制路径的选项，以便您可以粘贴到记事本单元格。


记事本左侧窗格中显示的上下文菜单选项

运行记事簿

您可以在您拥有的记事本中或从与您共享的记事本中运行代码。

可以使用三种方法从记事本运行代码：按需运行、作为一次性手动运行运行或创建调度的记事本作业。按需运行的作业仅运行一次。

在记事本中运行终端命令

您可以在记事本中运行基本的终端命令或 shell 命令，方法是将 '!' 作为前缀。例如，您可以使用 unzip 命令从工作区中的 ZIP 文件中提取数据。


正在使用的 unzip 命令示例

您还可以使用 Python 中的 subprocess 模块执行 shell 脚本。


正在使用的子进程命令示例

您还可以使用本机 Python 模块（如 zipfile ）执行诸如解压缩文件等任务，作为 shell 命令的替代方法。

限制

目前，Oracle AI Data Platform Workbench 对管道安装、CI/CD、Git 或版本控制系统没有原生支持。

记事本单元的运行选项

记事本中的“Run（运行）”菜单提供了用于在记事本中运行单元格的选项。

< 在此处输入部分标题 >

您可以从记事本顶部的运行菜单中找到用于在记事本中运行单元的所有选项。


记事本中的“运行”菜单，打开并显示用于在记事本中运行单元格的选项

表 11-1：笔记本单元的运行选项

选项 说明
全部运行 按顺序运行记事本中的所有单元格。
运行所选单元 运行当前选定的单元格。
以上运行 运行当前选定单元格以及显示在记事本中当前选定单元格上方的任何单元格。
运行以下所有项 运行当前选定单元格以及显示在记事本中当前选定单元格下方的任何单元格。
运行选定的文本 在单元格中运行选定的代码段。
转到上次运行单元格 导航到记事本中最近运行的单元格。
清除所有单元格输出 从记事本中的所有单元格中删除输出。

从记事本运行代码

您可以选择一次运行在记事本中开发的所有代码，也可以一次运行一个单元格。

用于在记事本中运行代码的键盘快捷键包括：
  • MacOS : Cmd + Return
  • Windows : Ctrl + Enter

您可以通过单击 记事本播放按钮 Play（播放）按钮在单个单元格中运行代码，也可以通过单击全部运行运行整个记事本。

  1. 在主页中，单击工作区。
  2. 导航到您的笔记本。
  3. 单击全部运行。
  4. 通过依次单击工作流和作业运行来检查记事本作业运行的状态。

从其他记事本运行代码

您可以在记事本中使用 %run magic 命令来包含其他记事本中的代码。

在以下示例中，您将名为 called-notebook.ipynb 的记事本中的代码引入到记事本 caller-notebook.ipynb 中。
  1. 安装 nbconvert Python 库。
  2. 在单元格中使用 %run 命令，如以下示例中所示：
    %run /Workspace/folder1/called-notebook.ipynb

执行以下步骤后，将使用您的用户主体（即 caller-notebook.ipynb ）并使用附加的 caller-notebook.ipynb 集群立即运行名为 called-notebook.ipynb 的记事本。called-notebook.ipynb 中定义的所有函数和变量将立即在名为 caller-notebook.ipynb 的记事本中可用。

使用 oidlUtils 共享记事本输出

您可以使用 oidlUtils 中提供的实用程序，通过记事本任务捕获和共享内容输出。

oidlUtils 是一组可供 Oracle AI Data Platform Workbench 的所有用户使用的实用程序。在笔记本之间共享内容时，可以调用 oidlUtils 将参数传递给一个笔记本并将输出传递回调用方笔记本，并且可以在记事本中的作业任务中调用 oidlUtils 以将输出传递回父任务，即调用记事本的任务。通过这种方式，您可以捕获并使用记事本任务返回的结构化输出。

这些 oidlUtils 模块可与笔记本一起使用：

模块 说明 范例
笔记本 编排记事本任务，并将单个结构化结果（通常为 JSON 字符串）返回给调用方。 
oidlUtils.notebook.run(
    notebook_path: str,
    timeout_seconds: int = 0, (Optional)
    parameters: dict (Optional)
) -> str
笔记本 允许记事本退出任务运行，并将单个字符串结果（通常为 JSON 有效负载）返回到调用方记事本或作业/任务输出 API。 
oidlUtils.notebook.exit(value: str)

示例 1：记事本到记事本共享

在本例中，您将使用记事本 A 调用记事本 B。记事本 B 返回将记事本 A 设置为捕获和使用的结果有效负载。

笔记本 A

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

记事本 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

记事本导航

您可以创建和维护可用于组织和浏览记事本的内容表。

您可以单击记事本左上角的目录图标以显示记事本大纲。目录是根据您可以创建的减价标题自动生成的，这样可以轻松组织和导航。

您可以添加格式化的文本、标题、列表和文档作为标记，以便自己和其他用户组织和解释记事本内容。

创建减价单元格

您可以创建减价单元格，以在记事本目录中提供标题，以便于组织和导航。

  1. 从主页中，导航到您的笔记本。
  2. 从单元格类型下拉列表中，选择标记。
  3. 将标记添加到单元格中。
    • Markdown 单元格可以包括格式化的文本、标题、列表和其他文档。
    • 要创建标题，请以 # 开头，后跟空格。标题 1 使用一个 # ，标题 2 使用 ## 。为每个附加标题级别添加其他 # 。

记事本输出和结果

您可以看到记事本输出并生成一个新单元格，该单元格显示在带代码的单元格之后。

单元正在进行时，您可以取消单元的执行。如果记事本作为工作流作业运行，则输出在同一记事本中不可见。在这种情况下，输出在相应的工作流作业运行的输出区域中可见。

您可以将输出单元格中的输出下载为 CSV 或 Excel 文件。您还可以将输出单元格的内容直接复制到剪贴板。


突出显示“复制”和“下载”按钮的记事本中的输出单元格。此时将打开“下载”菜单，并显示“下载 CSV”和“下载 Excel”选项。

下载记事本输出

您可以直接从结果面板下载记事本单元的结果输出。

  1. 在要从其下载输出的单元的右上角，单击下载。
  2. 从菜单中，选择要将输出下载为的格式。

复制记事本输出

您可以直接从结果面板复制记事本单元的结果输出。

  1. 在要从其下载输出的单元的右上角，单击复制。
  2. 输出单元的内容将直接复制到剪贴板。您可以将其粘贴到笔记本或外部位置。

记事本外观

您可以通过最小化左侧导航面板或展开记事本视图来更改可用于在记事本中工作的屏幕空间。

您可以通过单击导航面板右下角的最小化面板，最大限度地减少 Oracle AI Data Platform Workbench 左侧导航面板，同时使用笔记本来增加可用的屏幕空间。


突出显示了 "Minimize Panel"（最小化面板）图标的 AI Data Platform Workbench 左侧导航窗格

您还可以通过单击记事本右上角的展开来展开记事本，扩展可用空间，并使更大的单元格和输出更易于阅读。


突出显示了 "Expand"（展开）图标的记事本打开

单元运行编号

每个记事本单元显示一个运行编号，指示单元格的运行顺序。每次运行单元时，此数字都会更新。您可以按任意顺序运行单元，因此运行编号可能与记事本中单元格的物理顺序不匹配。

管理作业运行时

您可以创建作业运行，以管理如何以及何时从记事本运行代码。

可以再次运行手动作业运行，也可以稍后将手动作业运行设置为按计划运行。系统会根据您设置的计划自动触发计划的作业运行。除非配置了调度，否则手动作业只运行一次。

从记事本创建手动运行作业

您可以根据在笔记本中开发的代码创建可以手动运行的未调度作业。

  1. 在主页中，单击工作区。
  2. 导航到您的笔记本。
  3. 依次单击操作和计划。
  4. 为作业提供名称和说明。
  5. 单击浏览并选择要存储作业的位置。单击选择。
  6. 从 Cluster（集群）下拉列表中选择计算集群。
  7. 对于调度，选择手动运行。
  8. 单击创建。

从记事本创建调度的作业运行

您可以创建基于在记事本中开发的代码自动运行的调度作业。

  1. 在主页中，单击工作区。
  2. 导航到您的笔记本。
  3. 依次单击操作和计划。
  4. 为作业提供名称和说明。
  5. 单击浏览并选择要存储作业的位置。单击选择。
  6. 从 Cluster（集群）下拉列表中选择计算集群。
  7. 对于计划，选择计划。
  8. 选择计划状态。
    • 如果希望立即启用调度，请选择有效。
    • 如果要稍后手动启用计划的运行，请选择已暂停。
  9. 为要基于的计划提供时区。
  10. 选择计划类型。
    • 对于日历，您必须指定频率以及计划将重复的小时数或天数。
    • 对于 Cron Expression ，必须以 cron 表达式的形式提供调度。
  11. 检查底部的列出的运行时间以确认您的计划是否正确。单击创建。

记事本键盘快捷键

您可以使用键盘快捷键在笔记本中使用命令来简化操作。

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 Workbench

您可以调整 Apache Spark 代码以将其迁移到 Oracle AI Data Platform Workbench 记事本中。

如果您要从其他平台迁移现有的 Spark 代码，则可以使用以下准则调整代码以用于记事本。

表 11-2 Apache Spark to AI Data Platform Migration Guidelines

准则 详细资料
删除 SparkSession 创建命令 AI Data Platform Workbench 会自动为每个计算集群创建一个 SparkContext。我们建议删除会话创建命令或将其替换为 SparkSession.builder().getOrCreate()。
删除会话终止命令，例如 sys.exit() 或 spark.stop() 所有用途的计算集群都是共享集群，因此，如果任何用户停止 SparkSession，例如使用 sys.exit() 或 spark.stop()，则需要为所有人重新启动集群。为了避免中断，我们建议避免在笔记本中执行这些命令。