安装

从Conda安装

Conda是Python，CPP和其他软件包的软件包管理员。

目前，SINGA有适用于Linux和MacOSX的conda软件包（Python 2.7和Python 3.6）。 建议使用Miniconda3与SINGA一起使用。安装完miniconda后，执行以下命令之一来安装SINGA。

  1. CPU版本

     conda install -c nusdbsystem singa-cpu

  2. 由CUDA和cuDNN支持的GPU版本

     conda install -c nusdbsystem singa-gpu

等同于

	conda install -c nusdbsystem singa=1.1.1=py36_cuda9.0-cudnn7.1.2

在执行上述命令之前，必须先安装CUDA 9.0。 其他CUDA版本的Singa软件包也可用。 以下说明列出了所有可用的Singa软件包。

	conda search -c nusdbsystem singa

如果下面指令没有出现错误提示，说明SINGA已经安装成功。

	python -c "from singa import tensor"

从源码安装

源文件可以被下载为tar.gz 文件，或者为一个git仓库：

	$ git clone https://github.com/apache/incubator-singa.git
	$ cd incubator-singa/

由conda创建SINGA

Conda-build是一款构建工具，可以安装anaconda云中的相关库并执行构建脚本。 生成的软件包可以上传到anaconda云中供他人下载和安装。

安装conda-build (安装miniconda后)

	conda install conda-build

创建CPU版本的SINGA

	export BUILD_STR=cpu
	conda build tool/conda/singa/ --python3.6 (or --python2.7)

上面的指令已在Ubuntu 16.04和Mac OSX上测试过。更多信息请参考Travis-CI页面。

创建GPU版本的SINGA

	export BUILD_STR=cudax.y-cudnna.b.c (e.g. cuda9.0-cudnn7.1.2)
	export CUDNN_PATH=<path to cudnn folder>
	conda build tool/conda/singa/ --python3.6 (or --python2.7)

这些基于GPU平台的指令已经在Ubuntu 16.04 (cuDNN >= 7和CUDA >= 9)上测试过。 Nvidia的docker镜像提供了cuDNN和CUDA的创建环境。

屏幕上将显示生成的包文件的位置。 请参阅conda安装 对从本地文件安装软件包的说明。

使用本地工具在Ubuntu上创建SINGA

编译和运行SINGA需要以下库。 有关在Ubuntu 16.04上安装它们的说明， 请参阅SINGA Dockerfiles。

  • cmake (>=2.8)
  • gcc (>=4.8.1) or Clang
  • google protobuf (>=2.5)
  • blas (tested with openblas >=0.2.10)
  • swig(>=3.0.10) for compiling PySINGA
  • numpy(>=1.11.0) for compiling PySINGA

  1. 在incubator-singa目录下创建一个build文件夹并进入其中

  2. 运行 cmake [options] .. 默认情况下除了USE_PYTHON，其他所有可选项都是OFF

    • USE_MODULES=ON, 当protobuf和blas没有被安装时使用
    • USE_CUDA=ON, 当CUDA和cuDNN可用时使用
    • USE_PYTHON=ON, 用于编译PySINGA
    • USE_PYTHON3=ON, 用于支持Python 3编译 (默认的是Python 2)
    • USE_OPENCL=ON, 用于支持OpenCL编译
    • PACKAGE=ON, 用于创建Debian包
    • ENABLE_TEST，用于编译单元测试用例

  3. 编译代码， 如： make

  4. 进入python文件夹

  5. 运行 pip install .或者 pip install -e .。第二个指令创建符号链接而不是将文件复制到python站点包文件夹中。

当USE_PYTHON=ON时，第4步和第5步用于安装PySINGA。

在通过ENABLE_TEST=ON编译好SINGA后，你可以运行单元测试

	$ ./bin/test_singa

你可以看到所有测试用例和测试结果。 如果SINGA通过所有测试，那么你已经成功安装了SINGA。

在Windows上编译SINGA

基于Python支持的Windows上的安装说明可以在这里找到。

更多编译选择

USE_MODULES

如果protobuf和openblas没有安装，在编译SINGA时需要如下处理：

	$ In SINGA ROOT folder
	$ mkdir build
	$ cd build
	$ cmake -DUSE_MODULES=ON ..
	$ make

cmake会下载OpenBlas和Protobuf（2.6.1）并同SINGA一起编译。

你可以使用cmake ..来配置编译操作指令。 如果一些依赖库没有被安装在默认路径下，你需要导出相应的环境变量：

	export CMAKE_INCLUDE_PATH=<path to the header file folder>
	export CMAKE_LIBRARY_PATH=<path to the lib file folder>

USE_PYTHON

类似于编译CPP代码， PySINGA可以被这么编译：

	$ cmake -DUSE_PYTHON=ON ..
	$ make
	$ cd python
	$ pip install .

USE_CUDA

用户被推荐安装CUDA和cuDNN以在GPU上运行SINGA时获得更好的性能。

SINGA已经在CUDA 9和cuDNN 7上测试过。 如果cuDNN在非系统目录下解压，如/home/bob/local/cudnn/, 下面的指令需要被执行以让cmake和运行时能找到它：

	$ export CMAKE_INCLUDE_PATH=/home/bob/local/cudnn/include:$CMAKE_INCLUDE_PATH
	$ export CMAKE_LIBRARY_PATH=/home/bob/local/cudnn/lib64:$CMAKE_LIBRARY_PATH
	$ export LD_LIBRARY_PATH=/home/bob/local/cudnn/lib64:$LD_LIBRARY_PATH

cmake对CUDA和cuDNN的操作选项应该被开启：

	# 依赖库已经被安装
	$ cmake -DUSE_CUDA=ON ..
	$ make

USE_OPENCL

SINGA用opencl-header和viennacl（1.7.1版本或更新）以获得OpenCL支持。 它们可由以下指令安装：

	# 在Ubuntu 16.04上
	$ sudo apt-get install opencl-headers, libviennacl-dev
	# 在Fedora上
	$ sudo yum install opencl-headers, viennacl

另外，你将需要OpenCL Installable Client Driver (ICD)以在你的平台上运行OpenCL。

  • 对于AMD和Nvidia GPU, 驱动包还需要包含正确的OpenCL ICD。
  • 对于英特尔CPUs和/或GPUs, 可以从英特尔官网上获取到。 注意， 官网上提供的驱动仅支持近期的CPUs和GPUs。
  • 对于更老的英特尔CPUs，你可以选用beignet-opencl-icd包。

注意，在CPU上运行OpenCL目前是不推荐的，因为很慢。 内存传输是以秒的级别（CPU上为1000 ms，而GPU上为1毫秒）。

更多关于OpenCL环境配置的信息可以从这里获得。

如果ViennaCL包版本低于1.7.1，你将需要从源码编译：

从git仓库clone，checkout到release-1.7.1标签。记得把仓库的路径加到环境变量PATH中，并且创建库到LD_LIBRARY_PATH。

编译基于OpenCL支持的SINGA (测试与SINGA 1.1)：

	$ cmake -DUSE_OPENCL=ON ..
	$ make

PACKAGE

此设置用于创建Debian包。 设置PACKAGE=ON并用以下命令创建包：

	$ cmake -DPACKAGE=ON
	$ make package

FAQ

  • Q: 在使用由wheel安装的PySINGA(‘import singa’)时，出现错误。

    A: 请查看python -c "from singa import _singa_wrap"详细错误提示。 这有时是由依赖库造成的，比如，有多个版本的protobuf，cudnn缺失，numpy版本不匹配。 下面的步骤详述了不同的案例：

    1. 检查cudnn，cuda和gcc版本，推荐使用cudnn5，cuda7.5和gcc4.8/4.9。 如果gcc是5.0版本， 需要降低版本。 如果cudnn确实或者与wheel版本不匹配，你可以将正确的cudnn版本下载到~/local/cudnn/ 并且

       $ echo "export LD_LIBRARY_PATH=/home/<yourname>/local/cudnn/lib64:$LD_LIBRARY_PATH" >> ~/.bashrc

    2. 如果是protobuf的问题，需要下载最新的编译过protobuf和openblas的whl文件。 或者，你可以从源码安装protobuf到指定文件夹，比如：~/local/；解压tar文件，然后执行

       $ ./configure --prefix=/home/<yourname>local
 $ make && make install
 $ echo "export LD_LIBRARY_PATH=/home/<yourname>/local/lib:$LD_LIBRARY_PATH" >> ~/.bashrc
 $ source ~/.bashrc

    3. 如果找不到其他python库，你可以用pip或conda创建python虚拟环境。

    4. 如果不是以上原因造成的，进入_singa_wrap.so所在文件夹，执行

       $ python
 >> import importlib
 >> importlib.import_module('_singa_wrap')

    检查错误信息。 比如，如果numpy版本不匹配，错误信息将会是

      RuntimeError: module compiled against API version 0xb but this version of numpy is 0xa

接着，你需要提升numpy版本。

  • Q: 运行cmake ..报错，找不到依赖库。

    A: 如果你没有安装相应库，就去安装它们。如果你把这些库安装在非系统默认的路径下，如/usr/local，你可以将正确路径导出到环境变量中：

      $ export CMAKE_INCLUDE_PATH=<path to your header file folder>
  $ export CMAKE_LIBRARY_PATH=<path to your lib file folder>

  • Q: make报错，如连接阶段

    A: 如果你的库文件在非系统默认路径下，你需要导出相应的变量

      $ export LIBRARY_PATH=<path to your lib file folder>
  $ export LD_LIBRARY_PATH=<path to your lib file folder>

  • Q: 头文件错误，比如：‘cblas.h no such file or directory exists’

    A: 你需要把cblas.h的路径加入到CPLUS_INCLUDE_PATH，如

      $ export CPLUS_INCLUDE_PATH=/opt/OpenBLAS/include:$CPLUS_INCLUDE_PATH

  • Q:编译SINGA时，我发现了错误SSE2 instruction set not enabled

    A:你可以尝试如下命令

      $ make CFLAGS='-msse2' CXXFLAGS='-msse2'

  • Q:当我试图导入.py文件时，我得到错误提示ImportError: cannot import name enum_type_wrapper。

    A: 你需要安装绑定到python的protobuf，可以由如下命令安装

      $ sudo apt-get install protobuf

    或者从源码安装

      $ cd /PROTOBUF/SOURCE/FOLDER
  $ cd python
  $ python setup.py build
  $ python setup.py install

  • Q: 当我从源码创建OpenBLAS时，被告知需要Fortran编译器。

    A: 你可以用如下命令编译OpenBLAS

      $ make ONLY_CBLAS=1

    或者

      $ sudo apt-get install libopenblas-dev

  • Q: 当我创建protocol buffer时，出现错误提示GLIBC++_3.4.20 not found in /usr/lib64/libstdc++.so.6。

    A: 这说明连接器找到了libstdc++.so.6，但是这个库属于一个更老版本的GCC编译器。 要编译的程序依赖于定义在新版本GCC下的libstdc++库，所以连接器必须被告知如何找到新版的可共享的libstdc++库。 最简单的处理方法是找到正确的libstdc++库，导出到LD_LIBRARY_PATH变量。 比如，如果GLIBC++_3.4.20被列在如下命令的输出中

      $ strings /usr/local/lib64/libstdc++.so.6|grep GLIBC++

    之后，你只需要设置环境变量

      $ export LD_LIBRARY_PATH=/usr/local/lib64:$LD_LIBRARY_PATH

  • Q: 当我创建glog时报错，“src/logging_unittest.cc:83:20: error: ‘gflags’ is not a namespace-name”。

    A: 这可能是你装了一个不同命名空间的gflags，比如“google”，所以glog找不到‘gflags’命名空间。 gflags不是创建glog必须的， 所以你可以修改configure.ac文件以忽略gflags。

      1. cd to glog src directory
  2. change line 125 of configure.ac  to "AC_CHECK_LIB(gflags, main, ac_cv_have_libgflags=0, ac_cv_have_libgflags=0)"
  3. autoreconf

    之后，你可以重新创建glog。

  • Q: 当使用虚拟环境时，每次我运行pip install都会重新安装numpy。 然而，在import numpy时，numpy可能并没有被使用。

    A: 这可能是因为在使用虚拟环境时，PYTHONPATH被设置成了空以防止与虚拟环境中的路径发生冲突。

  • Q: 当从源码编译PySINGA时，会因为缺失<numpy/objectarray.h>而出现编译错误。

    A: 请安装numpy并且通过如下命令导出numpy头文件

      $ export CPLUS_INCLUDE_PATH=`python -c "import numpy; print numpy.get_include()"`:$CPLUS_INCLUDE_PATH

  • Q: 当在Mac OS X下运行PySINGA时，我得到了错误信息“Fatal Python error: PyThreadState_Get: no current thread Abort trap: 6”。

    A: 这个错误很典型地出现在当你系统中存在多个版本的python并且你是通过pip安装 SINGA的（这个问题可以通过由conda安装SINGA来解决）， 比如：一个来自于OS，一个通过Homebrew安装。 和SINGA连接的Python必须和Python解析器是同个版本。你可以通过which python来查看python解析器版本，并通过otool -L 检查和PySINGA连接的Python版本。 为了解决这个问题， 需要用正确的Python版本来编译SINGA。 特别地，如果你从源码创建的PySINGA，当唤起cmake时你需要指定安装路径

      $ cmake -DPYTHON_LIBRARY=`python-config --prefix`/lib/libpython2.7.dylib -DPYTHON_INCLUDE_DIR=`python-config --prefix`/include/python2.7/ ..

    如果从二进制文件安装PySINGA，比如debian或者wheel，那么你需要改变python解析器，如重置变量$PATH，把正确的Python路径加在最前面。