MaxFrame 本地调试模式（Local Debug）-云原生大数据计算服务 MaxCompute(MaxCompute)-阿里云帮助中心

本文介绍MaxFrame本地调试模式（Local Debug Mode）的功能特性和使用方式。本地调试模式允许在本地环境中直接调试apply()和apply_chunk()等UDF函数，无需连接远程服务。

背景信息

在传统的MaxFrame UDF开发流程中，调试apply()和apply_chunk()等函数时，需要将代码提交到远程集群环境执行，无法在本地设置断点或单步调试，每次修改后都需重新提交远程运行，且可能需要维护多套代码以区分本地和生产环境。

MaxFrame本地调试模式（Local Debug Mode）解决了以上问题。开启本地调试模式后，UDF函数在本地Python环境中直接执行，支持IDE断点调试，完全离线可用，且同一份代码可在本地调试和生产运行之间无缝切换。

适用场景

场景	描述
UDF 逻辑开发	编写复杂业务逻辑时可实时调试验证
数据转换测试	验证数据清洗、转换规则是否正确
问题排查	定位 UDF 执行异常的根本原因
离线开发	无网络环境下仍可继续开发工作

功能特性

与传统远程调试方式相比，本地调试模式具有以下优势：

维度	本地调试模式	传统方式
断点调试	支持IDE断点调试	不支持
远端依赖	完全离线本地调试	需连接远程集群环境
调试周期	本地即时执行	每次需提交远程执行
代码改造	同一份代码	需维护多套代码

零配置开启调试
只需 debug=True或debug="local"，无需额外工具或服务
```
session = new_session(o, debug=True)
```
完全离线可用
不依赖网络或远端集群资源
原生 IDE 支持
- 支持 PyCharm、VSCode等主流 IDE 以及 DataWorks Notebook。
- 完整保留设置断点、变量监视、单步执行等调试能力。
- 调试体验与本地 Python 开发一致。

灵活数据接入

支持内存、本地文件、MaxCompute 表等多种来源。

数据源类型	获取方式	适用场景
内存数据	`md.DataFrame(pd.DataFrame())`	快速验证逻辑
MaxCompute 表	`md.read_odps_table()`	真实数据测试
本地文件	`pd.read_csv()`等原生 Pandas 数据接口	离线开发

生产无缝切换
调试代码与生产代码完全一致，移除 debug=True或debug="local"后代码可直接上线运行。
```
# 调试环境
session = new_session(o, debug=True)

# 生产环境
session = new_session(o)
```

快速开始

环境准备

pip install --upgrade maxframe # maxframe SDK版本需至少为2.5.0

基础示例

from odps import ODPS
from maxframe import new_session
import maxframe.dataframe as md
import pandas as pd

# 初始化 ODPS 对象
o = ODPS(
    access_id='your_access_id',
    secret_access_key='your_secret_key',
    project='your_project',
    endpoint='your_endpoint'
)

# 启用调试模式
session = new_session(o, debug=True)

# 准备数据
df = md.DataFrame(pd.DataFrame({
    "sales": [5000, 8000, 12000, 3000],
    "region": ["A", "B", "C", "D"]
}))

def calculate_commission(row):
    sales = row['sales']
    if sales > 10000: # 可在此设置断点
        rate = 0.15
        print(rate)
    elif sales > 5000: # 可在此设置断点
        rate = 0.10
        print(rate)
    else:
        rate = 0.05
    return sales * rate

# 执行并获取结果
result = df.apply(calculate_commission, axis=1).execute().fetch()

注意事项

性能差异：本地调试模式用于开发验证，性能不等同于生产环境。
数据量限制：建议调试时使用小规模样本数据。
依赖一致性：确保本地 Python 环境与生产环境依赖版本一致。
敏感数据：调试 MaxCompute 表时注意数据权限和脱敏处理。