BigDL Programming Guide

本文为官方文档译文

• Tensor
• Table
• Module
• Create modules
• Construct complex networks
• Build neural network models
• Criterion
• Transformer
• Sample and MiniBatch
• Engine
• Optimizer
• Validator
• Model Persist
• Logging
• Visualization via TensorBoard
  </br>

Tensor

---

Tensor（张量）本质是多维数组，可以储存Int,Float,Double等类型的数据。可以在scala shell中输入scala -cp bigdl_0.1-0.1.0-SNAPSHOT-jar-with-dependencies.jar引入jar包，简单的使用一下Tensor。

scala> import com.intel.analytics.bigdl.tensor.Tensor
import com.intel.analytics.bigdl.tensor.Tensor

scala> val tensor = Tensor[Float](2, 3)
tensor: com.intel.analytics.bigdl.tensor.Tensor[Float] =
0.0     0.0     0.0
0.0     0.0     0.0
[com.intel.analytics.bigdl.tensor.DenseTensor of size 2x3]

</br>

Table

---

Tensor和Table在BigDL应用非常广泛，可以作为网络的输入和输出。Table可以看做是一个key-value的map，在BigDL中通过T()创建。

scala> import com.intel.analytics.bigdl.utils.T
import com.intel.analytics.bigdl.utils.T

scala> T(Tensor[Float](2,2), Tensor[Float](2,2))
res2: com.intel.analytics.bigdl.utils.Table =
 {
        2: 0.0  0.0
           0.0  0.0
           [com.intel.analytics.bigdl.tensor.DenseTensor of size 2x2]
        1: 0.0  0.0
           0.0  0.0
           [com.intel.analytics.bigdl.tensor.DenseTensor of size 2x2]
 }

</br>

Module

---

在BigDL中Module类代表网络中的单独的层，比如，ReLU, Linear, SpatialConvolution, Sequential

创建层

以Linear为例

scala> import com.intel.analytics.bigdl.numeric.NumericFloat // import global float tensor numeric type
import com.intel.analytics.bigdl.numeric.NumericFloat

scala> import com.intel.analytics.bigdl.nn._
import com.intel.analytics.bigdl.nn._

scala> val f = Linear(3,4) // create the module
mlp: com.intel.analytics.bigdl.nn.Linear[Float] = nn.Linear(3 -> 4)

// let's see what f's parameters were initialized to. ('nn' always inits to something reasonable)
scala> f.weight
res5: com.intel.analytics.bigdl.tensor.Tensor[Float] =
-0.008662592    0.543819        -0.028795477
-0.30469555     -0.3909278      -0.10871882
0.114964925     0.1411745       0.35646403
-0.16590376     -0.19962183     -0.18782845
[com.intel.analytics.bigdl.tensor.DenseTensor of size 4x3]

构建复杂的网络

可以使用已有的Sequential, Concat, ConcatTable等modle去构建复杂的网络。

scala> val g = Sum()
g: com.intel.analytics.bigdl.nn.Sum[Float] = nn.Sum

scala> val mlp = Sequential().add(f).add(g)
mlp: com.intel.analytics.bigdl.nn.Sequential[Float] =
nn.Sequential {
  [input -> (1) -> (2) -> output]
  (1): nn.Linear(3 -> 4)
  (2): nn.Sum
}

构建复杂的神经网络模型

以LeNet-5为例，用不同的module构建神经网络模型。

import com.intel.analytics.bigdl._
import com.intel.analytics.bigdl.numeric.NumericFloat
import com.intel.analytics.bigdl.nn._

object LeNet5 {
  def apply(classNum: Int): Module[Float] = {
    val model = Sequential()
    model.add(Reshape(Array(1, 28, 28)))
      .add(SpatialConvolution(1, 6, 5, 5))
      .add(Tanh())
      .add(SpatialMaxPooling(2, 2, 2, 2))
      .add(Tanh())
      .add(SpatialConvolution(6, 12, 5, 5))
      .add(SpatialMaxPooling(2, 2, 2, 2))
      .add(Reshape(Array(12 * 4 * 4)))
      .add(Linear(12 * 4 * 4, 100))
      .add(Tanh())
      .add(Linear(100, classNum))
      .add(LogSoftMax())
  }
}

</br>

Criterion

---

BigDL中的Criterion类可以计算损失和梯度，可以在BigDL Criterions查找列表。

scala> val mse = MSECriterion() // mean square error lost, usually used for regression loss
mse: com.intel.analytics.bigdl.nn.MSECriterion[Float] = com.intel.analytics.bigdl.nn.MSECriterion@0

scala> val target = Tensor(3).rand() // create a target tensor randomly
target: com.intel.analytics.bigdl.tensor.Tensor[Float] =
0.33631626
0.2535103
0.94784033
[com.intel.analytics.bigdl.tensor.DenseTensor$mcF$sp of size 3]

scala> val prediction = Tensor(3).rand() // create a predicted tensor randomly
prediction: com.intel.analytics.bigdl.tensor.Tensor[Float] =
0.91918194
0.6019384
0.38315287
[com.intel.analytics.bigdl.tensor.DenseTensor$mcF$sp of size 3]

scala> mse.forward(prediction, target) // use mse to get the loss, returns 1/n sum_i (yhat_i - t_i)^2
res11: Float = 0.2600022

</br>

Transformer

---

Transformer预处理。在许多深度学习将数据放入模型前需要预处理。例如在CNN中，图像需要从一些复杂的格式解码成float数组，归一化，裁剪成固定的形状。在其他类型的深度学习任务中同样需要预处理。BigDL给用户提供了许多预处理程序。通过Transformer执行。
Transformer接口：

trait Transformer[A, B] extends Serializable {
  def apply(prev: Iterator[A]): Iterator[B]
}

transformer仅仅是将A对象序列转为另一个B对象序列。

tansformer非常灵活，你可以把它们放在一起做预处理。仍然以CNN为例，首先我们需要读取文件，然后将图像转为float数组，然后归一化并且裁剪成同样大小。这里我们需要四次转化，读取图像，转成数组，归一化和裁剪。这些步骤可以链到一起。

class PathToImage extends Transformer[Path, Image]
class ImageToArray extends Transformer[Image, Array]
class Normalizor extends Transformer[Array, Array]
class Cropper extends Transformer[Array, Array]

PathToImage -> ImageToArray -> Normalizor -> Cropper

transformer的另一个优点是可以代码重构，你可能会发现，对于类似的任务处理的步骤是相同的，尽管有些小的差别。因此，将其分解成小步骤取代大的欲处理函数，可以提高代码重用并且节省时间。

spark使用transformer非常容易

val rddA : RDD[A] = ...
val tran : Transformer[A, B] = ...
val rddB : RDD[B] = rdd.mapPartitions(tran(_))

BigDL的transformer不同于Spark ML pipeline Transformer，但是功能类似。
</br>

Sample and MiniBatch

---

sample代表数据集中的一个个体，例如图像分类中一个图像，word2vec中的一个词或是RNN语言模型中的一句话。

minibatch代表若干个samples，为了计算效率更高，我们将训练分成若干批。

你需要用transformer将你的数据转为sample或是minibatch，然后归一化或者进一步处理。注意，如果你提供样本格式，BigDL仍然会在归一化或者进一步处之前自动的将数据集转为minibatch。
</br>

Engine

---

BigDL通过Engine.init设置检测运行环境。

// Scala code example
val conf = Engine.createSparkConf()
val sc = new SparkContext(conf)
Engine.init

# Python code example
conf=create_spark_conf()
sc = SparkContext(conf)
init_engine()

Optimizer

---

optimizer是一个优化过程，又叫做训练。

您需要提供模型，训练数据集和损失函数来使用优化。

val optimizer = Optimizer(
  model = model,
  dataset = trainDataSet,
  criterion = new ClassNLLCriterion[Float]()
)

你可以设置优化的其他属性，如下：

• 超参数

optimizer.setState(
  T(
    "learningRate" -> 0.01,
    "weightDecay" -> 0.0005,
    "momentum" -> 0.9,
    "dampening" -> 0.0,
    "learningRateSchedule" -> SGD.EpochStep(25, 0.5)
  )
)

• 优化方法，默认是SGD，可以参看 Optimization Algorithms列表选择优化函数。

// Change optimization method to adagrad
optimizer.setOptimMethod(new Adagrad())

• 停止，默认在100次迭代后停止。

// Stop after 10 epoch
optimizer.setEndWhen(Trigger.maxEpoch(10))

• 输出

// Every 50 iteration save current model and training status to ./checkpoint
optimizer.setCheckpoint("./checkpoint", Trigger.severalIteration(50))

• 验证，你可以分离出一个数据集验证。

// Every epoch do a validation on valData, use Top1 accuracy metrics
optimizer.setValidation(Trigger.everyEpoch, valData, Array(new Top1Accuracy[Float]))

BigDL如何在分布式集群上训练数据集

bigdl将数据并行进行分布式训练。训练数据在workers之间被分割并缓存在内存中。一个完整的模型也缓存在每个worker中。在训练中模型只使用相同worker的数据。

BigDL采用同步的分布式训练。在每次迭代中，每个worker都会同步最新的权重，计算与本地数据和局部模型的梯度，通过给定的优化算法（如SGD，Adagrad）同步梯度和更新权重。

同步梯度和权重，BigDL没有使用RDD API（broadcast, reduce, aggregate, treeAggregate）。这些方法每个worker都需要与驱动程序进行通信，所以当参数过大或worker过多时，驱动程序就会瓶颈。相反，bigdl实施消除瓶颈参数同步P2P算法。有关算法的详细介绍，请参阅代码 code。
</br>

Validator

---

Validator是用来检测模型的。模型可以从磁盘加载或在训练优化。该指标可以TOP1精度、损失等。验证方法可从Validation Methods列表查看

// Test the model with validationSet and Top1 accuracy
val validator = Validator(model, validationSet)
val result = validator.test(Array(new Top1Accuracy[Float]))

</br>

Model Persist

---

你可以使用下面代码保存你的model

// Save as Java object
model.save("./model")

// Save as Torch object
model.saveTorch("./model.t7")

这样读取model

// Load from Java object file
Module.load("./model")

// Load from torch file
Module.loadTorch("./model.t7")

</br>

Logging

---

训练中，BigDL提供了日志如下，你也可以在epoch/iteration/loss/throughput直接查看日志文件。

2017-01-10 10:03:55 INFO  DistriOptimizer$:241 - [Epoch 1 0/5000][Iteration 1][Wall Clock XXX] Train 512 in XXXseconds. Throughput is XXX records/second. Loss is XXX.
2017-01-10 10:03:58 INFO  DistriOptimizer$:241 - [Epoch 1 512/5000][Iteration 2][Wall Clock XXX] Train 512 in XXXseconds. Throughput is XXX records/second. Loss is XXX.
2017-01-10 10:04:00 INFO  DistriOptimizer$:241 - [Epoch 1 1024/5000][Iteration 3][Wall Clock XXX] Train 512 in XXXseconds. Throughput is XXX records/second. Loss is XXX.
2017-01-10 10:04:03 INFO  DistriOptimizer$:241 - [Epoch 1 1536/5000][Iteration 4][Wall Clock XXX] Train 512 in XXXseconds. Throughput is XXX records/second. Loss is XXX.
2017-01-10 10:04:05 INFO  DistriOptimizer$:241 - [Epoch 1 2048/5000][Iteration 5][Wall Clock XXX] Train 512 in XXXseconds. Throughput is XXX records/second. Loss is XXX.

DistriOptimizer的log等级是INFO，目前我们实现了方法为redirectFilterSparkInfoLogs在spark/utils/LoggerFilter.scala中，你可以引用并：

import com.intel.analytics.bigdl.utils.LoggerFilter
LoggerFilter.redirectSparkInfoLogs()

除了org.apache.spark.SparkContext,这个方法可以使用INFO等级，将org, akka, breeze 重定向。同样的，可以在控制台输出ERROR。

• 你可以使用java属性禁用重定向
  Dbigdl.utils.LoggerFilter.disable=true。默认情况下它会将代码中所有的examples和models重定向。
• 你可以在bigdl.log设置路径，-Dbigdl.utils.LoggerFilter.logFile=<path>，默认情况下，日志会在当前工作目录下。
  </br>

Visualization via TensorBoard

---

若想可视化，你需要先安装 install tensorboard ，在你调用optimize()之前，对你的optimizer setTrainSummary() 和 setValidationSummary()：

val logdir = "mylogdir"
val appName = "myapp"
val trainSummary = TrainSummary(logdir, appName)
val talidationSummary = ValidationSummary(logdir, appName)
optimizer.setTrainSummary(trainSummary)
optimizer.setValidationSummary(validationSummary)

在运行你的spark job之后，训练和验证日志会被保存到"mylogdir/myapp/train" 和"mylogdir/myapp/validation"。注意：在开始新的job之前改一下appName，否则日志文件会冲突。

• TrainSummary默认每次迭代显示"Loss"和"Throughput"。你可以使用setSummaryTrigger()使每次迭代显示"LearningRate"和"Parameters"，或者更改"Loss"和"Throughput":

trainSummary.setSummaryTrigger("LearningRate", Trigger.severalIteration(1))
trainSummary.setSummaryTrigger("Parameters", Trigger.severalIteration(20))

注意："Parameters"显示模型中parameters和gradParameters的直方图。但是从worker中获取参数是一个非常大的开销，建议每10次迭代获取一次。为了可视化更形象可以给每层命名。

• ValidationSummary通过setvalidation()显示检验集优化的结果，像“Loss”和“top1Accuracy”。
• Summary提供了readScalar方法读取标签名称。从"Loss"中读取summary：

val trainLoss = trainSummary.readScalar("Loss")
val validationLoss = validationSummary.readScalar("Loss")

</br>
</br>
</br>
</br>
</br>
北京师范大学
图形图像与模式识别实验室
sibofeng@mail.bnu.edu.cn