alibabacloud-odps-maxframe-coding 是什么？

为 AI Agent 提供 MaxFrame 开发技能。MaxFrame 是一个分布式计算框架，提供兼容 pandas 的 API，用于 MaxCompute 上的大规模数据处理。引导 Agent 完成完整的开发流程：会话管理、算子选择、数据读写、调试等。

alibabacloud-odps-maxframe-coding 怎么安装？

打开本页上方的「安装命令」标签页，复制命令到终端运行即可完成安装。

alibabacloud-odps-maxframe-coding 适合哪些场景？

主要用于「编程开发」等场景，适合需要为 AI Agent 提供 MaxFrame 开发技能。MaxFrame 是一个分布式计算框架，提供兼容 pandas 的 API，用于 MaxCompute 上的大规模数据处理。引导 Agent 完成完整的开发流程：会话管理、算子选择、数据读写、调试等。的任务。

alibabacloud-odps-maxframe-coding 收费吗？

本站收录的 Skill 安装包可免费获取使用；部分 Skill 依赖的第三方服务（如外部 API）可能需单独申请或订阅，以官方说明为准。

alibabacloud-odps-maxframe-coding：为 AI Agent 提供 MaxFrame 开发技能。MaxFrame

Q: alibabacloud-odps-maxframe-coding 适合哪些场景？

主要用于「编程开发」等场景，适合需要 为 AI Agent 提供 MaxFrame 开发技能。MaxFrame 是一个分布式计算框架，提供兼容 pandas 的 API，用于 MaxCompute 上的大规模数据处理。引导 Agent 完成完整的开发流程：会话管理、算子选择、数据读写、调试等。 的任务。

指令优先级

用户的明确指令（CLAUDE.md、GEMINI.md、AGENTS.md）—— 最高优先级
MaxFrame 编码 Skill —— 在冲突处覆盖默认系统行为
默认系统提示 —— 最低优先级

平台适配

本 Skill 使用 Claude Code 工具名。非 CC 平台：替换为等价工具。

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

本 Skill 能做什么

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

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

强制检查清单

检测场景类型 —— 识别是文档导航还是 4 个实现场景中的哪一个适用
理解需求 —— 就数据、操作、约束提问澄清
选择合适工作流 —— 将场景匹配到工作流模式
执行工作流步骤 —— 遵循下方场景特定步骤
校验执行 —— 确保调用了 execute()、会话已清理
提供后续指引 —— 调试技巧、优化建议

流程

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

digraph maxframe_workflow {
    "用户请求到达" [shape=box];
    "检测场景类型" [shape=diamond];
    "场景 1：编写代码" [shape=box];
    "场景 2：远程调试" [shape=box];
    "场景 3：本地调试" [shape=box];
    "场景 4：自定义运行时" [shape=box];
    "理解需求" [shape=box];
    "需要选择算子？" [shape=diamond];
    "使用 lookup_operator.py" [shape=box];
    "与用户确认" [shape=box];
    "实现代码/配置" [shape=box];
    "添加错误处理" [shape=box];
    "校验已调用 execute()" [shape=box];
    "校验会话清理" [shape=box];
    "提供指引" [shape=doublecircle];

    "用户请求到达" -> "检测场景类型";
    "检测场景类型" -> "场景 1：编写代码" [label="新管道"];
    "检测场景类型" -> "场景 2：远程调试" [label="集群测试"];
    "检测场景类型" -> "场景 3：本地调试" [label="IDE 断点"];
    "检测场景类型" -> "场景 4：自定义运行时" [label="自定义镜像"];
    "场景 1：编写代码" -> "理解需求";
    "场景 2：远程调试" -> "理解需求";
    "场景 3：本地调试" -> "理解需求";
    "场景 4：自定义运行时" -> "理解需求";
    "理解需求" -> "需要选择算子？";
    "需要选择算子？" -> "使用 lookup_operator.py" [label="是"];
    "需要选择算子？" -> "实现代码/配置" [label="否"];
    "使用 lookup_operator.py" -> "与用户确认";
    "与用户确认" -> "实现代码/配置";
    "实现代码/配置" -> "添加错误处理";
    "添加错误处理" -> "校验已调用 execute()";
    "校验已调用 execute()" -> "校验会话清理";
    "校验会话清理" -> "提供指引";
}

场景检测逻辑

场景 0：文档导航

用户询问通用 MaxFrame API、概念、示例或支持的 pandas API 问题
用户想搜索或浏览 MaxFrame 文档
用户询问某算子是否存在，或某文档化 API 应如何使用
关键词："MaxFrame 文档"、"documentation"、"API reference"、"官方示例"、"tutorial"、"supported pandas API"、"<api> 如何工作"

场景 1：编写 MaxFrame 代码

用户想创建新的数据处理管道
用户提到读写 MaxCompute 表
用户要求完整的 MaxFrame 程序
关键词："创建 MaxFrame"、"编写 MaxFrame 代码"、"构建管道"、"用 MaxCompute 处理数据"

场景 2：远程调试模式

用户想用真实集群资源测试
用户提到作业执行错误
用户要求 logview URL
用户想诊断执行失败
关键词："调试 MaxFrame 作业"、"logview"、"远程测试"、"执行错误"、"集群测试"

场景 3：本地调试模式

用户想迭代调试 UDF 函数
用户提到 IDE 断点（VSCode、PyCharm）
用户想用样本数据本地测试
用户想无需网络快速迭代
关键词："本地调试"、"IDE 断点"、"本地调试 UDF"、"VSCode/PyCharm 调试"

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

用户需要标准运行时中没有的 Python 库
用户想要 GPU 启用的运行时
用户提到构建自定义 DPE 镜像
关键词："自定义运行时"、"DPE 运行时镜像"、"GPU 运行时"、"安装自定义包"、"构建 Docker 镜像"

核心规则

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，否则不要结束场景 0；绝不输出 ...。如果无法查官方文档，在该行前包含 Official docs unavailable: <reason>; using local fallback.。

危险信号

想法	现实
"这只是个简单的 MaxFrame 问题"	问题也是任务。调用 Skill。
"我已经知道 MaxFrame API"	Skill 有最新模式。使用它们。
"让我直接写代码"	算子选择是强制的。
"我可以跳过算子确认"	用户确认是必需的。

场景 0：文档导航

用于不需要新建 MaxFrame 程序的 API / 概念 / 示例问题。

工作流步骤

分类问题 —— API / 算子、概念、支持的 pandas API、故障排查、运行时镜像或示例
先查官方文档 —— 在本地文档之前先尝试官方 URL：API / 概念用 https://maxframe.readthedocs.io/en/latest/，示例用 https://maxframe.readthedocs.io/en/latest/examples/index.html
将本地文档作为兜底或交叉核对

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

需要时使用本地主题位置

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/

基于来源作答 —— 最后非空行必须是 Sources: <完整官方 URL> (Primary)；仅当使用了本地文档时才追加 | <本地路径> (Fallback/Cross-check)

场景 1：编写 MaxFrame 代码

工作流步骤

理解需求 —— 源 / 目标表、schema、分区过滤、写入模式、处理逻辑
算子选择（强制） —— 使用 python scripts/lookup_operator.py search "<operation>"，呈现选项，获得确认
实现代码 —— 会话设置、读取数据、用已确认算子处理、写入结果、添加 execute()、在 finally 中清理
添加错误处理 —— 用 try/except 包裹 execute()，出错时打印 logview URL
校验 —— 规范导入、仅最终 .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 获取完整模式。

场景 2：远程调试模式

工作流步骤

理解需求 —— 当前代码状态、错误消息、表名
添加 Logview 支持 —— 操作前创建会话，仅最终 execute 前后加 try/except，except 中打印 logview URL
提供调试指引 —— 解释 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()

常见错误模式

鉴权错误 —— 验证环境变量
表未找到 —— 检查表名和权限
超时错误 —— 检查 logview，优化查询
类型不匹配 —— 检查 DataFrame dtypes
SQL 错误 —— 在 logview 中审查生成的 SQL

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

场景 3：本地调试模式

工作流步骤

理解需求 —— UDF 逻辑、样本数据 schema、IDE 偏好
创建本地调试设置 —— 用 debug=True 创建会话，用 md.DataFrame(pd.DataFrame(...)) 创建样本数据
提供 IDE 设置指引 —— 断点设置、执行流程，且仅最终 execute

示例代码结构

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):
    # 在 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 需求、包或输出目录，复述这些选择并继续。只询问缺失、模糊或不兼容的选择。

阅读最佳实践指南 —— references/runtime-image-guides/README.md
基础镜像选择 —— Ubuntu 22.04（GPU/ML 工作负载）或 Ubuntu 24.04（现代开发）
Python 版本选择 —— Python 3.11（生产）、3.10-3.12（开发）或所有版本
GPU 配置 —— CUDA 12.4 + PyTorch 2.6.0+cu124（若有 ML 工作负载）
迭代收集包 —— 收集所需包，记录版本约束
输出目录 —— 确认在哪里创建文件
逐段构建 Dockerfile —— 头部、基础设置、conda 设置、GPU 设置、包、环境配置、验证
创建支持文件 —— README.md、.dockerignore、requirements.txt
提供构建和测试说明
MaxFrame 用法示例

逐步指引

步骤 1：基础镜像选择（缺失时询问）

呈现 Ubuntu 选项及权衡：

自定义运行时用哪个 Ubuntu 版本？

A. Ubuntu 22.04（多数场景推荐）
   - 稳定、生产就绪
   - 出色的 CUDA 支持（12.4、12.1、11.8）
   - 广泛测试的 ML 库（PyTorch、TensorFlow）
   - LTS 至 2027

B. Ubuntu 24.04（现代 / 最新）
   - 更新的系统包
   - 最新 LTS（至 2029）
   - 更适合非 GPU 工作负载
   - Python 3.12 集成

推荐：
- GPU/ML 工作负载 → Ubuntu 22.04
- 现代开发 → Ubuntu 24.04

步骤 2：Python 版本选择（缺失时询问）

哪些 Python 版本？

A. 仅 Python 3.11（生产推荐）
   - 最佳性能
   - 最小镜像（约 1 GB）
   - 出色的包支持

B. Python 3.10、3.11、3.12（开发）
   - 良好兼容性
   - 中等大小（约 2 GB）
   - 较新版本

C. 所有版本 3.7-3.12（最大灵活性）
   - 最大镜像（约 3-5 GB）
   - 最大兼容性
   - 跨版本测试

推荐：
- 生产 → 单一版本（3.11）
- 开发 → 较新版本（3.10-3.12）

步骤 3：GPU 配置（缺失时询问）

如果用户提到 GPU 或 ML 包：

需要 GPU 支持吗？

A. 是 - GPU 启用，CUDA 12.4（推荐）
   - 安装 PyTorch 2.6.0+cu124
   - CUDA toolkit 12.4
   - 注意：为最佳兼容性需要 Ubuntu 22.04

B. 否 - 仅 CPU
   - 标准包安装
   - 更小镜像

推荐：对于 ML/AI 工作负载，GPU 支持显著提升性能。

兼容性处理：

如果用户之前选了 Ubuntu 24.04，现在要求 GPU 支持：

解释："Ubuntu 24.04 的 CUDA 支持有限。GPU 工作负载推荐 Ubuntu 22.04。"
AskUserQuestion："是否改用 Ubuntu 22.04 以获得更好的 GPU 兼容性？"（推荐"是"）

步骤 4：逐段构建 Dockerfile

对每一段：

从最佳实践指南读取模式
解释用途和权衡
写入带行内注释的段落
累积为完整 Dockerfile

段落：

头部 —— 镜像元数据、配置摘要
基础设置 —— FROM、apt 包、locale、时区
Conda 设置 —— Miniforge 安装、环境创建
GPU 设置 —— CUDA 安装、带 CUDA 的 PyTorch（如适用）
包安装 —— 多环境循环中的用户包
环境配置 —— MF_PYTHON_EXECUTABLE、CONDA_DEFAULT_ENV、PATH
验证 —— 健康检查、Python 版本验证

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

构建

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

测试 Python

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

测试 GPU（如适用）

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

测试包

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

推送到镜像仓库

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")

你的 MaxFrame 操作


### 默认推荐

| 组件 | 推荐 |
|-----------|---------------|
| 基础镜像 | 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> 并直接实现。

工作流

识别操作 —— 列出所需转换
查找算子 —— python scripts/lookup_operator.py search "<operation>"
呈现选项 —— 展示算子名、描述、权衡
获得用户确认 —— 确认算子和参数，或输出上述用户提示确认行
实现 —— 使用已确认算子

参见： references/operators-and-modules/operator-selector.md 获取详细指引。

关键校验点

完成前，校验：

[ ] 对结果 DataFrame 调用了 .execute()
[ ] 使用规范导入；无 from maxframe import new_session；无中间 .execute()
[ ] 操作前创建了会话
[ ] 在 finally 块中销毁了会话
[ ] 无硬编码凭证
[ ] 算子选择已与用户确认
[ ] 文档答案先引用官方文档 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

指令优先级

平台适配

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

本 Skill 能做什么

强制检查清单

流程

场景检测逻辑

核心规则

1. 只使用公共 API

2. 不要读取私有 .env 文件

3. 惰性执行

4. 会话管理

5. 算子选择需用户确认

6. 文档来源顺序

危险信号

场景 0：文档导航

工作流步骤

场景 1：编写 MaxFrame 代码

工作流步骤

示例代码结构

场景 2：远程调试模式

工作流步骤

示例代码结构

常见错误模式

场景 3：本地调试模式

工作流步骤

示例代码结构

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

何时创建自定义运行时

对话式工作流

逐步指引

构建

测试 Python

测试 GPU（如适用）

测试包

推送到镜像仓库

你的 MaxFrame 操作

算子选择工作流

工作流

关键校验点

资源

参考

示例

脚本

◯ 评论 0