DeepCL

• Python API
• 命令行 API
• C++ API
• Q-learning
• 构建指南
• 开发指南
• 变更记录

DeepCL

一个用于训练深度卷积神经网络的 OpenCL 库

• C++
• OpenCL
• 深度卷积
• Python 封装
• Lua 封装
• Q-learning

API：

• Python
• C++
• 命令行

层类型：

• 卷积层
• 最大池化层
• 归一化层
• 激活层
• Dropout 层
• 随机平移层
• 随机裁剪层
• 损失层

损失层类型：

• softmax
• 交叉熵（与多项逻辑回归等同）
• 均方误差

优化器：

• SGD
• Anneal
• Nesterov
• Adagrad
• Rmsprop
• Adadelta

激活函数：

• tanh
• 缩放 tanh（1.7519 * tanh(2/3x)）
• 线性
• sigmoid
• ReLU
• ELU（新！）

数据加载格式：

• JPEG 图片
• MNIST 数据集
• KGSGO v2 数据集
• NORB 数据集

权重初始化方法：

• 原始初始化
• 均匀分布
• 更多可能性...

也支持多列网络结构，如 McDNN 中所述。

示例用法

• 在下一步棋预测任务中，使用来自 KGSGO v2 数据集 的 3360 万条训练样本，获得了 37.2% 的测试准确率。

  • 命令行指令为：./deepcl_train dataset=kgsgoall netdef=12*(32c5z-relu)-500n-tanh-361n numepochs=15 learningrate=0.0001
  • 每个 epoch 耗时 2 天，共运行了 2 个 epoch，使用的硬件是一台亚马逊 GPU 实例，其中包含半块 NVidia GRID K520 GPU（性能约为 GTX780 的一半）。

• 在 MNIST 数据集上，使用 netdef=rt2-8c5z-relu-mp2-16c5z-relu-mp3-150n-tanh-10n numepochs=20 multinet=6 learningrate=0.002 的配置，获得了 99.5% 的测试准确率。

  • 每个 epoch 耗时 99.8 秒，使用的硬件同样是亚马逊的一半 NVidia GRID K520 GPU（由于我们并行训练 6 个网络，因此每个网络每个 epoch 只需约 16.6 秒）。

安装

原生库安装

本节介绍原生库及命令行工具的安装。即使你打算使用 Python 封装，也需要先完成这一步。

Windows

先决条件：

• 支持 OpenCL 的 GPU 或 APU，并已安装相应的 OpenCL 驱动程序
• 已在 Windows 2012 RC2 和（全新）Visual Studio 2015 上测试通过，这也是持续集成构建所使用的环境。

操作步骤：

• 从 http://deepcl.hughperkins.com/Downloads/ 下载最新的二进制压缩包（例如 v8.0.0rc8 版本）
• 解压后会生成 dist 文件夹
• 测试方法：
  • 打开命令提示符
  • 运行 call dist\bin\activate.bat（请根据你下载 DeepCL 二进制文件的实际路径调整命令）
  • 然后尝试运行 deepcl_unittests
  • （新增功能）现在可以选择运行测试的 GPU 设备，例如：deepcl_unittests gpuindex=1

请注意，每次打开新的命令提示符时都需要“激活”安装环境（或者你可以通过控制面板 | 系统 | 高级系统设置 | 环境变量永久添加相关环境变量）。

Linux

先决条件：

• 支持 OpenCL 的 GPU 或 APU，并已安装相应的 OpenCL 驱动程序（可通过运行 clinfo 检查，该命令应显示你期望的 GPU 设备）
• 已在 Ubuntu 14.04 32 位/64 位系统上测试通过。

操作步骤：

• 从 http://deepcl.hughperkins.com/Downloads/ 下载最新的 tar 包（例如 v8.0.0rc8 版本）
• 解压后会生成 dist 子文件夹
• 在 Bash 终端中运行 source dist/bin/activate.sh（请根据解压二进制 tar 包的实际路径调整命令）
• 测试方法：在同一 Bash 终端中运行 deepcl_unittests
  • （新增功能）现在可以选择运行测试的 GPU 设备，例如：deepcl_unittests gpuindex=1

请注意，每次打开新的 Bash 终端时都需要“激活”安装环境（或者你可以将 activate.sh 添加到你的 .bashrc 文件中）。

Python 封装

• 确保你已经安装了原生库，并通过运行 call dist\bin\activate.bat 或 source dist/bin/activate.sh 完成激活
• 运行 pip install --pre DeepCL
• 测试方法：运行 python -c "import PyDeepCL; cl = PyDeepCL.DeepCL()"

从源码构建

仅当使用二进制包无法满足你的配置需求，或你希望对 DeepCL 进行修改时，才需要从源码构建。

详情请参阅 Build.md。

如果无法运行怎么办？

• 检查你的系统是否配备了支持 OpenCL 的设备
  • 理想情况下是 GPU 或加速器，因为目前 DeepCL 并未针对 CPU 进行优化（至少暂时如此，未来可能会改变，欢迎提交 Pull Request :-) ）
• 尝试运行 gpuinfo（来自 EasyCL，但也作为本项目的一部分内置，以方便使用）
  • 该工具应至少输出一个支持 OpenCL 的设备
  • 如果没有，则需要确保你拥有支持 OpenCL 的设备，并已正确安装驱动程序以及配置 ICD（Windows 中为注册表，Linux 中为 /etc/OpenCL/vendors）。

如果我需要一个新功能怎么办？

请提交一个问题，告诉我你对此感兴趣。

• 如果这个功能本来就在我的待办事项列表中，迟早会实现的话（见下文），我可能会提前完成它。
• 如果这个功能与用户体验相关，我会尽量将其列为优先事项。

如果我想自己贡献代码呢？

• 请随意 fork 这个仓库，修改代码并提交 pull request。或者直接联系我。也可以两者都做 :-)

第三方库

• EasyCL
• clew
• libpng++
• Lua
• cogapp

硬件/驱动程序相关问题

• 如果你使用的是 Clover，你可能想看看：
  • 这个讨论串 https://github.com/hughperkins/DeepCL/issues/35
  • 这个分支 https://github.com/hughperkins/DeepCL/tree/clover-compatibility
  • 请注意，Clover 并不受官方支持，这些内容只是作为“起点”提供给那些想要尝试的人 :)

相关项目

• kgsgo-dataset-preprocessor 基于 kgsgo 棋局的数据集；包含 3300 万个数据点
• cltorch
• clnn

许可证

Mozilla 公共许可证 2.0

近期变更

• 2017年5月2日：
  • 分支 update-easycl-mac 更新至最新版 EasyCL，并在 Mac Sierra 上对以下 GPU 进行了单元测试：
    • Intel HD Graphics 530 GPU
    • Radeon Pro 450 GPU
  • 最新版 EasyCL 允许使用环境变量 CL_GPUOFFSET 来选择 GPU，例如设置为 1 选择第二个 GPU，或设置为 2 选择第三个 GPU。
  • 感谢我的雇主 ASAPP 提供了这台 Mac Sierra 给我使用 :-)
• 2016年8月7日：
  • Windows 编译器的“标准”版本由 msvc2010 更改为 msvc2015 update 3（Linux 和 Mac 不变）
  • Windows 上 Python 3.x 的“标准”版本由 3.4 更改为 3.5（Linux 和 Mac 不变）
  • （注：Python 2.7 在所有 Windows 32/64 位、Linux 和 Mac 上仍可正常使用）
  • Linux 和 Mac 上的标准 C++ 版本由 c++0x 更改为 c++11
• 2016年7月29日：
  • Python 相关修复：
    • 变更：现在必须使用 numpy 张量，不再接受 array.array
    • 新特性：现在可以将 numpy 张量作为 4D 张量提供，不再局限于 1D 张量
    • 错误修复：Q-learning 现在应该又能正常工作了
• 2016年7月26日：
  • 修复了清单加载器中的一些错误
  • 不再需要在清单文件的第一行指定图像数量
  • 为 deepcl_unittests 添加了 gpuindex= 选项（目前还处于测试阶段...）
• 2016年1月4日：
  • 修复了 Mac 上 OpenCL 构建和 C++ 构建中的多个编译警告
• 2016年1月3日：
  • 在 Travis 上创建了 Mac OS X 构建，并修复了构建问题，https://travis-ci.org/hughperkins/DeepCL
• 11月27日：
  • 添加了 ELU
• 10月第26周：
  • 创建了分支 clblas-2.8.0，该分支与 Visual Studio 2015 兼容。它使用最新的 clBLAS 2.8.x 版本。感谢 jakakonda 的帮助，使该分支得以成功运行。
• 8月28日：
  • 将 8.x 分支合并到主分支，即将发布 8.x 的第一个版本
  • 现在可以在 Windows 上通过二进制文件安装 8.x，例如在 32 位 Windows 7 上，假设你已经激活了合适的 Python 环境（假设已安装 7-Zip，默认位置，否则需手动解压）：

powershell Set-ExecutionPolicy unrestricted
rem following command is like `wget` in linux:
powershell.exe -Command (new-object System.Net.WebClient).DownloadFile('http://deepcl.hughperkins.com/Downloads/deepcl-win32-v8.0.0rc8.zip', 'deepcl-win32-v8.0.0rc8.zip')
rem following command is like `tar -xf` in linux:
"c:\program files\7-Zip\7z.exe" x deepcl-win32-v8.0.0rc8.zip
call dist\bin\activate.bat
pip install --pre DeepCL
python -c "import PyDeepCL; cl = PyDeepCL.DeepCL()"
# (last line is just to check works ok)

• 8月26日：现在也可以在 Linux 上通过二进制文件安装 8.x，例如在 64 位 Ubuntu 14.04 上：

mkdir 8.0.0rc4
cd 8.0.0rc4
wget http://deepcl.hughperkins.com/Downloads/deepcl-linux64-v8.0.0rc4.tar.bz2
tar -xf deepcl-linux64-v8.0.0rc4.tar.bz2
virtualenv env
source env/bin/activate
source dist/bin/activate.sh
pip install --pre DeepCL
python -c "import PyDeepCL; cl = PyDeepCL.DeepCL()"

（最后一行只是为了检查是否正常工作）

• 8月21日至24日：
  • 8.x 终于在所有 CI 测试配置上重新成功构建！
    • ubuntu 14.04 32 位 Python 2.7
    • ubuntu 14.04 32 位 Python 3.4
    • ubuntu 14.04 64 位 Python 2.7
    • ubuntu 14.04 64 位 Python 3.4
    • visual studio 2010 32 位 python 2.7
    • visual studio 2010 32 位 python 3.4
    • visual studio 2010 64 位 python 2.7
    • visual studio 2010 64 位 python 3.4
• 8月19日至20日：
  • Python 包装现在基于标准的原生 DeepCL 构建，使用非常简单的 setup.py 层进行构建
• 8月18日：
  • 添加了 BackwardIm2Col 层，该层在反向传播时使用 im2col
  • 添加了 BackpropWeightsIm2Col 层，该层在更新权重时使用 im2col
  • 添加了 BackwardAuto 层，该层会自动选择最快的反向传播层
  • 添加了 BackpropWeightsAuto 层，该层会自动选择更快的权重更新层
  • 在底层：
    • 创建了 ClBlasHelper，用于处理 Gemm 和 Gemv
    • 将 im2col 抽象为 Im2Col 类
• 截止到8月17日的一周内：
  • 添加了前向和反向 im2col 层
  • 前向 im2col 会在适当的时候自动用于前向传播
  • 反向部分尚未集成
  • 在底层：
    • 添加了 clBLAS
    • 将 Python 构建流程迁移到使用 cmake，而不是 setup.py（这样做是好是坏目前还不太确定）
• 6月22日：
  • 移除了 Lua 包装
  • 如果你想在 OpenCL 中使用 Lua，请考虑使用 cltorch 和 clnn

如何联系我

只需在 GitHub 页面右上角创建一个问题即可。不用担心你觉得这个问题是否荒谬或其他。反馈越多越好！

请注意，我目前 100% 的精力都集中在 cuda-on-cl 上，因此在此期间请耐心等待。

DeepCL 快速上手指南

DeepCL 是一个基于 OpenCL 的开源库，用于训练深度卷积神经网络。它支持 C++、Python 和命令行接口，能够利用 GPU 加速深度学习任务的训练过程。

环境准备

系统要求

• 操作系统: Windows (推荐 VS2015), Linux (Ubuntu 14.04+), macOS。
• 硬件: 必须配备支持 OpenCL 的 GPU 或 APU（目前主要针对 GPU 优化，CPU 运行效率较低）。
• 驱动: 安装对应显卡厂商提供的最新 OpenCL 驱动程序。
  • 验证方法: 在终端运行 clinfo (Linux) 或后续安装步骤中的 gpuinfo 工具，确认能检测到至少一个 OpenCL 设备。

前置依赖

• Windows: Visual Studio 2015 (用于编译或运行某些组件)，7-Zip (用于解压)。
• Linux: build-essential, cmake, python-dev, pip。
• Python: Python 2.7 或 3.4+ (推荐 3.5+)，需安装 numpy。

注意: 原文未提供中国镜像源。国内用户若下载二进制包速度慢，可尝试使用代理或寻找第三方镜像。安装 Python 包时，建议临时切换至国内 pip 源（如清华源）： pip install -i https://pypi.tuna.tsinghua.edu.cn/simple --pre DeepCL

安装步骤

DeepCL 提供预编译的二进制包，推荐优先使用此方式安装。仅当需要修改源码或二进制包不兼容时才选择从源码构建。

方案一：使用预编译二进制包（推荐）

1. Windows 安装

1. 从官网下载最新二进制压缩包 (例如 deepcl-win32-v8.0.0rc8.zip)： http://deepcl.hughperkins.com/Downloads/
2. 解压文件，生成 dist 文件夹。
3. 打开命令提示符 (cmd)，激活环境并测试：

   cd <解压后的路径>
   call dist\bin\activate.bat
   deepcl_unittests
   

   (可选) 指定特定 GPU 进行测试：deepcl_unittests gpuindex=1

2. Linux 安装

1. 从官网下载最新 tar 包 (例如 deepcl-linux64-v8.0.0rc8.tar.bz2)。
2. 解压并激活环境：

   tar -xf deepcl-linux64-v8.0.0rc8.tar.bz2
   cd dist
   source bin/activate.sh
   deepcl_unittests
   

   (可选) 指定特定 GPU 进行测试：deepcl_unittests gpuindex=1

方案二：安装 Python 封装器

在完成上述“原生库安装”并激活环境后，执行以下命令安装 Python 接口：

pip install --pre DeepCL

验证安装： 运行以下 Python 命令，若无报错则安装成功：

python -c "import PyDeepCL; cl = PyDeepCL.DeepCL()"

方案三：从源码构建

如果预编译包无法运行，请参考官方文档 doc/Build.md 进行源码编译。

基本使用

DeepCL 支持命令行直接训练、C++ API 和 Python API。以下是最常用的两种方式。

1. 命令行使用 (Command Line)

无需编写代码，通过定义网络结构和参数即可开始训练。

示例：在 MNIST 数据集上训练 该命令定义了一个包含卷积、池化、全连接层的网络，训练 20 个 epoch。

./deepcl_train dataset=mnist netdef="rt2-8c5z-relu-mp2-16c5z-relu-mp3-150n-tanh-10n" numepochs=20 multinet=6 learningrate=0.002

示例：围棋下一步预测任务 (kgsgo 数据集)

./deepcl_train dataset=kgsgoall netdef="12*(32c5z-relu)-500n-tanh-361n" numepochs=15 learningrate=0.0001

参数说明:

• dataset: 数据集类型 (支持 mnist, jpegs, kgsv2 等)。
• netdef: 网络结构定义字符串 (如 8c5z 表示 8 个 5x5 卷积核，relu 为激活函数，mp2 为 2x2 最大池化)。
• numepochs: 训练轮数。
• learningrate: 学习率。

2. Python API 使用

在 Python 脚本中调用 DeepCL 进行更灵活的控制。

import PyDeepCL

# 初始化 DeepCL 上下文
cl = PyDeepCL.DeepCL()

# 获取可用的 GPU 设备数量
num_devices = cl.getNumDevices()
print("Found {} OpenCL devices".format(num_devices))

# 后续可结合 numpy 数组进行数据加载、网络定义和训练
# 具体高级用法请参考 python/README.md

支持的核心功能概览

• 层类型: 卷积 (convolutional), 最大池化 (max-pooling), 归一化，Dropout, 随机平移/裁剪等。
• 损失函数: Softmax, 交叉熵 (cross-entropy), 平方损失 (square loss)。
• 优化器: SGD, Nesterov, Adagrad, Rmsprop, Adadelta。
• 激活函数: tanh, relu, sigmoid, elu, linear 等。