MaxFrame 本地偵錯模式（Local Debug） - MaxCompute

本文介紹MaxFrame本地偵錯模式（Local Debug Mode）的功能特性和使用方式。本地偵錯模式允許在本地環境中直接調試apply()和apply_chunk()等UDF函數，無需串連遠程服務。

背景資訊

在傳統的MaxFrame UDF開發流程中，調試apply()和apply_chunk()等函數時，需要將代碼提交到遠程叢集環境執行，無法在本地設定斷點或單步調試，每次修改後都需重新提交遠程運行，且可能需要維護多套代碼以區分本地和生產環境。

MaxFrame本地偵錯模式（Local Debug Mode）解決了以上問題。開啟本地偵錯模式後，UDF函數在本地Python環境中直接執行，支援IDE斷點調試，完全離線可用，且同一份代碼可在本地調試和生產運行之間無縫切換。

適用情境

情境	描述
UDF 邏輯開發	編寫複雜商務邏輯時可Just-in-Time 偵錯驗證
資料轉換測試	驗證資料清洗、轉換規則是否正確
問題排查	定位 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 表時注意資料許可權和脫敏處理。