Notebook

背景信息

随着Notebook在开源社区的广泛应用，许多数据或AI开发者已将其视为一个强大的代码编写和调试工具。因此Designer中提供了Notebook组件，可与DSW实例实现无缝连接，支持用户在工作流中直接使用Notebook编写、调试和运行代码，同时保留工作流的上下文和状态。

相对于直接使用DSW进行开发，在Designer中使用Notebook组件具有以下优势：

• 提升开发效率：可以在工作流中直接打开Notebook，利用容器化实例进行开发并调试代码。

• 上下文保留： Designer中的Notebook组件可在实例启动时，自动加载工作流中上游组件的输出数据和状态，使得用户能够立即使用这些数据进行进一步的分析和开发，并将结果传给下游。

• 工作流整体调试： Notebook组件将作为工作流中的一环，用户可以在不同的组件之间无缝切换，优化整个数据处理和模型训练的过程。

使用场景

开发环节

用户在组件中启动并前往DSW实例编辑Notebook文件，可以直接在DSW实例内部开发和调试Notebook，并且支持从Designer中获取自定义参数配置。

运行环节

用户在Designer画布直接执行Notebook组件、整个工作流或使用DataWorks周期性调度工作流，系统会启动一个DLC任务来执行jupyter nbconvert转换后的Notebook文件。

组件说明

Notebook组件共有4个输入端口和4个输出端口。其中，所有的输入端口均可连接OSS路径或MaxCompute表类型的数据；输出端口中端口1、2是OSS路径输出端口，端口3、4是MaxCompute表输出端口。

通过Notebook组件启动的DSW实例时，需要安装pai-notebook-utils包，用户通过pai-notebook-utils包可以获取Notebook节点的输入端口、输出端口、自定义参数等信息。

pai-notebook-utils包说明

• 安装pai-notebook-utils

  pip install --upgrade https://pai-sdk.oss-cn-shanghai.aliyuncs.com/pai_notebook_utils/dist/pai_notebook_utils-0.0.1-py2.py3-none-any.whl

• 使用pai-notebook-utils

  pai-notebook-utils提供了get_inputs()、get_outputs()、 get_custom_params()三个函数，分别用于获取输入端口配置、输出端口配置、自定义参数。

  from pai_notebook.utils.notebook_utils import NotebookUtils
  
  node_inputs = NotebookUtils.get_inputs()
  node_outputs = NotebookUtils.get_outputs()
  custom_params = NotebookUtils.get_custom_params()

输入端口

Notebook组件有4个输入端口，可以接收OSS数据或MaxCompute表，通过pai-notebook-utils提供的NotebookUtils.get_inputs()可以获取到所有端口的输入信息，其返回值是一个数组，数组中每个item包含以下字段：

• 当输入端为MaxCompute表类型时，此时location_type为MaxComputeTable，value包含project、table、endpoint字段，依次分别表示表所属的MaxCompute项目、MaxCompute表名、MaxCompute的endpoint。

  from pai_notebook.utils.notebook_utils import NotebookUtils
  
  node_inputs = NotebookUtils.get_inputs()
  
  for node_input in node_inputs:
      if node_input.location_type == "MaxComputeTable":
          input_name = node_input.name
          table_name = node_input.value["table"]
          project = node_input.value["project"]
          endpoint = node_input.value["endpoint"]
          print(f"input_name: {input_name}, project: {project}, table_name: {table_name}, endpoint: {endpoint}")

• 当输入端为OSS类型时，OSS路径会被挂载为本地路径，用户可以通过访问本地路径的方式访问OSS文件，也可以通过OSS SDK直接访问OSS。此时location_type为OSS，value包含key、bucket、endpoint、mountPath字段，依次分别表示OSS路径的Path、OSS Bucket、OSS的endpoint、OSS的本地挂载路径。

  重要

  如果上游OSS路径发生了变化，且新的路径未挂载到DSW实例中，将无法获取到mountPath，您需要重启DSW实例。

  from pai_notebook.utils.notebook_utils import NotebookUtils
  
  node_inputs = NotebookUtils.get_inputs()
  
  for node_input in node_inputs:
      if node_input.location_type == "OSS":
          input_name = node_input.name
          key = node_input.value["key"]
          bucket = node_input.value["bucket"]
          endpoint = node_input.value["endpoint"]
          mount_path = node_input.value["mountPath"]
          print(f"input_name: {input_name}, bucket: {bucket}, key: {key}, endpoint: {endpoint}, mount path: {mount_path}")

输出端口

Notebook组件有4个输出端口，其中端口1、2是OSS路径输出端口，端口3、4是MaxCompute表输出端口。通过pai-notebook-utils提供的NotebookUtils.get_outputs()可以获取到所有端口的输出信息，其返回值是一个数组，数组中每个item包含以下字段：

当输出端为MaxCompute表类型时，当前工作空间需要关联MaxCompute计算引擎；当输出端为OSS类型时，数据将会被保存到输出的OSS路径中，如果未配置任务输出路径，会通过全局的默认路径自动生成输出路径。输出端value中的字段和输入端口中的格式一致。

from pai_notebook.utils.notebook_utils import NotebookUtils

node_outputs = NotebookUtils.get_outputs()

for node_output in node_outputs:
    input_name = node_input.name
    if node_output.location_type == "MaxComputeTable":
        table_name = node_output.value["table"]
        project = node_output.value["project"]
        endpoint = node_output.value["endpoint"]
        print(f"input_name: {input_name}, project: {project}, table_name: {table_name}, endpoint: {endpoint}")
    elif node_output.location_type == "OSS":
        key = node_output.value["key"]
        bucket = node_output.value["bucket"]
        endpoint = node_output.value["endpoint"]
        mount_path = node_output.value["mountPath"]
        print(f"input_name: {input_name}, bucket: {bucket}, key: {key}, endpoint: {endpoint}, mount path: {mount_path}")
    else:
        print(json.dumps(node_output.value, indent=4))

自定义参数

您也可以自定义参数，参数值可以通过 ${globalParamName}（全局变量）的方式引用工作流中配置的全局变量，通过NotebookUtils.get_custom_params()可以获取到组件中配置的自定义参数，返回值是一个Map，对应的key和value都是字符串。

from pai_notebook.utils.notebook_utils import NotebookUtils

custom_params = NotebookUtils.get_custom_params()
print(custom_params)

配置组件

在Designer工作流页面添加Notebook组件，并在界面右侧配置相关参数：