MaxFrame Notebook 开发

适用场景

• 多步数据加工：抽取、清洗去重、脱敏、派生字段、写入结果表，用一个 Notebook 串起完整链路。

• SQL 不好写的逻辑：正则批量处理、复杂字符串加工、按行自定义计算、跨列派生等，用 Python 更直观。

• 多模态数据处理：配合 Blob 列类型，批量处理表中存储的图片、音频、视频。

• AI 自动生成：描述清楚「读哪张表、做什么、写到哪张表」，由 AI 生成代码、自动检查并跑通。

功能一览

步骤一：新建 Notebook

在左侧栏找到 MaxFrame 分区，单击右侧 +，填写名称（例如 mf_my_pipeline）后单击创建 Notebook。创建成功后自动打开编辑器。也可以从统一的新建文件对话框中选择 MaxFrame 类型创建。

步骤二：AI 生成代码

单击编辑器顶部的 AI 续写，右侧 AI 助手面板会切到 MaxFrame 作业助手。在输入框里描述需求，例如：

读 project_with_dr.sales_detail，去掉重复记录、过滤掉金额为空的行，
按天汇总销售额和订单数，写入 project_with_dr.sales_daily。
每一步用独立单元格，并在 Markdown 单元格里写明步骤名。

AI 会先读取当前 Notebook，然后生成代码。

步骤三：确认应用

AI 改动 Notebook 前会弹出确认卡片，展示修改内容以及修改原因：

• 单击应用到 Notebook：代码写入 Notebook，编辑器立即刷新，AI 接着自动做一次检查。

• 单击取消：本次改动不生效，拒绝后可以重新生成。

应用后如果不满意，直接继续说，例如「把去重改成只按订单号去重」，AI 记得前面的上下文。

步骤四：检查

单击顶部的检查，客户端会扫描代码里的常见问题，结果显示在底部面板的 Advisor 标签里。

单击某条问题的定位到可以跳到对应代码行；也可以直接单击让 Agent 修复全部，交给 AI 改。

步骤五：运行与写表

单击工具栏的运行，客户端将从上到下依次执行所有 Python 单元格，并在顶部显示执行进度（如"正在运行单元格 3/5"）。

to_odps_table(...).execute()执行完成后，结果即写入 MaxCompute 表，无需额外的发布或部署步骤。运行结束后，可在单元格下方预览写入的表数据。

如果只修改了某个单元格，无需重新执行全部单元格，在该单元格的工具栏单击运行单元格即可。

单元格类型

Notebook 用注释标记划分单元格，本质上还是普通的 Python 文件：

编辑器顶部会显示当前 Notebook 的单元格构成，例如 8 个单元格 · 3 个 Markdown · 5 个 Python。

编辑操作

内容自动保存，顶部会显示 未保存 / 保存中 / 已保存 状态。检查和运行前都会先保存。

在左侧栏的 Notebook 上单击右键，还可以加入聊天（把代码作为附件发给 AI）、复制名称、删除。

代码组织规则

每个单元格独立编译执行，但变量在单元格间共享。需注意如下两条规则：

• 规则一：每个单元格内的代码块必须语法完整。

  try/finally、if、for、def 等语句块不得跨单元格拆分，否则将报语法错误。

  # ✗ 错误：try 和 finally 被拆到两格# %%try:
      result.execute()
  
  # %%finally:
      session.destroy()

  # ✓ 正确：完整放在同一格# %%try:
      result.execute()
  finally:
      session.destroy()
  

• 规则二：变量可跨单元格使用。

  前序单元格中定义的变量（如session、df）可在后续单元格中直接引用，无需重复定义。

  AI 自动生成的代码已遵循上述两条规则，手动编写时请留意。

若单元格最后一行为表达式，其值将自动输出，便于快速查看结果（与 Jupyter 行为一致）。

完整示例

# %% [markdown]# ## 步骤 1：创建 session# MaxFrame 需要显式创建 session，作业结束时释放。# %%import maxframe.dataframe as md
from maxframe.session import new_session

session = new_session()

# %% [markdown]# ## 步骤 2：读表并清洗# 去重 + 过滤空金额。# %%
df = md.read_odps_table("project_with_dr.sales_detail")
clean = df.dropna(subset=["amount"]).drop_duplicates(subset=["order_id"])

# %% [markdown]# ## 步骤 3：按天汇总并写入结果表# %%
daily = clean.groupby("stat_date").agg({"amount": "sum", "order_id": "count"})
daily.columns = ["total_amount", "order_count"]

try:
    md.to_odps_table(daily, "project_with_dr.sales_daily", overwrite=True).execute()
finally:
    session.destroy()

注意事项：

• MaxFrame 采用惰性执行机制，未调用 execute() 时计算不会实际提交。

• overwrite=True 表示每次全量覆盖结果表；若表不存在，则自动创建。

• execute()与 session.destroy() 须通过 try/finally 封装在同一单元格内，确保资源正确释放。

• 请勿在代码中硬编码 AccessKey。凭证已根据当前连接自动注入，需要 PyODPS 时直接调用 ODPS.from_environments() 即可获取已鉴权的入口。

运行方式

运行中顶部会出现取消按钮。同一个 Notebook 同时只能有一个任务在跑，重复触发会提示该草稿已有运行中的任务，等它结束或取消后再试即可。

查看单元格输出

每格运行后，下方分三个标签展示结果：

• 目标表预览：客户端会自动识别这一格写入了哪张表，写完后在目标表标签里直接看数据。可以切换看前 20 / 50 / 100 行、刷新，或单击外链图标打开完整的表详情。

• 回看历史：同一格跑过多次时，右上角会出现一个选择器，按时间和状态切换查看之前某一次的结果。每格保留最近 10 次。输出区顶部还会显示本次运行的耗时、Instance ID 和 打开 LogView 链接，需要排查 MaxCompute 侧问题时可直接跳转。

底部面板

编辑器下方有三个标签，可以整体折叠：

• 运行详情：分为摘要、标准输出、控制台、DAG 四个子标签。摘要里看本次运行的状态与耗时，失败时会标出失败位置并提供让 Agent 修复按钮。

• 历史：这个 Notebook 的全部运行记录（时间、模式、状态、耗时），失败的标红，可展开看详情。

• Advisor：最近一次检查发现的问题列表。