Apache SINGA 配置参数详解
Apache SINGA 5.1.0 配置参数详解，围绕三类配置展开：cmake 构建参数决定编译哪些后端与语言绑定，示例与训练超参数控制迭代轮数、批大小与学习率，环境变量约束线程与加速库路径。本文给出参数总览表、逐项说明、生产配置模板与排错方法，全部取值与回显基于 Ubuntu 22.04 实测。
Apache SINGA 配置参数详解
目标：系统梳理 Apache SINGA 5.1.0 的三类配置——cmake 构建参数（决定编译哪些后端与绑定）、示例与训练超参数（epoch/batch/lr 等）、运行环境变量。以「查看方式 → 参数总览 → 逐项详解 → 生产配置模板」组织，全部取值与回显来自 Ubuntu 22.04 + SINGA 5.1.0（CPU + oneDNN）实测。
一、环境信息
- 操作系统：Ubuntu 22.04.5 LTS（x86_64，12 核）
- Python：3.10.12（虚拟环境
/root/singa-venv） - SINGA 版本：5.1.0（源码
/opt/singa，构建目录/opt/singa/build，CPU + oneDNN 1.1） - 编译工具：cmake 3.22.1、gcc 11.4.0、swig 4.0.2、protobuf 3.12.4、OpenBLAS 0.3.20
- 安装方式：源码编译安装（详见《Apache SINGA 安装指南》）
二、前置条件
已按《Apache SINGA 安装指南》完成源码编译安装，并确认：
source /root/singa-venv/bin/activate
python3 -c 'import singa; print(singa.__version__)'
实测回显：
5100
三、参数查看与修改方式
3.1 查看构建参数
SINGA 的编译期参数由 cmake 缓存管理，在构建目录用 -LAH 列出全部缓存变量及帮助文本：
cd /opt/singa/build
cmake -LAH . 2>/dev/null | grep -E '^USE_|^ENABLE_|^CMAKE_INSTALL_PREFIX'
实测回显（本指南构建取值）：
CMAKE_INSTALL_PREFIX:PATH=/root/singa-venv
ENABLE_DIST:BOOL=OFF
ENABLE_TEST:BOOL=OFF
USE_CUDA:BOOL=OFF
USE_CUDNN:BOOL=ON
USE_DIST:BOOL=OFF
USE_DNNL:BOOL=ON
USE_JAVA:BOOL=OFF
USE_LMDB:BOOL=OFF
USE_MODULES:BOOL=OFF
USE_OPENCL:BOOL=OFF
USE_OPENCV:BOOL=OFF
USE_PYTHON:BOOL=ON
USE_PYTHON3:BOOL=ON
3.2 修改构建参数
两种等价方式：直接传参重新 configure 后重编译：
cd /opt/singa/build
cmake -DUSE_DNNL=ON -DCMAKE_INSTALL_PREFIX=/root/singa-venv ..
make -j$(nproc) && make install
pip install --no-build-isolation /opt/singa/build/python
或用交互编辑器逐项修改（ccmake .，改完 c 配置、g 生成）。参数变更后必须重新编译并重新安装 Python 包才生效。
3.3 查看示例超参数
各示例的运行期超参数通过 --help 查看（MLP 示例）：
$ python3 mlp.py --help
usage: mlp.py [-h] [-m MAX_EPOCH] [-b BATCH_SIZE] [-l LR] [-H HIDDEN_SIZE]
options:
-h, --help show this help message and exit
-m MAX_EPOCH, --max-epoch MAX_EPOCH
maximum epochs
-b BATCH_SIZE, --batch-size BATCH_SIZE
batch size
-l LR, --learning-rate LR
learning rate
-H HIDDEN_SIZE, --hidden-size HIDDEN_SIZE
hidden perceptron size
四、构建参数总览
| 参数 | 类型 | 默认 | 本指南取值 | 作用 |
|---|---|---|---|---|
CMAKE_INSTALL_PREFIX | PATH | /usr/local | /root/singa-venv | 头文件/库/Python 包的安装前缀 |
USE_PYTHON | BOOL | ON | ON | 生成 Python 绑定 |
USE_PYTHON3 | BOOL | OFF | ON | 绑定到 Python 3（3.x 解释器与库） |
USE_CUDA | BOOL | OFF | OFF | 启用 CUDA/GPU 训练 |
USE_CUDNN | BOOL | ON | ON | 启用 cuDNN 加速（依赖 USE_CUDA） |
USE_DNNL | BOOL | OFF | ON | 启用 oneDNN CPU 加速（卷积等算子必需） |
USE_MODULES | BOOL | OFF | OFF | 从源码构建捆绑依赖（protobuf/OpenBLAS），OFF 时用系统库 |
USE_OPENCL | BOOL | OFF | OFF | 启用 OpenCL 后端 |
USE_JAVA | BOOL | OFF | OFF | 生成 Java 绑定 |
USE_OPENCV | BOOL | OFF | OFF | 启用 OpenCV 图像预处理 |
USE_LMDB | BOOL | OFF | OFF | 启用 LMDB 数据加载 |
USE_DIST | BOOL | OFF | OFF | 启用多 GPU 单机分布式（nccl/mpi 相关） |
ENABLE_DIST | BOOL | OFF | OFF | 启用跨机分布式训练（需 mpich/zmq） |
ENABLE_TEST | BOOL | OFF | OFF | 构建 C++ 单元测试 |
💡 说明：本指南构建显式指定了
USE_PYTHON3=ON、USE_DNNL=ON与CMAKE_INSTALL_PREFIX，其余参数为源码包默认值，与上方实测清单一致。
五、核心构建参数详解
5.1 计算后端参数
USE_DNNL（CPU 加速，强烈建议 ON）
启用 oneDNN（Intel MKL-DNN 后继）实现的卷积、池化等 CPU 算子。cmake 通过 DNNL_ROOT 环境变量定位预编译包；未启用时 CPU 卷积运行会触发断言失败并 abort：
Check failed: W.shape(0) == ch.num_filters && ... weights shape should not change
本指南配置：
export DNNL_ROOT=/root/dnnl_lnx_1.1.0_cpu_gomp/
cmake -DUSE_PYTHON3=ON -DUSE_DNNL=ON -DCMAKE_INSTALL_PREFIX=/root/singa-venv ..
实测定位回显：
-- Found DNNL at /root/dnnl_lnx_1.1.0_cpu_gomp/include
USE_CUDA / USE_CUDNN（GPU 加速）
USE_CUDA=ON 启用 CUDA 设备与 GPU 梯度同步算子，USE_CUDNN=ON（默认）启用 cuDNN 加速卷积/RNN。均需本机安装 CUDA 工具链（nvcc）与 cuDNN；无 GPU 环境保持 USE_CUDA=OFF（本指南实测取值 OFF，未展开 GPU 验证）。
USE_OPENCL
面向 AMD/异构 GPU 的 OpenCL 后端，默认 OFF。
5.2 依赖与绑定参数
USE_MODULES（捆绑依赖构建）
ON 时从源码下载并构建 protobuf、OpenBLAS 等捆绑依赖（耗时明显增加），OFF 时使用系统库。Ubuntu 22.04 的 protobuf 3.12.4 与 OpenBLAS 0.3.20 满足要求（实测 cmake 回显 found suitable version "3.12.4", minimum required is "3.0"），OFF 即可。
USE_PYTHON / USE_PYTHON3
生成 Python 绑定（singa 包）。USE_PYTHON3=ON 时 cmake 优先查找虚拟环境内的 Python 3 解释器：
-- Found PythonInterp: /root/singa-venv/bin/python3 (found suitable version "3.10.12", minimum required is "3")
-- Found PythonLibs: /usr/lib/x86_64-linux-gnu/libpython3.10.so (found suitable version "3.10.12", minimum required is "3")
-- Found SWIG: /usr/bin/swig4.0 (found suitable version "4.0.2", minimum required is "3.0.10")
CMAKE_INSTALL_PREFIX
make install 的落点。指向 venv 根目录时，库装到 <venv>/lib、头文件装到 <venv>/include，Python 包装入 <venv>/lib/python3.10/site-packages；多版本隔离即由此参数与独立 venv 组合实现。
5.3 分布式参数
ENABLE_DIST（跨机分布式）
启用基于 MPI（mpich）与 ZeroMQ 的跨机分布式训练路径，同时需要 USE_CUDA 配合（多 GPU 梯度聚合走 nccl/mpich）。本指南构建为 OFF，opt.DistOpt 接口存在但未实测，启用方法：安装 mpich libzmq3-dev 后以 -DENABLE_DIST=ON -DUSE_CUDA=ON 重新编译。
USE_DIST（单机多卡）
启用单机多 GPU 分布式（nccl 相关），同样需要 GPU 环境。
六、示例与训练超参数详解
以 MNIST MLP 示例的运行参数为例（实测环境 12 核 CPU）：
| 参数 | 默认值 | 实测取值 | 作用 | 调整建议 |
|---|---|---|---|---|
-m / --max-epoch | 2 | 2 | 训练轮数 | 验证功能用 1~2；正式训练按验证集准确率收敛判断 |
-b / --batch-size | 128 | 128 | 批大小 | 显存/内存不足时降到 64/32；过大影响泛化 |
-l / --learning-rate | 0.01 | 0.01 | 初始学习率 | loss 震荡则降 10 倍；收敛过慢则升 3~10 倍 |
-H / --hidden-size | 100 | 100 | 隐层单元数 | 提高模型容量，增大后需同步降 lr 或加正则 |
优化器构造参数（示例中 opt.SGD(lr, momentum, weight_decay)）：
| 参数 | 实测取值 | 作用 |
|---|---|---|
lr | 0.01 | 初始学习率，可传 opt.lr 调度器实现衰减 |
momentum | 0.9 | 动量系数，加速收敛并抑制震荡 |
weight_decay | 1e-5 | L2 正则系数，抑制过拟合 |
分布式梯度选项 dist_option（train_one_batch / mlp(tx, ty, dist_option, spars) 的实参）：plain（默认，全量同步）、half（半精度）、partialUpdate（部分更新）、sparseTopK/sparseThreshold（稀疏化，需 spars 参数）；多机场景需 ENABLE_DIST 构建支持。
七、环境变量与运行时配置
| 环境变量 | 作用 | 建议取值 |
|---|---|---|
DNNL_ROOT | cmake 定位 oneDNN（编译期） | /root/dnnl_lnx_1.1.0_cpu_gomp/ |
OMP_NUM_THREADS | 限制 OpenMP 线程 | 共机多任务时设为任务配额（如 4） |
OPENBLAS_NUM_THREADS | 限制 OpenBLAS 线程 | 同上；全机独占时保持默认 |
VIRTUAL_ENV / PATH | venv 激活状态 | source /root/singa-venv/bin/activate |
💡 说明：oneDNN 库路径在编译期经 RPATH 写入
singa/_singa_wrap.so（实测libdnnl.so.1 => /root/dnnl_lnx_1.1.0_cpu_gomp/lib/libdnnl.so.1），运行期无需再设置LD_LIBRARY_PATH。
八、生产配置模板
CPU 训练服务器（12 核 / 64 GB 参考，已按本指南构建验证）：
# /opt/singa/build 的生产构建命令
source /root/singa-venv/bin/activate
export DNNL_ROOT=/root/dnnl_lnx_1.1.0_cpu_gomp/
cd /opt/singa/build
cmake -DUSE_PYTHON3=ON -DUSE_DNNL=ON \
-DUSE_CUDA=OFF -DUSE_MODULES=OFF \
-DCMAKE_INSTALL_PREFIX=/root/singa-venv ..
make -j$(nproc) && make install
pip uninstall -y singa
pip install --no-build-isolation /opt/singa/build/python
训练脚本生产参数参考（MNIST MLP 实测基线）：
python3 mlp.py -m 2 -b 128 -l 0.01 -H 100
| 场景 | 参数组合 | 说明 |
|---|---|---|
| 冒烟验证 | -m 1 -b 128 | 实测单 epoch 约 17 秒（12 核） |
| 常规训练 | -m 10 -b 128 -l 0.01 | 按验证准确率收敛决定轮数 |
| 内存受限 | -b 64 -H 100 | 实测 batch 64 的 CNN 约 4 分钟/epoch（12 核 CPU） |
| GPU 环境 | USE_CUDA=ON 重建 + device.create_cuda_gpu() | 需 CUDA/cuDNN，本文未实测 |
九、常见问题
Q1：改了 cmake 参数重新 make 后，Python 里行为没变？
make install 只更新了系统库与 egg；必须再执行 pip uninstall -y singa && pip install --no-build-isolation /opt/singa/build/python 重装 Python 包才生效。
Q2：USE_DNNL=ON 时 cmake 找不到 DNNL？
DNNL_ROOT 未导出或路径不含 include/、lib/。确认 ls $DNNL_ROOT 能看到 include lib（实测内容：LICENSE README.md examples include lib）。
Q3：构建应该开 USE_MODULES=ON 吗？
仅在系统 protobuf/OpenBLAS 版本过低且无法升级时开启；Ubuntu 22.04 的 protobuf 3.12.4 满足最低要求 3.0，保持 OFF 可显著缩短编译时间。
Q4：怎么确认当前构建启用了哪些后端？
cd /opt/singa/build && cmake -LAH . 查看缓存值（实测清单见 3.1），或 ldd site-packages/singa/_singa_wrap.so | grep -E 'dnnl|cuda|openblas' 确认运行期链接。
Q5：学习率/动量在哪里改？
示例超参用命令行（-l），优化器动量/正则在脚本内 opt.SGD(lr=..., momentum=..., weight_decay=...) 修改；批大小/epoch 用 -b/-m。
十、参考链接
- 官方安装文档：
https://singa.apache.org/docs/installation/ - CMake 官方文档（缓存变量）：
https://cmake.org/cmake/help/latest/manual/cmake.1.html - oneDNN v1.1：
https://github.com/intel/mkl-dnn/releases/tag/v1.1 - SINGA 示例目录：
https://github.com/apache/singa/tree/master/examples