在DataWorks Notebook中使用MaxFrame

前提条件

步骤一：开通MaxCompute

MaxCompute是阿里云提供的大规模数据仓库与计算引擎，支持MaxFrame分布式Python计算框架。

1. 登录MaxCompute控制台，在左上角选择地域。

2. 在左侧导航栏，选择管理配置 > 项目管理。

3. 在项目管理页面，单击新建项目，在弹出的新增项目对话框，根据界面提示文案配置项目信息，单击确认。

   • 地域：必须与后续DataWorks地域一致（例如华东2（上海））。

   • 项目名称（全网唯一）：自定义，建议包含业务标识。

   • 计算资源付费类型：

     • 包年包月：适用于长期稳定运行的高负载生产业务场景，预付费购买固定CU（计算单元）资源，能够提供稳定的计算资源保障，避免资源抢占带来的不确定性。

     • 按量付费：（推荐选择）适用于短期或测试阶段的业务场景，能够根据实际使用CU（计算单元）情况灵活计费。

步骤二：开通DataWorks

DataWorks是一站式大数据开发治理平台，提供Notebook开发、调度运行、数据集成和数据治理等能力。

1. 前往DataWorks售卖页，开通DataWork版本。

   参数	说明	推荐值
   DataWorks版本	不同版本功能与价格有差异。	基础版（免费，满足Notebook开发）。
   地域与可用区	必须与MaxCompute项目地域一致。	按业务实际需求选择。

2. 前往资源组售卖页，购买用于任务运行的计算资源。选择以下配置参数：

   参数	说明
   地域与可用区	必须与MaxCompute项目地域一致。按业务实际需求选择。
   付费模式	按量付费（推荐） 包年包月
   资源组名称	自定义。必须以字母开头，可包含字母、数字、下划线（_），最多128个字符
   专有网络（VPC）和交换机（V-Switch）	如果没有VPC和交换机，DataWorks将自动创建。 如果已有VPC和交换机，选择已有的VPC和交换机，建议与待访问的云产品或存储服务保持一致。
   服务关联角色	根据页面提示，单击创建服务关联角色。

3. 单击确认订单并支付。

若选择DataWorks基础版和按量付费资源组，此步骤无需支付费用（0元）。

步骤三：创建DataWorks工作空间

工作空间是DataWorks的基础管理单元，用于隔离代码、资源和团队成员。

1. 登录DataWorks控制台，在左上角选择地域。

2. 在工作空间列表页面，单击创建工作空间。

3. 配置基本信息

   参数	说明
   工作空间名称	需要字母开头，只能包含字母、数字和下划线。
   显示名	可读性名称，自定义。
   生产、开发环境隔离	是否启用标准模式。单人开发可关闭（简单模式）。
   工作空间模板	功能集，推荐为全部能力。

4. 配置高级信息

   参数	说明
   空间管理员	如果使用RAM用户开发，请将对应RAM用户添加为空间管理员。
   创建同名PAI 工作空间	是否同步创建 PAI 空间，推荐关闭。
   默认资源组	用于调度任务。选择步骤二中创建的通用型资源组。
   阿里云资源组	阿里云资源分类标识，非必选。

5. 单击创建工作空间。

步骤四：绑定MaxCompute计算资源

将MaxCompute项目绑定到DataWorks工作空间作为计算资源，便于后续开发。

1. 登录DataWorks控制台，在左上角选择地域。

2. 在工作空间列表页面，单击目标工作空间对应的操作列的管理。

3. 在空间详情页面，单击左侧导航栏计算资源。

   在计算资源页面，单击绑定计算资源，选择MaxCompute。

   填写以下配置：

   参数	说明
   MaxCompute项目	选择步骤一中创建的MaxCompute项目。
   默认访问身份	执行作业的身份。推荐选择阿里云主账号。
   Endpoint	服务地址，自动适配。
   计算资源实例名	自定义。
   资源组名称	在计算资源和DataWorks之间连接和通信。 选择步骤二中创建的DataWorks通用型资源组名称，并单击测试连通性确认连接成功。

4. 单击确认。

步骤五：创建个人开发环境实例

DataWorks Notebook节点必须依托个人开发环境实例运行，否则无法执行代码。

1. 在工作空间列表页面，单击目标工作空间对应的操作列快速进入 > Data Studio。

2. 在顶部菜单选择个人开发环境，单击新建实例。

3. 配置以下参数：

   参数	说明
   实例名称	自定义实例名称。
   实例所有者	主账号或RAM用户。
   资源组	计算资源归属。选择已创建的通用型资源组。
   资源类型	选择CPU或GPU。一般场景选择CPU即可。
   资源配额	选择实例规格，例如ecs.g8i.xlarge（4 vCPU, 16 GiB，支持 4 CU 抵扣）。
   选择镜像	即运行环境。选择包含MaxFrame的镜像版本，例如dataworks-maxcompute:py3.11-ubuntu20.04:py3.11-ubuntu20.04-202504-1。
   专有网络	如需访问VPC内服务，选择与MaxCompute或OSS相同的VPC。
   交换机	子网，选择VPC下目标可用区的交换机。
   安全组	网络访问控制。选择已配置的安全组（需放通出网）。
   实例 RAM 角色	授权角色。推荐选择“DataWorks 默认角色”

4. 单击确定。

5. 等待2~3分钟，直至实例状态变为运行中。

步骤六：创建Notebook并运行开发示例

1. 在工作空间列表页面，单击目标工作空间对应的操作列快速进入 > Data Studio。

2. 在顶部菜单选择已启动的个人开发环境实例。

3. 在Data Studio页面，单击左侧导航栏的图标，进入数据开发页面。

4. 右键目标目录，选择新建节点 > Notebook。

5. 进入Notebook编辑页面，在页面右上角确认内核为Python 3，并运行以下代码验证MaxFrame版本：

   import maxframe
   print("MaxFrame version:", maxframe.__version__)
   # 如版本低于2.2.0，可运行以下命令升级：
   # !pip install maxframe -U

6. 在DataWorks Notebook的Python单元格中，可使用内置的Magic Command建立与MaxCompute计算资源的连接，无需在Python代码中频繁重复定义连接信息和明文AccessKey。

   import maxframe.dataframe as md
   import numpy as np
   from maxframe import new_session
   from maxframe.config import options
   from maxframe.udf import with_running_options
   from odps import ODPS
   import pandas as pd
   
   
   # -------------------------------
   # MaxFame Session 初始化
   # -------------------------------
   mf_session = %maxframe
   
   print("LogView 地址:", mf_session.get_logview_address())
   
   
   d = {'col1': [1, 2], 'col2': [3, 4]}
   df = md.DataFrame(data=d)
   print(df.execute().fetch())
   
   df = md.DataFrame(data=d, dtype=np.int8)
   print(df.execute().fetch())
   
   d = {'col1': [0, 1, 2, 3], 'col2': pd.Series([2, 3], index=[2, 3])}
   df = md.DataFrame(data=d, index=[0, 1, 2, 3])
   print(df.execute().fetch())
   
   data = np.array([(1, 2, 3), (4, 5, 6), (7, 8, 9)],
                   dtype=[("a", "i4"), ("b", "i4"), ("c", "i4")])
   df = md.DataFrame(data, columns=['c', 'a'])
   df.execute().fetch()
   
   mf_session.destroy()

其他实践

from maxframe import options

# 使用后付费Quota（避免包年包月资源不足）
options.session.quota_name = "默认后付费Quota"

# 控制写入并发，避免压垮OSS
options.sql.settings = {
    "odps.sql.split.dop": {"target_table": 5}
}

常见问题