Apache SystemDS 3.4.0 配置参数详解
基于 SystemDS 3.4.0 实机实测的配置参数详解，逐项解析 SystemDS-config.xml 配置项，覆盖并行、codegen、GPU、联邦与缓存参数，给出 JVM 堆内存设置方法与分场景生产配置模板。
Apache SystemDS 3.4.0 配置参数详解
一、环境信息
本文所有配置项与验证命令均在以下环境中实测采集：
| 项目 | 值 |
|---|---|
| 操作系统 | Ubuntu 22.04.5 LTS（root 用户，CentOS 8 验证结论一致） |
| SystemDS 版本 | 3.4.0（官方二进制包） |
| JDK | OpenJDK 17.0.20.1 |
| 安装路径 | /opt/systemds-3.4.0 |
| 默认配置文件 | /opt/systemds-3.4.0/conf/SystemDS-config.xml |
二、前置条件
- 已按部署指南完成 SystemDS 3.4.0 安装，且
SYSTEMDS_ROOT、SYSTEMDS_JAR_FILE环境变量已配置； - 已配置
SYSTEMDS_STANDALONE_OPTS环境变量控制 JVM 堆内存（本文采用 -Xms256m -Xmx512m）； java -version与systemds -f /tmp/hello.dml可正常执行。
三、参数查看与修改方式
3.1 配置文件的自动查找顺序
bin/systemds 启动脚本按以下顺序确定配置文件（实测脚本逻辑）：
- 运行参数中显式给出
-config <文件路径>时优先使用（脚本会校验文件存在性）； - 环境变量
CONFIG_FILE指定的文件（存在时使用）； - 依次查找
$SYSTEMDS_ROOT/conf/SystemDS-config-defaults.xml、$SYSTEMDS_ROOT/SystemDS-config-defaults.xml； - 最后回退查找
$SYSTEMDS_ROOT/conf/SystemDS-config.xml（3.4.0 发行包自带该文件，默认即命中）。
每次运行时的启动横幅会打印实际使用的配置文件（实测回显）：
# CONFIG_FILE= -config /opt/systemds-3.4.0/conf/SystemDS-config.xml
3.2 查看默认配置
cat $SYSTEMDS_ROOT/conf/SystemDS-config.xml | grep -vE '^\s*<!--|^\s*-->' | grep -E 'sysds\.'
实测回显（参数行汇总）：
<sysds.localtmpdir>/tmp/systemds</sysds.localtmpdir>
<sysds.scratch>scratch_space</sysds.scratch>
<sysds.optlevel>2</sysds.optlevel>
<sysds.defaultblocksize>1000</sysds.defaultblocksize>
<sysds.cp.parallel.ops>true</sysds.cp.parallel.ops>
<sysds.cp.parallel.io>true</sysds.cp.parallel.io>
<sysds.parallel.encode>true</sysds.parallel.encode>
<sysds.parallel.encode.staged>false</sysds.parallel.encode.staged>
<sysds.parallel.encode.buildBlocks>-1</sysds.parallel.encode.buildBlocks>
<sysds.parallel.encode.applyBlocks>-1</sysds.parallel.encode.applyBlocks>
<sysds.parallel.encode.numThreads>-1</sysds.parallel.encode.numThreads>
<sysds.parallel.tokenize>false</sysds.parallel.tokenize>
<sysds.parallel.tokenize.numBlocks>64</sysds.parallel.tokenize.numBlocks>
<sysds.frame.tomatrix.warncast>false</sysds.frame.tomatrix.warncast>
<sysds.compressed.linalg>false</sysds.compressed.linalg>
<sysds.codegen.enabled>false</sysds.codegen.enabled>
<sysds.codegen.api>auto</sysds.codegen.api>
<sysds.codegen.compiler>auto</sysds.codegen.compiler>
<sysds.codegen.optimizer>fuse_cost_based_v2</sysds.codegen.optimizer>
<sysds.codegen.plancache>true</sysds.codegen.plancache>
<sysds.codegen.literals>1</sysds.codegen.literals>
<sysds.native.blas>none</sysds.native.blas>
<sysds.native.blas.directory>none</sysds.native.blas.directory>
<sysds.gpu.availableGPUs>-1</sysds.gpu.availableGPUs>
<sysds.floating.point.precision>double</sysds.floating.point.precision>
<sysds.stats.maxWrapLength>30</sysds.stats.maxWrapLength>
<sysds.lineage.cachespill>true</sysds.lineage.cachespill>
<sysds.federated.planner>runtime</sysds.federated.planner>
<sysds.federated.compression>none</sysds.federated.compression>
<sysds.caching.bufferpoollimit>15</sysds.caching.bufferpoollimit>
<sysds.caching.memorymanager>static</sysds.caching.memorymanager>
<sysds.async.prefetch>false</sysds.async.prefetch>
3.3 修改配置并验证
推荐流程：复制默认配置为独立文件，修改后用 -config 参数传入。实测将编译优化级别从 2 提到 3、临时目录改到独立磁盘路径：
cp $SYSTEMDS_ROOT/conf/SystemDS-config.xml /opt/systemds-work/my-config.xml
sed -i 's|<sysds.optlevel>2</sysds.optlevel>|<sysds.optlevel>3</sysds.optlevel>|' /opt/systemds-work/my-config.xml
sed -i 's|<sysds.localtmpdir>/tmp/systemds</sysds.localtmpdir>|<sysds.localtmpdir>/opt/systemds-tmp</sysds.localtmpdir>|' /opt/systemds-work/my-config.xml
确认修改结果：
grep -E 'optlevel|localtmpdir' /opt/systemds-work/my-config.xml
实测回显：
<sysds.localtmpdir>/opt/systemds-tmp</sysds.localtmpdir>
<sysds.optlevel>3</sysds.optlevel>
使用自定义配置运行并观察效果（临时目录位置会在运行产物中体现）：
mkdir -p /opt/systemds-tmp
echo 'print("hello systemds");' > /tmp/hello.dml
systemds -f /tmp/hello.dml -config /opt/systemds-work/my-config.xml
实测回显（节选）：
hello systemds
SystemDS Statistics:
Total execution time: 0.019 sec.
3.4 JVM 内存参数的修改位置
SystemDS 的内存不受 SystemDS-config.xml 控制，而由 JVM 堆参数决定，修改位置为环境变量（/etc/profile.d/systemds.sh）：
export SYSTEMDS_STANDALONE_OPTS="-Xms256m -Xmx512m"
启动脚本内置默认值为 -Xmx4g -Xms4g -Xmn400m，该环境变量一设置即整体覆盖。实测将 4 GB 默认值覆盖为 256-512 MB 后，每次运行日志均出现内存预算收缩提示：
26/10/12 05:36:18 WARN utils.SettingsChecker: Low memory budget of total: 31 GB set to: 512 MB
进程级验证（任务运行期间在另一终端执行）：
jps -v | grep -i systemds
实测回显（节选）：
4435 systemds-3.4.0.jar -Xms256m -Xmx512m --add-modules=jdk.incubator.vector -Dlog4j.configuration=file:/opt/systemds-3.4.0/conf/log4j.properties
四、参数总览
| 分类 | 参数 | 默认值 | 作用 |
|---|---|---|---|
| 路径存储 | sysds.localtmpdir | /tmp/systemds | 本地临时工作目录 |
| 路径存储 | sysds.scratch | scratch_space | 分布式暂存目录名 |
| 编译优化 | sysds.optlevel | 2 | 编译器优化级别 0-4 |
| 编译优化 | sysds.defaultblocksize | 1000 | 二进制块文件默认块维度 |
| 并行执行 | sysds.cp.parallel.ops | true | 单机指令多线程执行 |
| 并行执行 | sysds.cp.parallel.io | true | 单机读写多线程 |
| 并行执行 | sysds.parallel.encode | true | transformencode 多线程 |
| 并行执行 | sysds.parallel.tokenize | false | 分词多线程 |
| 压缩计算 | sysds.compressed.linalg | false | 压缩线性代数（实验性） |
| 代码生成 | sysds.codegen.enabled | false | 算子融合 codegen |
| 本地库 | sysds.native.blas | none | 本地 BLAS 加速 |
| 精度 | sysds.floating.point.precision | double | 浮点精度 |
| GPU | sysds.gpu.availableGPUs | -1 | 可用 GPU 编号 |
| 统计 | sysds.stats.maxWrapLength | 30 | 统计表列宽 |
| 血缘 | sysds.lineage.cachespill | true | 血缘缓存落盘 |
| 联邦 | sysds.federated.planner | runtime | 联邦计划生成器 |
| 缓存 | sysds.caching.bufferpoollimit | 15 | 缓冲池占堆比例上限（%） |
| 缓存 | sysds.caching.memorymanager | static | 内存管理器类型 |
| 异步 | sysds.async.prefetch | false | 异步预取 |
五、核心参数分类详解
5.1 路径与存储参数
sysds.localtmpdir（默认 /tmp/systemds）：本地临时目录，存放运行期间的中间数据与缓存。实测将其改为 /opt/systemds-tmp 后运行正常。生产建议指向大容量数据盘，且避免与系统盘共用 /tmp（部分系统会定期清理 /tmp 导致长任务失败）。
sysds.scratch（默认 scratch_space）：分布式模式（HDFS）下的暂存目录名，单机本地模式不生效。配合 -clean 参数可整体清理工作目录。
5.2 编译优化参数
sysds.optlevel（默认 2，取值 0-4）：DML 编译器优化级别。级别越高编译期做的重写与剪枝越激进。实测取 3 运行正常；0 仅用于调试编译问题，生产保持 2 即可，短脚本反复重跑且计算模式固定时可试 3。
sysds.defaultblocksize（默认 1000）：二进制块格式（Matrix_market 二进制块）的默认行列块大小，与 Spark 生态常见的 1000x1000 块对齐，一般不修改。
5.3 单机多线程并行参数
sysds.cp.parallel.ops（默认 true）：singlenode 控制程序内算子多线程执行，多核机器保持开启。
sysds.cp.parallel.io（默认 true）：多线程读写，大矩阵 CSV/二进制读写加速明显，保持开启。
sysds.parallel.encode（默认 true）：特征工程 transformencode/apply 阶段多线程。配套细粒度参数：
| 参数 | 默认值 | 说明 |
|---|---|---|
| sysds.parallel.encode.staged | false | build 与 apply 阶段间加同步屏障 |
| sysds.parallel.encode.buildBlocks | -1 | build 阶段并行行块数，-1 自动 |
| sysds.parallel.encode.applyBlocks | -1 | apply 阶段并行行块数，-1 自动 |
| sysds.parallel.encode.numThreads | -1 | 线程数，-1 表示按核数 |
sysds.parallel.tokenize（默认 false）：文本分词多线程开关，处理大规模文本时开启；配套 sysds.parallel.tokenize.numBlocks（默认 64）控制分块数。
5.4 压缩线性代数与代码生成
sysds.compressed.linalg（默认 false）：压缩线性代数（CLALib），对稀疏、低秩矩阵可显著降内存，官方标注实验性，生产开启前需充分压测。
sysds.codegen.enabled（默认 false）：算子融合代码生成，将相邻算子编译为融合函数减少中间物化。配套参数：
| 参数 | 默认值 | 说明 |
|---|---|---|
| sysds.codegen.api | auto | 生成 API：auto/java/cuda |
| sysds.codegen.compiler | auto | 编译后端：auto/janino/javac/nvcc/nvrtc |
| sysds.codegen.optimizer | fuse_cost_based_v2 | 融合策略：fuse_all/fuse_no_redundancy/fuse_cost_based_v2 |
| sysds.codegen.plancache | true | 融合算子源码缓存 |
| sysds.codegen.literals | 1 | 字面量编译：1 启发式、2 总是 |
计算密集、表达式链长的脚本开启后收益明显，实测默认关闭亦可正常完成训练。
5.5 本地 BLAS 与 GPU 参数
sysds.native.blas（默认 none，可选 auto/mkl/openblas）：矩阵乘与卷积走本地 BLAS 库。实测默认 none（纯 Java 路径）。安装了 Intel MKL 或 OpenBLAS 的机器可设 auto 获得加速，配合 sysds.native.blas.directory 指定库目录（none 表示使用标准 LD_LIBRARY_PATH）。
sysds.gpu.availableGPUs（默认 -1）：可用的 GPU 编号，-1 全部、可指定单个（5）、区间（0-2）或列表（0,2,4）。无 GPU 环境保持默认，相关参数（eviction.policy、memory.util.factor 等）不生效。
5.6 精度与统计参数
sysds.floating.point.precision（默认 double，可选 single）：浮点精度。单精度可减半内存占用并配合 GPU 训练大模型，代价是数值误差增大，金融与科学计算保持 double。
sysds.stats.maxWrapLength（默认 30）：-stats 输出中指令名与计时列的换行宽度，按终端宽度调整。
5.7 联邦计算参数
联邦（federated）模式用于跨节点数据不出域计算，核心参数：
| 参数 | 默认值 | 说明 |
|---|---|---|
| sysds.federated.planner | runtime | 计划生成器：none/runtime/compile_fed_all/compile_fed_heuristic |
| sysds.federated.par_conn | 0 | worker 事件循环并行度，0 按核数 |
| sysds.federated.par_inst | 0 | 指令并行度，0 按核数 |
| sysds.federated.monitorFreq | 3 | 监控后端轮询频率（秒） |
| sysds.federated.readcache | true | 跨会话联邦读取缓存 |
| sysds.federated.compression | none | 联邦传输压缩：zlib/snappy/fastlz/lz4/lzf |
单机模式不涉及这些参数，仅在使用 systemds WORKER <端口> 启动联邦 worker 时生效。
5.8 缓存与内存参数
sysds.caching.bufferpoollimit（默认 15）：缓冲池上限占堆的比例（%）。堆 512 MB 时缓冲池约 76 MB，堆增大时按同比例增长；中间结果频繁落盘的场景可适当调高。
sysds.caching.memorymanager（默认 static，可选 unified）：static 按固定比例划分存储与计算内存；unified 统一管理可减少抖动，Spark 场景收益更明显。
sysds.async.prefetch / sysds.async.broadcast / sysds.async.checkpoint（均默认 false）：异步预取、异步广播、异步检查点，主要作用于 Spark 执行模式，单机模式保持默认。
5.9 数据转换容错参数
sysds.frame.tomatrix.warncast（默认 false）：frame 转 matrix 时遇到无法转 double 的单元格的行为。false 严格模式直接失败；true 写入 NaN 并告警一次。清洗不干净的 CSV 数据建议开启以便快速定位脏数据。
六、生产配置模板
6.1 小内存机器模板（堆 512 MB，单机演示与轻量训练）
适用：4 GB 内存机器、堆限制 512 MB、数据规模百万行以内。配置文件：
<root>
<sysds.localtmpdir>/data1/systemds-tmp</sysds.localtmpdir>
<sysds.optlevel>2</sysds.optlevel>
<sysds.defaultblocksize>1000</sysds.defaultblocksize>
<sysds.cp.parallel.ops>true</sysds.cp.parallel.ops>
<sysds.cp.parallel.io>true</sysds.cp.parallel.io>
<sysds.parallel.encode>true</sysds.parallel.encode>
<sysds.compressed.linalg>true</sysds.compressed.linalg>
<sysds.codegen.enabled>false</sysds.codegen.enabled>
<sysds.native.blas>auto</sysds.native.blas>
<sysds.floating.point.precision>double</sysds.floating.point.precision>
<sysds.caching.bufferpoollimit>15</sysds.caching.bufferpoollimit>
<sysds.caching.memorymanager>static</sysds.caching.memorymanager>
<sysds.frame.tomatrix.warncast>true</sysds.frame.tomatrix.warncast>
</root>
配套环境变量：
export SYSTEMDS_STANDALONE_OPTS="-Xms256m -Xmx512m"
要点：开启压缩线性代数弥补堆小；本地 BLAS 设 auto 借用 CPU 加速；临时目录独立于 /tmp；磁盘预留 10 GB（中间物化与缓存）。
6.2 标准服务器模板（单机生产批处理）
适用：32 GB 内存、16 核以上，亿行级数据批处理；JVM 堆仍限制在 256–512 MB，吞吐提升依靠压缩线性代数、codegen 与独立临时数据盘。
<root>
<sysds.localtmpdir>/data1/systemds-tmp</sysds.localtmpdir>
<sysds.optlevel>3</sysds.optlevel>
<sysds.cp.parallel.ops>true</sysds.cp.parallel.ops>
<sysds.cp.parallel.io>true</sysds.cp.parallel.io>
<sysds.parallel.encode>true</sysds.parallel.encode>
<sysds.parallel.encode.numThreads>-1</sysds.parallel.encode.numThreads>
<sysds.parallel.tokenize>true</sysds.parallel.tokenize>
<sysds.compressed.linalg>false</sysds.compressed.linalg>
<sysds.codegen.enabled>true</sysds.codegen.enabled>
<sysds.codegen.optimizer>fuse_cost_based_v2</sysds.codegen.optimizer>
<sysds.native.blas>auto</sysds.native.blas>
<sysds.floating.point.precision>double</sysds.floating.point.precision>
<sysds.caching.bufferpoollimit>15</sysds.caching.bufferpoollimit>
<sysds.caching.memorymanager>unified</sysds.caching.memorymanager>
</root>
配套环境变量：
export SYSTEMDS_STANDALONE_OPTS="-Xms256m -Xmx512m -Xmn256m"
要点：codegen 开启融合长表达式链；内存管理器 unified；临时目录所在数据盘预留 100 GB 以上。
6.3 GPU 训练模板（单卡 GPU）
适用：带 NVIDIA GPU 的训练节点，JVM 堆限制在 256–512 MB，显存占用由 GPU 参数控制。
<root>
<sysds.localtmpdir>/data1/systemds-tmp</sysds.localtmpdir>
<sysds.gpu.availableGPUs>0</sysds.gpu.availableGPUs>
<sysds.gpu.memory.util.factor>0.9</sysds.gpu.memory.util.factor>
<sysds.gpu.eviction.policy>min_evict</sysds.gpu.eviction.policy>
<sysds.floating.point.precision>single</sysds.floating.point.precision>
<sysds.codegen.enabled>true</sysds.codegen.enabled>
<sysds.codegen.api>auto</sysds.codegen.api>
<sysds.compressed.linalg>false</sysds.compressed.linalg>
</root>
配套环境变量：
export SYSTEMDS_STANDALONE_OPTS="-Xms256m -Xmx512m"
要点：单精度减半显存占用；GPU 显存占用比例 0.9；codegen 走 auto 自动选择 CUDA 后端（需机器已装 CUDA 驱动与工具链）。
七、常见问题
Q1：修改了 SystemDS-config.xml 为什么看起来没生效？
确认运行的命令是否带了 -config 指向修改后的文件；不带该参数时若 $SYSTEMDS_ROOT/conf/SystemDS-config-defaults.xml 存在会优先于 SystemDS-config.xml 被加载。最直接的验证方式是看启动横幅的 CONFIG_FILE= 一行打印的路径。
Q2：日志提示 Low memory budget of total 31 GB set to 512 MB 是报错吗？
不是。这是 SystemDS 按当前 JVM 堆大小自动收缩内部内存预算的提示，恰好证明堆参数已生效。堆 512 MB 属正常演示配置，生产可按 6.2 节模板放大。
Q3：堆内存应该在哪里修改？为什么改 XML 无效？
堆内存由 JVM 参数控制，与 SystemDS-config.xml 无关。修改位置为环境变量 SYSTEMDS_STANDALONE_OPTS（写入 /etc/profile.d/systemds.sh），重新 source 后，用 jps -v | grep -i systemds 确认进程命令行中已出现新的 -Xms/-Xmx 值。
Q4：开启 sysds.compressed.linalg 后脚本结果会变吗？
压缩线性代数只压缩矩阵存储与相应计算路径，数学结果理论上等价，但因实验性标记，极端稀疏模式下可能有性能波动，建议上线前与关闭状态对比精度与耗时。
Q5：联邦参数在单机模式需要配置吗？
不需要。单机 singlenode 模式完全忽略 sysds.federated 系列参数，仅在通过 systemds WORKER <端口> 启动联邦 worker 或脚本涉及联邦读写时生效。
八、参考链接
- Apache SystemDS 官方文档：https://systemds.apache.org/docs/
- 配置参考（SystemDS-config.xml 说明）：https://systemds.apache.org/site/configuration
- 官方下载页：https://downloads.apache.org/systemds/
- 官方 GitHub 仓库：https://github.com/apache/systemds