MaxFrame Flag配置指南 - MaxCompute

文檔結合豐富的配置樣本梳理MaxCompute Flag、運行時Flag以及MaxFrame運行參數的含義、預設值、可選值、典型應用情境與設定建議。

MaxFrame參數樣本

MaxCompute SQL Flag

在MaxFrame中，所有MaxCompute SQL相關Flag都通過options.sql.settings字典統一管理。

from maxframe import options

options.sql.settings = {
  # 樣本：設定作業最長已耗用時間為72小時
  "odps.sql.job.max.time.hours": 72,
  # 樣本：指定作業啟動並執行自訂鏡像
  "odps.session.image": "common",
  # 樣本：為所有輸入表設定50000的並發度
  "odps.sql.split.dop": '{"*":50000}',
  # 樣本：設定資料處理的批次大小為1024行
  "odps.sql.executionengine.batch.rowcount": 1024,
}

MaxFrame Options

MaxFrame自身的運行參數通過options.xxx的形式直接配置，樣本如下：

from maxframe import options

# 樣本：設定LogView連結的保留時間長度為24小時。
options.session.logview_hours = 24

# 樣本：設定用戶端在遇到可重試錯誤時的重試次數。
options.retry_times = 3

# 樣本：啟用MaxCompute內建的查詢最佳化功能。
options.sql.enable_mcqa = True

MaxCompute Flag

以下為options.sql.settings字典中常用的Flag參數。

參數類別	參數	用途	取值範圍及預設值	建議
並發與切分類	`odps.sql.split.dop`	基於列存統計資訊（CMF）按表配置資料讀取的並發度（DOP），其優先順序高於 split.size。配置的方法是 {表名: 數量} 的字典，如果針對特定表來使用，請使用完整的全限定名，即`project.[schema.]table`的格式來指定。如果對所有的表都指定切分，則使用 * 進行匹配，例如`{"*":50000}`。	範圍為 1 ~ 99999；預設無。	處理大表或執行大規模任務時，建議顯式開啟以獲得高並發。
並發與切分類	`odps.stage.mapper.split.size`	在 CMF 資訊不可用時，系統會基於輸入表的資料大小（MB）來切分任務。	範圍 ≥ 1；預設 256MB。	通常保持預設即可。
資源與記憶體類	`odps.stage.mapper.mem/reducer.mem/joiner.mem`	分別為Mapper、Reducer、Joiner階段的單個計算執行個體（Worker）分配記憶體（MB）。	範圍1024 ~ 12288MB；預設1024MB。	在處理巨量資料量、存在資料熱點或執行複雜Join導致記憶體溢出（OOM）時，應適當調大。
資源與記憶體類	`odps.stage.reducer.num / odps.stage.joiner.num`	手動設定Reduce和Join階段的並發執行個體數。	最大可設為10000；預設由系統動態計算。	當作業涉及大規模Shuffle（如 GROUP BY, JOIN）或存在資料扭曲時，建議顯式調大此值以分散計算壓力。
Shuffle與輸出安全	`odps.sql.runtime.flag.fuxi_streamline_x_EnableNormalCheckpoint` & `fuxi_ShuffleService_client_CheckpointMaxCopy`	為Mapper輸出的中間資料開啟備份，並設定備份份數。		在長耗時、大規模Shuffle的作業中，將副本數設為： `2 ("fuxi_ShuffleService_client_CheckpointMaxCopy": 2)`，可以顯著提高容錯能力和資料讀取的穩定性。
Shuffle與輸出安全	`odps.sql.sys.flag.fuxi_JobMaxInternalFolderSize`	設定單個作業允許產生的Shuffle中間資料的總空間上限（MB）。		在執行超大表Shuffle操作時，如果遇到`Internal data size exceeds limit`類的錯誤，需要調大此值。
計算穩定性與監控	`odps.sql.runtime.flag.fuxi_EnableInstanceMonitor` & `fuxi_InstanceMonitorTimeout`	兩者需搭配使用。啟用底層Fuxi調度器的心跳監控，並設定逾時時間（秒）。可防止因UDF長時間計算而被系統誤判為“假死”並終止。		`fuxi_InstanceMonitorTimeout`的修改需要聯絡支援人員加白名單。
	`odps.job.instance.retry.times`	單個 Worker（Instance）因偶發性錯誤（如機器宕機）失敗時，系統自動重試的最大次數。	預設 3；建議上限為 100。	需要聯絡支援人員加白名單才能設定超過預設值。
	`odps.dag2.compound.config`	配置底層 Worker 的複用策略。設定為 `fuxi.worker.reuse.policy:NO_REUSE`可禁用 Worker 複用。		當 UDF 存在記憶體流失或狀態汙染風險時，禁用複用可以保證每個任務都在乾淨的環境中運行，但會略微增加任務啟動開銷。
執行效率與最佳化	`odps.sql.executionengine.batch.rowcount`	設定 MaxCompute 內部處理資料的基本單位——批（Batch）的大小（行數）。	1024	這是記憶體與效能的平衡點。若單行資料極大導致 OOM，可調小此值；若計算簡單，可適當調大以提升吞吐。
	`odps.sql.runtime.flag.executionengine_EnableVectorizedExpr`	啟用運算式的向量化執行引擎，能大幅提升計算密集型操作的效能。		在使用 rand() 函數或進行大量算術運算的情境下，建議開啟。
	`odps.optimizer.enable.conditional.mapjoin` & `odps.optimizer.cbo.rule.filter.black`	兩者搭配使用可禁用 HashJoin。		將 cbo.rule.filter.black 設為 "hj"。專家選項，若不完全理解其對執行計畫的影響，請勿隨意配置。
	`odps.sql.split.cluster.parallel_explore`	在任務切分（Split）階段，並發讀取 CMF 資訊。		當作業的 Split 階段耗時過長時，建議開啟此項。
	`odps.sql.jobmaster.memory`	設定作業主控節點（JobMaster）的記憶體大小。		在執行涉及超大規模表的 Shuffle 作業時，建議加大此值，例如設定為 30000MB。
UDF與函數安全	`odps.sql.udf.timeout` & `odps.function.timeout`	控制一個資料批次（Batch）在 UDF 或函數中執行的逾時時間（秒）。	範圍 1 ~ 3600s；預設1800s。設定為0不會生效。
UDF與函數安全	`odps.sql.runtime.flag.executionengine_PythonStdoutMaxsize`	限制 Python UDF 中通過 print 語句輸出到 stdout 的日誌最大長度（MB）。	最大100MB；預設20MB。	需要聯絡支援人員加白名單才能修改。
資源與環境依賴	`odps.session.image`	為作業指定運行環境。該值必須是當前租戶的 MaxCompute 專案中已存在的自訂鏡像名稱。
	`odps.task.major.version`	將作業鎖定在 MaxCompute 的一個特定大版本上執行，以保證功能和行為的穩定性。		專家選項，若不清楚其影響，請勿隨意配置。
	`odps.storage.orc.row.group.stride` & `odps.storage.meta.file.version`	分別控制ORC檔案的行組（row group）大小和CMF中繼資料檔案的版本。		專家選項，若不瞭解其底層機制，請勿配置。
其他通用參數	`odps.sql.allow.fullscan`	是否允許在沒有分區過濾條件的情況下對分區表進行全表掃描。		謹慎開啟，以防產生意外的高額費用和長耗時。
	`odps.sql.cfile2.field.maxsize`	定義了單個欄位（列）允許儲存的最大尺寸（單位：Byte）。	預設 8388608 (8MB)；最大可設為 268435456 (256MB)。	當處理包含極大內容（如長文本、HTML、Base64編碼資料）的欄位時，需調大此值。
	`odps.sql.job.max.time.hours`	設定整個SQL作業最長的已耗用時間（小時）。	最大72小時；預設為24小時。
	`odps.sql.always.commit.result` & `odps.sql.runtime.flag.executionengine_EnableWorkerCommit`	兩者搭配使用可開啟“部分提交”功能。即使作業因部分資料處理失敗，已成功的結果也會被提交。		適用於允許部分成功的ETL情境。
寫表與CMF相關（固定搭配）	`{ "odps.task.merge.enabled": "false", "odps.sql.reshuffle.dynamicpt": "false", "odps.sql.enable.dynaparts.stats.collection": "true", "odps.optimizer.dynamic.partition.is.first.nth.value.split.enable": "false", "odps.sql.stats.collection.aggressive": "true", }`			固定搭配Flag組，確保在向動態分區表寫入資料時，能夠快速、正確地產生列存統計資訊（CMF）。這對於下遊作業使用 odps.sql.split.dop 進行精確的資料切分至關重要。

MaxFrame Options

以下為MaxFrame內建的主要Options參數，通過options.xxx的形式直接配置。

參數名	用途	類型	預設值
`options.local_timezone`	設定本地時區，影響日期與時間函數的預設行為。	STR/None	無預設值
`options.session.logview_hours`	設定產生的LogView連結的有效保留時間長度（小時）。	INT	24
`options.sql.enable_mcqa`	是否啟用MaxCompute內建的智能查詢最佳化與加速功能。	BOOL	TRUE
`options.sql.generate_comments`	是否在產生的SQL語句中自動添加註釋，便於溯源。	BOOL	TRUE
`options.sql.auto_use_common_image`	當檢測到代碼中使用了需要額外依賴的庫時，是否自動設定通用的公用鏡像。	BOOL	TRUE
`options.session.max_alive_seconds` `options.session.max_idle_seconds`	控制Session的生命週期。 `max_alive_seconds`是Session的最長存活時間； `max_idle_seconds`是Session允許的最大空閑時間。若空閑逾時，Session 會被回收。空閑間隔`max_idle_seconds`值應小於等於最長存活時間`max_alive_seconds`。
`options.session.temp_table_lifecycle`	設定通過MaxFrame建立的暫存資料表的預設生命週期（天）。	INT	1
`options.session.auto_purge_temp_tables`	Session結束時，是否自動清理本次Session建立的所有暫存資料表。	BOOL	FALSE
`options.function.default_running_options`	為通過`@remote`裝飾器註冊的函數設定預設的資源配置。	dict，鍵可包含 `cpu`, `memory`, `gpu`。

重要

許多特殊Flag的使用涉及白名單申請、自訂鏡像管理、CMF統計資訊依賴等前置條件。在配置這些進階選項前，請務必與MaxCompute支援人員團隊確認，以確保配置的正確性與有效性。