MaxFrame Flag配置指南-云原生大数据计算服务 MaxCompute(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技术支持团队确认，以确保配置的正确性与有效性。