本地调试模式#

本页介绍 MaxFrame Local Debug Mode 的能力和用法。Local Debug Mode 支持在本地环境直接调试 apply()、apply_chunk() 等 UDF 函数，无需连接远程服务。

背景#

在传统的 MaxFrame UDF 开发流程中，调试 apply()、apply_chunk() 等函数需要将代码提交到远程集群执行，因此无法在本地设置断点或单步调试。每次修改后都需要重新提交远程执行，并且常常需要维护不同代码路径来区分本地开发和生产运行。

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

使用场景#

场景	说明
UDF 逻辑开发	实时调试并验证复杂业务逻辑。
数据转换测试	验证数据清洗和数据转换规则。
问题排查	定位 UDF 执行失败的根因。
离线开发	在没有网络访问的情况下继续开发。

功能特性#

与传统远程调试流程相比，Local Debug Mode 提供以下优势：

维度	Local Debug Mode	传统方式
断点调试	支持 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 原生 API	离线开发

无缝切换到生产环境

调试代码与生产代码保持一致。移除 debug=True 或 debug="local" 后，代码即可直接在生产环境运行。
```
# Debugging
session = new_session(o, debug=True)

# Production
session = new_session(o)
```

快速开始#

准备环境

# MaxFrame SDK 2.5.0 or later is required
pip install --upgrade maxframe

基础示例

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

o = ODPS(
    access_id='your_access_id',
    secret_access_key='your_secret_key',
    project='your_project',
    endpoint='your_endpoint',
)

# Enable debug mode
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:  # set a breakpoint here
        rate = 0.15
        print(rate)
    elif sales > 5000:  # set a breakpoint here
        rate = 0.10
        print(rate)
    else:
        rate = 0.05
    return sales * rate

result = df.apply(calculate_commission, axis=1).execute().fetch()

注意事项#

性能差异：Local Debug Mode 面向开发和验证场景，性能不等同于生产环境。
数据量限制：调试时建议使用小规模样本数据。
依赖一致性：确保本地 Python 环境使用与生产环境一致的依赖版本。
敏感数据：调试 MaxCompute 表时，请遵守数据权限和数据脱敏要求。