Apache SystemDS 3.4.0 常用 CLI 命令与工具详解

一、环境信息

本文所有命令与回显均在以下环境中实测采集：

项目	值
操作系统	Ubuntu 22.04.5 LTS（root 用户，CentOS 8 验证结论一致）
SystemDS 版本	3.4.0（官方二进制包，安装于 /opt/systemds-3.4.0）
JDK	OpenJDK 17.0.20.1
环境变量	SYSTEMDS_ROOT、SYSTEMDS_JAR_FILE、SYSTEMDS_STANDALONE_OPTS="-Xms256m -Xmx512m"
入口命令	/opt/systemds-3.4.0/bin/systemds

二、工具概览

SystemDS 的命令行体系由三部分构成：

工具	位置	用途
systemds 启动脚本	$SYSTEMDS_ROOT/bin/systemds	唯一入口，负责拼装 JVM 参数并调用主程序
DMLScript 主程序	systemds-3.4.0.jar 内 org.apache.sysds.api.DMLScript	实际承载全部运行参数
官方 DML 脚本库	$SYSTEMDS_ROOT/scripts/	算法（builtin、algorithms）与工具脚本（utils），用命令行直接执行

systemds 启动脚本自身的参数只有 4 个：-f <dml文件>、-r（远程调试）、-help、jar/WORKER/FEDMONITORING 位置参数；其余全部参数原样透传给 DMLScript。

三、前置条件

已完成 SystemDS 3.4.0 安装并配置 SYSTEMDS_ROOT 与 SYSTEMDS_JAR_FILE 环境变量（缺少后者会报 Unable to access jarfile）；
systemds -help 可正常打印用法；
工作目录 /opt/systemds-work 已创建，用于存放演示脚本。

四、工具详解

4.1 查看帮助：systemds -help

systemds -help

实测回显（节选）：

Help requested. Will exit after extended usage message!

Usage: /opt/systemds-3.4.0/bin/systemds [-r] [SystemDS.jar] [-f] <dml-filename> [arguments] [-help]

    SystemDS.jar : Specify a custom SystemDS.jar file (this will be prepended
                   to the classpath
                   or fed to spark-submit
    -r           : Spawn a debug server for remote debugging (standalone and
                   spark driver only atm). Default port is 8787
    -f           : Optional prefix to the dml-filename for consistency with
                   previous behavior dml-filename : The script file to run.
    arguments    : The arguments specified after the DML script are passed to
                   SystemDS.
    -help        : Print this usage message and SystemDS parameter info

Worker Usage: /opt/systemds-3.4.0/bin/systemds [-r] WORKER [SystemDS.jar] <portnumber> [arguments] [-help]

查看 DMLScript 层面的完整参数（绕过启动脚本直接调用主程序）：

java -jar $SYSTEMDS_JAR_FILE -help

实测回显（参数名清单）：

usage: systemds
 -args <argN>                        specifies positional parameters
 -checkPrivacy                       Check which privacy constraints are loaded
 -clean                              cleans up all SystemDS working directories
 -config <filename>                  uses a given configuration file
 -debug                              runs in debug mode
 -exec <mode>                        sets execution mode; can be 'hadoop' / 'singlenode' / 'hybrid' / 'spark'
 -explain <level>                    explains plan levels; can be 'hops' / 'runtime' / 'recompile_hops' / 'recompile_runtime' / 'codegen' / 'codegen_recompile'
 -f <filename>                       specifies dml/pydml file to execute
 -federatedCompilation <key=value>   Compile federated instructions
 -fedMonitoring <arg>                Starts a federated monitoring backend
 -fedStats <count>                   monitors federated workers statistics
 -gpu <force>                        uses CUDA instructions when reasonable
 -help                               shows usage message
 -lineage <arg>                      computes lineage traces
 -mem                                monitors and reports max memory consumption in CP
 -nvargs <key=value>                 parameterizes DML script with named parameters
 -ooc                                uses OOC backend
 -oocStats <arg>                     monitors OOC operators statistics
 -s <script_contents>                specified script string to execute directly
 -seed <arg>                         A general seed for the execution through the commandline
 -sparseIntermediate                 uses sparseRowVector intermediates for rowwise operations
 -stats <count>                      monitors and reports summary execution statistics
 -w <arg>                            starts a federated worker with the given port

4.2 执行 DML 脚本：-f 与启动横幅

echo 'print("hello systemds");' > /tmp/hello.dml
systemds -f /tmp/hello.dml

实测回显：

###############################################################################
#  SYSTEMDS_ROOT= /opt/systemds-3.4.0
#  SYSTEMDS_JAR_FILE= /opt/systemds-3.4.0/systemds-3.4.0.jar
#  SYSDS_EXEC_MODE= singlenode
#  CONFIG_FILE= -config /opt/systemds-3.4.0/conf/SystemDS-config.xml
#  LOG4JPROP= -Dlog4j.configuration=file:/opt/systemds-3.4.0/conf/log4j.properties
#  HADOOP_HOME= /opt/systemds-3.4.0/lib/hadoop
#
#  Running script /tmp/hello.dml locally with opts:
#  Executing command:    java -Xms256m -Xmx512m  --add-modules=jdk.incubator.vector  -Dlog4j.configuration=file:/opt/systemds-3.4.0/conf/log4j.properties  -jar /opt/systemds-3.4.0/systemds-3.4.0.jar  -f /tmp/hello.dml  -exec singlenode  -config /opt/systemds-3.4.0/conf/SystemDS-config.xml
###############################################################################
WARNING: Using incubator modules: jdk.incubator.vector
hello systemds
SystemDS Statistics:
Total execution time:           0.014 sec.

横幅中的 Executing command 一行完整展示了最终 java 命令，是排查参数问题的第一入口。若希望精简输出，可设置 export SYSDS_QUIET=1 关闭横幅。

4.3 传递命名参数：-nvargs

DML 脚本中以 $参数名 引用命名参数。实测调用官方数据生成脚本：

systemds -f $SYSTEMDS_ROOT/scripts/utils/generateData.dml -nvargs R=1000 C=10 S=1.0 Min=0.0 Max=10.0 Pdf=normal Path=/opt/systemds-work/X.csv Fmt=csv

实测回显（节选）：

26/10/12 05:36:18 WARN utils.SettingsChecker: Low memory budget of total:     31 GB set to:    512 MB
SystemDS Statistics:
Total execution time:           0.162 sec.

wc -l /opt/systemds-work/X.csv

实测回显：

1000 /opt/systemds-work/X.csv

命名参数缺省时，脚本内 ifdef($R, 5) 之类的默认值表达式会生效；必填参数缺失则直接报 ParseException，例如官方 Univar-Stats.dml 缺少 STATS 参数时的实测报错：

ERROR api.DMLScript: line 141:17 The parameter $STATS either needs to be passed through commandline or initialized to default value.

4.4 传递位置参数：-args

DML 脚本中以 $1、$2 引用位置参数。实测：

cat > /tmp/argsdemo.dml << 'EOF'
print("pos1=" + $1 + " pos2=" + $2);
EOF
java -Xms256m -Xmx512m --add-modules=jdk.incubator.vector -jar $SYSTEMDS_JAR_FILE -f /tmp/argsdemo.dml -args alpha 42 -exec singlenode

实测回显（节选）：

pos1=alpha pos2=42

注意 -args 属于 DMLScript 参数，需要按上面方式直接调用 java，或将其置于脚本参数之后透传。

4.5 执行计划诊断：-explain

systemds -f /tmp/hello.dml -explain

实测回显（节选）：

# EXPLAIN (RUNTIME):
# Memory Budget local/remote = 358MB/?MB/?MB
# Degree of Parallelism (vcores) local/remote = 12/
PROGRAM ( size CP/MR = 2/0 )
--MAIN PROGRAM
----GENERIC (lines 1-1) [recompile=false]
------CP print hello systemds.SCALAR.STRING.true _Var0.SCALAR.STRING 12
------CP rmvar _Var0

hello systemds
SystemDS Statistics:
Total execution time:           0.020 sec.

explain 默认 runtime 级别，可加参数升级为 -explain recompile_hops 查看重编译后的 HOP 计划，是分析矩阵计算下推与算子选择的关键工具。

4.6 运行统计：-stats

systemds -f /opt/systemds-work/train.dml -stats 10

实测回显（节选）：

SystemDS Statistics:
Total elapsed time:             0.983 sec.
Total compilation time:         0.683 sec.
Total execution time:           0.300 sec.
Cache hits (Mem/Li/WB/FS/HDFS): 24/0/0/0/2.
Cache writes (Li/WB/FS/HDFS):   1/3/0/1.
Cache times (ACQr/m, RLS, EXP): 0.144/0.000/0.001/0.049 sec.
HOP DAGs recompiled (PRED, SB): 0/0.
Total JIT compile time:         1.576 sec.
Total JVM GC count:             3.
Total JVM GC time:              0.015 sec.
Heavy hitter instructions:
  #  Instruction  Time(s)  Count
  1  tsmm           0.175      2
  2  write          0.049      1
  3  r'             0.026      4
  4  solve          0.023      1
  5  <=             0.011      1
  6  rand           0.008      2
  7  ba+*           0.005      2
  8  *              0.004      1
  9  rmvar          0.003     14
 10  toString       0.002      1

Heavy hitter 表列出耗时最高的指令（tsmm 为转置矩阵乘、solve 为直接求解器），是性能调优的第一手数据；GC count 与 GC time 可反映堆大小是否充裕。

4.7 指定执行模式：-exec

-exec 可取 hybrid（默认）、singlenode、spark、hadoop。单机部署实测 singlenode（启动脚本在不设置 SYSDS_DISTRIBUTED 时自动使用）：

systemds -f /tmp/hello.dml -exec singlenode

实测回显（节选）：

#  SYSDS_EXEC_MODE= singlenode
hello systemds

使用 spark/hadoop 模式需要集群环境，单机指定会因找不到集群配置而失败。

4.8 指定配置文件：-config

systemds -f /tmp/hello.dml -config /opt/systemds-work/my-config.xml

实测回显（节选）：

#  CONFIG_FILE= -config /opt/systemds-work/my-config.xml
hello systemds

传入的文件不存在时脚本会打印 Warning! Passed config file does not exist 并回退默认配置，不会中断。

4.9 内联脚本：-s

启动脚本不支持 -s（实测传 -s 直接报 Unknown parameter -s），内联执行需绕过脚本直接调用主程序，且必须携带 --add-modules=jdk.incubator.vector：

java $SYSTEMDS_STANDALONE_OPTS --add-modules=jdk.incubator.vector -jar $SYSTEMDS_JAR_FILE -s "print(\"inline works\");" -exec singlenode

实测回显（节选）：

inline works
SystemDS Statistics:
Total execution time:           0.013 sec.

缺失模块参数时的实测报错（可直接定位）：

Exception in thread "main" java.lang.NoClassDefFoundError: jdk/incubator/vector/DoubleVector
Caused by: java.lang.ClassNotFoundException: jdk.incubator.vector.DoubleVector

4.10 随机数种子与可复现

命令行 -seed 参数实测对 rand() 默认行为无约束力（两次执行 -seed 1234 得到不同结果：31.167258659401792 与 31.57243540488864）。可复现需在脚本内为 rand 显式指定 seed：

cat > /tmp/seeddemo2.dml << 'EOF'
X = rand(rows=2, cols=3, min=0, max=9, pdf="uniform", seed=1234);
print("sum=" + toString(sum(X)));
EOF
java -Xms256m -Xmx512m --add-modules=jdk.incubator.vector -jar $SYSTEMDS_JAR_FILE -f /tmp/seeddemo2.dml -exec singlenode

实测两次回显完全一致：

sum=32.205060557409176
sum=32.205060557409176

4.11 启动联邦 worker：WORKER 位置参数

systemds WORKER 9090

后台启动后采集进程（另开终端）：

jps -v | grep -i systemds

实测回显（节选）：

1370 systemds-3.4.0.jar -Xms256m -Xmx512m --add-modules=jdk.incubator.vector -Dlog4j.configuration=file:/opt/systemds-3.4.0/conf/log4j.properties

worker 日志中同样打印完整 Executing command（实测节选）：

#  Executing command:    java -Xms256m -Xmx512m  -jar /opt/systemds-3.4.0/systemds-3.4.0.jar  -w 9090  -config /opt/systemds-3.4.0/conf/SystemDS-config.xml

即 WORKER <端口> 最终映射为 DMLScript 的 -w <端口>。测试完毕停止 worker：

pkill -f "[s]ystemds-3.4.0.jar"

4.12 清理工作目录：-clean

java -jar $SYSTEMDS_JAR_FILE -clean

实测回显（节选）：

26/10/12 05:41:17 WARN util.NativeCodeLoader: Unable to load native-hadoop library for your platform, using builtin-java classes where applicable

该命令清理本地临时目录（默认 /tmp/systemds）中的历史产物，常在卸载或磁盘排查时使用。

4.13 配套进程工具：jps 与 ps

运行较长的任务（如生成 800000x20 数据集）期间，在另一终端验证 JVM 进程：

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

ps -ef | grep "[j]ava -Xms256m"

实测回显（节选）：

root      4435  4395 99 05:36 ?  00:00:08 java -Xms256m -Xmx512m --add-modules=jdk.incubator.vector -jar /opt/systemds-3.4.0/systemds-3.4.0.jar -f /opt/systemds-3.4.0/scripts/utils/generateData.dml -exec singlenode -config /opt/systemds-3.4.0/conf/SystemDS-config.xml -nvargs R=800000 C=20 S=1.0 Min=0.0 Max=10.0 Pdf=normal Path=/opt/systemds-work/bigX.csv Fmt=csv

两种方式均能看到堆参数 -Xms256m -Xmx512m。CentOS 8 若无 jps 命令，安装 java-17-openjdk-devel 包即可。

五、注意事项

systemds 启动脚本仅识别 -f、-r、-help 与位置参数，其余参数必须放在 DML 脚本名之后原样透传；
SYSTEMDS_JAR_FILE 未设置时 3.4.0 脚本会因 jar 查找缺陷报 Unable to access jarfile，务必在环境变量中固定 jar 路径；
绕过脚本直连 java 时必须带上 --add-modules=jdk.incubator.vector，否则报 NoClassDefFoundError；
-stats 与 -explain 会在输出中附加大量诊断信息，生产脚本静默运行时不要开启；日常关闭启动横幅可用 SYSDS_QUIET=1；
随机实验需要可复现结果时，在 rand() 内显式传 seed，不要依赖命令行 -seed；
联邦 worker 与 FEDMONITORING 均为前台常驻进程，生产应配合 nohup 或进程管理工具运行。

六、常见问题

Q1：systemds -f 报 Error: Unable to access jarfile org.apache.sysds.api.DMLScript 怎么解决？

原因是 3.4.0 启动脚本查找 jar 的模式串存在引号缺陷，导致 jar 路径为空。执行 export SYSTEMDS_JAR_FILE=/opt/systemds-3.4.0/systemds-3.4.0.jar 后重试；或显式传 jar：systemds /opt/systemds-3.4.0/systemds-3.4.0.jar -f x.dml。

Q2：使用 -s 传内联脚本报 Unknown parameter -s 是什么原因？

启动脚本的参数解析不包含 -s。改用 java $SYSTEMDS_STANDALONE_OPTS --add-modules=jdk.incubator.vector -jar $SYSTEMDS_JAR_FILE -s "print(1);" -exec singlenode 直接调用主程序即可。

Q3：-stats 输出里 Total JIT compile time 占比很高正常吗？

JIT 编译耗时集中在 JVM 启动与首次热点编译阶段，短任务中占比高属正常；长任务中该值占比会迅速稀释。若 GC count 同步偏高，说明堆偏小，需上调 SYSTEMDS_STANDALONE_OPTS 并用 jps -v 验证。

Q4：Heavy hitter 表中 tsmm、r'、ba+ 这类指令名如何理解？*

tsmm 是转置矩阵乘，r' 是范围序列生成，ba+* 是块聚合加乘，solve 是线性方程组求解。这些是 SystemDS 底层指令名，结合脚本语义可定位热点算子。

Q5：CentOS 8 上 jps 命令不存在怎么办？

java-17-openjdk-headless 包不含 jps，执行 dnf install -y java-17-openjdk-devel 补装；也可用 ps -ef | grep "[j]ava" 替代查看进程参数。

七、参考链接

Apache SystemDS 官方文档：https://systemds.apache.org/docs/
DML 语言参考：https://systemds.apache.org/docs/latest/language/reference
官方下载页：https://downloads.apache.org/systemds/
官方 GitHub 仓库：https://github.com/apache/systemds