Apache SINGA 安装指南

Apache SINGA 5.1.0 安装指南，面向 Ubuntu 22.04 服务器：先完成版本选型与 PyPI wheel 可用性核查，再从零走通源码编译安装与验证全流程，覆盖编译依赖安装、oneDNN 加速后端、cmake 编译参数、Python 3.10 兼容性补丁、多方案对照、升级降级与卸载方式，全部命令与回显均经实测。

Apache SINGAApache SINGA2026/10/12

Apache SINGA 安装指南

目标：在 Ubuntu 22.04 服务器上完成 Apache SINGA 5.1.0（分布式深度学习库，以 Python SDK 形态提供，非独立服务）的安装与验证。本文给出版本选型对照、源码编译安装（含 oneDNN 后端）、PyPI wheel 方案核查结论、Python 3.10 兼容性补丁、升级降级与卸载方式。所有命令与回显均在 Ubuntu 22.04.5 + Python 3.10.12 环境实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（VERSION_CODENAME=jammy）
  • 架构：x86_64（内核 6.8.0-138-generic，12 核）
  • 编译器：gcc 11.4.0（build-essential）
  • Python：3.10.12（python3-venv / python3-pip）
  • SINGA 版本：5.1.0（Apache 官方下载目录当前最新稳定版）
  • 加速后端：oneDNN 1.1（dnnl_lnx_1.1.0_cpu_gomp，官方 CPU 构建推荐）
  • 系统依赖：libprotobuf-dev / protobuf-compiler 3.12.4、libopenblas-dev 0.3.20、swig 4.0.2、cmake 3.22.1
  • Python 依赖：numpy 1.23.5、protobuf 3.20.3、deprecated、future、wheel
  • 虚拟环境：/root/singa-venv，源码目录：/opt/singa，构建目录：/opt/singa/build

💡 说明：Apache SINGA 是发布为 C++ 核心 + Python 绑定的深度学习训练库（singa.* 模块），本身没有可执行守护进程或服务端口，所谓「安装」本质是准备好编译环境，把核心库编译出来并装入 Python 环境。

二、前置条件

2.1 更新软件源并安装 Python 基础工具

sudo apt-get update
sudo apt-get install -y python3 python3-venv python3-pip

验证版本：

python3 --version
pip3 --version

实测回显：

Python 3.10.12
pip 22.0.2 from /usr/lib/python3/dist-packages/pip (python 3.10)

2.2 创建并启用虚拟环境

SINGA 以 Python 包形态安装，建议使用 venv 隔离依赖：

python3 -m venv /root/singa-venv
source /root/singa-venv/bin/activate

启用后 pip 指向虚拟环境：

pip 22.0.2 from /root/singa-venv/lib/python3.10/site-packages/pip (python 3.10)

2.3 安装编译工具链与系统库

源码编译需要 cmake、swig、protobuf、openblas：

sudo apt-get install -y build-essential cmake swig python3-dev \
  libprotobuf-dev protobuf-compiler libopenblas-dev git

验证：

cmake --version | head -1
protoc --version
swig -version | grep Version | head -1

实测回显：

cmake version 3.22.1
libprotoc 3.12.4
SWIG Version 4.0.2

三、版本选型说明

3.1 探测官方下载目录当前版本

curl -s https://downloads.apache.org/singa/ | grep -oE 'href="[0-9.]+/"'

实测返回：

href="5.1.0/"

3.2 PyPI wheel 现状核查

curl -s --max-time 30 https://pypi.org/pypi/singa/json | \
  python3 -c 'import json,sys; d=json.load(sys.stdin); print("latest:", d["info"]["version"]); print("all versions:", sorted(d["releases"].keys()))'

实测回显：

latest: 3.0.0.dev1
all versions: ['3.0.0.dev1']

该版本仅提供一个 wheel 文件：

singa-3.0.0.dev1-cp36-cp36m-manylinux2014_x86_64.whl 21047725

⚠️ 前置说明：PyPI 上唯一可用的 wheel 面向 Python 3.6（cp36）。清华 PyPI 镜像（pypi.tuna.tsinghua.edu.cn/simple）上经 pip index versions singa 实测返回 ERROR: No matching distribution found for singa，连该 wheel 也未同步。Python 3.10 环境无法用 pip 直接安装，推荐按第四章源码编译安装。

3.3 版本对照与选择建议

版本获取方式Python 支持适用场景结论
5.1.0Apache 官方源码包3.10（需一处兼容性补丁）当前最新稳定主线，CPU/GPU 训练、PEFT、医疗模型库推荐
3.0.0.dev1PyPI wheel（cp36）仅 Python 3.6老环境快速试用仅限 Python 3.6

本指南全程按 SINGA 5.1.0 + Python 3.10.12 源码编译实测。

四、方案 A：源码编译安装（推荐，已实测）

4.1 下载官方源码包并校验

cd /opt
curl -sO https://downloads.apache.org/singa/5.1.0/apache-singa-5.1.0.tar.gz
curl -sO https://downloads.apache.org/singa/5.1.0/apache-singa-5.1.0.tar.gz.sha512
sha512sum apache-singa-5.1.0.tar.gz
cat apache-singa-5.1.0.tar.gz.sha512

实测回显（两值一致即校验通过）：

ae94d3c4212efffc4206a500088db460e14019c78f57467a15b25cde006e42d80b0f7dbd6f914f463200d16151d8563f1c773525e25ae3c314686ae792737d02  apache-singa-5.1.0.tar.gz
ae94d3c4212efffc4206a500088db460e14019c78f57467a15b25cde006e42d80b0f7dbd6f914f463200d16151d8563f1c773525e25ae3c314686ae792737d02  apache-singa-5.1.0.tar.gz

解压到 /opt/singa：

tar xzf apache-singa-5.1.0.tar.gz
head -1 singa/RELEASE_NOTES

实测回显：

Release Notes - SINGA - Version singa-5.1.0

4.2 安装 oneDNN 加速后端

SINGA 的 CPU 卷积算子依赖 oneDNN；官方 CPU 构建（源码树 tool/ 下的 Ubuntu CPU 构建脚本）使用 oneDNN v1.1 预编译包：

cd /tmp
curl -sL -o dnnl_lnx_1.1.0_cpu_gomp.tgz \
  https://github.com/intel/mkl-dnn/releases/download/v1.1/dnnl_lnx_1.1.0_cpu_gomp.tgz
tar zxf dnnl_lnx_1.1.0_cpu_gomp.tgz -C /root
ls /root/dnnl_lnx_1.1.0_cpu_gomp/

实测回显：

LICENSE  README.md  examples  include  lib

4.3 安装 Python 依赖

注意 numpy 必须固定为 1.23.x（原因见第七章 7.1）：

source /root/singa-venv/bin/activate
pip install numpy==1.23.5 'protobuf==3.20.3' deprecated future wheel pillow
python3 -c 'import numpy; print(numpy.__version__)'

实测回显：

1.23.5

4.4 cmake 配置

source /root/singa-venv/bin/activate
export DNNL_ROOT=/root/dnnl_lnx_1.1.0_cpu_gomp/
cd /opt/singa
mkdir -p build && cd build
cmake -DUSE_PYTHON3=ON -DUSE_DNNL=ON -DCMAKE_INSTALL_PREFIX=/root/singa-venv ..

关键回显（关注 Found 各行）：

-- SINGA git Version 5.1.0
-- SINGA Version 5100
-- Found Protobuf: /usr/lib/x86_64-linux-gnu/libprotobuf.so (found suitable version "3.12.4", minimum required is "3.0")
-- Found CBLAS: /usr/include/x86_64-linux-gnu
-- Could NOT find Glog (missing: GLOG_INCLUDE_DIR GLOG_LIBRARIES)
-- Found DNNL at /root/dnnl_lnx_1.1.0_cpu_gomp/include
-- 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")
-- Configuring done
-- Generating done
-- Build files have been written to: /opt/singa/build

💡 说明：Could NOT find Glog 不影响编译（glog 为可选依赖）。构建参数的完整清单与含义见《Apache SINGA 配置参数详解》。

4.5 编译与安装

make -j$(nproc)

末尾实测回显：

[ 98%] Built target singa
[100%] Linking CXX shared library singa/_singa_wrap.so
[100%] Built target _singa_wrap

安装（会自动执行 python setup.py install 把 Python 包装入 CMAKE_INSTALL_PREFIX 指向的虚拟环境）：

make install

末尾实测回显：

Installing singa script to /root/singa-venv/bin
Finished processing dependencies for singa==5.1.0

4.6 改为平铺安装并验证

setup.py install 产生 egg 包，egg 是 zip 归档，其中的 .so 扩展无法被 Python 直接加载（导入会报 cannot import name '_singa_wrap' from partially initialized module 'singa'）。改用 pip 平铺重装：

pip uninstall -y singa
pip install --no-build-isolation /opt/singa/build/python

实测回显：

Successfully installed singa-5.1.0

验证安装：

python3 -c 'import singa; print(singa.__version__)'
pip show singa | head -6
ldd /root/singa-venv/lib/python3.10/site-packages/singa/_singa_wrap.so | grep -E 'protobuf|openblas|dnnl'

实测回显：

5100

Name: singa
Version: 5.1.0
Summary: A General Deep Learning System
Home-page: https://github.com/apache/singa
Author: Apache SINGA
Author-email: dev@singa.apache.org

        libprotobuf.so.23 => /lib/x86_64-linux-gnu/libprotobuf.so.23 (0x...)
        libopenblas.so.0 => /lib/x86_64-linux-gnu/libopenblas.so.0 (0x...)
        libdnnl.so.1 => /root/dnnl_lnx_1.1.0_cpu_gomp/lib/libdnnl.so.1 (0x...)

pip show 的 Version 为 5.1.0；singa.__version__ 返回数字 5100（5.1.0 的数值编码）。

4.7 Python 3.10 兼容性补丁（必做）

singa 5.1.0 的 singa/model.py 使用了 Python 3.10 已移除的旧导入，未修补时任何示例（from singa import model）都会失败：

ImportError: cannot import name 'Iterable' from 'collections' (/usr/lib/python3.10/collections/__init__.py)

执行单行替换修补：

python3 -c "p='/root/singa-venv/lib/python3.10/site-packages/singa/model.py'; \
s=open(p).read(); \
open(p,'w').write(s.replace('from collections import Iterable','from collections.abc import Iterable'))"

验证：

python3 -c 'from singa import model; print("model import OK")'

实测回显：

model import OK

五、方案 B：PyPI wheel 安装（仅 Python 3.6 环境）

PyPI 上唯一可安装的 singa wheel 是 singa-3.0.0.dev1-cp36-cp36m-manylinux2014_x86_64.whl，仅适用于 Python 3.6 环境（manylinux2014，要求 glibc ≥ 2.17，Ubuntu 22.04 满足）：

# 需自备 Python 3.6 环境（如 conda/pyenv），此处仅给出 wheel 安装命令
pip install singa
python3 -c 'import singa; print(singa.__version__)'

⚠️ 前置说明：该方案要求环境内 Python 解释器为 3.6（cp36 wheel），且 wheel 对应的是 3.0.0.dev1 开发版，功能与 5.1.0 差距较大。Ubuntu 22.04 官方源无 Python 3.6，生产环境建议按方案 A 编译安装当前稳定版。本指南主体按方案 A 实测，方案 B 未在本环境展开验证。

六、多方案对照与选择建议

维度方案 A：源码编译方案 B：PyPI wheel
SINGA 版本5.1.0（当前稳定主线）3.0.0.dev1（开发版）
Python 要求3.10（附一行补丁）仅 3.6
是否需联网需（下载源码包与 oneDNN）需（pip 下载 wheel）
安装方式cmake + make + pip 平铺pip install
后端能力CPU（oneDNN/OpenBLAS），可选 CUDAwheel 内置 CPU 库
优缺点版本最新、可定制构建参数；编译耗时一条命令；但版本过旧且 Python 受限

选择建议：Python 3.10 及以上、或需要最新特性（PEFT、医疗模型库等）选方案 A；仅有 Python 3.6 老环境临时试用才选方案 B。

七、配置说明

7.1 Python 依赖版本固定

singa/tensor.py 的 from_numpy 使用了 np.float，numpy 1.24+ 已移除该别名，使用 1.24+ 时会报：

AttributeError: module 'numpy' has no attribute 'float'.

因此固定 numpy==1.23.5（见 4.3）。如误装了高版本 numpy，可用 pip install numpy==1.23.5 降级修复。

7.2 环境变量

变量作用本指南取值
DNNL_ROOTcmake 定位 oneDNN 头文件与库/root/dnnl_lnx_1.1.0_cpu_gomp/
VIRTUAL_ENV（由 activate 设置）隔离 Python 包环境/root/singa-venv
OMP_NUM_THREADS / OPENBLAS_NUM_THREADS限制 BLAS/OpenMP 线程数，多任务共机时建议设置默认（全核）

oneDNN 库路径已由构建期 RPATH 写入扩展模块，日常 import singa 无需再设置 LD_LIBRARY_PATH；若移动了 oneDNN 目录，需重新 cmake 编译安装。

7.3 环境自启加载

把虚拟环境与 DNNL 变量写入 /root/.bashrc，登录即用：

echo 'source /root/singa-venv/bin/activate' >> /root/.bashrc
echo 'export DNNL_ROOT=/root/dnnl_lnx_1.1.0_cpu_gomp/' >> /root/.bashrc
source /root/.bashrc

八、升级、降级与多版本管理

  • 升级：下载新版源码包，重复第四章步骤即可；make install 与 pip install --no-build-isolation 会覆盖同版本安装，若版本号变更，pip 会自动替换旧包。
  • 降级：pip install --no-build-isolation /opt/singa-<旧版>/build/python 按同流程编译旧版源码包并覆盖安装。
  • 多版本并存：为每个版本建独立 venv（如 /root/singa-510-venv、/root/singa-500-venv），各自执行 cmake（-DCMAKE_INSTALL_PREFIX 指向对应 venv）与安装；用 source <对应venv>/bin/activate 切换。
  • 查看当前版本：pip show singa 的 Version 字段，或 python3 -c 'import singa; print(singa.__version__)'（5.1.0 输出 5100）。

九、常见问题

Q1：import singa 报 cannot import name '_singa_wrap' from partially initialized module 'singa'？ make install 产生的 egg（zip 归档）内的 .so 扩展无法被 Python 加载。按 4.6 执行 pip uninstall -y singa && pip install --no-build-isolation /opt/singa/build/python 改为平铺安装。

Q2：from singa import model 报 cannot import name 'Iterable' from 'collections'？ Python 3.10 移除了 collections.Iterable。按 4.7 的单行替换命令修补 site-packages/singa/model.py。

Q3：tensor.from_numpy 报 module 'numpy' has no attribute 'float'？ numpy 版本过高（1.24+）。执行 pip install numpy==1.23.5 固定到 1.23.x。

Q4：cmake 报 Found DNNL at ... 为空或编译后运行 Conv 报 weights shape should not change？ 未启用或未正确安装 oneDNN。确认 DNNL_ROOT 指向解压目录并在 cmake 时加 -DUSE_DNNL=ON 后重新编译安装（见 4.2/4.4）。

Q5：pip index versions singa 提示 No matching distribution？ PyPI 上 singa 仅有 cp36 wheel，清华镜像甚至未同步。Python 3.10 环境走源码编译（方案 A）。

Q6：make 编译缓慢或 OOM？ make -j$(nproc) 会按全核并行（实测环境 12 核），内存紧张时可降低并行度，如 make -j4。

十、卸载方式

source /root/singa-venv/bin/activate
pip uninstall -y singa          # 移除 Python 包
rm -rf /opt/singa /opt/singa-5.1.0.tar.gz*   # 移除源码与构建目录（按实际路径）
rm -rf /root/dnnl_lnx_1.1.0_cpu_gomp /tmp/dnnl_lnx_1.1.0_cpu_gomp.tgz  # 移除 oneDNN
rm -rf /tmp/mnist.npz /tmp/train-images-idx3-ubyte.gz /tmp/train-labels-idx1-ubyte.gz \
       /tmp/t10k-images-idx3-ubyte.gz /tmp/t10k-labels-idx1-ubyte.gz  # 移除示例数据集
deactivate && rm -rf /root/singa-venv          # 不再使用时移除虚拟环境

验证已卸载：

python3 -c 'import singa'

预期回显：

ModuleNotFoundError: No module named 'singa'

十一、参考链接

  • Apache SINGA 官网：https://singa.apache.org/
  • 官方下载目录：https://downloads.apache.org/singa/
  • 官方安装文档：https://singa.apache.org/docs/installation/
  • oneDNN v1.1 发布页：https://github.com/intel/mkl-dnn/releases/tag/v1.1
  • SINGA 源码仓库：https://github.com/apache/singa