alibabacloud-odps-maxframe-coding

如果你认为这项技能有哪怕 1% 的可能适用于你的任务，就必须调用它。

如果某项技能适用于你的任务，你别无选择，必须使用它。

指令优先级

1. 用户的明确指令（CLAUDE.md、GEMINI.md、AGENTS.md）——优先级最高
2. MaxFrame 编码技能——与默认行为冲突时，以此为准
3. 默认系统提示——优先级最低

平台适配

此技能使用 Claude Code 工具名称。非 CC 平台：请使用等效工具替代。

MaxFrame 编码——创建、测试、调试、迭代并构建自定义运行时

此技能的功能

创建、测试、调试并迭代开发 MaxFrame 程序，以及构建自定义 DPE 运行时镜像。

• 浏览 MaxFrame 文档，了解 API、概念、示例和支持的 pandas API
• 从头创建 MaxFrame 作业，或修改现有作业
• 使用兼容 pandas 的 API 设计数据处理管道
• 通过正确的会话管理执行 MaxFrame 代码
• 使用远程 logview URL 或本地 IDE 断点进行调试
• 使用特定 Python 库生成自定义 Docker 镜像

必查清单

1. 识别场景类型——确定是文档导航，还是适用 4 种实现方案中的哪一种
2. 了解需求——询问有关数据、操作和限制条件的澄清问题
3. 选择适当的工作流——将场景与工作流模式匹配
4. 执行工作流步骤——遵循下方对应场景的步骤
5. 验证执行——确保已调用 execute()，并清理会话
6. 提供后续指导——提供调试技巧和优化建议

流程

仅涉及文档的问题可以跳过实现流程，使用下方的场景 0。

digraph maxframe_workflow {
    "User Request Arrives" [shape=box];
    "Detect Scenario Type" [shape=diamond];
    "Scenario 1: Writing Code" [shape=box];
    "Scenario 2: Remote Debug" [shape=box];
    "Scenario 3: Local Debug" [shape=box];
    "Scenario 4: Custom Runtime" [shape=box];
    "Understand Requirements" [shape=box];
    "Operator Selection Needed?" [shape=diamond];
    "Use lookup_operator.py" [shape=box];
    "Confirm with User" [shape=box];
    "Implement Code/Config" [shape=box];
    "Add Error Handling" [shape=box];
    "Validate execute() Called" [shape=box];
    "Validate Session Cleanup" [shape=box];
    "Provide Guidance" [shape=doublecircle];

    "User Request Arrives" -> "Detect Scenario Type";
    "Detect Scenario Type" -> "Scenario 1: Writing Code" [label="new pipeline"];
    "Detect Scenario Type" -> "Scenario 2: Remote Debug" [label="cluster testing"];
    "Detect Scenario Type" -> "Scenario 3: Local Debug" [label="IDE breakpoints"];
    "Detect Scenario Type" -> "Scenario 4: Custom Runtime" [label="custom image"];
    "Scenario 1: Writing Code" -> "Understand Requirements";
    "Scenario 2: Remote Debug" -> "Understand Requirements";
    "Scenario 3: Local Debug" -> "Understand Requirements";
    "Scenario 4: Custom Runtime" -> "Understand Requirements";
    "Understand Requirements" -> "Operator Selection Needed?";
    "Operator Selection Needed?" -> "Use lookup_operator.py" [label="yes"];
    "Operator Selection Needed?" -> "Implement Code/Config" [label="no"];
    "Use lookup_operator.py" -> "Confirm with User";
    "Confirm with User" -> "Implement Code/Config";
    "Implement Code/Config" -> "Add Error Handling";
    "Add Error Handling" -> "Validate execute() Called";
    "Validate execute() Called" -> "Validate Session Cleanup";
    "Validate Session Cleanup" -> "Provide Guidance";
}

场景识别逻辑

场景 0：文档导航

• 用户询问一般的 MaxFrame API、概念、示例或支持的 pandas API
• 用户想要搜索或浏览 MaxFrame 文档
• 用户询问是否存在某个算子，或如何使用文档中介绍的 API
• 关键词：“MaxFrame docs”“documentation”“API reference”“official example”“tutorial”“supported pandas API”“how does work”

场景 1：编写 MaxFrame 代码

• 用户想要创建新的数据处理管道
• 用户提到从 MaxCompute 表读取数据或向其中写入数据
• 用户要求提供完整的 MaxFrame 程序
• 关键词：“create MaxFrame”“write MaxFrame code”“build pipeline”“process data with MaxCompute”

场景 2：远程调试模式

• 用户想要使用实际集群资源进行测试
• 用户提到作业执行错误
• 用户询问 logview URL
• 用户想要诊断执行失败的问题
• 关键词：“debug MaxFrame job”“logview”“remote test”“execution error”“cluster testing”

场景 3：本地调试模式

• 用户想要迭代调试 UDF 函数
• 用户提到 IDE 断点（VSCode、PyCharm）
• 用户想要使用示例数据在本地测试
• 用户想要快速迭代且无需联网
• 关键词：“local debug”“IDE breakpoints”“debug UDF locally”“VSCode/PyCharm debug”

场景 4：创建自定义运行时镜像

• 用户需要标准运行时中没有的 Python 库
• 用户想要启用 GPU 的运行时
• 用户提到构建自定义 DPE 镜像
• 关键词：“custom runtime”“DPE runtime image”“GPU runtime”“install custom packages”“build Docker image”

核心规则

1. 仅使用公共 API

使用以下 API：maxframe.dataframe、maxframe.tensor、maxframe.learn、maxframe.session、maxframe.udf、maxframe.config。使用规范的导入方式：import maxframe.dataframe as md 和 from maxframe.session import new_session；切勿使用 from maxframe import new_session。

2. 切勿读取私有 .env 文件

以编程方式使用 dotenv.load_dotenv()。切勿使用 Read 工具直接读取 .env 文件。

3. 惰性执行

MaxFrame 采用惰性执行：操作会构建图，只有调用 .execute() 时才会运行。只对最终结果或写入操作调用 .execute()；除非用户明确要求预览或调试输出，否则不要对中间的 DataFrame 或 Series 变量调用 .execute()。

4. 会话管理

始终在执行操作前创建会话，并在 finally 块中销毁会话以进行清理。

5. 经用户确认后选择算子

实现处理逻辑前，使用 scripts/lookup_operator.py 与用户确认所选算子。如果用户已经明确指定了确切的算子，或要求只提供代码，则在实现前写上 Operator confirmed via user prompt: <operator>。

6. 文档来源顺序

回答 MaxFrame 文档相关问题时，先查看官方在线文档，因为 API 可能会变更。将随附的本地文档用作离线备用资料、快速交叉核对，或在网站缺少详细信息时使用。 除非最后一个非空行以 Sources: 开头且包含完整的 https://maxframe.readthedocs.io/ URL，否则不要结束 Scenario 0；绝不要输出 ...。如果无法查阅官方文档，请在该行之前注明 Official docs unavailable: <reason>; using local fallback.。

注意事项

想法	实际情况
“这只是个简单的 MaxFrame 问题”	问题就是任务。调用技能。
“我已经了解 MaxFrame API”	技能包含最新用法。请使用技能。
“我直接写代码就行”	算子选择是强制要求。
“我可以跳过算子确认”	必须获得用户确认。

Scenario 0：文档导航

适用于不需要编写新 MaxFrame 程序的 API、概念或示例问题。

工作流程步骤

1. 对问题分类 — API／算子、概念、支持的 pandas API、故障排除、运行时镜像或示例
2. 先查阅官方文档 — 使用本地文档前先访问官方 URL：API／概念问题请访问 https://maxframe.readthedocs.io/en/latest/；示例请访问 https://maxframe.readthedocs.io/en/latest/examples/index.html
3. 将本地文档用作备用资料或交叉核对
   • API／算子：python scripts/lookup_operator.py search "<term>"
   • API 详情：python scripts/lookup_operator.py info "<operator>" --section signature|params|examples
   • 概念／示例：rg -n "<keyword>" references/maxframe-client-docs references/practical-guides references/operators-and-modules
4. 必要时使用本地主题位置
   • API 参考：references/maxframe-client-docs/reference/
   • 入门指南：references/maxframe-client-docs/getting_started/
   • 用户指南：references/maxframe-client-docs/user_guide/
   • 支持的 pandas API：references/maxframe-client-docs/user_guide/dataframe/supported_pd_apis.md
   • 实用指南：references/practical-guides/
   • 运行时镜像：references/runtime-image-guides/
5. 基于来源作答 — 最后一个非空行必须为 Sources: <完整的官方 URL> (Primary)；仅在使用了本地文档时，才附加 | <本地路径> (Fallback/Cross-check)

Scenario 1：编写 MaxFrame 代码

工作流程步骤

1. 了解需求 — 源表／目标表、架构、分区筛选条件、写入模式和处理逻辑
2. 选择算子（强制要求） — 使用 python scripts/lookup_operator.py search "<operation>"，提供选项并获得确认
3. 编写代码 — 设置会话、读取数据、使用已确认的算子进行处理、写入结果、添加 execute()，并在 finally 中清理
4. 添加错误处理 — 使用 try/except 包装 execute()，发生错误时打印 logview URL
5. 验证 — 使用规范导入，只对最终结果调用 .execute()，在 finally 中调用 session.destroy()，不硬编码凭证

代码结构示例

import maxframe.dataframe as md
from maxframe.session import new_session
import dotenv

dotenv.load_dotenv()
session = new_session()

try:
    df = md.read_odps_table("source_table")
    result = df.groupby('column').agg({'value': 'sum'})
    md.to_odps_table(result, "target_table", overwrite=True).execute()
finally:
    session.destroy()

参见： references/common-workflow.md，了解完整模式。

Scenario 2：远程调试模式

工作流步骤

1. 了解需求 — 当前代码状态、错误消息、表名
2. 添加 Logview 支持 — 操作前创建会话，只在最终执行处添加 try/except，并在 except 中提供 Logview URL
3. 提供调试指导 — 说明 Logview 的用法和常见错误模式

代码结构示例

import maxframe.dataframe as md
from maxframe.session import new_session

session = new_session()

try:
    df = md.read_odps_table("table_name")
    result = df.groupby('region').agg({'sales': 'sum'})
    result.execute()
except Exception as e:
    print(f"Error: {e}")
    print(f"Logview URL: {session.get_logview_address()}")
finally:
    session.destroy()

常见错误模式

1. 身份验证错误 — 检查环境变量
2. 找不到表 — 检查表名和权限
3. 超时错误 — 检查 Logview，优化查询
4. 类型不匹配 — 检查 DataFrame 的数据类型
5. SQL 错误 — 在 Logview 中检查生成的 SQL

参见： references/remote-debug-guide.md，了解详细解决方案。

场景 3：本地调试模式

工作流步骤

1. 了解需求 — UDF 逻辑、示例数据架构、IDE 偏好
2. 创建本地调试设置 — 使用 debug=True 创建会话，并通过 md.DataFrame(pd.DataFrame(...)) 创建示例数据
3. 提供 IDE 设置指导 — 设置断点、了解执行流程，并且只执行最终步骤

代码结构示例

import maxframe.dataframe as md
from maxframe.session import new_session
import pandas as pd

session = new_session(debug=True)

sample_data = pd.DataFrame({
    'user_id': ['u1', 'u2', 'u3'],
    'level': ['gold', 'silver', 'bronze'],
    'amount': [1000, 500, 100]
})
df = md.DataFrame(sample_data)

def calculate_discount(row):
    # Set breakpoint here in IDE
    if row['level'] == 'gold':
        return row['amount'] * 0.1
    return row['amount'] * 0.02

try:
    result = df.apply(calculate_discount, axis=1)
    result.execute()
finally:
    session.destroy()

参见： references/local-debug-guide.md，了解完整指南。

场景 4：创建自定义运行时镜像

参考指南中的最佳实践，通过对话指导构建自定义 Docker 镜像。

何时创建自定义运行时

需要创建： 需要标准 DPE 运行时中没有的 Python 库、需要启用 GPU 的处理、需要特定 Python 版本或自定义系统依赖项时 无需创建： 标准软件包已满足需求，且不需要 GPU 时

对话式工作流

如果用户已指定基础镜像、Python 版本、GPU 要求、软件包或输出目录，请重述这些选择并继续。仅询问缺失、含糊或不兼容的选项。

1. 阅读最佳实践指南 — references/runtime-image-guides/README.md
2. 选择基础镜像 — Ubuntu 22.04（GPU/ML 工作负载）或 Ubuntu 24.04（现代开发）
3. 选择 Python 版本 — Python 3.11（生产环境）、3.10-3.12（开发环境）或所有版本
4. 配置 GPU — CUDA 12.4 + PyTorch 2.6.0+cu124（用于 ML 工作负载时）
5. 逐步收集软件包 — 收集所需软件包，并记录版本约束
6. 输出目录 — 确认文件的创建位置
7. 逐部分构建 Dockerfile — 标题、基础环境设置、conda 设置、GPU 设置、软件包、环境配置、验证
8. 创建支持文件 — README.md、.dockerignore、requirements.txt
9. 提供构建和测试说明
10. MaxFrame 使用示例

分步指南

步骤 1：选择基础镜像（如信息缺失则询问）

说明 Ubuntu 选项及其优缺点：

Which Ubuntu version for your custom runtime?

A. Ubuntu 22.04 (Recommended for most cases)
   - Stable, production-ready
   - Excellent CUDA support (12.4, 12.1, 11.8)
   - Widely tested ML libraries (PyTorch, TensorFlow)
   - LTS until 2027

B. Ubuntu 24.04 (Modern/latest)
   - Newer system packages
   - Latest LTS (until 2029)
   - Better for non-GPU workloads
   - Python 3.12 integration

Recommendation:
- GPU/ML workloads → Ubuntu 22.04
- Modern development → Ubuntu 24.04

步骤 2：选择 Python 版本（如信息缺失则询问）

Which Python versions?

A. Python 3.11 only (Recommended for production)
   - Best performance
   - Smallest image (~1 GB)
   - Excellent package support

B. Python 3.10, 3.11, 3.12 (Development)
   - Good compatibility
   - Medium size (~2 GB)
   - Recent versions

C. All versions 3.7-3.12 (Maximum flexibility)
   - Largest image (~3-5 GB)
   - Maximum compatibility
   - Testing across versions

Recommendation:
- Production → Single version (3.11)
- Development → Recent versions (3.10-3.12)

步骤 3：配置 GPU（如信息缺失则询问）

如果用户提到 GPU 或 ML 包：

Need GPU support?

A. Yes - GPU-enabled with CUDA 12.4 (Recommended)
   - Install PyTorch 2.6.0+cu124
   - CUDA toolkit 12.4
   - Note: Requires Ubuntu 22.04 for best compatibility

B. No - CPU only
   - Standard package installation
   - Smaller image size

Recommendation: For ML/AI workloads, GPU support significantly improves performance.

兼容性处理： 如果用户先前选择了 Ubuntu 24.04，现在又请求 GPU 支持：

• 说明：“Ubuntu 24.04 对 CUDA 的支持有限。建议使用 Ubuntu 22.04 来运行 GPU 工作负载。”
• AskUserQuestion：“是否改用 Ubuntu 22.04，以获得更好的 GPU 兼容性？”（推荐选择“是”）

步骤 4：逐段编写 Dockerfile

对于每个部分：

• 从最佳实践指南中查阅模式
• 说明用途及权衡
• 编写包含行内注释的部分
• 汇总为完整的 Dockerfile

各部分：

1. 文件头 — 镜像元数据、配置摘要
2. 基础设置 — FROM、apt 包、本地化设置、时区
3. Conda 设置 — 安装 Miniforge、创建环境
4. GPU 设置 — 安装 CUDA、配置支持 CUDA 的 PyTorch（如适用）
5. 包安装 — 在多个环境的循环中安装用户所需的包
6. 环境配置 — MF_PYTHON_EXECUTABLE、CONDA_DEFAULT_ENV、PATH
7. 验证 — 健康检查、Python 版本验证

步骤 5：提供构建和测试说明

# Build
docker build -t <image-tag> <output-dir>

# Test Python
docker run --rm <image-tag> conda run -n py311 python --version

# Test GPU (if applicable)
docker run --rm --gpus all <image-tag> python -c "import torch; print(torch.cuda.is_available())"

# Test packages
docker run --rm <image-tag> conda run -n py311 python -c "import transformers; print(transformers.__version__)"

# Push to registry
docker push <image-tag>

步骤 6：MaxFrame 用法示例 — 必须包含 new_session(odps=odps_connection, image="...")；绝不能单独展示 new_session(image=...)。

from maxframe.session import new_session

session = new_session(odps=odps_connection, image="your-registry/your-image:v1")

# Your MaxFrame operations here

默认建议

组件	建议
基础镜像	Ubuntu 22.04（生产环境、GPU、ML）
Python	3.11（生产环境），3.10-3.12（开发环境）
GPU	Ubuntu 22.04 + CUDA 12.4 + PyTorch 2.6.0+cu124

重要注意事项

MaxFrame SDK 不包含在运行时镜像中： SDK 和 pyodps 仅供客户端使用。自定义运行时需要用户特定的包（transformers、pandas 等）。

MF_PYTHON_EXECUTABLE（重要）： 始终设置：ENV MF_PYTHON_EXECUTABLE=/py-runtime/envs/<env_name>/bin/python

最佳实践参考

参见： references/runtime-image-guides/，其中提供了关于基础镜像选择、Python 环境策略、包管理、GPU/CUDA 配置、Dockerfile 模板以及测试/验证的详细指南。

算子选择工作流

在实现处理逻辑之前必须执行：当用户提到具体操作、询问效率/性能，或你需要查找合适的 MaxFrame 算子时。 对于仅涉及文档的回答，无需征求用户确认；但仍须使用查找脚本，以确保 API 相关表述有据可依。 如果用户明确指定算子或要求跳过交互，则输出 Operator confirmed via user prompt: <operator> 并直接实现。

工作流

1. 识别操作 — 列出所需的转换
2. 查找算子 — python scripts/lookup_operator.py search "<operation>"
3. 按数据形状分类 UDF 任务 — 对于自定义函数（UDF）任务，按数据组织方式（单表 / 分组 / 双表）和行基数（1→1、N→M、1→0..N）进行分类，然后根据 references/operators-and-modules/operator-selection-rules.md Rule 5 中的场景表选择 UDF 算子；绝不能默认使用 apply/apply_chunk
4. 展示选项 — 展示算子名称、说明及权衡
5. 征求用户确认 — 确认算子和参数，或输出上述用户指定算子的确认行
6. 实现 — 使用已确认的算子

参见： references/operators-and-modules/operator-selector.md，了解详细指南。

关键验证点

完成前，请验证：

• 在结果 DataFrame 上调用 .execute()
• 使用规范导入；不使用 from maxframe import new_session；不调用中间的 .execute()
• 在执行操作前创建 Session
• 在 finally 块中销毁 Session
• 不硬编码凭据
• 已与用户确认运算符选择；UDF 运算符与数据形状匹配（规则 5 场景表：组织 + 行数基数）
• 文档答复首先引用官方文档 URL；如果使用本地文档作为回退或交叉核对，则引用本地文档路径
• 场景检查——远程：使用 logview URL 进行错误处理；本地：使用 debug=True；自定义运行时：使用 MF_PYTHON_EXECUTABLE

资源

参考资料

• 运算符选择器：references/operators-and-modules/operator-selector.md
• 本地调试：references/local-debug-guide.md
• 远程调试：references/remote-debug-guide.md
• 完整工作流：references/common-workflow.md
• MaxFrame 客户端文档：references/maxframe-client-docs/
• 实用指南：references/practical-guides/
• 运行时指南：references/runtime-image-guides/
• 在线文档：https://maxframe.readthedocs.io/en/latest/
• 在线示例：https://maxframe.readthedocs.io/en/latest/examples/index.html
• 源代码：https://github.com/aliyun/alibabacloud-odps-maxframe-client.git

示例

• 可运行示例：assets/examples/*.py

脚本

• 运算符查询：scripts/lookup_operator.py