Merge pull request #1 from PaddlePaddle/develop

update

01.fit_a_line/README.cn.md

@@ -37,6 +37,12 @@ $$MSE=\frac{1}{n}\sum_{i=1}^{n}{(\hat{Y_i}-Y_i)}^2$$
 
 即对于一个大小为$n$的测试集，$MSE$是$n$个数据预测结果误差平方的均值。
 
+对损失函数进行优化所采用的方法一般为梯度下降法。梯度下降法是一种一阶最优化算法。如果$f(x)$在点$x_n$有定义且可微，则认为$f(x)$在点$x_n$沿着梯度的负方向$-▽f(x_n)$下降的是最快的。反复调节$x$，使得$f(x)$接近最小值或者极小值，调节的方式为：
+
+$$x_n+1=x_n-λ▽f(x), n≧0$$
+
+其中λ代表学习率。这种调节的方法称为梯度下降法。
+
 ### 训练过程
 
 定义好模型结构之后，我们要通过以下几个步骤进行模型训练
@@ -131,30 +137,71 @@ test_reader = paddle.batch(
         batch_size=BATCH_SIZE)
 ```
 
+如果想直接从txt文件中读取数据的话，可以参考以下方式。
+
+feature_names = [
+    'CRIM', 'ZN', 'INDUS', 'CHAS', 'NOX', 'RM', 'AGE', 'DIS', 'RAD', 'TAX',
+    'PTRATIO', 'B', 'LSTAT', 'convert'
+]
+
+feature_num = len(feature_names)
+
+data = numpy.fromfile(filename, sep=' ') # 从文件中读取原始数据
+
+data = data.reshape(data.shape[0] // feature_num, feature_num)
+
+maximums, minimums, avgs = data.max(axis=0), data.min(axis=0), data.sum(axis=0)/data.shape[0]
+
+for i in six.moves.range(feature_num-1):
+ data[:, i] = (data[:, i] - avgs[i]) / (maximums[i] - minimums[i]) # six.moves可以兼容python2和python3
+
+ratio = 0.8 # 训练集和验证集的划分比例
+
+offset = int(data.shape[0]*ratio)
+
+train_data = data[:offset]
+
+test_data = data[offset:]
+
+train_reader = paddle.batch(
+    paddle.reader.shuffle(
+        train_data, buf_size=500),
+        batch_size=BATCH_SIZE)
+
+test_reader = paddle.batch(
+    paddle.reader.shuffle(
+        test_data, buf_size=500),
+        batch_size=BATCH_SIZE)
+
 ### 配置训练程序
 训练程序的目的是定义一个训练模型的网络结构。对于线性回归来讲，它就是一个从输入到输出的简单的全连接层。更加复杂的结果，比如卷积神经网络，递归神经网络等会在随后的章节中介绍。训练程序必须返回`平均损失`作为第一个返回值，因为它会被后面反向传播算法所用到。
 
 ```python
-x = fluid.layers.data(name='x', shape=[13], dtype='float32')
-y = fluid.layers.data(name='y', shape=[1], dtype='float32')
-y_predict = fluid.layers.fc(input=x, size=1, act=None)
+x = fluid.layers.data(name='x', shape=[13], dtype='float32') # 定义输入的形状和数据类型
+y = fluid.layers.data(name='y', shape=[1], dtype='float32') # 定义输出的形状和数据类型
+y_predict = fluid.layers.fc(input=x, size=1, act=None) # 连接输入和输出的全连接层
 
-main_program = fluid.default_main_program()
-startup_program = fluid.default_startup_program()
+main_program = fluid.default_main_program() # 获取默认/全局主函数
+startup_program = fluid.default_startup_program() # 获取默认/全局启动程序
 
-cost = fluid.layers.square_error_cost(input=y_predict, label=y)
-avg_loss = fluid.layers.mean(cost)
+cost = fluid.layers.square_error_cost(input=y_predict, label=y) # 利用标签数据和输出的预测数据估计方差
+avg_loss = fluid.layers.mean(cost) # 对方差求均值，得到平均损失
 ```
+详细资料请参考：
+[fluid.default_main_program](http://www.paddlepaddle.org/documentation/docs/zh/develop/api_cn/fluid_cn.html#default-main-program)
+[fluid.default_startup_program](http://www.paddlepaddle.org/documentation/docs/zh/develop/api_cn/fluid_cn.html#default-startup-program)
 
 ### Optimizer Function 配置
 
-在下面的 `SGD optimizer`，`learning_rate` 是训练的速度，与网络的训练收敛速度有关系。
+在下面的 `SGD optimizer`，`learning_rate` 是学习率，与网络的训练收敛速度有关系。
 
 ```python
 sgd_optimizer = fluid.optimizer.SGD(learning_rate=0.001)
 sgd_optimizer.minimize(avg_loss)
 
-#clone a test_program
+#克隆main_program得到test_program
+#有些operator在训练和测试之间的操作是不同的，例如batch_norm，使用参数for_test来区分该程序是用来训练还是用来测试
+#该api不会删除任何操作符,请在backward和optimization之前使用
 test_program = main_program.clone(for_test=True)
 ```
 
@@ -163,31 +210,21 @@ test_program = main_program.clone(for_test=True)
 
 ```python
 use_cuda = False
-place = fluid.CUDAPlace(0) if use_cuda else fluid.CPUPlace()
+place = fluid.CUDAPlace(0) if use_cuda else fluid.CPUPlace() # 指明executor的执行场所
 
+###executor可以接受传入的program，并根据feed map(输入映射表)和fetch list(结果获取表)向program中添加数据输入算子和结果获取算子。使用close()关闭该executor，调用run(...)执行program。
 exe = fluid.Executor(place)
 
 ```
-
-除此之外，还可以通过画图，来展现`训练进程`：
-
-```python
-# Plot data
-from paddle.utils.plot import Ploter
-
-train_prompt = "Train cost"
-test_prompt = "Test cost"
-plot_prompt = Ploter(train_prompt, test_prompt)
-
-```
+详细资料请参考:
+[fluid.executor](http://www.paddlepaddle.org/documentation/docs/zh/develop/api_cn/fluid_cn.html#permalink-15-executor)
 
 ### 创建训练过程
-训练需要有一个训练程序和一些必要参数，并构建了一个获取训练过程中测试误差的函数。
+训练需要有一个训练程序和一些必要参数，并构建了一个获取训练过程中测试误差的函数。必要参数有executor,program,reader,feeder,fetch_list，executor表示之前创建的执行器，program表示执行器所执行的program，是之前创建的program，如果该项参数没有给定的话则默认使用defalut_main_program，reader表示读取到的数据，feeder表示前向输入的变量，fetch_list表示用户想得到的变量或者命名的结果。
 
 ```python
 num_epochs = 100
 
-# For training test cost
 def train_test(executor, program, reader, feeder, fetch_list):
     accumulated = 1 * [0]
     count = 0
@@ -195,19 +232,36 @@ def train_test(executor, program, reader, feeder, fetch_list):
         outs = executor.run(program=program,
                             feed=feeder.feed(data_test),
                             fetch_list=fetch_list)
-        accumulated = [x_c[0] + x_c[1][0] for x_c in zip(accumulated, outs)]
-        count += 1
-    return [x_d / count for x_d in accumulated]
+        accumulated = [x_c[0] + x_c[1][0] for x_c in zip(accumulated, outs)] # 累加测试过程中的损失值
+        count += 1 # 累加测试集中的样本数量
+    return [x_d / count for x_d in accumulated] # 计算平均损失
+
+```
+可以直接输出损失值来观察`训练进程`:
+
+```python
+train_prompt = "train cost"
+test_prompt = "test cost"
+print("%s', out %f" % (train_prompt, out))
+print("%s', out %f" % (test_prompt, out))
+
+```
+
+除此之外，还可以通过画图，来展现`训练进程`：
+
+```python
+from paddle.utils.plot import ploter
+
+plot_prompt = ploter(train_prompt, test_prompt)
 
 ```
 
 ### 训练主循环
-PaddlePaddle提供了读取数据者发生器机制来读取训练数据。读取数据者会一次提供多列数据，因此我们需要一个Python的list来定义读取顺序。我们构建一个循环来进行训练，直到训练结果足够好或者循环次数足够多。
-如果训练顺利，可以把训练参数保存到`params_dirname`。
+
+给出需要存储的目录名，并初始化一个执行器。
 
 ```python
 %matplotlib inline
-# Specify the directory to save the parameters
 params_dirname = "fit_a_line.inference.model"
 feeder = fluid.DataFeeder(place=place, feed_list=[x, y])
 naive_exe = fluid.Executor(place)
@@ -215,17 +269,21 @@ naive_exe.run(startup_program)
 step = 0
 
 exe_test = fluid.Executor(place)
+```
 
-# main train loop.
+paddlepaddle提供了reader机制来读取训练数据。reader会一次提供多列数据，因此我们需要一个python的列表来定义读取顺序。我们构建一个循环来进行训练，直到训练结果足够好或者循环次数足够多。
+如果训练迭代次数满足参数保存的迭代次数，可以把训练参数保存到`params_dirname`。
+设置训练主循环
+```python
 for pass_id in range(num_epochs):
     for data_train in train_reader():
         avg_loss_value, = exe.run(main_program,
                                   feed=feeder.feed(data_train),
                                   fetch_list=[avg_loss])
-        if step % 10 == 0:  # record a train cost every 10 batches
+        if step % 10 == 0: # 每10个批次记录一下训练损失
             plot_prompt.append(train_prompt, step, avg_loss_value[0])
             plot_prompt.plot()
-        if step % 100 == 0:  # record a test cost every 100 batches
+        if step % 100 == 0:  # 每100批次记录一下测试损失
             test_metics = train_test(executor=exe_test,
                                      program=test_program,
                                      reader=test_reader,
@@ -233,18 +291,17 @@ for pass_id in range(num_epochs):
                                      feeder=feeder)
             plot_prompt.append(test_prompt, step, test_metics[0])
             plot_prompt.plot()
-            # If the accuracy is good enough, we can stop the training.
-            if test_metics[0] < 10.0:
+            if test_metics[0] < 10.0: # 如果准确率达到要求，则停止训练
                 break
 
         step += 1
 
         if math.isnan(float(avg_loss_value[0])):
             sys.exit("got NaN loss, training failed.")
-    if params_dirname is not None:
-        # We can save the trained parameters for the inferences later
-        fluid.io.save_inference_model(params_dirname, ['x'],
-                                      [y_predict], exe)
+
+        #保存训练参数到之前给定的路径中
+        if params_dirname is not None:
+            fluid.io.save_inference_model(params_dirname, ['x'], [y_predict], exe)
 ```
 
 ## 预测
@@ -264,30 +321,52 @@ inference_scope = fluid.core.Scope()
 ```python
 with fluid.scope_guard(inference_scope):
     [inference_program, feed_target_names,
-     fetch_targets] = fluid.io.load_inference_model(params_dirname, infer_exe)
+     fetch_targets] = fluid.io.load_inference_model(params_dirname, infer_exe) # 载入预训练模型
     batch_size = 10
 
     infer_reader = paddle.batch(
-        paddle.dataset.uci_housing.test(), batch_size=batch_size)
+        paddle.dataset.uci_housing.test(), batch_size=batch_size) # 准备测试集
 
     infer_data = next(infer_reader())
     infer_feat = numpy.array(
-        [data[0] for data in infer_data]).astype("float32")
+        [data[0] for data in infer_data]).astype("float32") # 提取测试集中的数据
     infer_label = numpy.array(
-        [data[1] for data in infer_data]).astype("float32")
+        [data[1] for data in infer_data]).astype("float32") # 提取测试集中的标签
 
     assert feed_target_names[0] == 'x'
     results = infer_exe.run(inference_program,
                             feed={feed_target_names[0]: numpy.array(infer_feat)},
-                            fetch_list=fetch_targets)
+                            fetch_list=fetch_targets) # 进行预测
+```
+
+保存图片
+```python
+def save_result(points1, points2):
+    import matplotlib
+    matplotlib.use('Agg')
+    import matplotlib.pyplot as plt
+    x1 = [idx for idx in range(len(points1))]
+    y1 = points1
+    y2 = points2
+    l1 = plt.plot(x1, y1, 'r--', label='predictions')
+    l2 = plt.plot(x1, y2, 'g--', label='GT')
+    plt.plot(x1, y1, 'ro-', x1, y2, 'g+-')
+    plt.title('predictions VS GT')
+    plt.legend()
+    plt.savefig('./image/prediction_gt.png')
+```
+
+打印预测结果和标签并可视化结果
+```python
+ print("infer results: (House Price)")
+ for idx, val in enumerate(results[0]):
+     print("%d: %.2f" % (idx, val)) # 打印预测结果
 
-    print("infer results: (House Price)")
-    for idx, val in enumerate(results[0]):
-        print("%d: %.2f" % (idx, val))
+ print("\nground truth:")
+ for idx, val in enumerate(infer_label):
+     print("%d: %.2f" % (idx, val)) # 打印标签值
 
-    print("\nground truth:")
-    for idx, val in enumerate(infer_label):
-        print("%d: %.2f" % (idx, val))
+save_result(results[0], infer_label) # 保存图片
 ```
 
 ## 总结

01.fit_a_line/index.cn.html

@@ -79,6 +79,12 @@ $$MSE=\frac{1}{n}\sum_{i=1}^{n}{(\hat{Y_i}-Y_i)}^2$$
 
 即对于一个大小为$n$的测试集，$MSE$是$n$个数据预测结果误差平方的均值。
 
+对损失函数进行优化所采用的方法一般为梯度下降法。梯度下降法是一种一阶最优化算法。如果$f(x)$在点$x_n$有定义且可微，则认为$f(x)$在点$x_n$沿着梯度的负方向$-▽f(x_n)$下降的是最快的。反复调节$x$，使得$f(x)$接近最小值或者极小值，调节的方式为：
+
+$$x_n+1=x_n-λ▽f(x), n≧0$$
+
+其中λ代表学习率。这种调节的方法称为梯度下降法。
+
 ### 训练过程
 
 定义好模型结构之后，我们要通过以下几个步骤进行模型训练
@@ -173,30 +179,71 @@ test_reader = paddle.batch(
         batch_size=BATCH_SIZE)
 ```
 
+如果想直接从txt文件中读取数据的话，可以参考以下方式。
+
+feature_names = [
+    'CRIM', 'ZN', 'INDUS', 'CHAS', 'NOX', 'RM', 'AGE', 'DIS', 'RAD', 'TAX',
+    'PTRATIO', 'B', 'LSTAT', 'convert'
+]
+
+feature_num = len(feature_names)
+
+data = numpy.fromfile(filename, sep=' ') # 从文件中读取原始数据
+
+data = data.reshape(data.shape[0] // feature_num, feature_num)
+
+maximums, minimums, avgs = data.max(axis=0), data.min(axis=0), data.sum(axis=0)/data.shape[0]
+
+for i in six.moves.range(feature_num-1):
+ data[:, i] = (data[:, i] - avgs[i]) / (maximums[i] - minimums[i]) # six.moves可以兼容python2和python3
+
+ratio = 0.8 # 训练集和验证集的划分比例
+
+offset = int(data.shape[0]*ratio)
+
+train_data = data[:offset]
+
+test_data = data[offset:]
+
+train_reader = paddle.batch(
+    paddle.reader.shuffle(
+        train_data, buf_size=500),
+        batch_size=BATCH_SIZE)
+
+test_reader = paddle.batch(
+    paddle.reader.shuffle(
+        test_data, buf_size=500),
+        batch_size=BATCH_SIZE)
+
 ### 配置训练程序
 训练程序的目的是定义一个训练模型的网络结构。对于线性回归来讲，它就是一个从输入到输出的简单的全连接层。更加复杂的结果，比如卷积神经网络，递归神经网络等会在随后的章节中介绍。训练程序必须返回`平均损失`作为第一个返回值，因为它会被后面反向传播算法所用到。
 
 ```python
-x = fluid.layers.data(name='x', shape=[13], dtype='float32')
-y = fluid.layers.data(name='y', shape=[1], dtype='float32')
-y_predict = fluid.layers.fc(input=x, size=1, act=None)
+x = fluid.layers.data(name='x', shape=[13], dtype='float32') # 定义输入的形状和数据类型
+y = fluid.layers.data(name='y', shape=[1], dtype='float32') # 定义输出的形状和数据类型
+y_predict = fluid.layers.fc(input=x, size=1, act=None) # 连接输入和输出的全连接层
 
-main_program = fluid.default_main_program()
-startup_program = fluid.default_startup_program()
+main_program = fluid.default_main_program() # 获取默认/全局主函数
+startup_program = fluid.default_startup_program() # 获取默认/全局启动程序
 
-cost = fluid.layers.square_error_cost(input=y_predict, label=y)
-avg_loss = fluid.layers.mean(cost)
+cost = fluid.layers.square_error_cost(input=y_predict, label=y) # 利用标签数据和输出的预测数据估计方差
+avg_loss = fluid.layers.mean(cost) # 对方差求均值，得到平均损失
 ```
+详细资料请参考：
+[fluid.default_main_program](http://www.paddlepaddle.org/documentation/docs/zh/develop/api_cn/fluid_cn.html#default-main-program)
+[fluid.default_startup_program](http://www.paddlepaddle.org/documentation/docs/zh/develop/api_cn/fluid_cn.html#default-startup-program)
 
 ### Optimizer Function 配置
 
-在下面的 `SGD optimizer`，`learning_rate` 是训练的速度，与网络的训练收敛速度有关系。
+在下面的 `SGD optimizer`，`learning_rate` 是学习率，与网络的训练收敛速度有关系。
 
 ```python
 sgd_optimizer = fluid.optimizer.SGD(learning_rate=0.001)
 sgd_optimizer.minimize(avg_loss)
 
-#clone a test_program
+#克隆main_program得到test_program
+#有些operator在训练和测试之间的操作是不同的，例如batch_norm，使用参数for_test来区分该程序是用来训练还是用来测试
+#该api不会删除任何操作符,请在backward和optimization之前使用
 test_program = main_program.clone(for_test=True)
 ```
 
@@ -205,31 +252,21 @@ test_program = main_program.clone(for_test=True)
 
 ```python
 use_cuda = False
-place = fluid.CUDAPlace(0) if use_cuda else fluid.CPUPlace()
+place = fluid.CUDAPlace(0) if use_cuda else fluid.CPUPlace() # 指明executor的执行场所
 
+###executor可以接受传入的program，并根据feed map(输入映射表)和fetch list(结果获取表)向program中添加数据输入算子和结果获取算子。使用close()关闭该executor，调用run(...)执行program。
 exe = fluid.Executor(place)
 
 ```
-
-除此之外，还可以通过画图，来展现`训练进程`：
-
-```python
-# Plot data
-from paddle.utils.plot import Ploter
-
-train_prompt = "Train cost"
-test_prompt = "Test cost"
-plot_prompt = Ploter(train_prompt, test_prompt)
-
-```
+详细资料请参考:
+[fluid.executor](http://www.paddlepaddle.org/documentation/docs/zh/develop/api_cn/fluid_cn.html#permalink-15-executor)
 
 ### 创建训练过程
-训练需要有一个训练程序和一些必要参数，并构建了一个获取训练过程中测试误差的函数。
+训练需要有一个训练程序和一些必要参数，并构建了一个获取训练过程中测试误差的函数。必要参数有executor,program,reader,feeder,fetch_list，executor表示之前创建的执行器，program表示执行器所执行的program，是之前创建的program，如果该项参数没有给定的话则默认使用defalut_main_program，reader表示读取到的数据，feeder表示前向输入的变量，fetch_list表示用户想得到的变量或者命名的结果。
 
 ```python
 num_epochs = 100
 
-# For training test cost
 def train_test(executor, program, reader, feeder, fetch_list):
     accumulated = 1 * [0]
     count = 0
@@ -237,19 +274,36 @@ def train_test(executor, program, reader, feeder, fetch_list):
         outs = executor.run(program=program,
                             feed=feeder.feed(data_test),
                             fetch_list=fetch_list)
-        accumulated = [x_c[0] + x_c[1][0] for x_c in zip(accumulated, outs)]
-        count += 1
-    return [x_d / count for x_d in accumulated]
+        accumulated = [x_c[0] + x_c[1][0] for x_c in zip(accumulated, outs)] # 累加测试过程中的损失值
+        count += 1 # 累加测试集中的样本数量
+    return [x_d / count for x_d in accumulated] # 计算平均损失
+
+```
+可以直接输出损失值来观察`训练进程`:
+
+```python
+train_prompt = "train cost"
+test_prompt = "test cost"
+print("%s', out %f" % (train_prompt, out))
+print("%s', out %f" % (test_prompt, out))
+
+```
+
+除此之外，还可以通过画图，来展现`训练进程`：
+
+```python
+from paddle.utils.plot import ploter
+
+plot_prompt = ploter(train_prompt, test_prompt)
 
 ```
 
 ### 训练主循环
-PaddlePaddle提供了读取数据者发生器机制来读取训练数据。读取数据者会一次提供多列数据，因此我们需要一个Python的list来定义读取顺序。我们构建一个循环来进行训练，直到训练结果足够好或者循环次数足够多。
-如果训练顺利，可以把训练参数保存到`params_dirname`。
+
+给出需要存储的目录名，并初始化一个执行器。
 
 ```python
 %matplotlib inline
-# Specify the directory to save the parameters
 params_dirname = "fit_a_line.inference.model"
 feeder = fluid.DataFeeder(place=place, feed_list=[x, y])
 naive_exe = fluid.Executor(place)
@@ -257,17 +311,21 @@ naive_exe.run(startup_program)
 step = 0
 
 exe_test = fluid.Executor(place)
+```
 
-# main train loop.
+paddlepaddle提供了reader机制来读取训练数据。reader会一次提供多列数据，因此我们需要一个python的列表来定义读取顺序。我们构建一个循环来进行训练，直到训练结果足够好或者循环次数足够多。
+如果训练迭代次数满足参数保存的迭代次数，可以把训练参数保存到`params_dirname`。
+设置训练主循环
+```python
 for pass_id in range(num_epochs):
     for data_train in train_reader():
         avg_loss_value, = exe.run(main_program,
                                   feed=feeder.feed(data_train),
                                   fetch_list=[avg_loss])
-        if step % 10 == 0:  # record a train cost every 10 batches
+        if step % 10 == 0: # 每10个批次记录一下训练损失
             plot_prompt.append(train_prompt, step, avg_loss_value[0])
             plot_prompt.plot()
-        if step % 100 == 0:  # record a test cost every 100 batches
+        if step % 100 == 0:  # 每100批次记录一下测试损失
             test_metics = train_test(executor=exe_test,
                                      program=test_program,
                                      reader=test_reader,
@@ -275,18 +333,17 @@ for pass_id in range(num_epochs):
                                      feeder=feeder)
             plot_prompt.append(test_prompt, step, test_metics[0])
             plot_prompt.plot()
-            # If the accuracy is good enough, we can stop the training.
-            if test_metics[0] < 10.0:
+            if test_metics[0] < 10.0: # 如果准确率达到要求，则停止训练
                 break
 
         step += 1
 
         if math.isnan(float(avg_loss_value[0])):
             sys.exit("got NaN loss, training failed.")
-    if params_dirname is not None:
-        # We can save the trained parameters for the inferences later
-        fluid.io.save_inference_model(params_dirname, ['x'],
-                                      [y_predict], exe)
+
+        #保存训练参数到之前给定的路径中
+        if params_dirname is not None:
+            fluid.io.save_inference_model(params_dirname, ['x'], [y_predict], exe)
 ```
 
 ## 预测
@@ -306,30 +363,52 @@ inference_scope = fluid.core.Scope()
 ```python
 with fluid.scope_guard(inference_scope):
     [inference_program, feed_target_names,
-     fetch_targets] = fluid.io.load_inference_model(params_dirname, infer_exe)
+     fetch_targets] = fluid.io.load_inference_model(params_dirname, infer_exe) # 载入预训练模型
     batch_size = 10
 
     infer_reader = paddle.batch(
-        paddle.dataset.uci_housing.test(), batch_size=batch_size)
+        paddle.dataset.uci_housing.test(), batch_size=batch_size) # 准备测试集
 
     infer_data = next(infer_reader())
     infer_feat = numpy.array(
-        [data[0] for data in infer_data]).astype("float32")
+        [data[0] for data in infer_data]).astype("float32") # 提取测试集中的数据
     infer_label = numpy.array(
-        [data[1] for data in infer_data]).astype("float32")
+        [data[1] for data in infer_data]).astype("float32") # 提取测试集中的标签
 
     assert feed_target_names[0] == 'x'
     results = infer_exe.run(inference_program,
                             feed={feed_target_names[0]: numpy.array(infer_feat)},
-                            fetch_list=fetch_targets)
+                            fetch_list=fetch_targets) # 进行预测
+```
+
+保存图片
+```python
+def save_result(points1, points2):
+    import matplotlib
+    matplotlib.use('Agg')
+    import matplotlib.pyplot as plt
+    x1 = [idx for idx in range(len(points1))]
+    y1 = points1
+    y2 = points2
+    l1 = plt.plot(x1, y1, 'r--', label='predictions')
+    l2 = plt.plot(x1, y2, 'g--', label='GT')
+    plt.plot(x1, y1, 'ro-', x1, y2, 'g+-')
+    plt.title('predictions VS GT')
+    plt.legend()
+    plt.savefig('./image/prediction_gt.png')
+```
+
+打印预测结果和标签并可视化结果
+```python
+ print("infer results: (House Price)")
+ for idx, val in enumerate(results[0]):
+     print("%d: %.2f" % (idx, val)) # 打印预测结果
 
-    print("infer results: (House Price)")
-    for idx, val in enumerate(results[0]):
-        print("%d: %.2f" % (idx, val))
+ print("\nground truth:")
+ for idx, val in enumerate(infer_label):
+     print("%d: %.2f" % (idx, val)) # 打印标签值
 
-    print("\nground truth:")
-    for idx, val in enumerate(infer_label):
-        print("%d: %.2f" % (idx, val))
+save_result(results[0], infer_label) # 保存图片
 ```
 
 ## 总结

01.fit_a_line/train.py

@@ -33,6 +33,21 @@ def train_test(executor, program, reader, feeder, fetch_list):
     return [x_d / count for x_d in accumulated]
 
 
+def save_result(points1, points2):
+    import matplotlib
+    matplotlib.use('Agg')
+    import matplotlib.pyplot as plt
+    x1 = [idx for idx in range(len(points1))]
+    y1 = points1
+    y2 = points2
+    l1 = plt.plot(x1, y1, 'r--', label='predictions')
+    l2 = plt.plot(x1, y2, 'g--', label='GT')
+    plt.plot(x1, y1, 'ro-', x1, y2, 'g+-')
+    plt.title('predictions VS GT')
+    plt.legend()
+    plt.savefig('./image/prediction_gt.png')
+
+
 def main():
     batch_size = 20
     train_reader = paddle.batch(
@@ -141,6 +156,8 @@ def main():
         for idx, val in enumerate(infer_label):
             print("%d: %.2f" % (idx, val))
 
+        save_result(results[0], infer_label)
+
 
 if __name__ == '__main__':
     main()

02.recognize_digits/README.cn.md

-# 识别数字
+# 数字识别
 
 本教程源代码目录在[book/recognize_digits](https://github.com/PaddlePaddle/book/tree/develop/02.recognize_digits),初次使用请您参考[Book文档使用说明](https://github.com/PaddlePaddle/book/blob/develop/README.cn.md#运行这本书)。
 
@@ -12,26 +12,28 @@
 
 MNIST数据集是从 [NIST](https://www.nist.gov/srd/nist-special-database-19) 的Special Database 3（SD-3）和Special Database 1（SD-1）构建而来。由于SD-3是由美国人口调查局的员工进行标注，SD-1是由美国高中生进行标注，因此SD-3比SD-1更干净也更容易识别。Yann LeCun等人从SD-1和SD-3中各取一半作为MNIST的训练集（60000条数据）和测试集（10000条数据），其中训练集来自250位不同的标注员，此外还保证了训练集和测试集的标注员是不完全相同的。
 
-Yann LeCun早先在手写字符识别上做了很多研究，并在研究过程中提出了卷积神经网络（Convolutional Neural Network），大幅度地提高了手写字符的识别能力，也因此成为了深度学习领域的奠基人之一。如今的深度学习领域，卷积神经网络占据了至关重要的地位，从最早Yann LeCun提出的简单LeNet，到如今ImageNet大赛上的优胜模型VGGNet、GoogLeNet、ResNet等（请参见[图像分类](https://github.com/PaddlePaddle/book/tree/develop/03.image_classification) 教程），人们在图像分类领域，利用卷积神经网络得到了一系列惊人的结果。
+MNIST吸引了大量的科学家基于此数据集训练模型，1998年，LeCun分别用单层线性分类器、多层感知器（Multilayer Perceptron, MLP）和多层卷积神经网络LeNet进行实验，使得测试集上的误差不断下降（从12%下降到0.7%）\[[1](#参考文献)\]。在研究过程中，LeCun提出了卷积神经网络（Convolutional Neural Network），大幅度地提高了手写字符的识别能力，也因此成为了深度学习领域的奠基人之一。此后，科学家们又基于K近邻（K-Nearest Neighbors）算法\[[2](#参考文献)\]、支持向量机（SVM）\[[3](#参考文献)\]、神经网络\[[4-7](#参考文献)\]和Boosting方法\[[8](#参考文献)\]等做了大量实验，并采用多种预处理方法（如去除歪曲、去噪、模糊等）来提高识别的准确率。
 
-有很多算法在MNIST上进行实验。1998年，LeCun分别用单层线性分类器、多层感知器（Multilayer Perceptron, MLP）和多层卷积神经网络LeNet进行实验，使得测试集上的误差不断下降（从12%下降到0.7%）\[[1](#参考文献)\]。此后，科学家们又基于K近邻（K-Nearest Neighbors）算法\[[2](#参考文献)\]、支持向量机（SVM）\[[3](#参考文献)\]、神经网络\[[4-7](#参考文献)\]和Boosting方法\[[8](#参考文献)\]等做了大量实验，并采用多种预处理方法（如去除歪曲、去噪、模糊等）来提高识别的准确率。
+如今的深度学习领域，卷积神经网络占据了至关重要的地位，从最早Yann LeCun提出的简单LeNet，到如今ImageNet大赛上的优胜模型VGGNet、GoogLeNet、ResNet等（请参见[图像分类](https://github.com/PaddlePaddle/book/tree/develop/03.image_classification) 教程），人们在图像分类领域，利用卷积神经网络得到了一系列惊人的结果。
 
-本教程中，我们从简单的模型Softmax回归开始，带大家入门手写字符识别，并逐步进行模型优化。
+
+
+本教程中，我们从简单的Softmax回归模型开始，带大家了解手写字符识别，并向大家介绍如何改进模型，利用多层感知机（MLP）和卷积神经网络（CNN）优化识别效果。
 
 
 ## 模型概览
 
-基于MNIST数据训练一个分类器，在介绍本教程使用的三个基本图像分类网络前，我们先给出一些定义：
+基于MNIST数据集训练一个分类器，在介绍本教程使用的三个基本图像分类网络前，我们先给出一些定义：
 
 - $X$是输入：MNIST图片是$28\times28$ 的二维图像，为了进行计算，我们将其转化为$784$维向量，即$X=\left ( x_0, x_1, \dots, x_{783} \right )$。
 
 - $Y$是输出：分类器的输出是10类数字（0-9），即$Y=\left ( y_0, y_1, \dots, y_9 \right )$，每一维$y_i$代表图片分类为第$i$类数字的概率。
 
-- $L$是图片的真实标签：$L=\left ( l_0, l_1, \dots, l_9 \right )$也是10维，但只有一维为1，其他都为0。
+- $Label$是图片的真实标签：$Label=\left ( l_0, l_1, \dots, l_9 \right )$也是10维，但只有一维为1，其他都为0。例如某张图片上的数字为2，则它的标签为$(0,0,1,0, \dot, 0)$
 
 ### Softmax回归(Softmax Regression)
 
-最简单的Softmax回归模型是先将输入层经过一个全连接层得到的特征，然后直接通过softmax 函数进行多分类\[[9](#参考文献)\]。
+最简单的Softmax回归模型是先将输入层经过一个全连接层得到特征，然后直接通过 softmax 函数计算多个类别的概率并输出\[[9](#参考文献)\]。
 
 输入层的数据$X$传到输出层，在激活操作之前，会乘以相应的权重 $W$ ，并加上偏置变量 $b$ ，具体如下：
 
@@ -39,24 +41,26 @@ $$ y_i = \text{softmax}(\sum_j W_{i,j}x_j + b_i) $$
 
 其中 $ \text{softmax}(x_i) = \frac{e^{x_i}}{\sum_j e^{x_j}} $
 
+图2为softmax回归的网络图，图中权重用蓝线表示、偏置用红线表示、+1代表偏置参数的系数为1。
+
+<p align="center">
+<img src="https://github.com/PaddlePaddle/book/blob/develop/02.recognize_digits/image/softmax_regression.png?raw=true" width=400><br/>
+图2. softmax回归网络结构图<br/>
+</p>
+
 对于有 $N$ 个类别的多分类问题，指定 $N$ 个输出节点，$N$ 维结果向量经过softmax将归一化为 $N$ 个[0,1]范围内的实数值，分别表示该样本属于这 $N$ 个类别的概率。此处的 $y_i$ 即对应该图片为数字 $i$ 的预测概率。
 
 在分类问题中，我们一般采用交叉熵代价损失函数（cross entropy loss），公式如下：
 
 $$  L_{cross-entropy}(label, y) = -\sum_i label_ilog(y_i) $$
 
-图2为softmax回归的网络图，图中权重用蓝线表示、偏置用红线表示、+1代表偏置参数的系数为1。
 
-<p align="center">
-<img src="https://github.com/PaddlePaddle/book/blob/develop/02.recognize_digits/image/softmax_regression.png?raw=true" width=400><br/>
-图2. softmax回归网络结构图<br/>
-</p>
 
-### 多层感知器(Multilayer Perceptron, MLP)
+### 多层感知机(Multilayer Perceptron, MLP)
 
 Softmax回归模型采用了最简单的两层神经网络，即只有输入层和输出层，因此其拟合能力有限。为了达到更好的识别效果，我们考虑在输入层和输出层中间加上若干个隐藏层\[[10](#参考文献)\]。
 
-1.  经过第一个隐藏层，可以得到 $ H_1 = \phi(W_1X + b_1) $，其中$\phi$代表激活函数，常见的有sigmoid、tanh或ReLU等函数。
+1.  经过第一个隐藏层，可以得到 $ H_1 = \phi(W_1X + b_1) $，其中$\phi$代表激活函数，常见的有[sigmoid、tanh或ReLU](#常见激活函数介绍)等函数。
 2.  经过第二个隐藏层，可以得到 $ H_2 = \phi(W_2H_1 + b_2) $。
 3.  最后，再经过输出层，得到的$Y=\text{softmax}(W_3H_2 + b_3)$，即为最后的分类结果向量。
 
@@ -73,7 +77,7 @@ Softmax回归模型采用了最简单的两层神经网络，即只有输入层
 在多层感知器模型中，将图像展开成一维向量输入到网络中，忽略了图像的位置和结构信息，而卷积神经网络能够更好的利用图像的结构信息。[LeNet-5](http://yann.lecun.com/exdb/lenet/)是一个较简单的卷积神经网络。图4显示了其结构：输入的二维图像，先经过两次卷积层到池化层，再经过全连接层，最后使用softmax分类作为输出层。下面我们主要介绍卷积层和池化层。
 
 <p align="center">
-<img src="https://github.com/PaddlePaddle/book/blob/develop/02.recognize_digits/image/cnn.png?raw=true" width="400"><br/>
+<img src="https://github.com/PaddlePaddle/book/blob/develop/02.recognize_digits/image/cnn.png?raw=true" width="600"><br/>
 图4. LeNet-5卷积神经网络结构<br/>
 </p>
 
@@ -86,7 +90,9 @@ Softmax回归模型采用了最简单的两层神经网络，即只有输入层
 图5. 卷积层图片<br/>
 </p>
 
-图5给出一个卷积计算过程的示例图，输入图像大小为$H=5,W=5,D=3$，即$5 \times 5$大小的3通道（RGB，也称作深度）彩色图像。这个示例图中包含两（用$K$表示）组卷积核，即图中滤波器$W_0$和$W_1$。在卷积计算中，通常对不同的输入通道采用不同的卷积核，如图示例中每组卷积核包含（$D=3）$个$3 \times 3$（用$F \times F$表示）大小的卷积核。另外，这个示例中卷积核在图像的水平方向（$W$方向）和垂直方向（$H$方向）的滑动步长为2（用$S$表示）；对输入图像周围各填充1（用$P$表示）个0，即图中输入层原始数据为蓝色部分，灰色部分是进行了大小为1的扩展，用0来进行扩展。经过卷积操作得到输出为$3 \times 3 \times 2$（用$H_{o} \times W_{o} \times K$表示）大小的特征图，即$3 \times 3$大小的2通道特征图，其中$H_o$计算公式为：$H_o = (H - F + 2 \times P)/S + 1$，$W_o$同理。 而输出特征图中的每个像素，是每组滤波器与输入图像每个特征图的内积再求和，再加上偏置$b_o$，偏置通常对于每个输出特征图是共享的。输出特征图$o[:,:,0]$中的最后一个$-2$计算如图5右下角公式所示。
+图5给出一个卷积计算过程的示例图，输入图像大小为$H=5,W=5,D=3$，即$5 \times 5$大小的3通道（RGB，也称作深度）彩色图像。
+
+这个示例图中包含两（用$K$表示）组卷积核，即图中$Filter W_0$ 和 $Filter W_1$。在卷积计算中，通常对不同的输入通道采用不同的卷积核，如图示例中每组卷积核包含（$D=3）$个$3 \times 3$（用$F \times F$表示）大小的卷积核。另外，这个示例中卷积核在图像的水平方向（$W$方向）和垂直方向（$H$方向）的滑动步长为2（用$S$表示）；对输入图像周围各填充1（用$P$表示）个0，即图中输入层原始数据为蓝色部分，灰色部分是进行了大小为1的扩展，用0来进行扩展。经过卷积操作得到输出为$3 \times 3 \times 2$（用$H_{o} \times W_{o} \times K$表示）大小的特征图，即$3 \times 3$大小的2通道特征图，其中$H_o$计算公式为：$H_o = (H - F + 2 \times P)/S + 1$，$W_o$同理。 而输出特征图中的每个像素，是每组滤波器与输入图像每个特征图的内积再求和，再加上偏置$b_o$，偏置通常对于每个输出特征图是共享的。输出特征图$o[:,:,0]$中的最后一个$-2$计算如图5右下角公式所示。
 
 在卷积操作中卷积核是可学习的参数，经过上面示例介绍，每层卷积的参数大小为$D \times F \times F \times K$。在多层感知器模型中，神经元通常是全部连接，参数较多。而卷积层的参数较少，这也是由卷积层的主要特性即局部连接和共享权重所决定。
 
@@ -96,6 +102,8 @@ Softmax回归模型采用了最简单的两层神经网络，即只有输入层
 
 通过介绍卷积计算过程及其特性，可以看出卷积是线性操作，并具有平移不变性（shift-invariant），平移不变性即在图像每个位置执行相同的操作。卷积层的局部连接和权重共享使得需要学习的参数大大减小，这样也有利于训练较大卷积神经网络。
 
+关于卷积的更多内容可[参考阅读](http://ufldl.stanford.edu/wiki/index.php/Feature_extraction_using_convolution#Convolutions)。
+
 #### 池化层
 
 <p align="center">
@@ -105,8 +113,9 @@ Softmax回归模型采用了最简单的两层神经网络，即只有输入层
 
 池化是非线性下采样的一种形式，主要作用是通过减少网络的参数来减小计算量，并且能够在一定程度上控制过拟合。通常在卷积层的后面会加上一个池化层。池化包括最大池化、平均池化等。其中最大池化是用不重叠的矩形框将输入层分成不同的区域，对于每个矩形框的数取最大值作为输出层，如图6所示。
 
-更详细的关于卷积神经网络的具体知识可以参考[斯坦福大学公开课]( http://cs231n.github.io/convolutional-networks/ )和[图像分类]( https://github.com/PaddlePaddle/book/tree/develop/03.image_classification )教程。
+更详细的关于卷积神经网络的具体知识可以参考[斯坦福大学公开课]( http://cs231n.github.io/convolutional-networks/ )、[Ufldl](http://ufldl.stanford.edu/wiki/index.php/Pooling) 和 [图像分类]( https://github.com/PaddlePaddle/book/tree/develop/03.image_classification )教程。
 
+<a name="常见激活函数介绍"></a>
 ### 常见激活函数介绍  
 - sigmoid激活函数： $ f(x) = sigmoid(x) = \frac{1}{1+e^{-x}} $
 
@@ -132,50 +141,53 @@ PaddlePaddle在API中提供了自动加载[MNIST](http://yann.lecun.com/exdb/mni
 
 ## Fluid API 概述
 
-演示将使用最新的 `Fluid API`。Fluid API是最新的 PaddlePaddle API。它在不牺牲性能的情况下简化了模型配置。
-我们建议使用 Fluid API，因为它更容易学起来。
+演示将使用最新的 [Fluid API](http://paddlepaddle.org/documentation/docs/zh/1.2/api_cn/index_cn.html)。Fluid API是最新的 PaddlePaddle API。它在不牺牲性能的情况下简化了模型配置。
+我们建议使用 Fluid API，它易学易用的特性将帮助您快速完成机器学习任务。。
 
-下面是快速的 Fluid API 概述。
+下面是 Fluid API 中几个重要概念的概述：
 
-1. `inference_program`：指定如何从数据输入中获得预测的函数。
+1. `inference_program`：指定如何从数据输入中获得预测的函数，
 这是指定网络流的地方。
 
-2. `train_program`：指定如何从 `inference_program` 和`标签值`中获取 `loss` 的函数。
+2. `train_program`：指定如何从 `inference_program` 和`标签值`中获取 `loss` 的函数，
 这是指定损失计算的地方。
 
-3. `optimizer_func`: “指定优化器配置的函数。优化器负责减少损失并驱动培训。Paddle 支持多种不同的优化器。
-
-4. `Trainer`：PaddlePaddle Trainer 管理由 `train_program` 和 `optimizer` 指定的训练过程。
-通过 `event_handler` 回调函数，用户可以监控培训的进展。
-
-5. `Inferencer`：Fluid inferencer 加载 `inference_program` 和由 Trainer 训练的参数。
-然后，它可以推断数据和返回预测。
+3. `optimizer_func`: 指定优化器配置的函数，优化器负责减少损失并驱动训练，Paddle 支持多种不同的优化器。
 
-在这个演示中，我们将深入了解它们。
+在下面的代码示例中，我们将深入了解它们。
 
 ## 配置说明
 加载 PaddlePaddle 的 Fluid API 包。
 
 ```python
 import os
-from PIL import Image
+from PIL import Image # 导入图像处理模块
+import matplotlib.pyplot as plt
 import numpy
-import paddle
+import paddle # 导入paddle模块
 import paddle.fluid as fluid
-from __future__ import print_function
+from __future__ import print_function # 将python3中的print特性导入当前版本
 ```
 
 ### Program Functions 配置
 
-我们需要设置“推理程序”函数。我们想用这个程序来演示三个不同的分类器，每个分类器都定义为 Python 函数。
-我们需要将图像数据馈送到分类器。Paddle 为读取数据提供了一个特殊的层 `layer.data` 层。
+我们需要设置 `inference_program` 函数。我们想用这个程序来演示三个不同的分类器，每个分类器都定义为 Python 函数。
+我们需要将图像数据输入到分类器中。Paddle 为读取数据提供了一个特殊的层 `layer.data` 层。
 让我们创建一个数据层来读取图像并将其连接到分类网络。
 
 - Softmax回归：只通过一层简单的以softmax为激活函数的全连接层，就可以得到分类的结果。
 
 ```python
 def softmax_regression():
+    """
+    定义softmax分类器：
+        一个以softmax为激活函数的全连接层
+    Return:
+        predict_image -- 分类的结果
+    """
+    # 输入的原始图像数据，大小为28*28*1
     img = fluid.layers.data(name='img', shape=[1, 28, 28], dtype='float32')
+    # 以softmax为激活函数的全连接层，输出层的大小必须为数字的个数10
     predict = fluid.layers.fc(
         input=img, size=10, act='softmax')
     return predict
@@ -185,6 +197,15 @@ def softmax_regression():
 
 ```python
 def multilayer_perceptron():
+    """
+    定义多层感知机分类器：
+        含有两个隐藏层（全连接层）的多层感知器
+        其中前两个隐藏层的激活函数采用 ReLU，输出层的激活函数用 Softmax
+
+    Return:
+        predict_image -- 分类的结果
+    """
+    # 输入的原始图像数据，大小为28*28*1
     img = fluid.layers.data(name='img', shape=[1, 28, 28], dtype='float32')
     # 第一个全连接层，激活函数为ReLU
     hidden = fluid.layers.fc(input=img, size=200, act='relu')
@@ -199,8 +220,17 @@ def multilayer_perceptron():
 
 ```python
 def convolutional_neural_network():
+    """
+    定义卷积神经网络分类器：
+        输入的二维图像，经过两个卷积-池化层，使用以softmax为激活函数的全连接层作为输出层
+
+    Return:
+        predict -- 分类的结果
+    """
+    # 输入的原始图像数据，大小为28*28*1
     img = fluid.layers.data(name='img', shape=[1, 28, 28], dtype='float32')
     # 第一个卷积-池化层
+    # 使用20个5*5的滤波器，池化大小为2，池化步长为2，激活函数为Relu
     conv_pool_1 = fluid.nets.simple_img_conv_pool(
         input=img,
         filter_size=5,
@@ -210,6 +240,7 @@ def convolutional_neural_network():
         act="relu")
     conv_pool_1 = fluid.layers.batch_norm(conv_pool_1)
     # 第二个卷积-池化层
+    # 使用20个5*5的滤波器，池化大小为2，池化步长为2，激活函数为Relu
     conv_pool_2 = fluid.nets.simple_img_conv_pool(
         input=conv_pool_1,
         filter_size=5,
@@ -232,13 +263,27 @@ def convolutional_neural_network():
 
 ```python
 def train_program():
+    """
+    配置train_program
+
+    Return:
+        predict -- 分类的结果
+        avg_cost -- 平均损失
+        acc -- 分类的准确率
+
+    """
+    # 标签层，名称为label,对应输入图片的类别标签
     label = fluid.layers.data(name='label', shape=[1], dtype='int64')
 
-    # predict = softmax_regression() # uncomment for Softmax回归
-    # predict = multilayer_perceptron() # uncomment for 多层感知器
-    predict = convolutional_neural_network() # uncomment for LeNet5卷积神经网络
+    # predict = softmax_regression() # 取消注释将使用 Softmax回归
+    # predict = multilayer_perceptron() # 取消注释将使用 多层感知器
+    predict = convolutional_neural_network() # 取消注释将使用 LeNet5卷积神经网络
+
+    # 使用类交叉熵函数计算predict和label之间的损失函数
     cost = fluid.layers.cross_entropy(input=predict, label=label)
+    # 计算平均损失
     avg_cost = fluid.layers.mean(cost)
+    # 计算分类准确率
     acc = fluid.layers.accuracy(input=predict, label=label)
     return predict, [avg_cost, acc]
 
@@ -246,7 +291,7 @@ def train_program():
 
 #### Optimizer Function 配置
 
-在下面的 `Adam optimizer`，`learning_rate` 是训练的速度，与网络的训练收敛速度有关系。
+在下面的 `Adam optimizer`，`learning_rate` 是学习率，它的大小与网络的训练收敛速度有关系。
 
 ```python
 def optimizer_program():
@@ -262,43 +307,45 @@ def optimizer_program():
 `batch`是一个特殊的decorator，它的输入是一个reader，输出是一个batched reader。在PaddlePaddle里，一个reader每次yield一条训练数据，而一个batched reader每次yield一个minibatch。
 
 ```python
-
+# 一个minibatch中有64个数据
 BATCH_SIZE = 64
 
+# 每次读取训练集中的500个数据并随机打乱，传入batched reader中，batched reader 每次 yield 64个数据
 train_reader = paddle.batch(
         paddle.reader.shuffle(
             paddle.dataset.mnist.train(), buf_size=500),
         batch_size=BATCH_SIZE)
-
+# 读取测试集的数据，每次 yield 64个数据
 test_reader = paddle.batch(
             paddle.dataset.mnist.test(), batch_size=BATCH_SIZE)
 ```
 
-### Trainer 训练过程
+### 构建训练过程
 
-现在，我们需要构建一个训练过程。将使用到前面定义的训练程序 `train_program`, `place` 和优化器 `optimizer`，并包含训练迭代、检查训练期间测试误差以及保存所需要用来预测的模型参数。
+现在，我们需要构建一个训练过程。将使用到前面定义的训练程序 `train_program`, `place` 和优化器 `optimizer`,并包含训练迭代、检查训练期间测试误差以及保存所需要用来预测的模型参数。
 
 
 #### Event Handler 配置
 
-我们可以在训练期间通过调用一个handler函数来监控培训进度。
-我们将在这里演示两个 `event_handler` 程序。请随意修改 Jupyter 笔记本 ，看看有什么不同。
+我们可以在训练期间通过调用一个handler函数来监控训练进度。
+我们将在这里演示两个 `event_handler` 程序。请随意修改 Jupyter Notebook ，看看有什么不同。
 
 `event_handler` 用来在训练过程中输出训练结果
 
 ```python
 def event_handler(pass_id, batch_id, cost):
+    # 打印训练的中间结果，训练轮次，batch数，损失函数
     print("Pass %d, Batch %d, Cost %f" % (pass_id,batch_id, cost))
 ```
 
 ```python
-from paddle.v2.plot import Ploter
+from paddle.utils.plot import Ploter
 
 train_prompt = "Train cost"
 test_prompt = "Test cost"
 cost_ploter = Ploter(train_prompt, test_prompt)
 
-# event_handler to plot a figure
+# 将训练过程绘图表示
 def event_handler_plot(ploter_title, step, cost):
     cost_ploter.append(ploter_title, step, cost)
     cost_ploter.plot()
@@ -316,31 +363,49 @@ def event_handler_plot(ploter_title, step, cost):
 `feed_order` 用于将数据目录映射到 `train_program`
 创建一个反馈训练过程中误差的`train_test`
 
-训练完成后，模型参数存入`save_dirname`中
+定义网络结构：
 
 ```python
 # 该模型运行在单个CPU上
-use_cuda = False # set to True if training with GPU
+use_cuda = False # 如想使用GPU，请设置为 True
 place = fluid.CUDAPlace(0) if use_cuda else fluid.CPUPlace()
 
+# 调用train_program 获取预测值，损失值，
 prediction, [avg_loss, acc] = train_program()
 
+# 输入的原始图像数据，大小为28*28*1
 img = fluid.layers.data(name='img', shape=[1, 28, 28], dtype='float32')
+# 标签层，名称为label,对应输入图片的类别标签
 label = fluid.layers.data(name='label', shape=[1], dtype='int64')
+# 告知网络传入的数据分为两部分，第一部分是img值，第二部分是label值
 feeder = fluid.DataFeeder(feed_list=[img, label], place=place)
 
+# 选择Adam优化器
 optimizer = fluid.optimizer.Adam(learning_rate=0.001)
 optimizer.minimize(avg_loss)
+```
+
+设置训练过程的超参：
+
+```python
 
-PASS_NUM = 5
+PASS_NUM = 5 #训练5轮
 epochs = [epoch_id for epoch_id in range(PASS_NUM)]
 
+# 将模型参数存储在名为 save_dirname 的文件中
 save_dirname = "recognize_digits.inference.model"
+```
+
 
+```python
 def train_test(train_test_program,
                    train_test_feed, train_test_reader):
+
+    # 将分类准确率存储在acc_set中
     acc_set = []
+    # 将平均损失存储在avg_loss_set中
     avg_loss_set = []
+    # 将测试 reader yield 出的每一个数据传入网络中进行训练
     for test_data in train_test_reader():
         acc_np, avg_loss_np = exe.run(
             program=train_test_program,
@@ -348,17 +413,30 @@ def train_test(train_test_program,
             fetch_list=[acc, avg_loss])
         acc_set.append(float(acc_np))
         avg_loss_set.append(float(avg_loss_np))
-    # get test acc and loss
+    # 获得测试数据上的准确率和损失值
     acc_val_mean = numpy.array(acc_set).mean()
     avg_loss_val_mean = numpy.array(avg_loss_set).mean()
+    # 返回平均损失值，平均准确率
     return avg_loss_val_mean, acc_val_mean
+```
 
+创建执行器：
+
+```python
 exe = fluid.Executor(place)
 exe.run(fluid.default_startup_program())
+```
+
+设置 main_program 和 test_program ：
 
+```python
 main_program = fluid.default_main_program()
 test_program = fluid.default_main_program().clone(for_test=True)
+```
+
+开始训练：
 
+```python
 lists = []
 step = 0
 for epoch_id in epochs:
@@ -366,12 +444,12 @@ for epoch_id in epochs:
         metrics = exe.run(main_program,
                           feed=feeder.feed(data),
                           fetch_list=[avg_loss, acc])
-        if step % 100 == 0:
+        if step % 100 == 0: #每训练100次 打印一次log
             print("Pass %d, Batch %d, Cost %f" % (step, epoch_id, metrics[0]))
             event_handler_plot(train_prompt, step, metrics[0])
         step += 1
 
-    # test for epoch
+    # 测试每个epoch的分类效果
     avg_loss_val, acc_val = train_test(train_test_program=test_program,
                                        train_test_reader=test_reader,
                                        train_test_feed=feeder)
@@ -380,19 +458,25 @@ for epoch_id in epochs:
     event_handler_plot(test_prompt, step, metrics[0])
 
     lists.append((epoch_id, avg_loss_val, acc_val))
+
+    # 保存训练好的模型参数用于预测
     if save_dirname is not None:
         fluid.io.save_inference_model(save_dirname,
                                       ["img"], [prediction], exe,
                                       model_filename=None,
                                       params_filename=None)
 
-        # find the best pass
+# 选择效果最好的pass
 best = sorted(lists, key=lambda list: float(list[1]))[0]
 print('Best pass is %s, testing Avgcost is %s' % (best[0], best[1]))
 print('The classification accuracy is %.2f%%' % (float(best[2]) * 100))
 ```
 
-训练过程是完全自动的，event_handler里打印的日志类似如下所示：
+训练过程是完全自动的，event_handler里打印的日志类似如下所示。
+
+Pass表示训练轮次，Batch表示训练全量数据的次数，cost表示当前pass的损失值。
+
+每训练完一个Epoch后，计算一次平均损失和分类准确率。
 
 ```
 Pass 0, Batch 0, Cost 0.125650
@@ -417,7 +501,7 @@ Test with Epoch 0, avg_cost: 0.053097883707459624, acc: 0.9822850318471338
 
 ### 生成预测输入数据
 
-`infer_3.png` 是数字 3 的一个示例图像。把它变成一个 numpy 数组以匹配数据馈送格式。
+`infer_3.png` 是数字 3 的一个示例图像。把它变成一个 numpy 数组以匹配数据feed格式。
 
 ```python
 def load_image(file):
@@ -427,7 +511,7 @@ def load_image(file):
     im = im / 255.0 * 2.0 - 1.0
     return im
 
-cur_dir = cur_dir = os.getcwd()
+cur_dir = os.getcwd()
 tensor_img = load_image(cur_dir + '/image/infer_3.png')
 ```
 
@@ -436,20 +520,23 @@ tensor_img = load_image(cur_dir + '/image/infer_3.png')
 ```python
 inference_scope = fluid.core.Scope()
 with fluid.scope_guard(inference_scope):
-    # Use fluid.io.load_inference_model to obtain the inference program desc,
-    # the feed_target_names (the names of variables that will be feeded
-    # data using feed operators), and the fetch_targets (variables that
-    # we want to obtain data from using fetch operators).
+    # 使用 fluid.io.load_inference_model 获取 inference program desc,
+    # feed_target_names 用于指定需要传入网络的变量名
+    # fetch_targets 指定希望从网络中fetch出的变量名
     [inference_program, feed_target_names,
      fetch_targets] = fluid.io.load_inference_model(
      save_dirname, exe, None, None)
 
-    # Construct feed as a dictionary of {feed_target_name: feed_target_data}
-    # and results will contain a list of data corresponding to fetch_targets.
+    # 将feed构建成字典 {feed_target_name: feed_target_data}
+    # 结果将包含一个与fetch_targets对应的数据列表
     results = exe.run(inference_program,
                             feed={feed_target_names[0]: tensor_img},
                             fetch_list=fetch_targets)
     lab = numpy.argsort(results)
+
+    # 打印 infer_3.png 这张图片的预测结果
+    img=Image.open('image/infer_3.png')
+    plt.imshow(img)
     print("Inference result of image/infer_3.png is: %d" % lab[0][0][-1])
 ```
 
@@ -457,11 +544,11 @@ with fluid.scope_guard(inference_scope):
 ### 预测结果
 
 如果顺利，预测结果输入如下：
-`Inference result of image/infer_3.png is: 3`
+`Inference result of image/infer_3.png is: 3` , 说明我们的网络成功的识别出了这张图片！
 
 ## 总结
 
-本教程的softmax回归、多层感知器和卷积神经网络是最基础的深度学习模型，后续章节中复杂的神经网络都是从它们衍生出来的，因此这几个模型对之后的学习大有裨益。同时，我们也观察到从最简单的softmax回归变换到稍复杂的卷积神经网络的时候，MNIST数据集上的识别准确率有了大幅度的提升，原因是卷积层具有局部连接和共享权重的特性。在之后学习新模型的时候，希望大家也要深入到新模型相比原模型带来效果提升的关键之处。此外，本教程还介绍了PaddlePaddle模型搭建的基本流程，从dataprovider的编写、网络层的构建，到最后的训练和预测。对这个流程熟悉以后，大家就可以用自己的数据，定义自己的网络模型，并完成自己的训练和预测任务了。
+本教程的softmax回归、多层感知机和卷积神经网络是最基础的深度学习模型，后续章节中复杂的神经网络都是从它们衍生出来的，因此这几个模型对之后的学习大有裨益。同时，我们也观察到从最简单的softmax回归变换到稍复杂的卷积神经网络的时候，MNIST数据集上的识别准确率有了大幅度的提升，原因是卷积层具有局部连接和共享权重的特性。在之后学习新模型的时候，希望大家也要深入到新模型相比原模型带来效果提升的关键之处。此外，本教程还介绍了PaddlePaddle模型搭建的基本流程，从dataprovider的编写、网络层的构建，到最后的训练和预测。对这个流程熟悉以后，大家就可以用自己的数据，定义自己的网络模型，并完成自己的训练和预测任务了。
 
 <a name="参考文献"></a>
 ## 参考文献
@@ -479,3 +566,4 @@ with fluid.scope_guard(inference_scope):
 
 <br/>
 <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/"><img alt="知识共享许可协议" style="border-width:0" src="https://i.creativecommons.org/l/by-sa/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" href="http://purl.org/dc/dcmitype/Text" property="dct:title" rel="dct:type">本教程</span> 由 <a xmlns:cc="http://creativecommons.org/ns#" href="http://book.paddlepaddle.org" property="cc:attributionName" rel="cc:attributionURL">PaddlePaddle</a> 创作，采用 <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">知识共享 署名-相同方式共享 4.0 国际 许可协议</a>进行许可。
+

02.recognize_digits/index.cn.html

@@ -40,7 +40,7 @@
 
 <!-- This block will be replaced by each markdown file content. Please do not change lines below.-->
 <div id="markdown" style='display:none'>
-# 识别数字
+# 数字识别
 
 本教程源代码目录在[book/recognize_digits](https://github.com/PaddlePaddle/book/tree/develop/02.recognize_digits),初次使用请您参考[Book文档使用说明](https://github.com/PaddlePaddle/book/blob/develop/README.cn.md#运行这本书)。
 
@@ -54,26 +54,28 @@
 
 MNIST数据集是从 [NIST](https://www.nist.gov/srd/nist-special-database-19) 的Special Database 3（SD-3）和Special Database 1（SD-1）构建而来。由于SD-3是由美国人口调查局的员工进行标注，SD-1是由美国高中生进行标注，因此SD-3比SD-1更干净也更容易识别。Yann LeCun等人从SD-1和SD-3中各取一半作为MNIST的训练集（60000条数据）和测试集（10000条数据），其中训练集来自250位不同的标注员，此外还保证了训练集和测试集的标注员是不完全相同的。
 
-Yann LeCun早先在手写字符识别上做了很多研究，并在研究过程中提出了卷积神经网络（Convolutional Neural Network），大幅度地提高了手写字符的识别能力，也因此成为了深度学习领域的奠基人之一。如今的深度学习领域，卷积神经网络占据了至关重要的地位，从最早Yann LeCun提出的简单LeNet，到如今ImageNet大赛上的优胜模型VGGNet、GoogLeNet、ResNet等（请参见[图像分类](https://github.com/PaddlePaddle/book/tree/develop/03.image_classification) 教程），人们在图像分类领域，利用卷积神经网络得到了一系列惊人的结果。
+MNIST吸引了大量的科学家基于此数据集训练模型，1998年，LeCun分别用单层线性分类器、多层感知器（Multilayer Perceptron, MLP）和多层卷积神经网络LeNet进行实验，使得测试集上的误差不断下降（从12%下降到0.7%）\[[1](#参考文献)\]。在研究过程中，LeCun提出了卷积神经网络（Convolutional Neural Network），大幅度地提高了手写字符的识别能力，也因此成为了深度学习领域的奠基人之一。此后，科学家们又基于K近邻（K-Nearest Neighbors）算法\[[2](#参考文献)\]、支持向量机（SVM）\[[3](#参考文献)\]、神经网络\[[4-7](#参考文献)\]和Boosting方法\[[8](#参考文献)\]等做了大量实验，并采用多种预处理方法（如去除歪曲、去噪、模糊等）来提高识别的准确率。
 
-有很多算法在MNIST上进行实验。1998年，LeCun分别用单层线性分类器、多层感知器（Multilayer Perceptron, MLP）和多层卷积神经网络LeNet进行实验，使得测试集上的误差不断下降（从12%下降到0.7%）\[[1](#参考文献)\]。此后，科学家们又基于K近邻（K-Nearest Neighbors）算法\[[2](#参考文献)\]、支持向量机（SVM）\[[3](#参考文献)\]、神经网络\[[4-7](#参考文献)\]和Boosting方法\[[8](#参考文献)\]等做了大量实验，并采用多种预处理方法（如去除歪曲、去噪、模糊等）来提高识别的准确率。
+如今的深度学习领域，卷积神经网络占据了至关重要的地位，从最早Yann LeCun提出的简单LeNet，到如今ImageNet大赛上的优胜模型VGGNet、GoogLeNet、ResNet等（请参见[图像分类](https://github.com/PaddlePaddle/book/tree/develop/03.image_classification) 教程），人们在图像分类领域，利用卷积神经网络得到了一系列惊人的结果。
 
-本教程中，我们从简单的模型Softmax回归开始，带大家入门手写字符识别，并逐步进行模型优化。
+
+
+本教程中，我们从简单的Softmax回归模型开始，带大家了解手写字符识别，并向大家介绍如何改进模型，利用多层感知机（MLP）和卷积神经网络（CNN）优化识别效果。
 
 
 ## 模型概览
 
-基于MNIST数据训练一个分类器，在介绍本教程使用的三个基本图像分类网络前，我们先给出一些定义：
+基于MNIST数据集训练一个分类器，在介绍本教程使用的三个基本图像分类网络前，我们先给出一些定义：
 
 - $X$是输入：MNIST图片是$28\times28$ 的二维图像，为了进行计算，我们将其转化为$784$维向量，即$X=\left ( x_0, x_1, \dots, x_{783} \right )$。
 
 - $Y$是输出：分类器的输出是10类数字（0-9），即$Y=\left ( y_0, y_1, \dots, y_9 \right )$，每一维$y_i$代表图片分类为第$i$类数字的概率。
 
-- $L$是图片的真实标签：$L=\left ( l_0, l_1, \dots, l_9 \right )$也是10维，但只有一维为1，其他都为0。
+- $Label$是图片的真实标签：$Label=\left ( l_0, l_1, \dots, l_9 \right )$也是10维，但只有一维为1，其他都为0。例如某张图片上的数字为2，则它的标签为$(0,0,1,0, \dot, 0)$
 
 ### Softmax回归(Softmax Regression)
 
-最简单的Softmax回归模型是先将输入层经过一个全连接层得到的特征，然后直接通过softmax 函数进行多分类\[[9](#参考文献)\]。
+最简单的Softmax回归模型是先将输入层经过一个全连接层得到特征，然后直接通过 softmax 函数计算多个类别的概率并输出\[[9](#参考文献)\]。
 
 输入层的数据$X$传到输出层，在激活操作之前，会乘以相应的权重 $W$ ，并加上偏置变量 $b$ ，具体如下：
 
@@ -81,24 +83,26 @@ $$ y_i = \text{softmax}(\sum_j W_{i,j}x_j + b_i) $$
 
 其中 $ \text{softmax}(x_i) = \frac{e^{x_i}}{\sum_j e^{x_j}} $
 
+图2为softmax回归的网络图，图中权重用蓝线表示、偏置用红线表示、+1代表偏置参数的系数为1。
+
+<p align="center">
+<img src="https://github.com/PaddlePaddle/book/blob/develop/02.recognize_digits/image/softmax_regression.png?raw=true" width=400><br/>
+图2. softmax回归网络结构图<br/>
+</p>
+
 对于有 $N$ 个类别的多分类问题，指定 $N$ 个输出节点，$N$ 维结果向量经过softmax将归一化为 $N$ 个[0,1]范围内的实数值，分别表示该样本属于这 $N$ 个类别的概率。此处的 $y_i$ 即对应该图片为数字 $i$ 的预测概率。
 
 在分类问题中，我们一般采用交叉熵代价损失函数（cross entropy loss），公式如下：
 
 $$  L_{cross-entropy}(label, y) = -\sum_i label_ilog(y_i) $$
 
-图2为softmax回归的网络图，图中权重用蓝线表示、偏置用红线表示、+1代表偏置参数的系数为1。
 
-<p align="center">
-<img src="https://github.com/PaddlePaddle/book/blob/develop/02.recognize_digits/image/softmax_regression.png?raw=true" width=400><br/>
-图2. softmax回归网络结构图<br/>
-</p>
 
-### 多层感知器(Multilayer Perceptron, MLP)
+### 多层感知机(Multilayer Perceptron, MLP)
 
 Softmax回归模型采用了最简单的两层神经网络，即只有输入层和输出层，因此其拟合能力有限。为了达到更好的识别效果，我们考虑在输入层和输出层中间加上若干个隐藏层\[[10](#参考文献)\]。
 
-1.  经过第一个隐藏层，可以得到 $ H_1 = \phi(W_1X + b_1) $，其中$\phi$代表激活函数，常见的有sigmoid、tanh或ReLU等函数。
+1.  经过第一个隐藏层，可以得到 $ H_1 = \phi(W_1X + b_1) $，其中$\phi$代表激活函数，常见的有[sigmoid、tanh或ReLU](#常见激活函数介绍)等函数。
 2.  经过第二个隐藏层，可以得到 $ H_2 = \phi(W_2H_1 + b_2) $。
 3.  最后，再经过输出层，得到的$Y=\text{softmax}(W_3H_2 + b_3)$，即为最后的分类结果向量。
 
@@ -115,7 +119,7 @@ Softmax回归模型采用了最简单的两层神经网络，即只有输入层
 在多层感知器模型中，将图像展开成一维向量输入到网络中，忽略了图像的位置和结构信息，而卷积神经网络能够更好的利用图像的结构信息。[LeNet-5](http://yann.lecun.com/exdb/lenet/)是一个较简单的卷积神经网络。图4显示了其结构：输入的二维图像，先经过两次卷积层到池化层，再经过全连接层，最后使用softmax分类作为输出层。下面我们主要介绍卷积层和池化层。
 
 <p align="center">
-<img src="https://github.com/PaddlePaddle/book/blob/develop/02.recognize_digits/image/cnn.png?raw=true" width="400"><br/>
+<img src="https://github.com/PaddlePaddle/book/blob/develop/02.recognize_digits/image/cnn.png?raw=true" width="600"><br/>
 图4. LeNet-5卷积神经网络结构<br/>
 </p>
 
@@ -128,7 +132,9 @@ Softmax回归模型采用了最简单的两层神经网络，即只有输入层
 图5. 卷积层图片<br/>
 </p>
 
-图5给出一个卷积计算过程的示例图，输入图像大小为$H=5,W=5,D=3$，即$5 \times 5$大小的3通道（RGB，也称作深度）彩色图像。这个示例图中包含两（用$K$表示）组卷积核，即图中滤波器$W_0$和$W_1$。在卷积计算中，通常对不同的输入通道采用不同的卷积核，如图示例中每组卷积核包含（$D=3）$个$3 \times 3$（用$F \times F$表示）大小的卷积核。另外，这个示例中卷积核在图像的水平方向（$W$方向）和垂直方向（$H$方向）的滑动步长为2（用$S$表示）；对输入图像周围各填充1（用$P$表示）个0，即图中输入层原始数据为蓝色部分，灰色部分是进行了大小为1的扩展，用0来进行扩展。经过卷积操作得到输出为$3 \times 3 \times 2$（用$H_{o} \times W_{o} \times K$表示）大小的特征图，即$3 \times 3$大小的2通道特征图，其中$H_o$计算公式为：$H_o = (H - F + 2 \times P)/S + 1$，$W_o$同理。 而输出特征图中的每个像素，是每组滤波器与输入图像每个特征图的内积再求和，再加上偏置$b_o$，偏置通常对于每个输出特征图是共享的。输出特征图$o[:,:,0]$中的最后一个$-2$计算如图5右下角公式所示。
+图5给出一个卷积计算过程的示例图，输入图像大小为$H=5,W=5,D=3$，即$5 \times 5$大小的3通道（RGB，也称作深度）彩色图像。
+
+这个示例图中包含两（用$K$表示）组卷积核，即图中$Filter W_0$ 和 $Filter W_1$。在卷积计算中，通常对不同的输入通道采用不同的卷积核，如图示例中每组卷积核包含（$D=3）$个$3 \times 3$（用$F \times F$表示）大小的卷积核。另外，这个示例中卷积核在图像的水平方向（$W$方向）和垂直方向（$H$方向）的滑动步长为2（用$S$表示）；对输入图像周围各填充1（用$P$表示）个0，即图中输入层原始数据为蓝色部分，灰色部分是进行了大小为1的扩展，用0来进行扩展。经过卷积操作得到输出为$3 \times 3 \times 2$（用$H_{o} \times W_{o} \times K$表示）大小的特征图，即$3 \times 3$大小的2通道特征图，其中$H_o$计算公式为：$H_o = (H - F + 2 \times P)/S + 1$，$W_o$同理。 而输出特征图中的每个像素，是每组滤波器与输入图像每个特征图的内积再求和，再加上偏置$b_o$，偏置通常对于每个输出特征图是共享的。输出特征图$o[:,:,0]$中的最后一个$-2$计算如图5右下角公式所示。
 
 在卷积操作中卷积核是可学习的参数，经过上面示例介绍，每层卷积的参数大小为$D \times F \times F \times K$。在多层感知器模型中，神经元通常是全部连接，参数较多。而卷积层的参数较少，这也是由卷积层的主要特性即局部连接和共享权重所决定。
 
@@ -138,6 +144,8 @@ Softmax回归模型采用了最简单的两层神经网络，即只有输入层
 
 通过介绍卷积计算过程及其特性，可以看出卷积是线性操作，并具有平移不变性（shift-invariant），平移不变性即在图像每个位置执行相同的操作。卷积层的局部连接和权重共享使得需要学习的参数大大减小，这样也有利于训练较大卷积神经网络。
 
+关于卷积的更多内容可[参考阅读](http://ufldl.stanford.edu/wiki/index.php/Feature_extraction_using_convolution#Convolutions)。
+
 #### 池化层
 
 <p align="center">
@@ -147,8 +155,9 @@ Softmax回归模型采用了最简单的两层神经网络，即只有输入层
 
 池化是非线性下采样的一种形式，主要作用是通过减少网络的参数来减小计算量，并且能够在一定程度上控制过拟合。通常在卷积层的后面会加上一个池化层。池化包括最大池化、平均池化等。其中最大池化是用不重叠的矩形框将输入层分成不同的区域，对于每个矩形框的数取最大值作为输出层，如图6所示。
 
-更详细的关于卷积神经网络的具体知识可以参考[斯坦福大学公开课]( http://cs231n.github.io/convolutional-networks/ )和[图像分类]( https://github.com/PaddlePaddle/book/tree/develop/03.image_classification )教程。
+更详细的关于卷积神经网络的具体知识可以参考[斯坦福大学公开课]( http://cs231n.github.io/convolutional-networks/ )、[Ufldl](http://ufldl.stanford.edu/wiki/index.php/Pooling) 和 [图像分类]( https://github.com/PaddlePaddle/book/tree/develop/03.image_classification )教程。
 
+<a name="常见激活函数介绍"></a>
 ### 常见激活函数介绍  
 - sigmoid激活函数： $ f(x) = sigmoid(x) = \frac{1}{1+e^{-x}} $
 
@@ -174,50 +183,53 @@ PaddlePaddle在API中提供了自动加载[MNIST](http://yann.lecun.com/exdb/mni
 
 ## Fluid API 概述
 
-演示将使用最新的 `Fluid API`。Fluid API是最新的 PaddlePaddle API。它在不牺牲性能的情况下简化了模型配置。
-我们建议使用 Fluid API，因为它更容易学起来。
+演示将使用最新的 [Fluid API](http://paddlepaddle.org/documentation/docs/zh/1.2/api_cn/index_cn.html)。Fluid API是最新的 PaddlePaddle API。它在不牺牲性能的情况下简化了模型配置。
+我们建议使用 Fluid API，它易学易用的特性将帮助您快速完成机器学习任务。。
 
-下面是快速的 Fluid API 概述。
+下面是 Fluid API 中几个重要概念的概述：
 
-1. `inference_program`：指定如何从数据输入中获得预测的函数。
+1. `inference_program`：指定如何从数据输入中获得预测的函数，
 这是指定网络流的地方。
 
-2. `train_program`：指定如何从 `inference_program` 和`标签值`中获取 `loss` 的函数。
+2. `train_program`：指定如何从 `inference_program` 和`标签值`中获取 `loss` 的函数，
 这是指定损失计算的地方。
 
-3. `optimizer_func`: “指定优化器配置的函数。优化器负责减少损失并驱动培训。Paddle 支持多种不同的优化器。
-
-4. `Trainer`：PaddlePaddle Trainer 管理由 `train_program` 和 `optimizer` 指定的训练过程。
-通过 `event_handler` 回调函数，用户可以监控培训的进展。
-
-5. `Inferencer`：Fluid inferencer 加载 `inference_program` 和由 Trainer 训练的参数。
-然后，它可以推断数据和返回预测。
+3. `optimizer_func`: 指定优化器配置的函数，优化器负责减少损失并驱动训练，Paddle 支持多种不同的优化器。
 
-在这个演示中，我们将深入了解它们。
+在下面的代码示例中，我们将深入了解它们。
 
 ## 配置说明
 加载 PaddlePaddle 的 Fluid API 包。
 
 ```python
 import os
-from PIL import Image
+from PIL import Image # 导入图像处理模块
+import matplotlib.pyplot as plt
 import numpy
-import paddle
+import paddle # 导入paddle模块
 import paddle.fluid as fluid
-from __future__ import print_function
+from __future__ import print_function # 将python3中的print特性导入当前版本
 ```
 
 ### Program Functions 配置
 
-我们需要设置“推理程序”函数。我们想用这个程序来演示三个不同的分类器，每个分类器都定义为 Python 函数。
-我们需要将图像数据馈送到分类器。Paddle 为读取数据提供了一个特殊的层 `layer.data` 层。
+我们需要设置 `inference_program` 函数。我们想用这个程序来演示三个不同的分类器，每个分类器都定义为 Python 函数。
+我们需要将图像数据输入到分类器中。Paddle 为读取数据提供了一个特殊的层 `layer.data` 层。
 让我们创建一个数据层来读取图像并将其连接到分类网络。
 
 - Softmax回归：只通过一层简单的以softmax为激活函数的全连接层，就可以得到分类的结果。
 
 ```python
 def softmax_regression():
+    """
+    定义softmax分类器：
+        一个以softmax为激活函数的全连接层
+    Return:
+        predict_image -- 分类的结果
+    """
+    # 输入的原始图像数据，大小为28*28*1
     img = fluid.layers.data(name='img', shape=[1, 28, 28], dtype='float32')
+    # 以softmax为激活函数的全连接层，输出层的大小必须为数字的个数10
     predict = fluid.layers.fc(
         input=img, size=10, act='softmax')
     return predict
@@ -227,6 +239,15 @@ def softmax_regression():
 
 ```python
 def multilayer_perceptron():
+    """
+    定义多层感知机分类器：
+        含有两个隐藏层（全连接层）的多层感知器
+        其中前两个隐藏层的激活函数采用 ReLU，输出层的激活函数用 Softmax
+
+    Return:
+        predict_image -- 分类的结果
+    """
+    # 输入的原始图像数据，大小为28*28*1
     img = fluid.layers.data(name='img', shape=[1, 28, 28], dtype='float32')
     # 第一个全连接层，激活函数为ReLU
     hidden = fluid.layers.fc(input=img, size=200, act='relu')
@@ -241,8 +262,17 @@ def multilayer_perceptron():
 
 ```python
 def convolutional_neural_network():
+    """
+    定义卷积神经网络分类器：
+        输入的二维图像，经过两个卷积-池化层，使用以softmax为激活函数的全连接层作为输出层
+
+    Return:
+        predict -- 分类的结果
+    """
+    # 输入的原始图像数据，大小为28*28*1
     img = fluid.layers.data(name='img', shape=[1, 28, 28], dtype='float32')
     # 第一个卷积-池化层
+    # 使用20个5*5的滤波器，池化大小为2，池化步长为2，激活函数为Relu
     conv_pool_1 = fluid.nets.simple_img_conv_pool(
         input=img,
         filter_size=5,
@@ -252,6 +282,7 @@ def convolutional_neural_network():
         act="relu")
     conv_pool_1 = fluid.layers.batch_norm(conv_pool_1)
     # 第二个卷积-池化层
+    # 使用20个5*5的滤波器，池化大小为2，池化步长为2，激活函数为Relu
     conv_pool_2 = fluid.nets.simple_img_conv_pool(
         input=conv_pool_1,
         filter_size=5,
@@ -274,13 +305,27 @@ def convolutional_neural_network():
 
 ```python
 def train_program():
+    """
+    配置train_program
+
+    Return:
+        predict -- 分类的结果
+        avg_cost -- 平均损失
+        acc -- 分类的准确率
+
+    """
+    # 标签层，名称为label,对应输入图片的类别标签
     label = fluid.layers.data(name='label', shape=[1], dtype='int64')
 
-    # predict = softmax_regression() # uncomment for Softmax回归
-    # predict = multilayer_perceptron() # uncomment for 多层感知器
-    predict = convolutional_neural_network() # uncomment for LeNet5卷积神经网络
+    # predict = softmax_regression() # 取消注释将使用 Softmax回归
+    # predict = multilayer_perceptron() # 取消注释将使用 多层感知器
+    predict = convolutional_neural_network() # 取消注释将使用 LeNet5卷积神经网络
+
+    # 使用类交叉熵函数计算predict和label之间的损失函数
     cost = fluid.layers.cross_entropy(input=predict, label=label)
+    # 计算平均损失
     avg_cost = fluid.layers.mean(cost)
+    # 计算分类准确率
     acc = fluid.layers.accuracy(input=predict, label=label)
     return predict, [avg_cost, acc]
 
@@ -288,7 +333,7 @@ def train_program():
 
 #### Optimizer Function 配置
 
-在下面的 `Adam optimizer`，`learning_rate` 是训练的速度，与网络的训练收敛速度有关系。
+在下面的 `Adam optimizer`，`learning_rate` 是学习率，它的大小与网络的训练收敛速度有关系。
 
 ```python
 def optimizer_program():
@@ -304,43 +349,45 @@ def optimizer_program():
 `batch`是一个特殊的decorator，它的输入是一个reader，输出是一个batched reader。在PaddlePaddle里，一个reader每次yield一条训练数据，而一个batched reader每次yield一个minibatch。
 
 ```python
-
+# 一个minibatch中有64个数据
 BATCH_SIZE = 64
 
+# 每次读取训练集中的500个数据并随机打乱，传入batched reader中，batched reader 每次 yield 64个数据
 train_reader = paddle.batch(
         paddle.reader.shuffle(
             paddle.dataset.mnist.train(), buf_size=500),
         batch_size=BATCH_SIZE)
-
+# 读取测试集的数据，每次 yield 64个数据
 test_reader = paddle.batch(
             paddle.dataset.mnist.test(), batch_size=BATCH_SIZE)
 ```
 
-### Trainer 训练过程
+### 构建训练过程
 
-现在，我们需要构建一个训练过程。将使用到前面定义的训练程序 `train_program`, `place` 和优化器 `optimizer`，并包含训练迭代、检查训练期间测试误差以及保存所需要用来预测的模型参数。
+现在，我们需要构建一个训练过程。将使用到前面定义的训练程序 `train_program`, `place` 和优化器 `optimizer`,并包含训练迭代、检查训练期间测试误差以及保存所需要用来预测的模型参数。
 
 
 #### Event Handler 配置
 
-我们可以在训练期间通过调用一个handler函数来监控培训进度。
-我们将在这里演示两个 `event_handler` 程序。请随意修改 Jupyter 笔记本 ，看看有什么不同。
+我们可以在训练期间通过调用一个handler函数来监控训练进度。
+我们将在这里演示两个 `event_handler` 程序。请随意修改 Jupyter Notebook ，看看有什么不同。
 
 `event_handler` 用来在训练过程中输出训练结果
 
 ```python
 def event_handler(pass_id, batch_id, cost):
+    # 打印训练的中间结果，训练轮次，batch数，损失函数
     print("Pass %d, Batch %d, Cost %f" % (pass_id,batch_id, cost))
 ```
 
 ```python
-from paddle.v2.plot import Ploter
+from paddle.utils.plot import Ploter
 
 train_prompt = "Train cost"
 test_prompt = "Test cost"
 cost_ploter = Ploter(train_prompt, test_prompt)
 
-# event_handler to plot a figure
+# 将训练过程绘图表示
 def event_handler_plot(ploter_title, step, cost):
     cost_ploter.append(ploter_title, step, cost)
     cost_ploter.plot()
@@ -358,31 +405,49 @@ def event_handler_plot(ploter_title, step, cost):
 `feed_order` 用于将数据目录映射到 `train_program`
 创建一个反馈训练过程中误差的`train_test`
 
-训练完成后，模型参数存入`save_dirname`中
+定义网络结构：
 
 ```python
 # 该模型运行在单个CPU上
-use_cuda = False # set to True if training with GPU
+use_cuda = False # 如想使用GPU，请设置为 True
 place = fluid.CUDAPlace(0) if use_cuda else fluid.CPUPlace()
 
+# 调用train_program 获取预测值，损失值，
 prediction, [avg_loss, acc] = train_program()
 
+# 输入的原始图像数据，大小为28*28*1
 img = fluid.layers.data(name='img', shape=[1, 28, 28], dtype='float32')
+# 标签层，名称为label,对应输入图片的类别标签
 label = fluid.layers.data(name='label', shape=[1], dtype='int64')
+# 告知网络传入的数据分为两部分，第一部分是img值，第二部分是label值
 feeder = fluid.DataFeeder(feed_list=[img, label], place=place)
 
+# 选择Adam优化器
 optimizer = fluid.optimizer.Adam(learning_rate=0.001)
 optimizer.minimize(avg_loss)
+```
+
+设置训练过程的超参：
+
+```python
 
-PASS_NUM = 5
+PASS_NUM = 5 #训练5轮
 epochs = [epoch_id for epoch_id in range(PASS_NUM)]
 
+# 将模型参数存储在名为 save_dirname 的文件中
 save_dirname = "recognize_digits.inference.model"
+```
+
 
+```python
 def train_test(train_test_program,
                    train_test_feed, train_test_reader):
+
+    # 将分类准确率存储在acc_set中
     acc_set = []
+    # 将平均损失存储在avg_loss_set中
     avg_loss_set = []
+    # 将测试 reader yield 出的每一个数据传入网络中进行训练
     for test_data in train_test_reader():
         acc_np, avg_loss_np = exe.run(
             program=train_test_program,
@@ -390,17 +455,30 @@ def train_test(train_test_program,
             fetch_list=[acc, avg_loss])
         acc_set.append(float(acc_np))
         avg_loss_set.append(float(avg_loss_np))
-    # get test acc and loss
+    # 获得测试数据上的准确率和损失值
     acc_val_mean = numpy.array(acc_set).mean()
     avg_loss_val_mean = numpy.array(avg_loss_set).mean()
+    # 返回平均损失值，平均准确率
     return avg_loss_val_mean, acc_val_mean
+```
 
+创建执行器：
+
+```python
 exe = fluid.Executor(place)
 exe.run(fluid.default_startup_program())
+```
+
+设置 main_program 和 test_program ：
 
+```python
 main_program = fluid.default_main_program()
 test_program = fluid.default_main_program().clone(for_test=True)
+```
+
+开始训练：
 
+```python
 lists = []
 step = 0
 for epoch_id in epochs:
@@ -408,12 +486,12 @@ for epoch_id in epochs:
         metrics = exe.run(main_program,
                           feed=feeder.feed(data),
                           fetch_list=[avg_loss, acc])
-        if step % 100 == 0:
+        if step % 100 == 0: #每训练100次 打印一次log
             print("Pass %d, Batch %d, Cost %f" % (step, epoch_id, metrics[0]))
             event_handler_plot(train_prompt, step, metrics[0])
         step += 1
 
-    # test for epoch
+    # 测试每个epoch的分类效果
     avg_loss_val, acc_val = train_test(train_test_program=test_program,
                                        train_test_reader=test_reader,
                                        train_test_feed=feeder)
@@ -422,19 +500,25 @@ for epoch_id in epochs:
     event_handler_plot(test_prompt, step, metrics[0])
 
     lists.append((epoch_id, avg_loss_val, acc_val))
+
+    # 保存训练好的模型参数用于预测
     if save_dirname is not None:
         fluid.io.save_inference_model(save_dirname,
                                       ["img"], [prediction], exe,
                                       model_filename=None,
                                       params_filename=None)
 
-        # find the best pass
+# 选择效果最好的pass
 best = sorted(lists, key=lambda list: float(list[1]))[0]
 print('Best pass is %s, testing Avgcost is %s' % (best[0], best[1]))
 print('The classification accuracy is %.2f%%' % (float(best[2]) * 100))
 ```
 
-训练过程是完全自动的，event_handler里打印的日志类似如下所示：
+训练过程是完全自动的，event_handler里打印的日志类似如下所示。
+
+Pass表示训练轮次，Batch表示训练全量数据的次数，cost表示当前pass的损失值。
+
+每训练完一个Epoch后，计算一次平均损失和分类准确率。
 
 ```
 Pass 0, Batch 0, Cost 0.125650
@@ -459,7 +543,7 @@ Test with Epoch 0, avg_cost: 0.053097883707459624, acc: 0.9822850318471338
 
 ### 生成预测输入数据
 
-`infer_3.png` 是数字 3 的一个示例图像。把它变成一个 numpy 数组以匹配数据馈送格式。
+`infer_3.png` 是数字 3 的一个示例图像。把它变成一个 numpy 数组以匹配数据feed格式。
 
 ```python
 def load_image(file):
@@ -469,7 +553,7 @@ def load_image(file):
     im = im / 255.0 * 2.0 - 1.0
     return im
 
-cur_dir = cur_dir = os.getcwd()
+cur_dir = os.getcwd()
 tensor_img = load_image(cur_dir + '/image/infer_3.png')
 ```
 
@@ -478,20 +562,23 @@ tensor_img = load_image(cur_dir + '/image/infer_3.png')
 ```python
 inference_scope = fluid.core.Scope()
 with fluid.scope_guard(inference_scope):
-    # Use fluid.io.load_inference_model to obtain the inference program desc,
-    # the feed_target_names (the names of variables that will be feeded
-    # data using feed operators), and the fetch_targets (variables that
-    # we want to obtain data from using fetch operators).
+    # 使用 fluid.io.load_inference_model 获取 inference program desc,
+    # feed_target_names 用于指定需要传入网络的变量名
+    # fetch_targets 指定希望从网络中fetch出的变量名
     [inference_program, feed_target_names,
      fetch_targets] = fluid.io.load_inference_model(
      save_dirname, exe, None, None)
 
-    # Construct feed as a dictionary of {feed_target_name: feed_target_data}
-    # and results will contain a list of data corresponding to fetch_targets.
+    # 将feed构建成字典 {feed_target_name: feed_target_data}
+    # 结果将包含一个与fetch_targets对应的数据列表
     results = exe.run(inference_program,
                             feed={feed_target_names[0]: tensor_img},
                             fetch_list=fetch_targets)
     lab = numpy.argsort(results)
+
+    # 打印 infer_3.png 这张图片的预测结果
+    img=Image.open('image/infer_3.png')
+    plt.imshow(img)
     print("Inference result of image/infer_3.png is: %d" % lab[0][0][-1])
 ```
 
@@ -499,11 +586,11 @@ with fluid.scope_guard(inference_scope):
 ### 预测结果
 
 如果顺利，预测结果输入如下：
-`Inference result of image/infer_3.png is: 3`
+`Inference result of image/infer_3.png is: 3` , 说明我们的网络成功的识别出了这张图片！
 
 ## 总结
 
-本教程的softmax回归、多层感知器和卷积神经网络是最基础的深度学习模型，后续章节中复杂的神经网络都是从它们衍生出来的，因此这几个模型对之后的学习大有裨益。同时，我们也观察到从最简单的softmax回归变换到稍复杂的卷积神经网络的时候，MNIST数据集上的识别准确率有了大幅度的提升，原因是卷积层具有局部连接和共享权重的特性。在之后学习新模型的时候，希望大家也要深入到新模型相比原模型带来效果提升的关键之处。此外，本教程还介绍了PaddlePaddle模型搭建的基本流程，从dataprovider的编写、网络层的构建，到最后的训练和预测。对这个流程熟悉以后，大家就可以用自己的数据，定义自己的网络模型，并完成自己的训练和预测任务了。
+本教程的softmax回归、多层感知机和卷积神经网络是最基础的深度学习模型，后续章节中复杂的神经网络都是从它们衍生出来的，因此这几个模型对之后的学习大有裨益。同时，我们也观察到从最简单的softmax回归变换到稍复杂的卷积神经网络的时候，MNIST数据集上的识别准确率有了大幅度的提升，原因是卷积层具有局部连接和共享权重的特性。在之后学习新模型的时候，希望大家也要深入到新模型相比原模型带来效果提升的关键之处。此外，本教程还介绍了PaddlePaddle模型搭建的基本流程，从dataprovider的编写、网络层的构建，到最后的训练和预测。对这个流程熟悉以后，大家就可以用自己的数据，定义自己的网络模型，并完成自己的训练和预测任务了。
 
 <a name="参考文献"></a>
 ## 参考文献
@@ -521,6 +608,7 @@ with fluid.scope_guard(inference_scope):
 
 <br/>
 <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/"><img alt="知识共享许可协议" style="border-width:0" src="https://i.creativecommons.org/l/by-sa/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" href="http://purl.org/dc/dcmitype/Text" property="dct:title" rel="dct:type">本教程</span> 由 <a xmlns:cc="http://creativecommons.org/ns#" href="http://book.paddlepaddle.org" property="cc:attributionName" rel="cc:attributionURL">PaddlePaddle</a> 创作，采用 <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">知识共享 署名-相同方式共享 4.0 国际 许可协议</a>进行许可。
+
 
 </div>
 <!-- You can change the lines below now. -->

03.image_classification/README.cn.md

@@ -10,7 +10,7 @@
 图像分类是根据图像的语义信息将不同类别图像区分开来，是计算机视觉中重要的基本问题，也是图像检测、图像分割、物体跟踪、行为分析等其他高层视觉任务的基础。图像分类在很多领域有广泛应用，包括安防领域的人脸识别和智能视频分析等，交通领域的交通场景识别，互联网领域基于内容的图像检索和相册自动归类，医学领域的图像识别等。
 
 
-一般来说，图像分类通过手工特征或特征学习方法对整个图像进行全部描述，然后使用分类器判别物体类别，因此如何提取图像的特征至关重要。在深度学习算法之前使用较多的是基于词袋(Bag of Words)模型的物体分类方法。词袋方法从自然语言处理中引入，即一句话可以用一个装了词的袋子表示其特征，袋子中的词为句子中的单词、短语或字。对于图像而言，词袋方法需要构建字典。最简单的词袋模型框架可以设计为**底层特征抽取**、**特征编码**、**分类器设计**三个过程。
+一般来说，图像分类通过手工提取特征或特征学习方法对整个图像进行全部描述，然后使用分类器判别物体类别，因此如何提取图像的特征至关重要。在深度学习算法之前使用较多的是基于词袋(Bag of Words)模型的物体分类方法。词袋方法从自然语言处理中引入，即一句话可以用一个装了词的袋子表示其特征，袋子中的词为句子中的单词、短语或字。对于图像而言，词袋方法需要构建字典。最简单的词袋模型框架可以设计为**底层特征抽取**、**特征编码**、**分类器设计**三个过程。
 
 而基于深度学习的图像分类方法，可以通过有监督或无监督的方式**学习**层次化的特征描述，从而取代了手工设计或选择图像特征的工作。深度学习模型中的卷积神经网络(Convolution Neural Network, CNN)近年来在图像领域取得了惊人的成绩，CNN直接利用图像像素信息作为输入，最大程度上保留了输入图像的所有信息，通过卷积操作进行特征的提取和高层抽象，模型输出直接是图像识别的结果。这种基于"输入-输出"直接端到端的学习方法取得了非常好的效果，得到了广泛的应用。
 
@@ -48,15 +48,15 @@
 
 在2012年之前的传统图像分类方法可以用背景描述中提到的三步完成，但通常完整建立图像识别模型一般包括底层特征学习、特征编码、空间约束、分类器设计、模型融合等几个阶段。
 
-  1). **底层特征提取**: 通常从图像中按照固定步长、尺度提取大量局部特征描述。常用的局部特征包括SIFT(Scale-Invariant Feature Transform, 尺度不变特征转换) \[[1](#参考文献)\]、HOG(Histogram of Oriented Gradient, 方向梯度直方图) \[[2](#参考文献)\]、LBP(Local Bianray Pattern, 局部二值模式) \[[3](#参考文献)\] 等，一般也采用多种特征描述子，防止丢失过多的有用信息。
+  1). **底层特征提取**: 通常从图像中按照固定步长、尺度提取大量局部特征描述。常用的局部特征包括SIFT(Scale-Invariant Feature Transform, 尺度不变特征转换) \[[1](#参考文献)\]、HOG(Histogram of Oriented Gradient, 方向梯度直方图) \[[2](#参考文献)\]、LBP(Local Bianray Pattern, 局部二值模式) \[[3](#参考文献)\] 等，一般也采用多种特征描述，防止丢失过多的有用信息。
 
-  2). **特征编码**: 底层特征中包含了大量冗余与噪声，为了提高特征表达的鲁棒性，需要使用一种特征变换算法对底层特征进行编码，称作特征编码。常用的特征编码包括向量量化编码 \[[4](#参考文献)\]、稀疏编码 \[[5](#参考文献)\]、局部线性约束编码 \[[6](#参考文献)\]、Fisher向量编码 \[[7](#参考文献)\] 等。
+  2). **特征编码**: 底层特征中包含了大量冗余与噪声，为了提高特征表达的鲁棒性，需要使用一种特征变换算法对底层特征进行编码，称作特征编码。常用的特征编码方法包括向量量化编码 \[[4](#参考文献)\]、稀疏编码 \[[5](#参考文献)\]、局部线性约束编码 \[[6](#参考文献)\]、Fisher向量编码 \[[7](#参考文献)\] 等。
 
   3). **空间特征约束**: 特征编码之后一般会经过空间特征约束，也称作**特征汇聚**。特征汇聚是指在一个空间范围内，对每一维特征取最大值或者平均值，可以获得一定特征不变形的特征表达。金字塔特征匹配是一种常用的特征聚会方法，这种方法提出将图像均匀分块，在分块内做特征汇聚。
 
   4). **通过分类器分类**: 经过前面步骤之后一张图像可以用一个固定维度的向量进行描述，接下来就是经过分类器对图像进行分类。通常使用的分类器包括SVM(Support Vector Machine, 支持向量机)、随机森林等。而使用核方法的SVM是最为广泛的分类器，在传统图像分类任务上性能很好。
 
-这种方法在PASCAL VOC竞赛中的图像分类算法中被广泛使用 \[[18](#参考文献)\]。[NEC实验室](http://www.nec-labs.com/)在ILSVRC2010中采用SIFT和LBP特征，两个非线性编码器以及SVM分类器获得图像分类的冠军 \[[8](#参考文献)\]。
+这种传统的图像分类方法在PASCAL VOC竞赛中的图像分类算法中被广泛使用 \[[18](#参考文献)\]。[NEC实验室](http://www.nec-labs.com/)在ILSVRC2010中采用SIFT和LBP特征，两个非线性编码器以及SVM分类器获得图像分类的冠军 \[[8](#参考文献)\]。
 
 Alex Krizhevsky在2012年ILSVRC提出的CNN模型 \[[9](#参考文献)\] 取得了历史性的突破，效果大幅度超越传统方法，获得了ILSVRC2012冠军，该模型被称作AlexNet。这也是首次将深度学习用于大规模图像分类中。从AlexNet之后，涌现了一系列CNN模型，不断地在ImageNet上刷新成绩，如图4展示。随着模型变得越来越深以及精妙的结构设计，Top-5的错误率也越来越低，降到了3.5%附近。而在同样的ImageNet数据集上，人眼的辨识错误率大概在5.1%，也就是目前的深度学习模型的识别能力已经超过了人眼。
 
@@ -77,7 +77,7 @@ Alex Krizhevsky在2012年ILSVRC提出的CNN模型 \[[9](#参考文献)\] 取得
 - 卷积层(convolution layer): 执行卷积操作提取底层到高层的特征，发掘出图片局部关联性质和空间不变性质。
 - 池化层(pooling layer): 执行降采样操作。通过取卷积输出特征图中局部区块的最大值(max-pooling)或者均值(avg-pooling)。降采样也是图像处理中常见的一种操作，可以过滤掉一些不重要的高频信息。
 - 全连接层(fully-connected layer，或者fc layer): 输入层到隐藏层的神经元是全部连接的。
-- 非线性变化: 卷积层、全连接层后面一般都会接非线性变化层，例如Sigmoid、Tanh、ReLu等来增强网络的表达能力，在CNN里最常使用的为ReLu激活函数。
+- 非线性变化: 卷积层、全连接层后面一般都会接非线性变化函数，例如Sigmoid、Tanh、ReLu等来增强网络的表达能力，在CNN里最常使用的为ReLu激活函数。
 - Dropout \[[10](#参考文献)\] : 在模型训练阶段随机让一些隐层节点权重不工作，提高网络的泛化能力，一定程度上防止过拟合。
 
 另外，在训练过程中由于每层参数不断更新，会导致下一次输入分布发生变化，这样导致训练过程需要精心设计超参数。如2015年Sergey Ioffe和Christian Szegedy提出了Batch Normalization (BN)算法 \[[14](#参考文献)\] 中，每个batch对网络中的每一层特征都做归一化，使得每层分布相对稳定。BN算法不仅起到一定的正则作用，而且弱化了一些超参数的设计。经过实验证明，BN算法加速了模型收敛过程，在后来较深的模型中被广泛使用。
@@ -110,7 +110,7 @@ Inception模块如下图7所示，图(a)是最简单的设计，输出是3个卷
 图7. Inception模块
 </p>
 
-GoogleNet由多组Inception模块堆积而成。另外，在网络最后也没有采用传统的多层全连接层，而是像NIN网络一样采用了均值池化层；但与NIN不同的是，池化层后面接了一层到类别数映射的全连接层。除了这两个特点之外，由于网络中间层特征也很有判别性，GoogleNet在中间层添加了两个辅助分类器，在后向传播中增强梯度并且增强正则化，而整个网络的损失函数是这个三个分类器的损失加权求和。
+GoogleNet由多组Inception模块堆积而成。另外，在网络最后也没有采用传统的多层全连接层，而是像NIN网络一样采用了均值池化层；但与NIN不同的是，GoogleNet在池化层后加了一个全连接层来映射类别数。除了这两个特点之外，由于网络中间层特征也很有判别性，GoogleNet在中间层添加了两个辅助分类器，在后向传播中增强梯度并且增强正则化，而整个网络的损失函数是这个三个分类器的损失加权求和。
 
 GoogleNet整体网络结构如图8所示，总共22层网络：开始由3层普通的卷积组成；接下来由三组子网络组成，第一组子网络包含2个Inception模块，第二组包含5个Inception模块，第三组包含2个Inception模块；然后接均值池化层、全连接层。
 
@@ -125,7 +125,7 @@ GoogleNet整体网络结构如图8所示，总共22层网络：开始由3层普
 
 ### ResNet
 
-ResNet(Residual Network) \[[15](#参考文献)\] 是2015年ImageNet图像分类、图像物体定位和图像物体检测比赛的冠军。针对训练卷积神经网络时加深网络导致准确度下降的问题，ResNet提出了采用残差学习。在已有设计思路(BN, 小卷积核，全卷积网络)的基础上，引入了残差模块。每个残差模块包含两条路径，其中一条路径是输入特征的直连通路，另一条路径对该特征做两到三次卷积操作得到该特征的残差，最后再将两条路径上的特征相加。
+ResNet(Residual Network) \[[15](#参考文献)\] 是2015年ImageNet图像分类、图像物体定位和图像物体检测比赛的冠军。针对随着网络训练加深导致准确度下降的问题，ResNet提出了残差学习方法来减轻训练深层网络的困难。在已有设计思路(BN, 小卷积核，全卷积网络)的基础上，引入了残差模块。每个残差模块包含两条路径，其中一条路径是输入特征的直连通路，另一条路径对该特征做两到三次卷积操作得到该特征的残差，最后再将两条路径上的特征相加。
 
 残差模块如图9所示，左边是基本模块连接方式，由两个输出通道数相同的3x3卷积组成。右边是瓶颈模块(Bottleneck)连接方式，之所以称为瓶颈，是因为上面的1x1卷积用来降维(图示例即256->64)，下面的1x1卷积用来升维(图示例即64->256)，这样中间3x3卷积的输入和输出通道数都较小(图示例即64->64)。
 
@@ -215,7 +215,7 @@ def vgg_bn_drop(input):
 
 3. 最后接两层512维的全连接。
 
-4. 通过上面VGG网络提取高层特征，然后经过全连接层映射到类别维度大小的向量，再通过Softmax归一化得到每个类别的概率，也可称作分类器。
+4. 在这里，VGG网络首先提取高层特征，随后在全连接层中将其映射到和类别维度大小一致的向量上，最后通过Softmax方法计算图片划为每个类别的概率。
 
 ### ResNet
 
@@ -226,7 +226,6 @@ ResNet模型的第1、3、4步和VGG模型相同，这里不再介绍。主要
   - `conv_bn_layer` : 带BN的卷积层。
   - `shortcut` : 残差模块的"直连"路径，"直连"实际分两种形式：残差模块输入和输出特征通道数不等时，采用1x1卷积的升维操作；残差模块输入和输出通道相等时，采用直连操作。
   - `basicblock` : 一个基础残差模块，即图9左边所示，由两组3x3卷积组成的路径和一条"直连"路径组成。
-  - `bottleneck` : 一个瓶颈残差模块，即图9右边所示，由上下1x1卷积和中间3x3卷积组成的路径和一条"直连"路径组成。
   - `layer_warp` : 一组残差模块，由若干个残差模块堆积而成。每组中第一个残差模块滑动窗口大小与其他可以不同，以用来减少特征图在垂直和水平方向的大小。
 
 ```python
@@ -277,7 +276,7 @@ def layer_warp(block_func, input, ch_in, ch_out, count, stride):
 
 3. 最后对网络做均值池化并返回该层。
 
-注意：除过第一层卷积层和最后一层全连接层之外，要求三组 `layer_warp` 总的含参层数能够被6整除，即 `resnet_cifar10` 的 depth 要满足 $(depth - 2) % 6 == 0$ 。
+注意：除第一层卷积层和最后一层全连接层之外，要求三组 `layer_warp` 总的含参层数能够被6整除，即 `resnet_cifar10` 的 depth 要满足 $(depth - 2) % 6 = 0$ 。
 
 ```python
 def resnet_cifar10(ipt, depth=32):
@@ -331,7 +330,7 @@ def train_program():
 
 ## Optimizer Function 配置
 
-在下面的 `Adam optimizer`，`learning_rate` 是训练的速度，与网络的训练收敛速度有关系。
+在下面的 `Adam optimizer`，`learning_rate` 是学习率，与网络的训练收敛速度有关系。
 
 ```python
 def optimizer_program():
@@ -371,8 +370,7 @@ feed_order = ['pixel', 'label']
 main_program = fluid.default_main_program()
 star_program = fluid.default_startup_program()
 
-predict = inference_program()
-avg_cost, acc = train_program(predict)
+avg_cost, acc = train_program()
 
 # Test program
 test_program = main_program.clone(for_test=True)

03.image_classification/index.cn.html

@@ -52,7 +52,7 @@
 图像分类是根据图像的语义信息将不同类别图像区分开来，是计算机视觉中重要的基本问题，也是图像检测、图像分割、物体跟踪、行为分析等其他高层视觉任务的基础。图像分类在很多领域有广泛应用，包括安防领域的人脸识别和智能视频分析等，交通领域的交通场景识别，互联网领域基于内容的图像检索和相册自动归类，医学领域的图像识别等。
 
 
-一般来说，图像分类通过手工特征或特征学习方法对整个图像进行全部描述，然后使用分类器判别物体类别，因此如何提取图像的特征至关重要。在深度学习算法之前使用较多的是基于词袋(Bag of Words)模型的物体分类方法。词袋方法从自然语言处理中引入，即一句话可以用一个装了词的袋子表示其特征，袋子中的词为句子中的单词、短语或字。对于图像而言，词袋方法需要构建字典。最简单的词袋模型框架可以设计为**底层特征抽取**、**特征编码**、**分类器设计**三个过程。
+一般来说，图像分类通过手工提取特征或特征学习方法对整个图像进行全部描述，然后使用分类器判别物体类别，因此如何提取图像的特征至关重要。在深度学习算法之前使用较多的是基于词袋(Bag of Words)模型的物体分类方法。词袋方法从自然语言处理中引入，即一句话可以用一个装了词的袋子表示其特征，袋子中的词为句子中的单词、短语或字。对于图像而言，词袋方法需要构建字典。最简单的词袋模型框架可以设计为**底层特征抽取**、**特征编码**、**分类器设计**三个过程。
 
 而基于深度学习的图像分类方法，可以通过有监督或无监督的方式**学习**层次化的特征描述，从而取代了手工设计或选择图像特征的工作。深度学习模型中的卷积神经网络(Convolution Neural Network, CNN)近年来在图像领域取得了惊人的成绩，CNN直接利用图像像素信息作为输入，最大程度上保留了输入图像的所有信息，通过卷积操作进行特征的提取和高层抽象，模型输出直接是图像识别的结果。这种基于"输入-输出"直接端到端的学习方法取得了非常好的效果，得到了广泛的应用。
 
@@ -90,15 +90,15 @@
 
 在2012年之前的传统图像分类方法可以用背景描述中提到的三步完成，但通常完整建立图像识别模型一般包括底层特征学习、特征编码、空间约束、分类器设计、模型融合等几个阶段。
 
-  1). **底层特征提取**: 通常从图像中按照固定步长、尺度提取大量局部特征描述。常用的局部特征包括SIFT(Scale-Invariant Feature Transform, 尺度不变特征转换) \[[1](#参考文献)\]、HOG(Histogram of Oriented Gradient, 方向梯度直方图) \[[2](#参考文献)\]、LBP(Local Bianray Pattern, 局部二值模式) \[[3](#参考文献)\] 等，一般也采用多种特征描述子，防止丢失过多的有用信息。
+  1). **底层特征提取**: 通常从图像中按照固定步长、尺度提取大量局部特征描述。常用的局部特征包括SIFT(Scale-Invariant Feature Transform, 尺度不变特征转换) \[[1](#参考文献)\]、HOG(Histogram of Oriented Gradient, 方向梯度直方图) \[[2](#参考文献)\]、LBP(Local Bianray Pattern, 局部二值模式) \[[3](#参考文献)\] 等，一般也采用多种特征描述，防止丢失过多的有用信息。
 
-  2). **特征编码**: 底层特征中包含了大量冗余与噪声，为了提高特征表达的鲁棒性，需要使用一种特征变换算法对底层特征进行编码，称作特征编码。常用的特征编码包括向量量化编码 \[[4](#参考文献)\]、稀疏编码 \[[5](#参考文献)\]、局部线性约束编码 \[[6](#参考文献)\]、Fisher向量编码 \[[7](#参考文献)\] 等。
+  2). **特征编码**: 底层特征中包含了大量冗余与噪声，为了提高特征表达的鲁棒性，需要使用一种特征变换算法对底层特征进行编码，称作特征编码。常用的特征编码方法包括向量量化编码 \[[4](#参考文献)\]、稀疏编码 \[[5](#参考文献)\]、局部线性约束编码 \[[6](#参考文献)\]、Fisher向量编码 \[[7](#参考文献)\] 等。
 
   3). **空间特征约束**: 特征编码之后一般会经过空间特征约束，也称作**特征汇聚**。特征汇聚是指在一个空间范围内，对每一维特征取最大值或者平均值，可以获得一定特征不变形的特征表达。金字塔特征匹配是一种常用的特征聚会方法，这种方法提出将图像均匀分块，在分块内做特征汇聚。
 
   4). **通过分类器分类**: 经过前面步骤之后一张图像可以用一个固定维度的向量进行描述，接下来就是经过分类器对图像进行分类。通常使用的分类器包括SVM(Support Vector Machine, 支持向量机)、随机森林等。而使用核方法的SVM是最为广泛的分类器，在传统图像分类任务上性能很好。
 
-这种方法在PASCAL VOC竞赛中的图像分类算法中被广泛使用 \[[18](#参考文献)\]。[NEC实验室](http://www.nec-labs.com/)在ILSVRC2010中采用SIFT和LBP特征，两个非线性编码器以及SVM分类器获得图像分类的冠军 \[[8](#参考文献)\]。
+这种传统的图像分类方法在PASCAL VOC竞赛中的图像分类算法中被广泛使用 \[[18](#参考文献)\]。[NEC实验室](http://www.nec-labs.com/)在ILSVRC2010中采用SIFT和LBP特征，两个非线性编码器以及SVM分类器获得图像分类的冠军 \[[8](#参考文献)\]。
 
 Alex Krizhevsky在2012年ILSVRC提出的CNN模型 \[[9](#参考文献)\] 取得了历史性的突破，效果大幅度超越传统方法，获得了ILSVRC2012冠军，该模型被称作AlexNet。这也是首次将深度学习用于大规模图像分类中。从AlexNet之后，涌现了一系列CNN模型，不断地在ImageNet上刷新成绩，如图4展示。随着模型变得越来越深以及精妙的结构设计，Top-5的错误率也越来越低，降到了3.5%附近。而在同样的ImageNet数据集上，人眼的辨识错误率大概在5.1%，也就是目前的深度学习模型的识别能力已经超过了人眼。
 
@@ -119,7 +119,7 @@ Alex Krizhevsky在2012年ILSVRC提出的CNN模型 \[[9](#参考文献)\] 取得
 - 卷积层(convolution layer): 执行卷积操作提取底层到高层的特征，发掘出图片局部关联性质和空间不变性质。
 - 池化层(pooling layer): 执行降采样操作。通过取卷积输出特征图中局部区块的最大值(max-pooling)或者均值(avg-pooling)。降采样也是图像处理中常见的一种操作，可以过滤掉一些不重要的高频信息。
 - 全连接层(fully-connected layer，或者fc layer): 输入层到隐藏层的神经元是全部连接的。
-- 非线性变化: 卷积层、全连接层后面一般都会接非线性变化层，例如Sigmoid、Tanh、ReLu等来增强网络的表达能力，在CNN里最常使用的为ReLu激活函数。
+- 非线性变化: 卷积层、全连接层后面一般都会接非线性变化函数，例如Sigmoid、Tanh、ReLu等来增强网络的表达能力，在CNN里最常使用的为ReLu激活函数。
 - Dropout \[[10](#参考文献)\] : 在模型训练阶段随机让一些隐层节点权重不工作，提高网络的泛化能力，一定程度上防止过拟合。
 
 另外，在训练过程中由于每层参数不断更新，会导致下一次输入分布发生变化，这样导致训练过程需要精心设计超参数。如2015年Sergey Ioffe和Christian Szegedy提出了Batch Normalization (BN)算法 \[[14](#参考文献)\] 中，每个batch对网络中的每一层特征都做归一化，使得每层分布相对稳定。BN算法不仅起到一定的正则作用，而且弱化了一些超参数的设计。经过实验证明，BN算法加速了模型收敛过程，在后来较深的模型中被广泛使用。
@@ -152,7 +152,7 @@ Inception模块如下图7所示，图(a)是最简单的设计，输出是3个卷
 图7. Inception模块
 </p>
 
-GoogleNet由多组Inception模块堆积而成。另外，在网络最后也没有采用传统的多层全连接层，而是像NIN网络一样采用了均值池化层；但与NIN不同的是，池化层后面接了一层到类别数映射的全连接层。除了这两个特点之外，由于网络中间层特征也很有判别性，GoogleNet在中间层添加了两个辅助分类器，在后向传播中增强梯度并且增强正则化，而整个网络的损失函数是这个三个分类器的损失加权求和。
+GoogleNet由多组Inception模块堆积而成。另外，在网络最后也没有采用传统的多层全连接层，而是像NIN网络一样采用了均值池化层；但与NIN不同的是，GoogleNet在池化层后加了一个全连接层来映射类别数。除了这两个特点之外，由于网络中间层特征也很有判别性，GoogleNet在中间层添加了两个辅助分类器，在后向传播中增强梯度并且增强正则化，而整个网络的损失函数是这个三个分类器的损失加权求和。
 
 GoogleNet整体网络结构如图8所示，总共22层网络：开始由3层普通的卷积组成；接下来由三组子网络组成，第一组子网络包含2个Inception模块，第二组包含5个Inception模块，第三组包含2个Inception模块；然后接均值池化层、全连接层。
 
@@ -167,7 +167,7 @@ GoogleNet整体网络结构如图8所示，总共22层网络：开始由3层普
 
 ### ResNet
 
-ResNet(Residual Network) \[[15](#参考文献)\] 是2015年ImageNet图像分类、图像物体定位和图像物体检测比赛的冠军。针对训练卷积神经网络时加深网络导致准确度下降的问题，ResNet提出了采用残差学习。在已有设计思路(BN, 小卷积核，全卷积网络)的基础上，引入了残差模块。每个残差模块包含两条路径，其中一条路径是输入特征的直连通路，另一条路径对该特征做两到三次卷积操作得到该特征的残差，最后再将两条路径上的特征相加。
+ResNet(Residual Network) \[[15](#参考文献)\] 是2015年ImageNet图像分类、图像物体定位和图像物体检测比赛的冠军。针对随着网络训练加深导致准确度下降的问题，ResNet提出了残差学习方法来减轻训练深层网络的困难。在已有设计思路(BN, 小卷积核，全卷积网络)的基础上，引入了残差模块。每个残差模块包含两条路径，其中一条路径是输入特征的直连通路，另一条路径对该特征做两到三次卷积操作得到该特征的残差，最后再将两条路径上的特征相加。
 
 残差模块如图9所示，左边是基本模块连接方式，由两个输出通道数相同的3x3卷积组成。右边是瓶颈模块(Bottleneck)连接方式，之所以称为瓶颈，是因为上面的1x1卷积用来降维(图示例即256->64)，下面的1x1卷积用来升维(图示例即64->256)，这样中间3x3卷积的输入和输出通道数都较小(图示例即64->64)。
 
@@ -257,7 +257,7 @@ def vgg_bn_drop(input):
 
 3. 最后接两层512维的全连接。
 
-4. 通过上面VGG网络提取高层特征，然后经过全连接层映射到类别维度大小的向量，再通过Softmax归一化得到每个类别的概率，也可称作分类器。
+4. 在这里，VGG网络首先提取高层特征，随后在全连接层中将其映射到和类别维度大小一致的向量上，最后通过Softmax方法计算图片划为每个类别的概率。
 
 ### ResNet
 
@@ -268,7 +268,6 @@ ResNet模型的第1、3、4步和VGG模型相同，这里不再介绍。主要
   - `conv_bn_layer` : 带BN的卷积层。
   - `shortcut` : 残差模块的"直连"路径，"直连"实际分两种形式：残差模块输入和输出特征通道数不等时，采用1x1卷积的升维操作；残差模块输入和输出通道相等时，采用直连操作。
   - `basicblock` : 一个基础残差模块，即图9左边所示，由两组3x3卷积组成的路径和一条"直连"路径组成。
-  - `bottleneck` : 一个瓶颈残差模块，即图9右边所示，由上下1x1卷积和中间3x3卷积组成的路径和一条"直连"路径组成。
   - `layer_warp` : 一组残差模块，由若干个残差模块堆积而成。每组中第一个残差模块滑动窗口大小与其他可以不同，以用来减少特征图在垂直和水平方向的大小。
 
 ```python
@@ -319,7 +318,7 @@ def layer_warp(block_func, input, ch_in, ch_out, count, stride):
 
 3. 最后对网络做均值池化并返回该层。
 
-注意：除过第一层卷积层和最后一层全连接层之外，要求三组 `layer_warp` 总的含参层数能够被6整除，即 `resnet_cifar10` 的 depth 要满足 $(depth - 2) % 6 == 0$ 。
+注意：除第一层卷积层和最后一层全连接层之外，要求三组 `layer_warp` 总的含参层数能够被6整除，即 `resnet_cifar10` 的 depth 要满足 $(depth - 2) % 6 = 0$ 。
 
 ```python
 def resnet_cifar10(ipt, depth=32):
@@ -373,7 +372,7 @@ def train_program():
 
 ## Optimizer Function 配置
 
-在下面的 `Adam optimizer`，`learning_rate` 是训练的速度，与网络的训练收敛速度有关系。
+在下面的 `Adam optimizer`，`learning_rate` 是学习率，与网络的训练收敛速度有关系。
 
 ```python
 def optimizer_program():
@@ -413,8 +412,7 @@ feed_order = ['pixel', 'label']
 main_program = fluid.default_main_program()
 star_program = fluid.default_startup_program()
 
-predict = inference_program()
-avg_cost, acc = train_program(predict)
+avg_cost, acc = train_program()
 
 # Test program
 test_program = main_program.clone(for_test=True)

04.word2vec/README.cn.md

@@ -14,7 +14,7 @@ One-hot vector虽然自然，但是用处有限。比如，在互联网广告系
 
 在机器学习领域里，各种“知识”被各种模型表示，词向量模型(word embedding model)就是其中的一类。通过词向量模型可将一个 one-hot vector映射到一个维度更低的实数向量（embedding vector），如$embedding(母亲节) = [0.3, 4.2, -1.5, ...], embedding(康乃馨) = [0.2, 5.6, -2.3, ...]$。在这个映射到的实数向量表示中，希望两个语义（或用法）上相似的词对应的词向量“更像”，这样如“母亲节”和“康乃馨”的对应词向量的余弦相似度就不再为零了。
 
-词向量模型可以是概率模型、共生矩阵(co-occurrence matrix)模型或神经元网络模型。在用神经网络求词向量之前，传统做法是统计一个词语的共生矩阵$X$。$X$是一个$|V| \times |V|$ 大小的矩阵，$X_{ij}$表示在所有语料中，词汇表`V`(vocabulary)中第i个词和第j个词同时出现的词数，$|V|$为词汇表的大小。对$X$做矩阵分解（如奇异值分解，Singular Value Decomposition \[[5](#参考文献)\]），得到的$U$即视为所有词的词向量：
+词向量模型可以是概率模型、共生矩阵(co-occurrence matrix)模型或神经元网络模型。在用神经网络求词向量之前，传统做法是统计一个词语的共生矩阵$X$。$X$是一个$|V| \times |V|$ 大小的矩阵，$X_{ij}$表示在所有语料中，词汇表$V$(vocabulary)中第i个词和第j个词同时出现的词数，$|V|$为词汇表的大小。对$X$做矩阵分解（如奇异值分解，Singular Value Decomposition \[[5](#参考文献)\]），得到的$U$即视为所有词的词向量：
 
 $$X = USV^T$$
 
@@ -26,7 +26,7 @@ $$X = USV^T$$
 
 3) 需要手动去掉停用词（如although, a,...），不然这些频繁出现的词也会影响矩阵分解的效果。
 
-基于神经网络的模型不需要计算存储一个在全语料上统计的大表，而是通过学习语义信息得到词向量，因此能很好地解决以上问题。在本章里，我们将展示基于神经网络训练词向量的细节，以及如何用PaddlePaddle训练一个词向量模型。
+基于神经网络的模型不需要计算和存储一个在全语料上统计产生的大表，而是通过学习语义信息得到词向量，因此能很好地解决以上问题。在本章里，我们将展示基于神经网络训练词向量的细节，以及如何用PaddlePaddle训练一个词向量模型。
 
 
 ## 效果展示
@@ -77,7 +77,7 @@ $$P(w_1, ..., w_T) = \prod_{t=1}^TP(w_t | w_1, ... , w_{t-1})$$
 
 在计算语言学中，n-gram是一种重要的文本表示方法，表示一个文本中连续的n个项。基于具体的应用场景，每一项可以是一个字母、单词或者音节。 n-gram模型也是统计语言模型中的一种重要方法，用n-gram训练语言模型时，一般用每个n-gram的历史n-1个词语组成的内容来预测第n个词。
 
-Yoshua Bengio等科学家就于2003年在著名论文 Neural Probabilistic Language Models \[[1](#参考文献)\] 中介绍如何学习一个神经元网络表示的词向量模型。文中的神经概率语言模型（Neural Network Language Model，NNLM）通过一个线性映射和一个非线性隐层连接，同时学习了语言模型和词向量，即通过学习大量语料得到词语的向量表达，通过这些向量得到整个句子的概率。用这种方法学习语言模型可以克服维度灾难（curse of dimensionality）,即训练和测试数据不同导致的模型不准。注意：由于“神经概率语言模型”说法较为泛泛，我们在这里不用其NNLM的本名，考虑到其具体做法，本文中称该模型为N-gram neural model。
+Yoshua Bengio等科学家就于2003年在著名论文 Neural Probabilistic Language Models \[[1](#参考文献)\] 中介绍如何学习一个神经元网络表示的词向量模型。文中的神经概率语言模型（Neural Network Language Model，NNLM）通过一个线性映射和一个非线性隐层连接，同时学习了语言模型和词向量，即通过学习大量语料得到词语的向量表达，通过这些向量得到整个句子的概率。因所有的词语都用一个低维向量来表示，用这种方法学习语言模型可以克服维度灾难（curse of dimensionality）。注意：由于“神经概率语言模型”说法较为泛泛，我们在这里不用其NNLM的本名，考虑到其具体做法，本文中称该模型为N-gram neural model。
 
 我们在上文中已经讲到用条件概率建模语言模型，即一句话中第$t$个词的概率和该句话的前$t-1$个词相关。可实际上越远的词语其实对该词的影响越小，那么如果考虑一个n-gram, 每个词都只受其前面`n-1`个词的影响，则有：
 
@@ -95,15 +95,15 @@ $$\frac{1}{T}\sum_t f(w_t, w_{t-1}, ..., w_{t-n+1};\theta) + R(\theta)$$
 </p>
 
 图2展示了N-gram神经网络模型，从下往上看，该模型分为以下几个部分：
- - 对于每个样本，模型输入$w_{t-n+1},...w_{t-1}$, 输出句子第t个词为字典中`|V|`个词的概率。
+ - 对于每个样本，模型输入$w_{t-n+1},...w_{t-1}$, 输出句子第t个词在字典中`|V|`个词上的概率分布。
 
    每个输入词$w_{t-n+1},...w_{t-1}$首先通过映射矩阵映射到词向量$C(w_{t-n+1}),...C(w_{t-1})$。
 
- - 然后所有词语的词向量连接成一个大向量，并经过一个非线性映射得到历史词语的隐层表示：
+ - 然后所有词语的词向量拼接成一个大向量，并经过一个非线性映射得到历史词语的隐层表示：
 
     $$g=Utanh(\theta^Tx + b_1) + Wx + b_2$$
 
-    其中，$x$为所有词语的词向量连接成的大向量，表示文本历史特征；$\theta$、$U$、$b_1$、$b_2$和$W$分别为词向量层到隐层连接的参数。$g$表示未经归一化的所有输出单词概率，$g_i$表示未经归一化的字典中第$i$个单词的输出概率。
+    其中，$x$为所有词语的词向量拼接成的大向量，表示文本历史特征；$\theta$、$U$、$b_1$、$b_2$和$W$分别为词向量层到隐层连接的参数。$g$表示未经归一化的所有输出单词概率，$g_i$表示未经归一化的字典中第$i$个单词的输出概率。
 
  - 根据softmax的定义，通过归一化$g_i$, 生成目标词$w_t$的概率为：
 
@@ -111,7 +111,7 @@ $$\frac{1}{T}\sum_t f(w_t, w_{t-1}, ..., w_{t-n+1};\theta) + R(\theta)$$
 
  - 整个网络的损失值(cost)为多类分类交叉熵，用公式表示为
 
-   $$J(\theta) = -\sum_{i=1}^N\sum_{c=1}^{|V|}y_k^{i}log(softmax(g_k^i))$$
+   $$J(\theta) = -\sum_{i=1}^N\sum_{k=1}^{|V|}y_k^{i}log(softmax(g_k^i))$$
 
    其中$y_k^i$表示第$i$个样本第$k$类的真实标签(0或1)，$softmax(g_k^i)$表示第i个样本第k类softmax输出的概率。
 
@@ -213,15 +213,16 @@ from __future__ import print_function
 
 ```
 
-然后，定义参数：
+然后，定义参数：
+
 ```python
-EMBED_SIZE = 32
-HIDDEN_SIZE = 256
-N = 5
-BATCH_SIZE = 100
-PASS_NUM = 100
+EMBED_SIZE = 32      # embedding维度
+HIDDEN_SIZE = 256    # 隐层大小
+N = 5                # ngram大小，这里固定取5
+BATCH_SIZE = 100     # batch大小
+PASS_NUM = 100       # 训练轮数
 
-use_cuda = False  # set to True if training with GPU
+use_cuda = False  # 如果用GPU训练，则设置为True
 
 word_dict = paddle.dataset.imikolov.build_dict()
 dict_size = len(word_dict)
@@ -269,13 +270,13 @@ def inference_program(words, is_sparse):
     return predict_word
 ```
 
-- 基于以上的神经网络结构，我们可以如下定义我们的`训练`方法
+- 基于以上的神经网络结构，我们可以如下定义我们的训练方法
 
 ```python
 def train_program(predict_word):
-    # The declaration of 'next_word' must be after the invoking of inference_program,
-    # or the data input order of train program would be [next_word, firstw, secondw,
-    # thirdw, fourthw], which is not correct.
+    # 'next_word'的定义必须要在inference_program的声明之后，
+    # 否则train program输入数据的顺序就变成了[next_word, firstw, secondw,
+    # thirdw, fourthw], 这是不正确的.
     next_word = fluid.layers.data(name='nextw', shape=[1], dtype='int64')
     cost = fluid.layers.cross_entropy(input=predict_word, label=next_word)
     avg_cost = fluid.layers.mean(cost)
@@ -357,11 +358,11 @@ def train(if_use_cuda, params_dirname, is_sparse=True):
                     outs = train_test(test_program, test_reader)
 
                     print("Step %d: Average Cost %f" % (step, outs[0]))
-
-                    # it will take a few hours.
-                    # If average cost is lower than 5.8, we consider the model good enough to stop.
-                    # Note 5.8 is a relatively high value. In order to get a better model, one should
-                    # aim for avg_cost lower than 3.5. But the training could take longer time.
+
+                    # 整个训练过程要花费几个小时，如果平均损失低于5.8，
+                    # 我们就认为模型已经达到很好的效果可以停止训练了。
+                    # 注意5.8是一个相对较高的值，为了获取更好的模型，可以将
+                    # 这里的阈值设为3.5，但训练时间也会更长。
                     if outs[0] < 5.8:
                         if params_dirname is not None:
                             fluid.io.save_inference_model(params_dirname, [
@@ -377,7 +378,7 @@ def train(if_use_cuda, params_dirname, is_sparse=True):
     train_loop()
 ```
 
-- `train_loop`将会开始训练。期间打印返回的监控情况如下：
+- `train_loop`将会开始训练。期间打印训练过程的日志如下：
 
 ```text
 Step 0: Average Cost 7.337213
@@ -400,23 +401,16 @@ def infer(use_cuda, params_dirname=None):
     exe = fluid.Executor(place)
 
     inference_scope = fluid.core.Scope()
-
-    inference_scope = fluid.core.Scope()
-    with fluid.scope_guard(inference_scope):
-        # Use fluid.io.load_inference_model to obtain the inference program desc,
-        # the feed_target_names (the names of variables that will be feeded
-        # data using feed operators), and the fetch_targets (variables that
-        # we want to obtain data from using fetch operators).
+    with fluid.scope_guard(inference_scope):
+        # 使用fluid.io.load_inference_model获取inference program，
+        # feed变量的名称feed_target_names和从scope中fetch的对象fetch_targets
         [inferencer, feed_target_names,
          fetch_targets] = fluid.io.load_inference_model(params_dirname, exe)
 
-        # Setup inputs by creating 4 LoDTensors representing 4 words. Here each word
-        # is simply an index to look up for the corresponding word vector and hence
-        # the shape of word (base_shape) should be [1]. The recursive_sequence_lengths,
-        # which is length-based level of detail (lod) of each LoDTensor, should be [[1]]
-        # meaning there is only one level of detail and there is only one sequence of
-        # one word on this level.
-        # Note that recursive_sequence_lengths should be a list of lists.
+        # 设置输入，用四个LoDTensor来表示4个词语。这里每个词都是一个id，
+        # 用来查询embedding表获取对应的词向量，因此其形状大小是[1]。
+        # recursive_sequence_lengths设置的是基于长度的LoD，因此都应该设为[[1]]
+        # 注意recursive_sequence_lengths是列表的列表
         data1 = [[211]]  # 'among'
         data2 = [[6]]  # 'a'
         data3 = [[96]]  # 'group'
@@ -433,8 +427,8 @@ def infer(use_cuda, params_dirname=None):
         assert feed_target_names[2] == 'thirdw'
         assert feed_target_names[3] == 'fourthw'
 
-        # Construct feed as a dictionary of {feed_target_name: feed_target_data}
-        # and results will contain a list of data corresponding to fetch_targets.
+        # 构造feed词典 {feed_target_name: feed_target_data}
+        # 预测结果包含在results之中
         results = exe.run(
             inferencer,
             feed={
@@ -453,17 +447,16 @@ def infer(use_cuda, params_dirname=None):
             key for key, value in six.iteritems(word_dict)
             if value == most_possible_word_index
         ][0])
-
-
 ```
 
-由于词向量矩阵本身比较稀疏，训练的过程如果要达到一定的精度耗时会比较长。为了能简单看到效果，教程只设置了经过很少的训练就结束并得到如下的预测。我们的模型预测 `among a group of` 的下一个词是`the`。这比较符合文法规律。如果我们训练时间更长，比如几个小时，那么我们会得到的下一个预测是 `workers`。
+由于词向量矩阵本身比较稀疏，训练的过程如果要达到一定的精度耗时会比较长。为了能简单看到效果，教程只设置了经过很少的训练就结束并得到如下的预测。我们的模型预测 `among a group of` 的下一个词是`the`。这比较符合文法规律。如果我们训练时间更长，比如几个小时，那么我们会得到的下一个预测是 `workers`。预测输出的格式如下所示:
 
 ```text
 [[0.03768077 0.03463154 0.00018074 ... 0.00022283 0.00029888 0.02967956]]
 0
 the
-```
+```
+其中第一行表示预测词在词典上的概率分布，第二行表示概率最大的词对应的id，第三行表示概率最大的词。
 
 整个程序的入口很简单：
 

04.word2vec/index.cn.html

@@ -56,7 +56,7 @@ One-hot vector虽然自然，但是用处有限。比如，在互联网广告系
 
 在机器学习领域里，各种“知识”被各种模型表示，词向量模型(word embedding model)就是其中的一类。通过词向量模型可将一个 one-hot vector映射到一个维度更低的实数向量（embedding vector），如$embedding(母亲节) = [0.3, 4.2, -1.5, ...], embedding(康乃馨) = [0.2, 5.6, -2.3, ...]$。在这个映射到的实数向量表示中，希望两个语义（或用法）上相似的词对应的词向量“更像”，这样如“母亲节”和“康乃馨”的对应词向量的余弦相似度就不再为零了。
 
-词向量模型可以是概率模型、共生矩阵(co-occurrence matrix)模型或神经元网络模型。在用神经网络求词向量之前，传统做法是统计一个词语的共生矩阵$X$。$X$是一个$|V| \times |V|$ 大小的矩阵，$X_{ij}$表示在所有语料中，词汇表`V`(vocabulary)中第i个词和第j个词同时出现的词数，$|V|$为词汇表的大小。对$X$做矩阵分解（如奇异值分解，Singular Value Decomposition \[[5](#参考文献)\]），得到的$U$即视为所有词的词向量：
+词向量模型可以是概率模型、共生矩阵(co-occurrence matrix)模型或神经元网络模型。在用神经网络求词向量之前，传统做法是统计一个词语的共生矩阵$X$。$X$是一个$|V| \times |V|$ 大小的矩阵，$X_{ij}$表示在所有语料中，词汇表$V$(vocabulary)中第i个词和第j个词同时出现的词数，$|V|$为词汇表的大小。对$X$做矩阵分解（如奇异值分解，Singular Value Decomposition \[[5](#参考文献)\]），得到的$U$即视为所有词的词向量：
 
 $$X = USV^T$$
 
@@ -68,7 +68,7 @@ $$X = USV^T$$
 
 3) 需要手动去掉停用词（如although, a,...），不然这些频繁出现的词也会影响矩阵分解的效果。
 
-基于神经网络的模型不需要计算存储一个在全语料上统计的大表，而是通过学习语义信息得到词向量，因此能很好地解决以上问题。在本章里，我们将展示基于神经网络训练词向量的细节，以及如何用PaddlePaddle训练一个词向量模型。
+基于神经网络的模型不需要计算和存储一个在全语料上统计产生的大表，而是通过学习语义信息得到词向量，因此能很好地解决以上问题。在本章里，我们将展示基于神经网络训练词向量的细节，以及如何用PaddlePaddle训练一个词向量模型。
 
 
 ## 效果展示
@@ -119,7 +119,7 @@ $$P(w_1, ..., w_T) = \prod_{t=1}^TP(w_t | w_1, ... , w_{t-1})$$
 
 在计算语言学中，n-gram是一种重要的文本表示方法，表示一个文本中连续的n个项。基于具体的应用场景，每一项可以是一个字母、单词或者音节。 n-gram模型也是统计语言模型中的一种重要方法，用n-gram训练语言模型时，一般用每个n-gram的历史n-1个词语组成的内容来预测第n个词。
 
-Yoshua Bengio等科学家就于2003年在著名论文 Neural Probabilistic Language Models \[[1](#参考文献)\] 中介绍如何学习一个神经元网络表示的词向量模型。文中的神经概率语言模型（Neural Network Language Model，NNLM）通过一个线性映射和一个非线性隐层连接，同时学习了语言模型和词向量，即通过学习大量语料得到词语的向量表达，通过这些向量得到整个句子的概率。用这种方法学习语言模型可以克服维度灾难（curse of dimensionality）,即训练和测试数据不同导致的模型不准。注意：由于“神经概率语言模型”说法较为泛泛，我们在这里不用其NNLM的本名，考虑到其具体做法，本文中称该模型为N-gram neural model。
+Yoshua Bengio等科学家就于2003年在著名论文 Neural Probabilistic Language Models \[[1](#参考文献)\] 中介绍如何学习一个神经元网络表示的词向量模型。文中的神经概率语言模型（Neural Network Language Model，NNLM）通过一个线性映射和一个非线性隐层连接，同时学习了语言模型和词向量，即通过学习大量语料得到词语的向量表达，通过这些向量得到整个句子的概率。因所有的词语都用一个低维向量来表示，用这种方法学习语言模型可以克服维度灾难（curse of dimensionality）。注意：由于“神经概率语言模型”说法较为泛泛，我们在这里不用其NNLM的本名，考虑到其具体做法，本文中称该模型为N-gram neural model。
 
 我们在上文中已经讲到用条件概率建模语言模型，即一句话中第$t$个词的概率和该句话的前$t-1$个词相关。可实际上越远的词语其实对该词的影响越小，那么如果考虑一个n-gram, 每个词都只受其前面`n-1`个词的影响，则有：
 
@@ -137,15 +137,15 @@ $$\frac{1}{T}\sum_t f(w_t, w_{t-1}, ..., w_{t-n+1};\theta) + R(\theta)$$
 </p>
 
 图2展示了N-gram神经网络模型，从下往上看，该模型分为以下几个部分：
- - 对于每个样本，模型输入$w_{t-n+1},...w_{t-1}$, 输出句子第t个词为字典中`|V|`个词的概率。
+ - 对于每个样本，模型输入$w_{t-n+1},...w_{t-1}$, 输出句子第t个词在字典中`|V|`个词上的概率分布。
 
    每个输入词$w_{t-n+1},...w_{t-1}$首先通过映射矩阵映射到词向量$C(w_{t-n+1}),...C(w_{t-1})$。
 
- - 然后所有词语的词向量连接成一个大向量，并经过一个非线性映射得到历史词语的隐层表示：
+ - 然后所有词语的词向量拼接成一个大向量，并经过一个非线性映射得到历史词语的隐层表示：
 
     $$g=Utanh(\theta^Tx + b_1) + Wx + b_2$$
 
-    其中，$x$为所有词语的词向量连接成的大向量，表示文本历史特征；$\theta$、$U$、$b_1$、$b_2$和$W$分别为词向量层到隐层连接的参数。$g$表示未经归一化的所有输出单词概率，$g_i$表示未经归一化的字典中第$i$个单词的输出概率。
+    其中，$x$为所有词语的词向量拼接成的大向量，表示文本历史特征；$\theta$、$U$、$b_1$、$b_2$和$W$分别为词向量层到隐层连接的参数。$g$表示未经归一化的所有输出单词概率，$g_i$表示未经归一化的字典中第$i$个单词的输出概率。
 
  - 根据softmax的定义，通过归一化$g_i$, 生成目标词$w_t$的概率为：
 
@@ -153,7 +153,7 @@ $$\frac{1}{T}\sum_t f(w_t, w_{t-1}, ..., w_{t-n+1};\theta) + R(\theta)$$
 
  - 整个网络的损失值(cost)为多类分类交叉熵，用公式表示为
 
-   $$J(\theta) = -\sum_{i=1}^N\sum_{c=1}^{|V|}y_k^{i}log(softmax(g_k^i))$$
+   $$J(\theta) = -\sum_{i=1}^N\sum_{k=1}^{|V|}y_k^{i}log(softmax(g_k^i))$$
 
    其中$y_k^i$表示第$i$个样本第$k$类的真实标签(0或1)，$softmax(g_k^i)$表示第i个样本第k类softmax输出的概率。
 
@@ -255,15 +255,16 @@ from __future__ import print_function
 
 ```
 
-然后，定义参数：
+然后，定义参数：
+
 ```python
-EMBED_SIZE = 32
-HIDDEN_SIZE = 256
-N = 5
-BATCH_SIZE = 100
-PASS_NUM = 100
+EMBED_SIZE = 32      # embedding维度
+HIDDEN_SIZE = 256    # 隐层大小
+N = 5                # ngram大小，这里固定取5
+BATCH_SIZE = 100     # batch大小
+PASS_NUM = 100       # 训练轮数
 
-use_cuda = False  # set to True if training with GPU
+use_cuda = False  # 如果用GPU训练，则设置为True
 
 word_dict = paddle.dataset.imikolov.build_dict()
 dict_size = len(word_dict)
@@ -311,13 +312,13 @@ def inference_program(words, is_sparse):
     return predict_word
 ```
 
-- 基于以上的神经网络结构，我们可以如下定义我们的`训练`方法
+- 基于以上的神经网络结构，我们可以如下定义我们的训练方法
 
 ```python
 def train_program(predict_word):
-    # The declaration of 'next_word' must be after the invoking of inference_program,
-    # or the data input order of train program would be [next_word, firstw, secondw,
-    # thirdw, fourthw], which is not correct.
+    # 'next_word'的定义必须要在inference_program的声明之后，
+    # 否则train program输入数据的顺序就变成了[next_word, firstw, secondw,
+    # thirdw, fourthw], 这是不正确的.
     next_word = fluid.layers.data(name='nextw', shape=[1], dtype='int64')
     cost = fluid.layers.cross_entropy(input=predict_word, label=next_word)
     avg_cost = fluid.layers.mean(cost)
@@ -399,11 +400,11 @@ def train(if_use_cuda, params_dirname, is_sparse=True):
                     outs = train_test(test_program, test_reader)
 
                     print("Step %d: Average Cost %f" % (step, outs[0]))
-
-                    # it will take a few hours.
-                    # If average cost is lower than 5.8, we consider the model good enough to stop.
-                    # Note 5.8 is a relatively high value. In order to get a better model, one should
-                    # aim for avg_cost lower than 3.5. But the training could take longer time.
+
+                    # 整个训练过程要花费几个小时，如果平均损失低于5.8，
+                    # 我们就认为模型已经达到很好的效果可以停止训练了。
+                    # 注意5.8是一个相对较高的值，为了获取更好的模型，可以将
+                    # 这里的阈值设为3.5，但训练时间也会更长。
                     if outs[0] < 5.8:
                         if params_dirname is not None:
                             fluid.io.save_inference_model(params_dirname, [
@@ -419,7 +420,7 @@ def train(if_use_cuda, params_dirname, is_sparse=True):
     train_loop()
 ```
 
-- `train_loop`将会开始训练。期间打印返回的监控情况如下：
+- `train_loop`将会开始训练。期间打印训练过程的日志如下：
 
 ```text
 Step 0: Average Cost 7.337213
@@ -442,23 +443,16 @@ def infer(use_cuda, params_dirname=None):
     exe = fluid.Executor(place)
 
     inference_scope = fluid.core.Scope()
-
-    inference_scope = fluid.core.Scope()
-    with fluid.scope_guard(inference_scope):
-        # Use fluid.io.load_inference_model to obtain the inference program desc,
-        # the feed_target_names (the names of variables that will be feeded
-        # data using feed operators), and the fetch_targets (variables that
-        # we want to obtain data from using fetch operators).
+    with fluid.scope_guard(inference_scope):
+        # 使用fluid.io.load_inference_model获取inference program，
+        # feed变量的名称feed_target_names和从scope中fetch的对象fetch_targets
         [inferencer, feed_target_names,
          fetch_targets] = fluid.io.load_inference_model(params_dirname, exe)
 
-        # Setup inputs by creating 4 LoDTensors representing 4 words. Here each word
-        # is simply an index to look up for the corresponding word vector and hence
-        # the shape of word (base_shape) should be [1]. The recursive_sequence_lengths,
-        # which is length-based level of detail (lod) of each LoDTensor, should be [[1]]
-        # meaning there is only one level of detail and there is only one sequence of
-        # one word on this level.
-        # Note that recursive_sequence_lengths should be a list of lists.
+        # 设置输入，用四个LoDTensor来表示4个词语。这里每个词都是一个id，
+        # 用来查询embedding表获取对应的词向量，因此其形状大小是[1]。
+        # recursive_sequence_lengths设置的是基于长度的LoD，因此都应该设为[[1]]
+        # 注意recursive_sequence_lengths是列表的列表
         data1 = [[211]]  # 'among'
         data2 = [[6]]  # 'a'
         data3 = [[96]]  # 'group'
@@ -475,8 +469,8 @@ def infer(use_cuda, params_dirname=None):
         assert feed_target_names[2] == 'thirdw'
         assert feed_target_names[3] == 'fourthw'
 
-        # Construct feed as a dictionary of {feed_target_name: feed_target_data}
-        # and results will contain a list of data corresponding to fetch_targets.
+        # 构造feed词典 {feed_target_name: feed_target_data}
+        # 预测结果包含在results之中
         results = exe.run(
             inferencer,
             feed={
@@ -495,17 +489,16 @@ def infer(use_cuda, params_dirname=None):
             key for key, value in six.iteritems(word_dict)
             if value == most_possible_word_index
         ][0])
-
-
 ```
 
-由于词向量矩阵本身比较稀疏，训练的过程如果要达到一定的精度耗时会比较长。为了能简单看到效果，教程只设置了经过很少的训练就结束并得到如下的预测。我们的模型预测 `among a group of` 的下一个词是`the`。这比较符合文法规律。如果我们训练时间更长，比如几个小时，那么我们会得到的下一个预测是 `workers`。
+由于词向量矩阵本身比较稀疏，训练的过程如果要达到一定的精度耗时会比较长。为了能简单看到效果，教程只设置了经过很少的训练就结束并得到如下的预测。我们的模型预测 `among a group of` 的下一个词是`the`。这比较符合文法规律。如果我们训练时间更长，比如几个小时，那么我们会得到的下一个预测是 `workers`。预测输出的格式如下所示:
 
 ```text
 [[0.03768077 0.03463154 0.00018074 ... 0.00022283 0.00029888 0.02967956]]
 0
 the
-```
+```
+其中第一行表示预测词在词典上的概率分布，第二行表示概率最大的词对应的id，第三行表示概率最大的词。
 
 整个程序的入口很简单：
 

05.recommender_system/README.cn.md

@@ -4,19 +4,19 @@
 
 ## 背景介绍
 
-在网络技术不断发展和电子商务规模不断扩大的背景下，商品数量和种类快速增长，用户需要花费大量时间才能找到自己想买的商品，这就是信息超载问题。为了解决这个难题，推荐系统（Recommender System）应运而生。
+在网络技术不断发展和电子商务规模不断扩大的背景下，商品数量和种类快速增长，用户需要花费大量时间才能找到自己想买的商品，这就是信息超载问题。为了解决这个难题，个性化推荐系统（Recommender System）应运而生。
 
-个性化推荐系统是信息过滤系统（Information Filtering System）的子集，它可以用在很多领域，如电影、音乐、电商和 Feed 流推荐等。推荐系统通过分析、挖掘用户行为，发现用户的个性化需求与兴趣特点，将用户可能感兴趣的信息或商品推荐给用户。与搜索引擎不同，推荐系统不需要用户准确地描述出自己的需求，而是根据分析历史行为建模，主动提供满足用户兴趣和需求的信息。
+个性化推荐系统是信息过滤系统（Information Filtering System）的子集，它可以用在很多领域，如电影、音乐、电商和 Feed 流推荐等。个性化推荐系统通过分析、挖掘用户行为，发现用户的个性化需求与兴趣特点，将用户可能感兴趣的信息或商品推荐给用户。与搜索引擎不同，个性化推荐系统不需要用户准确地描述出自己的需求，而是根据用户的历史行为进行建模，主动提供满足用户兴趣和需求的信息。
 
-传统的推荐系统方法主要有：
+1994年明尼苏达大学推出的GroupLens系统[[1](#参考文献)]一般被认为是个性化推荐系统成为一个相对独立的研究方向的标志。该系统首次提出了基于协同过滤来完成推荐任务的思想，此后，基于该模型的协同过滤推荐引领了个性化推荐系统十几年的发展方向。
 
-- 协同过滤推荐（Collaborative Filtering Recommendation）：该方法收集分析用户历史行为、活动、偏好，计算一个用户与其他用户的相似度，利用目标用户的相似用户对商品评价的加权评价值，来预测目标用户对特定商品的喜好程度。优点是可以给用户推荐未浏览过的新产品；缺点是对于没有任何行为的新用户存在冷启动的问题，同时也存在用户与商品之间的交互数据不够多造成的稀疏问题，会导致模型难以找到相近用户。
-- 基于内容过滤推荐[[1](#参考文献)]（Content-based Filtering Recommendation）：该方法利用商品的内容描述，抽象出有意义的特征，通过计算用户的兴趣和商品描述之间的相似度，来给用户做推荐。优点是简单直接，不需要依据其他用户对商品的评价，而是通过商品属性进行商品相似度度量，从而推荐给用户所感兴趣商品的相似商品；缺点是对于没有任何行为的新用户同样存在冷启动的问题。
-- 组合推荐[[2](#参考文献)]（Hybrid Recommendation）：运用不同的输入和技术共同进行推荐，以弥补各自推荐技术的缺点。
+传统的个性化推荐系统方法主要有：
 
-其中协同过滤是应用最广泛的技术之一，它又可以分为多个子类：基于用户 （User-Based）的推荐[[3](#参考文献)] 、基于物品（Item-Based）的推荐[[4](#参考文献)]、基于社交网络关系（Social-Based）的推荐[[5](#参考文献)]、基于模型（Model-based）的推荐等。1994年明尼苏达大学推出的GroupLens系统[[3](#参考文献)]一般被认为是推荐系统成为一个相对独立的研究方向的标志。该系统首次提出了基于协同过滤来完成推荐任务的思想，此后，基于该模型的协同过滤推荐引领了推荐系统十几年的发展方向。
+- 协同过滤推荐（Collaborative Filtering Recommendation）：该方法是应用最广泛的技术之一，需要收集和分析用户的历史行为、活动和偏好。它通常可以分为两个子类：基于用户 （User-Based）的推荐[[1](#参考文献)] 和基于物品（Item-Based）的推荐[[2](#参考文献)]。该方法的一个关键优势是它不依赖于机器去分析物品的内容特征，因此它无需理解物品本身也能够准确地推荐诸如电影之类的复杂物品；缺点是对于没有任何行为的新用户存在冷启动的问题，同时也存在用户与商品之间的交互数据不够多造成的稀疏问题。值得一提的是，社交网络[[3](#参考文献)]或地理位置等上下文信息都可以结合到协同过滤中去。
+- 基于内容过滤推荐[[4](#参考文献)]（Content-based Filtering Recommendation）：该方法利用商品的内容描述，抽象出有意义的特征，通过计算用户的兴趣和商品描述之间的相似度，来给用户做推荐。优点是简单直接，不需要依据其他用户对商品的评价，而是通过商品属性进行商品相似度度量，从而推荐给用户所感兴趣商品的相似商品；缺点是对于没有任何行为的新用户同样存在冷启动的问题。
+- 组合推荐[[5](#参考文献)]（Hybrid Recommendation）：运用不同的输入和技术共同进行推荐，以弥补各自推荐技术的缺点。
 
-深度学习具有优秀的自动提取特征的能力，能够学习多层次的抽象特征表示，并对异质或跨域的内容信息进行学习，可以一定程度上处理推荐系统冷启动问题[[6](#参考文献)]。本教程主要介绍个性化推荐的深度学习模型，以及如何使用PaddlePaddle实现模型。
+近些年来，深度学习在很多领域都取得了巨大的成功。学术界和工业界都在尝试将深度学习应用于个性化推荐系统领域中。深度学习具有优秀的自动提取特征的能力，能够学习多层次的抽象特征表示，并对异质或跨域的内容信息进行学习，可以一定程度上处理个性化推荐系统冷启动问题[[6](#参考文献)]。本教程主要介绍个性化推荐的深度学习模型，以及如何使用PaddlePaddle实现模型。
 
 ## 效果展示
 
@@ -30,15 +30,15 @@ Prediction Score is 4.25
 
 ## 模型概览
 
-本章中，我们首先介绍YouTube的视频推荐系统[[7](#参考文献)]，然后介绍我们实现的融合推荐模型。
+本章中，我们首先介绍YouTube的视频个性化推荐系统[[7](#参考文献)]，然后介绍我们实现的融合推荐模型。
 
-### YouTube的深度神经网络推荐系统
+### YouTube的深度神经网络个性化推荐系统
 
-YouTube是世界上最大的视频上传、分享和发现网站，YouTube推荐系统为超过10亿用户从不断增长的视频库中推荐个性化的内容。整个系统由两个神经网络组成：候选生成网络和排序网络。候选生成网络从百万量级的视频库中生成上百个候选，排序网络对候选进行打分排序，输出排名最高的数十个结果。系统结构如图1所示：
+YouTube是世界上最大的视频上传、分享和发现网站，YouTube个性化推荐系统为超过10亿用户从不断增长的视频库中推荐个性化的内容。整个系统由两个神经网络组成：候选生成网络和排序网络。候选生成网络从百万量级的视频库中生成上百个候选，排序网络对候选进行打分排序，输出排名最高的数十个结果。系统结构如图1所示：
 
 <p align="center">
 <img src="https://github.com/PaddlePaddle/book/blob/develop/05.recommender_system/image/YouTube_Overview.png?raw=true" width="70%" ><br/>
-图1. YouTube 推荐系统结构
+图1. YouTube 个性化推荐系统结构
 </p>
 
 #### 候选生成网络（Candidate Generation Network）
@@ -64,7 +64,7 @@ $$P(\omega=i|u)=\frac{e^{v_{i}u}}{\sum_{j \in V}e^{v_{j}u}}$$
 排序网络的结构类似于候选生成网络，但是它的目标是对候选进行更细致的打分排序。和传统广告排序中的特征抽取方法类似，这里也构造了大量的用于视频排序的相关特征（如视频 ID、上次观看时间等）。这些特征的处理方式和候选生成网络类似，不同之处是排序网络的顶部是一个加权逻辑回归（weighted logistic regression），它对所有候选视频进行打分，从高到底排序后将分数较高的一些视频返回给用户。
 
 ### 融合推荐模型
-本节会使卷积神经网络（Convolutional Neural Networks）来学习电影名称的表示。下面会依次介绍文本卷积神经网络以及融合推荐模型。
+本节会使用卷积神经网络（Convolutional Neural Networks）来学习电影名称的表示。下面会依次介绍文本卷积神经网络以及融合推荐模型。
 
 #### 文本卷积神经网络（CNN）
 
@@ -77,7 +77,7 @@ $$P(\omega=i|u)=\frac{e^{v_{i}u}}{\sum_{j \in V}e^{v_{j}u}}$$
 图3. 卷积神经网络文本分类模型
 </p>
 
-假设待处理句子的长度为$n$，其中第$i$个词的词向量（word embedding）为$x_i\in\mathbb{R}^k$，$k$为维度大小。
+假设待处理句子的长度为$n$，其中第$i$个词的词向量为$x_i\in\mathbb{R}^k$，$k$为维度大小。
 
 首先，进行词向量的拼接操作：将每$h$个词拼接起来形成一个大小为$h$的词窗口，记为$x_{i:i+h-1}$，它表示词序列$x_{i},x_{i+1},\ldots,x_{i+h-1}$的拼接，其中，$i$表示词窗口中第一个词在整个句子中的位置，取值范围从$1$到$n-h+1$，$x_{i:i+h-1}\in\mathbb{R}^{hk}$。
 
@@ -89,9 +89,9 @@ $$c=[c_1,c_2,\ldots,c_{n-h+1}], c \in \mathbb{R}^{n-h+1}$$
 
 $$\hat c=max(c)$$
 
-#### 模型概览
+#### 融合推荐模型概览
 
-在融合推荐模型的电影推荐系统中：
+在融合推荐模型的电影个性化推荐系统中：
 
 1. 首先，使用用户特征和电影特征作为神经网络的输入，其中：
 
@@ -103,10 +103,9 @@ $$\hat c=max(c)$$
 
 3. 对电影特征，将电影ID以类似用户ID的方式进行处理，电影类型ID以向量的形式直接输入全连接层，电影名称用文本卷积神经网络得到其定长向量表示。然后将三个属性的特征表示分别全连接并相加。
 
-4. 得到用户和电影的向量表示后，计算二者的余弦相似度作为推荐系统的打分。最后，用该相似度打分和用户真实打分的差异的平方作为该回归模型的损失函数。
+4. 得到用户和电影的向量表示后，计算二者的余弦相似度作为个性化推荐系统的打分。最后，用该相似度打分和用户真实打分的差异的平方作为该回归模型的损失函数。
 
 <p align="center">
-
 <img src="https://github.com/PaddlePaddle/book/blob/develop/05.recommender_system/image/rec_regression_network.png?raw=true" width="90%" ><br/>
 图4. 融合推荐模型
 </p>
@@ -214,6 +213,8 @@ print "User %s rates Movie %s with Score %s"%(user_info[uid], movie_info[mov_id]
 ## 模型配置说明
 
 下面我们开始根据输入数据的形式配置模型。首先引入所需的库函数以及定义全局变量。
+- IS_SPARSE: embedding中是否使用稀疏更新
+- PASS_NUM: epoch数量
 
 
 ```python
@@ -227,14 +228,15 @@ import paddle.fluid.layers as layers
 import paddle.fluid.nets as nets
 
 IS_SPARSE = True
-USE_GPU = False
 BATCH_SIZE = 256
+PASS_NUM = 20
 ```
 
 然后为我们的用户特征综合模型定义模型配置
 
 ```python
 def get_usr_combined_features():
+    """network definition for user part"""
 
     USR_DICT_SIZE = paddle.dataset.movielens.max_user_id() + 1
 
@@ -300,6 +302,7 @@ def get_usr_combined_features():
 
 ```python
 def get_mov_combined_features():
+    """network definition for item(movie) part"""
 
     MOV_DICT_SIZE = paddle.dataset.movielens.max_movie_id() + 1
 
@@ -354,6 +357,8 @@ def get_mov_combined_features():
 
 ```python
 def inference_program():
+    """the combined network"""
+
     usr_combined_features = get_usr_combined_features()
     mov_combined_features = get_mov_combined_features()
 
@@ -367,6 +372,7 @@ def inference_program():
 
 ```python
 def train_program():
+    """define the cost function"""
 
     scale_infer = inference_program()
 
@@ -440,14 +446,14 @@ def train_test(program, reader):
     feeder_test = fluid.DataFeeder(
     feed_list=feed_var_list, place=place)
     test_exe = fluid.Executor(place)
-    accumulated = len([avg_cost, scale_infer]) * [0]
+    accumulated = 0
     for test_data in reader():
         avg_cost_np = test_exe.run(program=program,
                                                feed=feeder_test.feed(test_data),
-                                               fetch_list=[avg_cost, scale_infer])
-        accumulated = [x[0] + x[1][0] for x in zip(accumulated, avg_cost_np)]
+                                               fetch_list=[avg_cost])
+        accumulated += avg_cost_np[0]
         count += 1
-    return [x / count for x in accumulated]
+    return accumulated / count
 ```
 
 ### 构建训练主循环并开始训练
@@ -458,8 +464,10 @@ def train_test(program, reader):
 params_dirname = "recommender_system.inference.model"
 
 from paddle.utils.plot import Ploter
+train_prompt = "Train cost"
 test_prompt = "Test cost"
-plot_cost = Ploter(test_prompt)
+
+plot_cost = Ploter(train_prompt, test_prompt)
 
 def train_loop():
     feed_list = [
@@ -476,13 +484,12 @@ def train_loop():
                                fetch_list=[avg_cost])
             out = np.array(outs[0])
 
-            avg_cost_set = train_test(test_program, test_reader)
-
             # get test avg_cost
-            test_avg_cost = np.array(avg_cost_set).mean()
-            plot_cost.append(test_prompt, batch_id, outs[0])
+            test_avg_cost = train_test(test_program, test_reader)
+
+            plot_cost.append(train_prompt, batch_id, outs[0])
+            plot_cost.append(test_prompt, batch_id, test_avg_cost)
             plot_cost.plot()
-            print("avg_cost: %s" % test_avg_cost)
 
             if batch_id == 20:
                 if params_dirname is not None:
@@ -491,13 +498,13 @@ def train_loop():
                                 "movie_id", "category_id", "movie_title"
                         ], [scale_infer], exe)
                 return
-            else:
-                print('BatchID {0}, Test Loss {1:0.2}'.format(pass_id + 1,
-                                                                  float(test_avg_cost)))
+            print('EpochID {0}, BatchID {1}, Test Loss {2:0.2}'.format(
+                            pass_id + 1, batch_id + 1, float(test_avg_cost)))
 
             if math.isnan(float(out[0])):
                 sys.exit("got NaN loss, training failed.")
 ```
+开始训练
 ```python
 train_loop()
 ```
@@ -562,16 +569,16 @@ with fluid.scope_guard(inference_scope):
 
 ## 总结
 
-本章介绍了传统的推荐系统方法和YouTube的深度神经网络推荐系统，并以电影推荐为例，使用PaddlePaddle训练了一个个性化推荐神经网络模型。推荐系统几乎涵盖了电商系统、社交网络、广告推荐、搜索引擎等领域的方方面面，而在图像处理、自然语言处理等领域已经发挥重要作用的深度学习技术，也将会在推荐系统领域大放异彩。
+本章介绍了传统的个性化推荐系统方法和YouTube的深度神经网络个性化推荐系统，并以电影推荐为例，使用PaddlePaddle训练了一个个性化推荐神经网络模型。个性化推荐系统几乎涵盖了电商系统、社交网络、广告推荐、搜索引擎等领域的方方面面，而在图像处理、自然语言处理等领域已经发挥重要作用的深度学习技术，也将会在个性化推荐系统领域大放异彩。
 
 <a name="参考文献"></a>
 ## 参考文献
 
-1. [Peter Brusilovsky](https://en.wikipedia.org/wiki/Peter_Brusilovsky) (2007). *The Adaptive Web*. p. 325.
-2. Robin Burke , [Hybrid Web Recommender Systems](http://www.dcs.warwick.ac.uk/~acristea/courses/CS411/2010/Book%20-%20The%20Adaptive%20Web/HybridWebRecommenderSystems.pdf), pp. 377-408, The Adaptive Web, Peter Brusilovsky, Alfred Kobsa, Wolfgang Nejdl (Ed.), Lecture Notes in Computer Science, Springer-Verlag, Berlin, Germany, Lecture Notes in Computer Science, Vol. 4321, May 2007, 978-3-540-72078-2.
-3. P. Resnick, N. Iacovou, etc. “[GroupLens: An Open Architecture for Collaborative Filtering of Netnews](http://ccs.mit.edu/papers/CCSWP165.html)”, Proceedings of ACM Conference on Computer Supported Cooperative Work, CSCW 1994. pp.175-186.
-4. Sarwar, Badrul, et al. "[Item-based collaborative filtering recommendation algorithms.](http://files.grouplens.org/papers/www10_sarwar.pdf)" *Proceedings of the 10th international conference on World Wide Web*. ACM, 2001.
-5. Kautz, Henry, Bart Selman, and Mehul Shah. "[Referral Web: combining social networks and collaborative filtering.](http://www.cs.cornell.edu/selman/papers/pdf/97.cacm.refweb.pdf)" Communications of the ACM 40.3 (1997): 63-65. APA
+1. P. Resnick, N. Iacovou, etc. “[GroupLens: An Open Architecture for Collaborative Filtering of Netnews](http://ccs.mit.edu/papers/CCSWP165.html)”, Proceedings of ACM Conference on Computer Supported Cooperative Work, CSCW 1994. pp.175-186.
+2. Sarwar, Badrul, et al. "[Item-based collaborative filtering recommendation algorithms.](http://files.grouplens.org/papers/www10_sarwar.pdf)" *Proceedings of the 10th international conference on World Wide Web*. ACM, 2001.
+3. Kautz, Henry, Bart Selman, and Mehul Shah. "[Referral Web: combining social networks and collaborative filtering.](http://www.cs.cornell.edu/selman/papers/pdf/97.cacm.refweb.pdf)" Communications of the ACM 40.3 (1997): 63-65. APA
+4. [Peter Brusilovsky](https://en.wikipedia.org/wiki/Peter_Brusilovsky) (2007). *The Adaptive Web*. p. 325.
+5. Robin Burke , [Hybrid Web Recommender Systems](http://www.dcs.warwick.ac.uk/~acristea/courses/CS411/2010/Book%20-%20The%20Adaptive%20Web/HybridWebRecommenderSystems.pdf), pp. 377-408, The Adaptive Web, Peter Brusilovsky, Alfred Kobsa, Wolfgang Nejdl (Ed.), Lecture Notes in Computer Science, Springer-Verlag, Berlin, Germany, Lecture Notes in Computer Science, Vol. 4321, May 2007, 978-3-540-72078-2.
 6. Yuan, Jianbo, et al. ["Solving Cold-Start Problem in Large-scale Recommendation Engines: A Deep Learning Approach."](https://arxiv.org/pdf/1611.05480v1.pdf) *arXiv preprint arXiv:1611.05480* (2016).
 7. Covington P, Adams J, Sargin E. [Deep neural networks for youtube recommendations](https://static.googleusercontent.com/media/research.google.com/zh-CN//pubs/archive/45530.pdf)[C]//Proceedings of the 10th ACM Conference on Recommender Systems. ACM, 2016: 191-198.
 

05.recommender_system/index.cn.html

@@ -46,19 +46,19 @@
 
 ## 背景介绍
 
-在网络技术不断发展和电子商务规模不断扩大的背景下，商品数量和种类快速增长，用户需要花费大量时间才能找到自己想买的商品，这就是信息超载问题。为了解决这个难题，推荐系统（Recommender System）应运而生。
+在网络技术不断发展和电子商务规模不断扩大的背景下，商品数量和种类快速增长，用户需要花费大量时间才能找到自己想买的商品，这就是信息超载问题。为了解决这个难题，个性化推荐系统（Recommender System）应运而生。
 
-个性化推荐系统是信息过滤系统（Information Filtering System）的子集，它可以用在很多领域，如电影、音乐、电商和 Feed 流推荐等。推荐系统通过分析、挖掘用户行为，发现用户的个性化需求与兴趣特点，将用户可能感兴趣的信息或商品推荐给用户。与搜索引擎不同，推荐系统不需要用户准确地描述出自己的需求，而是根据分析历史行为建模，主动提供满足用户兴趣和需求的信息。
+个性化推荐系统是信息过滤系统（Information Filtering System）的子集，它可以用在很多领域，如电影、音乐、电商和 Feed 流推荐等。个性化推荐系统通过分析、挖掘用户行为，发现用户的个性化需求与兴趣特点，将用户可能感兴趣的信息或商品推荐给用户。与搜索引擎不同，个性化推荐系统不需要用户准确地描述出自己的需求，而是根据用户的历史行为进行建模，主动提供满足用户兴趣和需求的信息。
 
-传统的推荐系统方法主要有：
+1994年明尼苏达大学推出的GroupLens系统[[1](#参考文献)]一般被认为是个性化推荐系统成为一个相对独立的研究方向的标志。该系统首次提出了基于协同过滤来完成推荐任务的思想，此后，基于该模型的协同过滤推荐引领了个性化推荐系统十几年的发展方向。
 
-- 协同过滤推荐（Collaborative Filtering Recommendation）：该方法收集分析用户历史行为、活动、偏好，计算一个用户与其他用户的相似度，利用目标用户的相似用户对商品评价的加权评价值，来预测目标用户对特定商品的喜好程度。优点是可以给用户推荐未浏览过的新产品；缺点是对于没有任何行为的新用户存在冷启动的问题，同时也存在用户与商品之间的交互数据不够多造成的稀疏问题，会导致模型难以找到相近用户。
-- 基于内容过滤推荐[[1](#参考文献)]（Content-based Filtering Recommendation）：该方法利用商品的内容描述，抽象出有意义的特征，通过计算用户的兴趣和商品描述之间的相似度，来给用户做推荐。优点是简单直接，不需要依据其他用户对商品的评价，而是通过商品属性进行商品相似度度量，从而推荐给用户所感兴趣商品的相似商品；缺点是对于没有任何行为的新用户同样存在冷启动的问题。
-- 组合推荐[[2](#参考文献)]（Hybrid Recommendation）：运用不同的输入和技术共同进行推荐，以弥补各自推荐技术的缺点。
+传统的个性化推荐系统方法主要有：
 
-其中协同过滤是应用最广泛的技术之一，它又可以分为多个子类：基于用户 （User-Based）的推荐[[3](#参考文献)] 、基于物品（Item-Based）的推荐[[4](#参考文献)]、基于社交网络关系（Social-Based）的推荐[[5](#参考文献)]、基于模型（Model-based）的推荐等。1994年明尼苏达大学推出的GroupLens系统[[3](#参考文献)]一般被认为是推荐系统成为一个相对独立的研究方向的标志。该系统首次提出了基于协同过滤来完成推荐任务的思想，此后，基于该模型的协同过滤推荐引领了推荐系统十几年的发展方向。
+- 协同过滤推荐（Collaborative Filtering Recommendation）：该方法是应用最广泛的技术之一，需要收集和分析用户的历史行为、活动和偏好。它通常可以分为两个子类：基于用户 （User-Based）的推荐[[1](#参考文献)] 和基于物品（Item-Based）的推荐[[2](#参考文献)]。该方法的一个关键优势是它不依赖于机器去分析物品的内容特征，因此它无需理解物品本身也能够准确地推荐诸如电影之类的复杂物品；缺点是对于没有任何行为的新用户存在冷启动的问题，同时也存在用户与商品之间的交互数据不够多造成的稀疏问题。值得一提的是，社交网络[[3](#参考文献)]或地理位置等上下文信息都可以结合到协同过滤中去。
+- 基于内容过滤推荐[[4](#参考文献)]（Content-based Filtering Recommendation）：该方法利用商品的内容描述，抽象出有意义的特征，通过计算用户的兴趣和商品描述之间的相似度，来给用户做推荐。优点是简单直接，不需要依据其他用户对商品的评价，而是通过商品属性进行商品相似度度量，从而推荐给用户所感兴趣商品的相似商品；缺点是对于没有任何行为的新用户同样存在冷启动的问题。
+- 组合推荐[[5](#参考文献)]（Hybrid Recommendation）：运用不同的输入和技术共同进行推荐，以弥补各自推荐技术的缺点。
 
-深度学习具有优秀的自动提取特征的能力，能够学习多层次的抽象特征表示，并对异质或跨域的内容信息进行学习，可以一定程度上处理推荐系统冷启动问题[[6](#参考文献)]。本教程主要介绍个性化推荐的深度学习模型，以及如何使用PaddlePaddle实现模型。
+近些年来，深度学习在很多领域都取得了巨大的成功。学术界和工业界都在尝试将深度学习应用于个性化推荐系统领域中。深度学习具有优秀的自动提取特征的能力，能够学习多层次的抽象特征表示，并对异质或跨域的内容信息进行学习，可以一定程度上处理个性化推荐系统冷启动问题[[6](#参考文献)]。本教程主要介绍个性化推荐的深度学习模型，以及如何使用PaddlePaddle实现模型。
 
 ## 效果展示
 
@@ -72,15 +72,15 @@ Prediction Score is 4.25
 
 ## 模型概览
 
-本章中，我们首先介绍YouTube的视频推荐系统[[7](#参考文献)]，然后介绍我们实现的融合推荐模型。
+本章中，我们首先介绍YouTube的视频个性化推荐系统[[7](#参考文献)]，然后介绍我们实现的融合推荐模型。
 
-### YouTube的深度神经网络推荐系统
+### YouTube的深度神经网络个性化推荐系统
 
-YouTube是世界上最大的视频上传、分享和发现网站，YouTube推荐系统为超过10亿用户从不断增长的视频库中推荐个性化的内容。整个系统由两个神经网络组成：候选生成网络和排序网络。候选生成网络从百万量级的视频库中生成上百个候选，排序网络对候选进行打分排序，输出排名最高的数十个结果。系统结构如图1所示：
+YouTube是世界上最大的视频上传、分享和发现网站，YouTube个性化推荐系统为超过10亿用户从不断增长的视频库中推荐个性化的内容。整个系统由两个神经网络组成：候选生成网络和排序网络。候选生成网络从百万量级的视频库中生成上百个候选，排序网络对候选进行打分排序，输出排名最高的数十个结果。系统结构如图1所示：
 
 <p align="center">
 <img src="https://github.com/PaddlePaddle/book/blob/develop/05.recommender_system/image/YouTube_Overview.png?raw=true" width="70%" ><br/>
-图1. YouTube 推荐系统结构
+图1. YouTube 个性化推荐系统结构
 </p>
 
 #### 候选生成网络（Candidate Generation Network）
@@ -106,7 +106,7 @@ $$P(\omega=i|u)=\frac{e^{v_{i}u}}{\sum_{j \in V}e^{v_{j}u}}$$
 排序网络的结构类似于候选生成网络，但是它的目标是对候选进行更细致的打分排序。和传统广告排序中的特征抽取方法类似，这里也构造了大量的用于视频排序的相关特征（如视频 ID、上次观看时间等）。这些特征的处理方式和候选生成网络类似，不同之处是排序网络的顶部是一个加权逻辑回归（weighted logistic regression），它对所有候选视频进行打分，从高到底排序后将分数较高的一些视频返回给用户。
 
 ### 融合推荐模型
-本节会使卷积神经网络（Convolutional Neural Networks）来学习电影名称的表示。下面会依次介绍文本卷积神经网络以及融合推荐模型。
+本节会使用卷积神经网络（Convolutional Neural Networks）来学习电影名称的表示。下面会依次介绍文本卷积神经网络以及融合推荐模型。
 
 #### 文本卷积神经网络（CNN）
 
@@ -119,7 +119,7 @@ $$P(\omega=i|u)=\frac{e^{v_{i}u}}{\sum_{j \in V}e^{v_{j}u}}$$
 图3. 卷积神经网络文本分类模型
 </p>
 
-假设待处理句子的长度为$n$，其中第$i$个词的词向量（word embedding）为$x_i\in\mathbb{R}^k$，$k$为维度大小。
+假设待处理句子的长度为$n$，其中第$i$个词的词向量为$x_i\in\mathbb{R}^k$，$k$为维度大小。
 
 首先，进行词向量的拼接操作：将每$h$个词拼接起来形成一个大小为$h$的词窗口，记为$x_{i:i+h-1}$，它表示词序列$x_{i},x_{i+1},\ldots,x_{i+h-1}$的拼接，其中，$i$表示词窗口中第一个词在整个句子中的位置，取值范围从$1$到$n-h+1$，$x_{i:i+h-1}\in\mathbb{R}^{hk}$。
 
@@ -131,9 +131,9 @@ $$c=[c_1,c_2,\ldots,c_{n-h+1}], c \in \mathbb{R}^{n-h+1}$$
 
 $$\hat c=max(c)$$
 
-#### 模型概览
+#### 融合推荐模型概览
 
-在融合推荐模型的电影推荐系统中：
+在融合推荐模型的电影个性化推荐系统中：
 
 1. 首先，使用用户特征和电影特征作为神经网络的输入，其中：
 
@@ -145,10 +145,9 @@ $$\hat c=max(c)$$
 
 3. 对电影特征，将电影ID以类似用户ID的方式进行处理，电影类型ID以向量的形式直接输入全连接层，电影名称用文本卷积神经网络得到其定长向量表示。然后将三个属性的特征表示分别全连接并相加。
 
-4. 得到用户和电影的向量表示后，计算二者的余弦相似度作为推荐系统的打分。最后，用该相似度打分和用户真实打分的差异的平方作为该回归模型的损失函数。
+4. 得到用户和电影的向量表示后，计算二者的余弦相似度作为个性化推荐系统的打分。最后，用该相似度打分和用户真实打分的差异的平方作为该回归模型的损失函数。
 
 <p align="center">
-
 <img src="https://github.com/PaddlePaddle/book/blob/develop/05.recommender_system/image/rec_regression_network.png?raw=true" width="90%" ><br/>
 图4. 融合推荐模型
 </p>
@@ -256,6 +255,8 @@ print "User %s rates Movie %s with Score %s"%(user_info[uid], movie_info[mov_id]
 ## 模型配置说明
 
 下面我们开始根据输入数据的形式配置模型。首先引入所需的库函数以及定义全局变量。
+- IS_SPARSE: embedding中是否使用稀疏更新
+- PASS_NUM: epoch数量
 
 
 ```python
@@ -269,14 +270,15 @@ import paddle.fluid.layers as layers
 import paddle.fluid.nets as nets
 
 IS_SPARSE = True
-USE_GPU = False
 BATCH_SIZE = 256
+PASS_NUM = 20
 ```
 
 然后为我们的用户特征综合模型定义模型配置
 
 ```python
 def get_usr_combined_features():
+    """network definition for user part"""
 
     USR_DICT_SIZE = paddle.dataset.movielens.max_user_id() + 1
 
@@ -342,6 +344,7 @@ def get_usr_combined_features():
 
 ```python
 def get_mov_combined_features():
+    """network definition for item(movie) part"""
 
     MOV_DICT_SIZE = paddle.dataset.movielens.max_movie_id() + 1
 
@@ -396,6 +399,8 @@ def get_mov_combined_features():
 
 ```python
 def inference_program():
+    """the combined network"""
+
     usr_combined_features = get_usr_combined_features()
     mov_combined_features = get_mov_combined_features()
 
@@ -409,6 +414,7 @@ def inference_program():
 
 ```python
 def train_program():
+    """define the cost function"""
 
     scale_infer = inference_program()
 
@@ -482,14 +488,14 @@ def train_test(program, reader):
     feeder_test = fluid.DataFeeder(
     feed_list=feed_var_list, place=place)
     test_exe = fluid.Executor(place)
-    accumulated = len([avg_cost, scale_infer]) * [0]
+    accumulated = 0
     for test_data in reader():
         avg_cost_np = test_exe.run(program=program,
                                                feed=feeder_test.feed(test_data),
-                                               fetch_list=[avg_cost, scale_infer])
-        accumulated = [x[0] + x[1][0] for x in zip(accumulated, avg_cost_np)]
+                                               fetch_list=[avg_cost])
+        accumulated += avg_cost_np[0]
         count += 1
-    return [x / count for x in accumulated]
+    return accumulated / count
 ```
 
 ### 构建训练主循环并开始训练
@@ -500,8 +506,10 @@ def train_test(program, reader):
 params_dirname = "recommender_system.inference.model"
 
 from paddle.utils.plot import Ploter
+train_prompt = "Train cost"
 test_prompt = "Test cost"
-plot_cost = Ploter(test_prompt)
+
+plot_cost = Ploter(train_prompt, test_prompt)
 
 def train_loop():
     feed_list = [
@@ -518,13 +526,12 @@ def train_loop():
                                fetch_list=[avg_cost])
             out = np.array(outs[0])
 
-            avg_cost_set = train_test(test_program, test_reader)
-
             # get test avg_cost
-            test_avg_cost = np.array(avg_cost_set).mean()
-            plot_cost.append(test_prompt, batch_id, outs[0])
+            test_avg_cost = train_test(test_program, test_reader)
+
+            plot_cost.append(train_prompt, batch_id, outs[0])
+            plot_cost.append(test_prompt, batch_id, test_avg_cost)
             plot_cost.plot()
-            print("avg_cost: %s" % test_avg_cost)
 
             if batch_id == 20:
                 if params_dirname is not None:
@@ -533,13 +540,13 @@ def train_loop():
                                 "movie_id", "category_id", "movie_title"
                         ], [scale_infer], exe)
                 return
-            else:
-                print('BatchID {0}, Test Loss {1:0.2}'.format(pass_id + 1,
-                                                                  float(test_avg_cost)))
+            print('EpochID {0}, BatchID {1}, Test Loss {2:0.2}'.format(
+                            pass_id + 1, batch_id + 1, float(test_avg_cost)))
 
             if math.isnan(float(out[0])):
                 sys.exit("got NaN loss, training failed.")
 ```
+开始训练
 ```python
 train_loop()
 ```
@@ -604,16 +611,16 @@ with fluid.scope_guard(inference_scope):
 
 ## 总结
 
-本章介绍了传统的推荐系统方法和YouTube的深度神经网络推荐系统，并以电影推荐为例，使用PaddlePaddle训练了一个个性化推荐神经网络模型。推荐系统几乎涵盖了电商系统、社交网络、广告推荐、搜索引擎等领域的方方面面，而在图像处理、自然语言处理等领域已经发挥重要作用的深度学习技术，也将会在推荐系统领域大放异彩。
+本章介绍了传统的个性化推荐系统方法和YouTube的深度神经网络个性化推荐系统，并以电影推荐为例，使用PaddlePaddle训练了一个个性化推荐神经网络模型。个性化推荐系统几乎涵盖了电商系统、社交网络、广告推荐、搜索引擎等领域的方方面面，而在图像处理、自然语言处理等领域已经发挥重要作用的深度学习技术，也将会在个性化推荐系统领域大放异彩。
 
 <a name="参考文献"></a>
 ## 参考文献
 
-1. [Peter Brusilovsky](https://en.wikipedia.org/wiki/Peter_Brusilovsky) (2007). *The Adaptive Web*. p. 325.
-2. Robin Burke , [Hybrid Web Recommender Systems](http://www.dcs.warwick.ac.uk/~acristea/courses/CS411/2010/Book%20-%20The%20Adaptive%20Web/HybridWebRecommenderSystems.pdf), pp. 377-408, The Adaptive Web, Peter Brusilovsky, Alfred Kobsa, Wolfgang Nejdl (Ed.), Lecture Notes in Computer Science, Springer-Verlag, Berlin, Germany, Lecture Notes in Computer Science, Vol. 4321, May 2007, 978-3-540-72078-2.
-3. P. Resnick, N. Iacovou, etc. “[GroupLens: An Open Architecture for Collaborative Filtering of Netnews](http://ccs.mit.edu/papers/CCSWP165.html)”, Proceedings of ACM Conference on Computer Supported Cooperative Work, CSCW 1994. pp.175-186.
-4. Sarwar, Badrul, et al. "[Item-based collaborative filtering recommendation algorithms.](http://files.grouplens.org/papers/www10_sarwar.pdf)" *Proceedings of the 10th international conference on World Wide Web*. ACM, 2001.
-5. Kautz, Henry, Bart Selman, and Mehul Shah. "[Referral Web: combining social networks and collaborative filtering.](http://www.cs.cornell.edu/selman/papers/pdf/97.cacm.refweb.pdf)" Communications of the ACM 40.3 (1997): 63-65. APA
+1. P. Resnick, N. Iacovou, etc. “[GroupLens: An Open Architecture for Collaborative Filtering of Netnews](http://ccs.mit.edu/papers/CCSWP165.html)”, Proceedings of ACM Conference on Computer Supported Cooperative Work, CSCW 1994. pp.175-186.
+2. Sarwar, Badrul, et al. "[Item-based collaborative filtering recommendation algorithms.](http://files.grouplens.org/papers/www10_sarwar.pdf)" *Proceedings of the 10th international conference on World Wide Web*. ACM, 2001.
+3. Kautz, Henry, Bart Selman, and Mehul Shah. "[Referral Web: combining social networks and collaborative filtering.](http://www.cs.cornell.edu/selman/papers/pdf/97.cacm.refweb.pdf)" Communications of the ACM 40.3 (1997): 63-65. APA
+4. [Peter Brusilovsky](https://en.wikipedia.org/wiki/Peter_Brusilovsky) (2007). *The Adaptive Web*. p. 325.
+5. Robin Burke , [Hybrid Web Recommender Systems](http://www.dcs.warwick.ac.uk/~acristea/courses/CS411/2010/Book%20-%20The%20Adaptive%20Web/HybridWebRecommenderSystems.pdf), pp. 377-408, The Adaptive Web, Peter Brusilovsky, Alfred Kobsa, Wolfgang Nejdl (Ed.), Lecture Notes in Computer Science, Springer-Verlag, Berlin, Germany, Lecture Notes in Computer Science, Vol. 4321, May 2007, 978-3-540-72078-2.
 6. Yuan, Jianbo, et al. ["Solving Cold-Start Problem in Large-scale Recommendation Engines: A Deep Learning Approach."](https://arxiv.org/pdf/1611.05480v1.pdf) *arXiv preprint arXiv:1611.05480* (2016).
 7. Covington P, Adams J, Sargin E. [Deep neural networks for youtube recommendations](https://static.googleusercontent.com/media/research.google.com/zh-CN//pubs/archive/45530.pdf)[C]//Proceedings of the 10th ACM Conference on Recommender Systems. ACM, 2016: 191-198.
 

05.recommender_system/train.py

@@ -181,17 +181,15 @@ def train(use_cuda, params_dirname):
         ]
         feeder_test = fluid.DataFeeder(feed_list=feed_var_list, place=place)
         test_exe = fluid.Executor(place)
-        accumulated = len([avg_cost, scale_infer]) * [0]
+        accumulated = 0
         for test_data in reader():
             avg_cost_np = test_exe.run(
                 program=program,
                 feed=feeder_test.feed(test_data),
-                fetch_list=[avg_cost, scale_infer])
-            accumulated = [
-                x[0] + x[1][0] for x in zip(accumulated, avg_cost_np)
-            ]
+                fetch_list=[avg_cost])
+            accumulated += avg_cost_np[0]
             count += 1
-        return [x / count for x in accumulated]
+        return accumulated / count
 
     def train_loop():
         feed_list = [
@@ -209,11 +207,8 @@ def train(use_cuda, params_dirname):
                     fetch_list=[avg_cost])
                 out = np.array(outs[0])
 
-                avg_cost_set = train_test(test_program, test_reader)
-
                 # get test avg_cost
-                test_avg_cost = np.array(avg_cost_set).mean()
-                print("avg_cost: %s" % test_avg_cost)
+                test_avg_cost = train_test(test_program, test_reader)
 
                 # if test_avg_cost < 4.0: # Change this number to adjust accuracy
                 if batch_id == 20:
@@ -223,9 +218,8 @@ def train(use_cuda, params_dirname):
                             "movie_id", "category_id", "movie_title"
                         ], [scale_infer], exe)
                     return
-                else:
-                    print('BatchID {0}, Test Loss {1:0.2}'.format(
-                        pass_id + 1, float(test_avg_cost)))
+                print('EpochID {0}, BatchID {1}, Test Loss {2:0.2}'.format(
+                    pass_id + 1, batch_id + 1, float(test_avg_cost)))
 
                 if math.isnan(float(out[0])):
                     sys.exit("got NaN loss, training failed.")

06.understand_sentiment/README.cn.md

@@ -28,7 +28,12 @@
 
 我们在[推荐系统](https://github.com/PaddlePaddle/book/tree/develop/05.recommender_system)一节介绍过应用于文本数据的卷积神经网络模型的计算过程，这里进行一个简单的回顾。
 
-对卷积神经网络来说，首先使用卷积处理输入的词向量序列，产生一个特征图（feature map），对特征图采用时间维度上的最大池化（max pooling over time）操作得到此卷积核对应的整句话的特征，最后，将所有卷积核得到的特征拼接起来即为文本的定长向量表示，对于文本分类问题，将其连接至softmax即构建出完整的模型。在实际应用中，我们会使用多个卷积核来处理句子，窗口大小相同的卷积核堆叠起来形成一个矩阵，这样可以更高效的完成运算。另外，我们也可使用窗口大小不同的卷积核来处理句子，[推荐系统](https://github.com/PaddlePaddle/book/tree/develop/05.recommender_system)一节的图3作为示意画了四个卷积核，不同颜色表示不同大小的卷积核操作。
+对卷积神经网络来说，首先使用卷积处理输入的词向量序列，产生一个特征图（feature map），对特征图采用时间维度上的最大池化（max pooling over time）操作得到此卷积核对应的整句话的特征，最后，将所有卷积核得到的特征拼接起来即为文本的定长向量表示，对于文本分类问题，将其连接至softmax即构建出完整的模型。在实际应用中，我们会使用多个卷积核来处理句子，窗口大小相同的卷积核堆叠起来形成一个矩阵，这样可以更高效的完成运算。另外，我们也可使用窗口大小不同的卷积核来处理句子，[推荐系统](https://github.com/PaddlePaddle/book/tree/develop/05.recommender_system)一节的图3作为示意画了四个卷积核，既文本图1，不同颜色表示不同大小的卷积核操作。
+
+<p align="center">
+<img src="https://github.com/PaddlePaddle/book/blob/develop/05.recommender_system/image/text_cnn.png?raw=true" width = "80%" align="center"/><br/>
+图1. 卷积神经网络文本分类模型
+</p>
 
 对于一般的短文本分类问题，上文所述的简单的文本卷积网络即可达到很高的正确率\[[1](#参考文献)\]。若想得到更抽象更高级的文本特征表示，可以构建深层文本卷积神经网络\[[2](#参考文献),[3](#参考文献)\]。
 
@@ -38,16 +43,16 @@
 
 <p align="center">
 <img src="https://github.com/PaddlePaddle/book/blob/develop/06.understand_sentiment/image/rnn.png?raw=true" width = "60%" align="center"/><br/>
-图1. 循环神经网络按时间展开的示意图
+图2. 循环神经网络按时间展开的示意图
 </p>
 
-循环神经网络按时间展开后如图1所示：在第$t$时刻，网络读入第$t$个输入$x_t$（向量表示）及前一时刻隐层的状态值$h_{t-1}$（向量表示，$h_0$一般初始化为$0$向量），计算得出本时刻隐层的状态值$h_t$，重复这一步骤直至读完所有输入。如果将循环神经网络所表示的函数记为$f$，则其公式可表示为：
+循环神经网络按时间展开后如图2所示：在第$t$时刻，网络读入第$t$个输入$x_t$（向量表示）及前一时刻隐层的状态值$h_{t-1}$（向量表示，$h_0$一般初始化为$0$向量），计算得出本时刻隐层的状态值$h_t$，重复这一步骤直至读完所有输入。如果将循环神经网络所表示的函数记为$f$，则其公式可表示为：
 
 $$h_t=f(x_t,h_{t-1})=\sigma(W_{xh}x_t+W_{hh}h_{t-1}+b_h)$$
 
 其中$W_{xh}$是输入到隐层的矩阵参数，$W_{hh}$是隐层到隐层的矩阵参数，$b_h$为隐层的偏置向量（bias）参数，$\sigma$为$sigmoid$函数。  
 
-在处理自然语言时，一般会先将词（one-hot表示）映射为其词向量（word embedding）表示，然后再作为循环神经网络每一时刻的输入$x_t$。此外，可以根据实际需要的不同在循环神经网络的隐层上连接其它层。如，可以把一个循环神经网络的隐层输出连接至下一个循环神经网络的输入构建深层（deep or stacked）循环神经网络，或者提取最后一个时刻的隐层状态作为句子表示进而使用分类模型等等。  
+在处理自然语言时，一般会先将词（one-hot表示）映射为其词向量表示，然后再作为循环神经网络每一时刻的输入$x_t$。此外，可以根据实际需要的不同在循环神经网络的隐层上连接其它层。如，可以把一个循环神经网络的隐层输出连接至下一个循环神经网络的输入构建深层（deep or stacked）循环神经网络，或者提取最后一个时刻的隐层状态作为句子表示进而使用分类模型等等。  
 
 ### 长短期记忆网络（LSTM）
 
@@ -63,11 +68,11 @@ $$ f_t = \sigma(W_{xf}x_t+W_{hf}h_{t-1}+W_{cf}c_{t-1}+b_f) $$
 $$ c_t = f_t\odot c_{t-1}+i_t\odot tanh(W_{xc}x_t+W_{hc}h_{t-1}+b_c) $$
 $$ o_t = \sigma(W_{xo}x_t+W_{ho}h_{t-1}+W_{co}c_{t}+b_o) $$
 $$ h_t = o_t\odot tanh(c_t) $$
-其中，$i_t, f_t, c_t, o_t$分别表示输入门，遗忘门，记忆单元及输出门的向量值，带角标的$W$及$b$为模型参数，$tanh$为双曲正切函数，$\odot$表示逐元素（elementwise）的乘法操作。输入门控制着新输入进入记忆单元$c$的强度，遗忘门控制着记忆单元维持上一时刻值的强度，输出门控制着输出记忆单元的强度。三种门的计算方式类似，但有着完全不同的参数，它们各自以不同的方式控制着记忆单元$c$，如图2所示：
+其中，$i_t, f_t, c_t, o_t$分别表示输入门，遗忘门，记忆单元及输出门的向量值，带角标的$W$及$b$为模型参数，$tanh$为双曲正切函数，$\odot$表示逐元素（elementwise）的乘法操作。输入门控制着新输入进入记忆单元$c$的强度，遗忘门控制着记忆单元维持上一时刻值的强度，输出门控制着输出记忆单元的强度。三种门的计算方式类似，但有着完全不同的参数，它们各自以不同的方式控制着记忆单元$c$，如图3所示：
 
 <p align="center">
 <img src="https://github.com/PaddlePaddle/book/blob/develop/06.understand_sentiment/image/lstm.png?raw=true" width = "65%" align="center"/><br/>
-图2. 时刻$t$的LSTM [7]
+图3. 时刻$t$的LSTM [7]
 </p>
 
 LSTM通过给简单的循环神经网络增加记忆及控制门的方式，增强了其处理远距离依赖问题的能力。类似原理的改进还有Gated Recurrent Unit (GRU)\[[8](#参考文献)\]，其设计更为简洁一些。**这些改进虽然各有不同，但是它们的宏观描述却与简单的循环神经网络一样（如图2所示），即隐状态依据当前输入及前一时刻的隐状态来改变，不断地循环这一过程直至输入处理完毕：**
@@ -80,11 +85,11 @@ $$ h_t=Recrurent(x_t,h_{t-1})$$
 
 对于正常顺序的循环神经网络，$h_t$包含了$t$时刻之前的输入信息，也就是上文信息。同样，为了得到下文信息，我们可以使用反方向（将输入逆序处理）的循环神经网络。结合构建深层循环神经网络的方法（深层神经网络往往能得到更抽象和高级的特征表示），我们可以通过构建更加强有力的基于LSTM的栈式双向循环神经网络\[[9](#参考文献)\]，来对时序数据进行建模。  
 
-如图3所示（以三层为例），奇数层LSTM正向，偶数层LSTM反向，高一层的LSTM使用低一层LSTM及之前所有层的信息作为输入，对最高层LSTM序列使用时间维度上的最大池化即可得到文本的定长向量表示（这一表示充分融合了文本的上下文信息，并且对文本进行了深层次抽象），最后我们将文本表示连接至softmax构建分类模型。
+如图4所示（以三层为例），奇数层LSTM正向，偶数层LSTM反向，高一层的LSTM使用低一层LSTM及之前所有层的信息作为输入，对最高层LSTM序列使用时间维度上的最大池化即可得到文本的定长向量表示（这一表示充分融合了文本的上下文信息，并且对文本进行了深层次抽象），最后我们将文本表示连接至softmax构建分类模型。
 
 <p align="center">
 <img src="https://github.com/PaddlePaddle/book/blob/develop/06.understand_sentiment/image/stacked_lstm.jpg?raw=true" width=450><br/>
-图3. 栈式双向LSTM用于文本分类
+图4. 栈式双向LSTM用于文本分类
 </p>
 
 
@@ -114,11 +119,11 @@ import numpy as np
 import sys
 import math
 
-CLASS_DIM = 2
-EMB_DIM = 128
-HID_DIM = 512
-STACKED_NUM = 3
-BATCH_SIZE = 128
+CLASS_DIM = 2     #情感分类的类别数
+EMB_DIM = 128     #词向量的维度
+HID_DIM = 512     #隐藏层的维度
+STACKED_NUM = 3   #LSTM双向栈的层数
+BATCH_SIZE = 128  #batch的大小
 
 ```
 
@@ -128,6 +133,7 @@ BATCH_SIZE = 128
 需要注意的是：`fluid.nets.sequence_conv_pool` 包含卷积和池化层两个操作。
 
 ```python
+#文本卷积神经网络
 def convolution_net(data, input_dim, class_dim, emb_dim, hid_dim):
     emb = fluid.layers.embedding(
         input=data, size=[input_dim, emb_dim], is_sparse=True)
@@ -157,32 +163,40 @@ def convolution_net(data, input_dim, class_dim, emb_dim, hid_dim):
 栈式双向神经网络`stacked_lstm_net`的代码片段如下：
 
 ```python
+#栈式双向LSTM
 def stacked_lstm_net(data, input_dim, class_dim, emb_dim, hid_dim, stacked_num):
 
+    #计算词向量
     emb = fluid.layers.embedding(
         input=data, size=[input_dim, emb_dim], is_sparse=True)
 
+    #第一层栈
+    #全连接层
     fc1 = fluid.layers.fc(input=emb, size=hid_dim)
+    #lstm层
     lstm1, cell1 = fluid.layers.dynamic_lstm(input=fc1, size=hid_dim)
 
     inputs = [fc1, lstm1]
 
+    #其余的所有栈结构
     for i in range(2, stacked_num + 1):
         fc = fluid.layers.fc(input=inputs, size=hid_dim)
         lstm, cell = fluid.layers.dynamic_lstm(
             input=fc, size=hid_dim, is_reverse=(i % 2) == 0)
         inputs = [fc, lstm]
 
+    #池化层
     fc_last = fluid.layers.sequence_pool(input=inputs[0], pool_type='max')
     lstm_last = fluid.layers.sequence_pool(input=inputs[1], pool_type='max')
 
+    #全连接层，softmax预测
     prediction = fluid.layers.fc(
         input=[fc_last, lstm_last], size=class_dim, act='softmax')
     return prediction
 ```
-以上的栈式双向LSTM抽象出了高级特征并把其映射到和分类类别数同样大小的向量上。`paddle.activation.Softmax`函数用来计算分类属于某个类别的概率。
+以上的栈式双向LSTM抽象出了高级特征并把其映射到和分类类别数同样大小的向量上。最后一个全连接层的'softmax'激活函数用来计算分类属于某个类别的概率。
 
-重申一下，此处我们可以调用`convolution_net`或`stacked_lstm_net`的任何一个。我们以`convolution_net`为例。
+重申一下，此处我们可以调用`convolution_net`或`stacked_lstm_net`的任何一个网络结构进行训练学习。我们以`convolution_net`为例。
 
 接下来我们定义预测程序（`inference_program`）。预测程序使用`convolution_net`来对`fluid.layer.data`的输入进行预测。
 
@@ -199,9 +213,9 @@ def inference_program(word_dict):
 
 我们这里定义了`training_program`。它使用了从`inference_program`返回的结果来计算误差。我们同时定义了优化函数`optimizer_func`。
 
-因为是有监督的学习，训练集的标签也在`paddle.layer.data`中定义了。在训练过程中，交叉熵用来在`paddle.layer.classification_cost`中作为损失函数。
+因为是有监督的学习，训练集的标签也在`fluid.layers.data`中定义了。在训练过程中，交叉熵用来在`fluid.layer.cross_entropy`中作为损失函数。
 
-在测试过程中，分类器会计算各个输出的概率。第一个返回的数值规定为 损耗(cost)。
+在测试过程中，分类器会计算各个输出的概率。第一个返回的数值规定为cost。
 
 ```python
 def train_program(prediction):
@@ -209,9 +223,9 @@ def train_program(prediction):
     cost = fluid.layers.cross_entropy(input=prediction, label=label)
     avg_cost = fluid.layers.mean(cost)
     accuracy = fluid.layers.accuracy(input=prediction, label=label)
-    return [avg_cost, accuracy]
-
+    return [avg_cost, accuracy]   #返回平均cost和准确率acc
 
+#优化函数
 def optimizer_func():
     return fluid.optimizer.Adagrad(learning_rate=0.002)
 ```
@@ -224,13 +238,13 @@ def optimizer_func():
 
 
 ```python
-use_cuda = False
+use_cuda = False  #在cpu上进行训练
 place = fluid.CUDAPlace(0) if use_cuda else fluid.CPUPlace()
 ```
 
 ### 定义数据提供器
 
-下一步是为训练和测试定义数据提供器。提供器读入一个大小为 BATCH_SIZE的数据。paddle.dataset.imdb.train 每次会在乱序化后提供一个大小为BATCH_SIZE的数据，乱序化的大小为缓存大小buf_size。
+下一步是为训练和测试定义数据提供器。提供器读入一个大小为 BATCH_SIZE的数据。paddle.dataset.imdb.word_dict 每次会在乱序化后提供一个大小为BATCH_SIZE的数据，乱序化的大小为缓存大小buf_size。
 
 注意：读取IMDB的数据可能会花费几分钟的时间，请耐心等待。
 
@@ -243,32 +257,65 @@ train_reader = paddle.batch(
     paddle.reader.shuffle(
         paddle.dataset.imdb.train(word_dict), buf_size=25000),
     batch_size=BATCH_SIZE)
+print("Reading testing data....")
+test_reader = paddle.batch(
+    paddle.dataset.imdb.test(word_dict), batch_size=BATCH_SIZE)
+```
+word_dict是一个字典序列，是词和label的对应关系，运行下一行可以看到具体内容：
+```python
+word_dict
 ```
+每行是如（'limited': 1726）的对应关系，该行表示单词limited所对应的label是1726。
 
-### 构造训练器(trainer)
+### 构造训练器
 训练器需要一个训练程序和一个训练优化函数。
 
 ```python
 exe = fluid.Executor(place)
 prediction = inference_program(word_dict)
-[avg_cost, accuracy] = train_program(prediction)
-sgd_optimizer = optimizer_func()
+[avg_cost, accuracy] = train_program(prediction)#训练程序
+sgd_optimizer = optimizer_func()#训练优化函数
 sgd_optimizer.minimize(avg_cost)
 ```
 
+该函数用来计算训练中模型在test数据集上的结果
+```python
+def train_test(program, reader):
+    count = 0
+    feed_var_list = [
+        program.global_block().var(var_name) for var_name in feed_order
+    ]
+    feeder_test = fluid.DataFeeder(feed_list=feed_var_list, place=place)
+    test_exe = fluid.Executor(place)
+    accumulated = len([avg_cost, accuracy]) * [0]
+    for test_data in reader():
+        avg_cost_np = test_exe.run(
+            program=program,
+            feed=feeder_test.feed(test_data),
+            fetch_list=[avg_cost, accuracy])
+        accumulated = [
+            x[0] + x[1][0] for x in zip(accumulated, avg_cost_np)
+        ]
+        count += 1
+    return [x / count for x in accumulated]
+```
+
 ### 提供数据并构建主训练循环
 
-`feed_order`用来定义每条产生的数据和`paddle.layer.data`之间的映射关系。比如，`imdb.train`产生的第一列的数据对应的是`words`这个特征。
+`feed_order`用来定义每条产生的数据和`fluid.layers.data`之间的映射关系。比如，`imdb.train`产生的第一列的数据对应的是`words`这个特征。
 
 ```python
 # Specify the directory path to save the parameters
 params_dirname = "understand_sentiment_conv.inference.model"
 
 feed_order = ['words', 'label']
-pass_num = 1
+pass_num = 1  #训练循环的轮数
 
+#程序主循环部分
 def train_loop(main_program):
+    #启动上文构建的训练器
     exe.run(fluid.default_startup_program())
+
     feed_var_list_loop = [
         main_program.global_block().var(var_name) for var_name in feed_order
     ]
@@ -277,12 +324,15 @@ def train_loop(main_program):
 
     test_program = fluid.default_main_program().clone(for_test=True)
 
+    #训练循环
     for epoch_id in range(pass_num):
         for step_id, data in enumerate(train_reader()):
+            #运行训练器  
             metrics = exe.run(main_program,
                               feed=feeder.feed(data),
                               fetch_list=[avg_cost, accuracy])
 
+            #测试结果
             avg_cost_test, acc_test = train_test(test_program, test_reader)
             print('Step {0}, Test Loss {1:0.2}, Acc {2:0.2}'.format(
                 step_id, avg_cost_test, acc_test))
@@ -294,7 +344,7 @@ def train_loop(main_program):
             if step_id == 30:
                 if params_dirname is not None:
                     fluid.io.save_inference_model(params_dirname, ["words"],
-                                                  prediction, exe)
+                                                  prediction, exe)#保存模型
                 return
 ```
 
@@ -325,7 +375,7 @@ inference_scope = fluid.core.Scope()
 ### 生成测试用输入数据
 
 为了进行预测，我们任意选取3个评论。请随意选取您看好的3个。我们把评论中的每个词对应到`word_dict`中的id。如果词典中没有这个词，则设为`unknown`。
-然后我们用`create_lod_tensor`来创建细节层次的张量。
+然后我们用`create_lod_tensor`来创建细节层次的张量，关于该函数的详细解释请参照[API文档](http://paddlepaddle.org/documentation/docs/zh/1.2/user_guides/howto/basic_concept/lod_tensor.html)。
 
 ```python
 reviews_str = [
@@ -354,7 +404,7 @@ with fluid.scope_guard(inference_scope):
      fetch_targets] = fluid.io.load_inference_model(params_dirname, exe)
 
     assert feed_target_names[0] == "words"
-    results = exe.run(inference_program,
+    results = exe.run(inferencer,
                       feed={feed_target_names[0]: tensor_words},
                       fetch_list=fetch_targets,
                       return_numpy=False)

06.understand_sentiment/index.cn.html

@@ -70,7 +70,12 @@
 
 我们在[推荐系统](https://github.com/PaddlePaddle/book/tree/develop/05.recommender_system)一节介绍过应用于文本数据的卷积神经网络模型的计算过程，这里进行一个简单的回顾。
 
-对卷积神经网络来说，首先使用卷积处理输入的词向量序列，产生一个特征图（feature map），对特征图采用时间维度上的最大池化（max pooling over time）操作得到此卷积核对应的整句话的特征，最后，将所有卷积核得到的特征拼接起来即为文本的定长向量表示，对于文本分类问题，将其连接至softmax即构建出完整的模型。在实际应用中，我们会使用多个卷积核来处理句子，窗口大小相同的卷积核堆叠起来形成一个矩阵，这样可以更高效的完成运算。另外，我们也可使用窗口大小不同的卷积核来处理句子，[推荐系统](https://github.com/PaddlePaddle/book/tree/develop/05.recommender_system)一节的图3作为示意画了四个卷积核，不同颜色表示不同大小的卷积核操作。
+对卷积神经网络来说，首先使用卷积处理输入的词向量序列，产生一个特征图（feature map），对特征图采用时间维度上的最大池化（max pooling over time）操作得到此卷积核对应的整句话的特征，最后，将所有卷积核得到的特征拼接起来即为文本的定长向量表示，对于文本分类问题，将其连接至softmax即构建出完整的模型。在实际应用中，我们会使用多个卷积核来处理句子，窗口大小相同的卷积核堆叠起来形成一个矩阵，这样可以更高效的完成运算。另外，我们也可使用窗口大小不同的卷积核来处理句子，[推荐系统](https://github.com/PaddlePaddle/book/tree/develop/05.recommender_system)一节的图3作为示意画了四个卷积核，既文本图1，不同颜色表示不同大小的卷积核操作。
+
+<p align="center">
+<img src="https://github.com/PaddlePaddle/book/blob/develop/05.recommender_system/image/text_cnn.png?raw=true" width = "80%" align="center"/><br/>
+图1. 卷积神经网络文本分类模型
+</p>
 
 对于一般的短文本分类问题，上文所述的简单的文本卷积网络即可达到很高的正确率\[[1](#参考文献)\]。若想得到更抽象更高级的文本特征表示，可以构建深层文本卷积神经网络\[[2](#参考文献),[3](#参考文献)\]。
 
@@ -80,16 +85,16 @@
 
 <p align="center">
 <img src="https://github.com/PaddlePaddle/book/blob/develop/06.understand_sentiment/image/rnn.png?raw=true" width = "60%" align="center"/><br/>
-图1. 循环神经网络按时间展开的示意图
+图2. 循环神经网络按时间展开的示意图
 </p>
 
-循环神经网络按时间展开后如图1所示：在第$t$时刻，网络读入第$t$个输入$x_t$（向量表示）及前一时刻隐层的状态值$h_{t-1}$（向量表示，$h_0$一般初始化为$0$向量），计算得出本时刻隐层的状态值$h_t$，重复这一步骤直至读完所有输入。如果将循环神经网络所表示的函数记为$f$，则其公式可表示为：
+循环神经网络按时间展开后如图2所示：在第$t$时刻，网络读入第$t$个输入$x_t$（向量表示）及前一时刻隐层的状态值$h_{t-1}$（向量表示，$h_0$一般初始化为$0$向量），计算得出本时刻隐层的状态值$h_t$，重复这一步骤直至读完所有输入。如果将循环神经网络所表示的函数记为$f$，则其公式可表示为：
 
 $$h_t=f(x_t,h_{t-1})=\sigma(W_{xh}x_t+W_{hh}h_{t-1}+b_h)$$
 
 其中$W_{xh}$是输入到隐层的矩阵参数，$W_{hh}$是隐层到隐层的矩阵参数，$b_h$为隐层的偏置向量（bias）参数，$\sigma$为$sigmoid$函数。  
 
-在处理自然语言时，一般会先将词（one-hot表示）映射为其词向量（word embedding）表示，然后再作为循环神经网络每一时刻的输入$x_t$。此外，可以根据实际需要的不同在循环神经网络的隐层上连接其它层。如，可以把一个循环神经网络的隐层输出连接至下一个循环神经网络的输入构建深层（deep or stacked）循环神经网络，或者提取最后一个时刻的隐层状态作为句子表示进而使用分类模型等等。  
+在处理自然语言时，一般会先将词（one-hot表示）映射为其词向量表示，然后再作为循环神经网络每一时刻的输入$x_t$。此外，可以根据实际需要的不同在循环神经网络的隐层上连接其它层。如，可以把一个循环神经网络的隐层输出连接至下一个循环神经网络的输入构建深层（deep or stacked）循环神经网络，或者提取最后一个时刻的隐层状态作为句子表示进而使用分类模型等等。  
 
 ### 长短期记忆网络（LSTM）
 
@@ -105,11 +110,11 @@ $$ f_t = \sigma(W_{xf}x_t+W_{hf}h_{t-1}+W_{cf}c_{t-1}+b_f) $$
 $$ c_t = f_t\odot c_{t-1}+i_t\odot tanh(W_{xc}x_t+W_{hc}h_{t-1}+b_c) $$
 $$ o_t = \sigma(W_{xo}x_t+W_{ho}h_{t-1}+W_{co}c_{t}+b_o) $$
 $$ h_t = o_t\odot tanh(c_t) $$
-其中，$i_t, f_t, c_t, o_t$分别表示输入门，遗忘门，记忆单元及输出门的向量值，带角标的$W$及$b$为模型参数，$tanh$为双曲正切函数，$\odot$表示逐元素（elementwise）的乘法操作。输入门控制着新输入进入记忆单元$c$的强度，遗忘门控制着记忆单元维持上一时刻值的强度，输出门控制着输出记忆单元的强度。三种门的计算方式类似，但有着完全不同的参数，它们各自以不同的方式控制着记忆单元$c$，如图2所示：
+其中，$i_t, f_t, c_t, o_t$分别表示输入门，遗忘门，记忆单元及输出门的向量值，带角标的$W$及$b$为模型参数，$tanh$为双曲正切函数，$\odot$表示逐元素（elementwise）的乘法操作。输入门控制着新输入进入记忆单元$c$的强度，遗忘门控制着记忆单元维持上一时刻值的强度，输出门控制着输出记忆单元的强度。三种门的计算方式类似，但有着完全不同的参数，它们各自以不同的方式控制着记忆单元$c$，如图3所示：
 
 <p align="center">
 <img src="https://github.com/PaddlePaddle/book/blob/develop/06.understand_sentiment/image/lstm.png?raw=true" width = "65%" align="center"/><br/>
-图2. 时刻$t$的LSTM [7]
+图3. 时刻$t$的LSTM [7]
 </p>
 
 LSTM通过给简单的循环神经网络增加记忆及控制门的方式，增强了其处理远距离依赖问题的能力。类似原理的改进还有Gated Recurrent Unit (GRU)\[[8](#参考文献)\]，其设计更为简洁一些。**这些改进虽然各有不同，但是它们的宏观描述却与简单的循环神经网络一样（如图2所示），即隐状态依据当前输入及前一时刻的隐状态来改变，不断地循环这一过程直至输入处理完毕：**
@@ -122,11 +127,11 @@ $$ h_t=Recrurent(x_t,h_{t-1})$$
 
 对于正常顺序的循环神经网络，$h_t$包含了$t$时刻之前的输入信息，也就是上文信息。同样，为了得到下文信息，我们可以使用反方向（将输入逆序处理）的循环神经网络。结合构建深层循环神经网络的方法（深层神经网络往往能得到更抽象和高级的特征表示），我们可以通过构建更加强有力的基于LSTM的栈式双向循环神经网络\[[9](#参考文献)\]，来对时序数据进行建模。  
 
-如图3所示（以三层为例），奇数层LSTM正向，偶数层LSTM反向，高一层的LSTM使用低一层LSTM及之前所有层的信息作为输入，对最高层LSTM序列使用时间维度上的最大池化即可得到文本的定长向量表示（这一表示充分融合了文本的上下文信息，并且对文本进行了深层次抽象），最后我们将文本表示连接至softmax构建分类模型。
+如图4所示（以三层为例），奇数层LSTM正向，偶数层LSTM反向，高一层的LSTM使用低一层LSTM及之前所有层的信息作为输入，对最高层LSTM序列使用时间维度上的最大池化即可得到文本的定长向量表示（这一表示充分融合了文本的上下文信息，并且对文本进行了深层次抽象），最后我们将文本表示连接至softmax构建分类模型。
 
 <p align="center">
 <img src="https://github.com/PaddlePaddle/book/blob/develop/06.understand_sentiment/image/stacked_lstm.jpg?raw=true" width=450><br/>
-图3. 栈式双向LSTM用于文本分类
+图4. 栈式双向LSTM用于文本分类
 </p>
 
 
@@ -156,11 +161,11 @@ import numpy as np
 import sys
 import math
 
-CLASS_DIM = 2
-EMB_DIM = 128
-HID_DIM = 512
-STACKED_NUM = 3
-BATCH_SIZE = 128
+CLASS_DIM = 2     #情感分类的类别数
+EMB_DIM = 128     #词向量的维度
+HID_DIM = 512     #隐藏层的维度
+STACKED_NUM = 3   #LSTM双向栈的层数
+BATCH_SIZE = 128  #batch的大小
 
 ```
 
@@ -170,6 +175,7 @@ BATCH_SIZE = 128
 需要注意的是：`fluid.nets.sequence_conv_pool` 包含卷积和池化层两个操作。
 
 ```python
+#文本卷积神经网络
 def convolution_net(data, input_dim, class_dim, emb_dim, hid_dim):
     emb = fluid.layers.embedding(
         input=data, size=[input_dim, emb_dim], is_sparse=True)
@@ -199,32 +205,40 @@ def convolution_net(data, input_dim, class_dim, emb_dim, hid_dim):
 栈式双向神经网络`stacked_lstm_net`的代码片段如下：
 
 ```python
+#栈式双向LSTM
 def stacked_lstm_net(data, input_dim, class_dim, emb_dim, hid_dim, stacked_num):
 
+    #计算词向量
     emb = fluid.layers.embedding(
         input=data, size=[input_dim, emb_dim], is_sparse=True)
 
+    #第一层栈
+    #全连接层
     fc1 = fluid.layers.fc(input=emb, size=hid_dim)
+    #lstm层
     lstm1, cell1 = fluid.layers.dynamic_lstm(input=fc1, size=hid_dim)
 
     inputs = [fc1, lstm1]
 
+    #其余的所有栈结构
     for i in range(2, stacked_num + 1):
         fc = fluid.layers.fc(input=inputs, size=hid_dim)
         lstm, cell = fluid.layers.dynamic_lstm(
             input=fc, size=hid_dim, is_reverse=(i % 2) == 0)
         inputs = [fc, lstm]
 
+    #池化层
     fc_last = fluid.layers.sequence_pool(input=inputs[0], pool_type='max')
     lstm_last = fluid.layers.sequence_pool(input=inputs[1], pool_type='max')
 
+    #全连接层，softmax预测
     prediction = fluid.layers.fc(
         input=[fc_last, lstm_last], size=class_dim, act='softmax')
     return prediction
 ```
-以上的栈式双向LSTM抽象出了高级特征并把其映射到和分类类别数同样大小的向量上。`paddle.activation.Softmax`函数用来计算分类属于某个类别的概率。
+以上的栈式双向LSTM抽象出了高级特征并把其映射到和分类类别数同样大小的向量上。最后一个全连接层的'softmax'激活函数用来计算分类属于某个类别的概率。
 
-重申一下，此处我们可以调用`convolution_net`或`stacked_lstm_net`的任何一个。我们以`convolution_net`为例。
+重申一下，此处我们可以调用`convolution_net`或`stacked_lstm_net`的任何一个网络结构进行训练学习。我们以`convolution_net`为例。
 
 接下来我们定义预测程序（`inference_program`）。预测程序使用`convolution_net`来对`fluid.layer.data`的输入进行预测。
 
@@ -241,9 +255,9 @@ def inference_program(word_dict):
 
 我们这里定义了`training_program`。它使用了从`inference_program`返回的结果来计算误差。我们同时定义了优化函数`optimizer_func`。
 
-因为是有监督的学习，训练集的标签也在`paddle.layer.data`中定义了。在训练过程中，交叉熵用来在`paddle.layer.classification_cost`中作为损失函数。
+因为是有监督的学习，训练集的标签也在`fluid.layers.data`中定义了。在训练过程中，交叉熵用来在`fluid.layer.cross_entropy`中作为损失函数。
 
-在测试过程中，分类器会计算各个输出的概率。第一个返回的数值规定为 损耗(cost)。
+在测试过程中，分类器会计算各个输出的概率。第一个返回的数值规定为cost。
 
 ```python
 def train_program(prediction):
@@ -251,9 +265,9 @@ def train_program(prediction):
     cost = fluid.layers.cross_entropy(input=prediction, label=label)
     avg_cost = fluid.layers.mean(cost)
     accuracy = fluid.layers.accuracy(input=prediction, label=label)
-    return [avg_cost, accuracy]
-
+    return [avg_cost, accuracy]   #返回平均cost和准确率acc
 
+#优化函数
 def optimizer_func():
     return fluid.optimizer.Adagrad(learning_rate=0.002)
 ```
@@ -266,13 +280,13 @@ def optimizer_func():
 
 
 ```python
-use_cuda = False
+use_cuda = False  #在cpu上进行训练
 place = fluid.CUDAPlace(0) if use_cuda else fluid.CPUPlace()
 ```
 
 ### 定义数据提供器
 
-下一步是为训练和测试定义数据提供器。提供器读入一个大小为 BATCH_SIZE的数据。paddle.dataset.imdb.train 每次会在乱序化后提供一个大小为BATCH_SIZE的数据，乱序化的大小为缓存大小buf_size。
+下一步是为训练和测试定义数据提供器。提供器读入一个大小为 BATCH_SIZE的数据。paddle.dataset.imdb.word_dict 每次会在乱序化后提供一个大小为BATCH_SIZE的数据，乱序化的大小为缓存大小buf_size。
 
 注意：读取IMDB的数据可能会花费几分钟的时间，请耐心等待。
 
@@ -285,32 +299,65 @@ train_reader = paddle.batch(
     paddle.reader.shuffle(
         paddle.dataset.imdb.train(word_dict), buf_size=25000),
     batch_size=BATCH_SIZE)
+print("Reading testing data....")
+test_reader = paddle.batch(
+    paddle.dataset.imdb.test(word_dict), batch_size=BATCH_SIZE)
+```
+word_dict是一个字典序列，是词和label的对应关系，运行下一行可以看到具体内容：
+```python
+word_dict
 ```
+每行是如（'limited': 1726）的对应关系，该行表示单词limited所对应的label是1726。
 
-### 构造训练器(trainer)
+### 构造训练器
 训练器需要一个训练程序和一个训练优化函数。
 
 ```python
 exe = fluid.Executor(place)
 prediction = inference_program(word_dict)
-[avg_cost, accuracy] = train_program(prediction)
-sgd_optimizer = optimizer_func()
+[avg_cost, accuracy] = train_program(prediction)#训练程序
+sgd_optimizer = optimizer_func()#训练优化函数
 sgd_optimizer.minimize(avg_cost)
 ```
 
+该函数用来计算训练中模型在test数据集上的结果
+```python
+def train_test(program, reader):
+    count = 0
+    feed_var_list = [
+        program.global_block().var(var_name) for var_name in feed_order
+    ]
+    feeder_test = fluid.DataFeeder(feed_list=feed_var_list, place=place)
+    test_exe = fluid.Executor(place)
+    accumulated = len([avg_cost, accuracy]) * [0]
+    for test_data in reader():
+        avg_cost_np = test_exe.run(
+            program=program,
+            feed=feeder_test.feed(test_data),
+            fetch_list=[avg_cost, accuracy])
+        accumulated = [
+            x[0] + x[1][0] for x in zip(accumulated, avg_cost_np)
+        ]
+        count += 1
+    return [x / count for x in accumulated]
+```
+
 ### 提供数据并构建主训练循环
 
-`feed_order`用来定义每条产生的数据和`paddle.layer.data`之间的映射关系。比如，`imdb.train`产生的第一列的数据对应的是`words`这个特征。
+`feed_order`用来定义每条产生的数据和`fluid.layers.data`之间的映射关系。比如，`imdb.train`产生的第一列的数据对应的是`words`这个特征。
 
 ```python
 # Specify the directory path to save the parameters
 params_dirname = "understand_sentiment_conv.inference.model"
 
 feed_order = ['words', 'label']
-pass_num = 1
+pass_num = 1  #训练循环的轮数
 
+#程序主循环部分
 def train_loop(main_program):
+    #启动上文构建的训练器
     exe.run(fluid.default_startup_program())
+
     feed_var_list_loop = [
         main_program.global_block().var(var_name) for var_name in feed_order
     ]
@@ -319,12 +366,15 @@ def train_loop(main_program):
 
     test_program = fluid.default_main_program().clone(for_test=True)
 
+    #训练循环
     for epoch_id in range(pass_num):
         for step_id, data in enumerate(train_reader()):
+            #运行训练器  
             metrics = exe.run(main_program,
                               feed=feeder.feed(data),
                               fetch_list=[avg_cost, accuracy])
 
+            #测试结果
             avg_cost_test, acc_test = train_test(test_program, test_reader)
             print('Step {0}, Test Loss {1:0.2}, Acc {2:0.2}'.format(
                 step_id, avg_cost_test, acc_test))
@@ -336,7 +386,7 @@ def train_loop(main_program):
             if step_id == 30:
                 if params_dirname is not None:
                     fluid.io.save_inference_model(params_dirname, ["words"],
-                                                  prediction, exe)
+                                                  prediction, exe)#保存模型
                 return
 ```
 
@@ -367,7 +417,7 @@ inference_scope = fluid.core.Scope()
 ### 生成测试用输入数据
 
 为了进行预测，我们任意选取3个评论。请随意选取您看好的3个。我们把评论中的每个词对应到`word_dict`中的id。如果词典中没有这个词，则设为`unknown`。
-然后我们用`create_lod_tensor`来创建细节层次的张量。
+然后我们用`create_lod_tensor`来创建细节层次的张量，关于该函数的详细解释请参照[API文档](http://paddlepaddle.org/documentation/docs/zh/1.2/user_guides/howto/basic_concept/lod_tensor.html)。
 
 ```python
 reviews_str = [
@@ -396,7 +446,7 @@ with fluid.scope_guard(inference_scope):
      fetch_targets] = fluid.io.load_inference_model(params_dirname, exe)
 
     assert feed_target_names[0] == "words"
-    results = exe.run(inference_program,
+    results = exe.run(inferencer,
                       feed={feed_target_names[0]: tensor_words},
                       fetch_list=fetch_targets,
                       return_numpy=False)

07.label_semantic_roles/README.cn.md

@@ -151,7 +151,7 @@ conll05st-release/
 4. 构造以BIO法表示的标记；
 5. 依据词典获取词对应的整数索引。
 
-预处理完成之后一条训练样本包含9个特征，分别是：句子序列、谓词、谓词上下文（占 5 列）、谓词上下区域标志、标注序列。下表是一条训练样本的示例。
+预处理完成之后一条训练样本数据包含9个域，分别是：句子序列、谓词、谓词上下文（占 5 列）、谓词上下区域标志、标注序列。下表是一条训练样本的示例。
 
 | 句子序列 | 谓词 | 谓词上下文（窗口 = 5） | 谓词上下文区域标记 | 标注序列 |
 |---|---|---|---|---|
@@ -206,243 +206,239 @@ print('pred_dict_len: ', pred_dict_len)
 - 定义输入数据维度及模型超参数。
 
 ```python
-mark_dict_len = 2   # 谓上下文区域标志的维度，是一个0-1 2值特征，因此维度为2
-word_dim = 32       # 词向量维度
-mark_dim = 5        # 谓词上下文区域通过词表被映射为一个实向量，这个是相邻的维度
-hidden_dim = 512    # LSTM隐层向量的维度 ： 512 / 4
-depth = 8           # 栈式LSTM的深度
-mix_hidden_lr = 1e-3
+mark_dict_len = 2    # 谓上下文区域标志的维度，是一个0-1 2值特征，因此维度为2
+word_dim = 32        # 词向量维度
+mark_dim = 5         # 谓词上下文区域通过词表被映射为一个实向量，这个是相邻的维度
+hidden_dim = 512     # LSTM隐层向量的维度 ： 512 / 4
+depth = 8            # 栈式LSTM的深度
+mix_hidden_lr = 1e-3 # linear_chain_crf层的基础学习率
 
-IS_SPARSE = True
-PASS_NUM = 10
-BATCH_SIZE = 10
+IS_SPARSE = True     # 是否以稀疏方式更新embedding
+PASS_NUM = 10        # 训练轮数
+BATCH_SIZE = 10      # batch size 大小
 
 embedding_name = 'emb'
 ```
 
-这里需要特别说明的是hidden_dim = 512指定了LSTM隐层向量的维度为128维，关于这一点请参考PaddlePaddle官方文档中[lstmemory](http://www.paddlepaddle.org/doc/ui/api/trainer_config_helpers/layers.html#lstmemory)的说明。
+这里需要特别说明的是，参数 `hidden_dim = 512` 实际指定了LSTM隐层向量的维度为128，关于这一点请参考PaddlePaddle官方文档中[dynamic_lstm](http://www.paddlepaddle.org/documentation/docs/zh/1.2/api_cn/layers_cn.html#dynamic-lstm)的说明。
 
 - 如上文提到，我们用基于英文维基百科训练好的词向量来初始化序列输入、谓词上下文总共6个特征的embedding层参数，在训练中不更新。
 
 ```python
-# 这里加载PaddlePaddle上版保存的二进制模型
+# 这里加载PaddlePaddle保存的二进制参数
 def load_parameter(file_name, h, w):
     with open(file_name, 'rb') as f:
         f.read(16)  # skip header.
         return np.fromfile(f, dtype=np.float32).reshape(h, w)
 ```
 
-- 8个LSTM单元以“正向/反向”的顺序对所有输入序列进行学习。
-
-```python  
-def db_lstm(word, predicate, ctx_n2, ctx_n1, ctx_0, ctx_p1, ctx_p2, mark,
-            **ignored):
-    # 8 features
-    predicate_embedding = fluid.layers.embedding(
-        input=predicate,
-        size=[pred_dict_len, word_dim],
-        dtype='float32',
-        is_sparse=IS_SPARSE,
-        param_attr='vemb')
-
-    mark_embedding = fluid.layers.embedding(
-        input=mark,
-        size=[mark_dict_len, mark_dim],
-        dtype='float32',
-        is_sparse=IS_SPARSE)
-
-    word_input = [word, ctx_n2, ctx_n1, ctx_0, ctx_p1, ctx_p2]
-    # Since word vector lookup table is pre-trained, we won't update it this time.
-    # trainable being False prevents updating the lookup table during training.
-    emb_layers = [
-        fluid.layers.embedding(
-            size=[word_dict_len, word_dim],
-            input=x,
-            param_attr=fluid.ParamAttr(
-                name=embedding_name, trainable=False)) for x in word_input
-    ]
-    emb_layers.append(predicate_embedding)
-    emb_layers.append(mark_embedding)
-
-    # 8 LSTM units are trained through alternating left-to-right / right-to-left order
-    # denoted by the variable `reverse`.
-    hidden_0_layers = [
-        fluid.layers.fc(input=emb, size=hidden_dim, act='tanh')
-        for emb in emb_layers
-    ]
-
-    hidden_0 = fluid.layers.sums(input=hidden_0_layers)
-
-    lstm_0 = fluid.layers.dynamic_lstm(
-        input=hidden_0,
+## 训练模型
+
+- 我们根据网络拓扑结构和模型参数来进行训练，在构造时还需指定优化方法，这里使用最基本的SGD方法(momentum设置为0)，同时设定了学习率、正则等。
+
+定义训练过程的超参数
+```python
+use_cuda = False #在cpu上执行训练
+save_dirname = "label_semantic_roles.inference.model" #训练得到的模型参数保存在文件中
+is_local = True
+```
+
+### 数据输入层定义
+定义了模型输入特征的格式，包括句子序列、谓词、谓词上下文的5个特征、和谓词上下区域标志
+
+```python
+# 句子序列
+word = fluid.layers.data(
+    name='word_data', shape=[1], dtype='int64', lod_level=1)
+
+# 谓词
+predicate = fluid.layers.data(
+    name='verb_data', shape=[1], dtype='int64', lod_level=1)
+
+# 谓词上下文5个特征
+ctx_n2 = fluid.layers.data(
+    name='ctx_n2_data', shape=[1], dtype='int64', lod_level=1)
+ctx_n1 = fluid.layers.data(
+    name='ctx_n1_data', shape=[1], dtype='int64', lod_level=1)
+ctx_0 = fluid.layers.data(
+    name='ctx_0_data', shape=[1], dtype='int64', lod_level=1)
+ctx_p1 = fluid.layers.data(
+    name='ctx_p1_data', shape=[1], dtype='int64', lod_level=1)
+ctx_p2 = fluid.layers.data(
+    name='ctx_p2_data', shape=[1], dtype='int64', lod_level=1)
+
+# 谓词上下区域标志
+mark = fluid.layers.data(
+    name='mark_data', shape=[1], dtype='int64', lod_level=1)
+```
+### 定义网络结构
+首先预训练并定义模型输入层
+
+```python
+#预训练谓词和谓词上下区域标志
+predicate_embedding = fluid.layers.embedding(
+    input=predicate,
+    size=[pred_dict_len, word_dim],
+    dtype='float32',
+    is_sparse=IS_SPARSE,
+    param_attr='vemb')
+
+mark_embedding = fluid.layers.embedding(
+    input=mark,
+    size=[mark_dict_len, mark_dim],
+    dtype='float32',
+    is_sparse=IS_SPARSE)
+
+#句子序列和谓词上下文5个特征并预训练
+word_input = [word, ctx_n2, ctx_n1, ctx_0, ctx_p1, ctx_p2]
+# 因词向量是预训练好的，这里不再训练embedding表，
+# 参数属性trainable设置成False阻止了embedding表在训练过程中被更新
+emb_layers = [
+    fluid.layers.embedding(
+        size=[word_dict_len, word_dim],
+        input=x,
+        param_attr=fluid.ParamAttr(
+            name=embedding_name, trainable=False)) for x in word_input
+]
+#加入谓词和谓词上下区域标志的预训练结果
+emb_layers.append(predicate_embedding)
+emb_layers.append(mark_embedding)
+```
+定义8个LSTM单元以“正向/反向”的顺序对所有输入序列进行学习。
+
+```python
+# 共有8个LSTM单元被训练，每个单元的方向为从左到右或从右到左，
+# 由参数`is_reverse`确定
+# 第一层栈结构
+hidden_0_layers = [
+    fluid.layers.fc(input=emb, size=hidden_dim, act='tanh')
+    for emb in emb_layers
+]
+
+hidden_0 = fluid.layers.sums(input=hidden_0_layers)
+
+lstm_0 = fluid.layers.dynamic_lstm(
+    input=hidden_0,
+    size=hidden_dim,
+    candidate_activation='relu',
+    gate_activation='sigmoid',
+    cell_activation='sigmoid')
+
+# 用直连的边来堆叠L-LSTM、R-LSTM
+input_tmp = [hidden_0, lstm_0]
+
+# 其余的栈结构
+for i in range(1, depth):
+    mix_hidden = fluid.layers.sums(input=[
+        fluid.layers.fc(input=input_tmp[0], size=hidden_dim, act='tanh'),
+        fluid.layers.fc(input=input_tmp[1], size=hidden_dim, act='tanh')
+    ])
+
+    lstm = fluid.layers.dynamic_lstm(
+        input=mix_hidden,
         size=hidden_dim,
         candidate_activation='relu',
         gate_activation='sigmoid',
-        cell_activation='sigmoid')
-
-    # stack L-LSTM and R-LSTM with direct edges
-    input_tmp = [hidden_0, lstm_0]
-
-    # In PaddlePaddle, state features and transition features of a CRF are implemented
-    # by a fully connected layer and a CRF layer seperately. The fully connected layer
-    # with linear activation learns the state features, here we use fluid.layers.sums
-    # (fluid.layers.fc can be uesed as well), and the CRF layer in PaddlePaddle:
-    # fluid.layers.linear_chain_crf only
-    # learns the transition features, which is a cost layer and is the last layer of the network.
-    # fluid.layers.linear_chain_crf outputs the log probability of true tag sequence
-    # as the cost by given the input sequence and it requires the true tag sequence
-    # as target in the learning process.
-
-    for i in range(1, depth):
-        mix_hidden = fluid.layers.sums(input=[
-            fluid.layers.fc(input=input_tmp[0], size=hidden_dim, act='tanh'),
-            fluid.layers.fc(input=input_tmp[1], size=hidden_dim, act='tanh')
-        ])
-
-        lstm = fluid.layers.dynamic_lstm(
-            input=mix_hidden,
-            size=hidden_dim,
-            candidate_activation='relu',
-            gate_activation='sigmoid',
-            cell_activation='sigmoid',
-            is_reverse=((i % 2) == 1))
-
-        input_tmp = [mix_hidden, lstm]
-
-    # 取最后一个栈式LSTM的输出和这个LSTM单元的输入到隐层映射，
-    # 经过一个全连接层映射到标记字典的维度，来学习 CRF 的状态特征
-    feature_out = fluid.layers.sums(input=[
-        fluid.layers.fc(input=input_tmp[0], size=label_dict_len, act='tanh'),
-        fluid.layers.fc(input=input_tmp[1], size=label_dict_len, act='tanh')
-    ])
+        cell_activation='sigmoid',
+        is_reverse=((i % 2) == 1))
+
+    input_tmp = [mix_hidden, lstm]
+
+# 取最后一个栈式LSTM的输出和这个LSTM单元的输入到隐层映射，
+# 经过一个全连接层映射到标记字典的维度，来学习 CRF 的状态特征
+feature_out = fluid.layers.sums(input=[
+    fluid.layers.fc(input=input_tmp[0], size=label_dict_len, act='tanh'),
+    fluid.layers.fc(input=input_tmp[1], size=label_dict_len, act='tanh')
+])
+
+# 标注序列
+target = fluid.layers.data(
+    name='target', shape=[1], dtype='int64', lod_level=1)
+
+# 学习 CRF 的转移特征
+crf_cost = fluid.layers.linear_chain_crf(
+    input=feature_out,
+    label=target,
+    param_attr=fluid.ParamAttr(
+        name='crfw', learning_rate=mix_hidden_lr))
+
+
+avg_cost = fluid.layers.mean(crf_cost)
+
+# 使用最基本的SGD优化方法(momentum设置为0)
+sgd_optimizer = fluid.optimizer.SGD(
+    learning_rate=fluid.layers.exponential_decay(
+        learning_rate=0.01,
+        decay_steps=100000,
+        decay_rate=0.5,
+        staircase=True))
+
+sgd_optimizer.minimize(avg_cost)
+
 
-    return feature_out
 ```
 
-## 训练模型
+数据介绍部分提到CoNLL 2005训练集付费，这里我们使用测试集训练供大家学习。conll05.test()每次产生一条样本，包含9个特征，shuffle和组完batch后作为训练的输入。
 
-- 我们根据网络拓扑结构和模型参数来构造出trainer用来训练，在构造时还需指定优化方法，这里使用最基本的SGD方法(momentum设置为0)，同时设定了学习率、正则等。
+```python
+crf_decode = fluid.layers.crf_decoding(
+    input=feature_out, param_attr=fluid.ParamAttr(name='crfw'))
 
-- 数据介绍部分提到CoNLL 2005训练集付费，这里我们使用测试集训练供大家学习。conll05.test()每次产生一条样本，包含9个特征，shuffle和组完batch后作为训练的输入。
+train_data = paddle.batch(
+    paddle.reader.shuffle(
+        paddle.dataset.conll05.test(), buf_size=8192),
+    batch_size=BATCH_SIZE)
 
-- 通过feeding来指定每一个数据和data_layer的对应关系。 例如 下面feeding表示: conll05.test()产生数据的第0列对应word_data层的特征。
+place = fluid.CUDAPlace(0) if use_cuda else fluid.CPUPlace()
 
-- 可以使用event_handler回调函数来观察训练过程，或进行测试等。这里我们打印了训练过程的cost，该回调函数是trainer.train函数里设定。
+```
+通过feeder来指定每一个数据和data_layer的对应关系, 下面的feeder表示 conll05.test()产生数据的第0列对应的data_layer是 `word`。
 
-- 通过trainer.train函数训练
+```python
+feeder = fluid.DataFeeder(
+    feed_list=[
+        word, ctx_n2, ctx_n1, ctx_0, ctx_p1, ctx_p2, predicate, mark, target
+    ],
+    place=place)
+exe = fluid.Executor(place)
+```
+开始训练
 
 ```python
-def train(use_cuda, save_dirname=None, is_local=True):
-    # define network topology
-
-    # 句子序列
-    word = fluid.layers.data(
-        name='word_data', shape=[1], dtype='int64', lod_level=1)
-
-    # 谓词
-    predicate = fluid.layers.data(
-        name='verb_data', shape=[1], dtype='int64', lod_level=1)
-
-    # 谓词上下文5个特征
-    ctx_n2 = fluid.layers.data(
-        name='ctx_n2_data', shape=[1], dtype='int64', lod_level=1)
-    ctx_n1 = fluid.layers.data(
-        name='ctx_n1_data', shape=[1], dtype='int64', lod_level=1)
-    ctx_0 = fluid.layers.data(
-        name='ctx_0_data', shape=[1], dtype='int64', lod_level=1)
-    ctx_p1 = fluid.layers.data(
-        name='ctx_p1_data', shape=[1], dtype='int64', lod_level=1)
-    ctx_p2 = fluid.layers.data(
-        name='ctx_p2_data', shape=[1], dtype='int64', lod_level=1)
-
-    # 谓词上下区域标志
-    mark = fluid.layers.data(
-        name='mark_data', shape=[1], dtype='int64', lod_level=1)
-
-    # define network topology
-    feature_out = db_lstm(**locals())
-
-    # 标注序列
-    target = fluid.layers.data(
-        name='target', shape=[1], dtype='int64', lod_level=1)
-
-    # 学习 CRF 的转移特征
-    crf_cost = fluid.layers.linear_chain_crf(
-        input=feature_out,
-        label=target,
-        param_attr=fluid.ParamAttr(
-            name='crfw', learning_rate=mix_hidden_lr))
-
-    avg_cost = fluid.layers.mean(crf_cost)
-
-    sgd_optimizer = fluid.optimizer.SGD(
-        learning_rate=fluid.layers.exponential_decay(
-            learning_rate=0.01,
-            decay_steps=100000,
-            decay_rate=0.5,
-            staircase=True))
-
-    sgd_optimizer.minimize(avg_cost)
-
-    # The CRF decoding layer is used for evaluation and inference.
-    # It shares weights with CRF layer.  The sharing of parameters among multiple layers
-    # is specified by using the same parameter name in these layers. If true tag sequence
-    # is provided in training process, `fluid.layers.crf_decoding` calculates labelling error
-    # for each input token and sums the error over the entire sequence.
-    # Otherwise, `fluid.layers.crf_decoding`  generates the labelling tags.
-    crf_decode = fluid.layers.crf_decoding(
-        input=feature_out, param_attr=fluid.ParamAttr(name='crfw'))
-
-    train_data = paddle.batch(
-        paddle.reader.shuffle(
-            paddle.dataset.conll05.test(), buf_size=8192),
-        batch_size=BATCH_SIZE)
-
-    place = fluid.CUDAPlace(0) if use_cuda else fluid.CPUPlace()
-
-
-    feeder = fluid.DataFeeder(
-        feed_list=[
-            word, ctx_n2, ctx_n1, ctx_0, ctx_p1, ctx_p2, predicate, mark, target
-        ],
-        place=place)
-    exe = fluid.Executor(place)
-
-    def train_loop(main_program):
-        exe.run(fluid.default_startup_program())
-        embedding_param = fluid.global_scope().find_var(
-            embedding_name).get_tensor()
-        embedding_param.set(
-            load_parameter(conll05.get_embedding(), word_dict_len, word_dim),
-            place)
-
-        start_time = time.time()
-        batch_id = 0
-        for pass_id in six.moves.xrange(PASS_NUM):
-            for data in train_data():
-                cost = exe.run(main_program,
-                               feed=feeder.feed(data),
-                               fetch_list=[avg_cost])
-                cost = cost[0]
-
-                if batch_id % 10 == 0:
-                    print("avg_cost: " + str(cost))
-                    if batch_id != 0:
-                        print("second per batch: " + str((time.time(
-                        ) - start_time) / batch_id))
-                    # Set the threshold low to speed up the CI test
-                    if float(cost) < 60.0:
-                        if save_dirname is not None:
-                            fluid.io.save_inference_model(save_dirname, [
-                                'word_data', 'verb_data', 'ctx_n2_data',
-                                'ctx_n1_data', 'ctx_0_data', 'ctx_p1_data',
-                                'ctx_p2_data', 'mark_data'
-                            ], [feature_out], exe)
-                        return
-
-                batch_id = batch_id + 1
-
-    train_loop(fluid.default_main_program())
+main_program = fluid.default_main_program()
+
+exe.run(fluid.default_startup_program())
+embedding_param = fluid.global_scope().find_var(
+    embedding_name).get_tensor()
+embedding_param.set(
+    load_parameter(conll05.get_embedding(), word_dict_len, word_dim),
+    place)
+
+start_time = time.time()
+batch_id = 0
+for pass_id in six.moves.xrange(PASS_NUM):
+    for data in train_data():
+        cost = exe.run(main_program,
+                       feed=feeder.feed(data),
+                       fetch_list=[avg_cost])
+        cost = cost[0]
+
+        if batch_id % 10 == 0:
+            print("avg_cost: " + str(cost))
+            if batch_id != 0:
+                print("second per batch: " + str((time.time(
+                ) - start_time) / batch_id))
+            # Set the threshold low to speed up the CI test
+            if float(cost) < 60.0:
+                if save_dirname is not None:
+                    fluid.io.save_inference_model(save_dirname, [
+                        'word_data', 'verb_data', 'ctx_n2_data',
+                        'ctx_n1_data', 'ctx_0_data', 'ctx_p1_data',
+                        'ctx_p2_data', 'mark_data'
+                    ], [feature_out], exe)
+                break
+
+        batch_id = batch_id + 1
 ```
 
 
@@ -450,99 +446,88 @@ def train(use_cuda, save_dirname=None, is_local=True):
 
 训练完成之后，需要依据某个我们关心的性能指标选择最优的模型进行预测，可以简单的选择测试集上标记错误最少的那个模型。以下我们给出一个使用训练后的模型进行预测的示例。
 
+首先设置预测过程的参数
+
 ```python
-def infer(use_cuda, save_dirname=None):
-    if save_dirname is None:
-        return
-
-    place = fluid.CUDAPlace(0) if use_cuda else fluid.CPUPlace()
-    exe = fluid.Executor(place)
-
-    inference_scope = fluid.core.Scope()
-    with fluid.scope_guard(inference_scope):
-        # Use fluid.io.load_inference_model to obtain the inference program desc,
-        # the feed_target_names (the names of variables that will be fed
-        # data using feed operators), and the fetch_targets (variables that
-        # we want to obtain data from using fetch operators).
-        [inference_program, feed_target_names,
-         fetch_targets] = fluid.io.load_inference_model(save_dirname, exe)
-
-        # Setup inputs by creating LoDTensors to represent sequences of words.
-        # Here each word is the basic element of these LoDTensors and the shape of
-        # each word (base_shape) should be [1] since it is simply an index to
-        # look up for the corresponding word vector.
-        # Suppose the length_based level of detail (lod) info is set to [[3, 4, 2]],
-        # which has only one lod level. Then the created LoDTensors will have only
-        # one higher level structure (sequence of words, or sentence) than the basic
-        # element (word). Hence the LoDTensor will hold data for three sentences of
-        # length 3, 4 and 2, respectively.
-        # Note that lod info should be a list of lists.
-        lod = [[3, 4, 2]]
-        base_shape = [1]
-        # The range of random integers is [low, high]
-        word = fluid.create_random_int_lodtensor(
-            lod, base_shape, place, low=0, high=word_dict_len - 1)
-        pred = fluid.create_random_int_lodtensor(
-            lod, base_shape, place, low=0, high=pred_dict_len - 1)
-        ctx_n2 = fluid.create_random_int_lodtensor(
-            lod, base_shape, place, low=0, high=word_dict_len - 1)
-        ctx_n1 = fluid.create_random_int_lodtensor(
-            lod, base_shape, place, low=0, high=word_dict_len - 1)
-        ctx_0 = fluid.create_random_int_lodtensor(
-            lod, base_shape, place, low=0, high=word_dict_len - 1)
-        ctx_p1 = fluid.create_random_int_lodtensor(
-            lod, base_shape, place, low=0, high=word_dict_len - 1)
-        ctx_p2 = fluid.create_random_int_lodtensor(
-            lod, base_shape, place, low=0, high=word_dict_len - 1)
-        mark = fluid.create_random_int_lodtensor(
-            lod, base_shape, place, low=0, high=mark_dict_len - 1)
-
-        # Construct feed as a dictionary of {feed_target_name: feed_target_data}
-        # and results will contain a list of data corresponding to fetch_targets.
-        assert feed_target_names[0] == 'word_data'
-        assert feed_target_names[1] == 'verb_data'
-        assert feed_target_names[2] == 'ctx_n2_data'
-        assert feed_target_names[3] == 'ctx_n1_data'
-        assert feed_target_names[4] == 'ctx_0_data'
-        assert feed_target_names[5] == 'ctx_p1_data'
-        assert feed_target_names[6] == 'ctx_p2_data'
-        assert feed_target_names[7] == 'mark_data'
-
-        results = exe.run(inference_program,
-                          feed={
-                              feed_target_names[0]: word,
-                              feed_target_names[1]: pred,
-                              feed_target_names[2]: ctx_n2,
-                              feed_target_names[3]: ctx_n1,
-                              feed_target_names[4]: ctx_0,
-                              feed_target_names[5]: ctx_p1,
-                              feed_target_names[6]: ctx_p2,
-                              feed_target_names[7]: mark
-                          },
-                          fetch_list=fetch_targets,
-                          return_numpy=False)
-        print(results[0].lod())
-        np_data = np.array(results[0])
-        print("Inference Shape: ", np_data.shape)
+use_cuda = False #在cpu上进行预测
+save_dirname = "label_semantic_roles.inference.model" #调用训练好的模型进行预测
+
+place = fluid.CUDAPlace(0) if use_cuda else fluid.CPUPlace()
+exe = fluid.Executor(place)
 ```
+设置输入，用LoDTensor来表示输入的词序列，这里每个词的形状 base_shape都是[1]，是因为每个词都是用一个id来表示的。假如基于长度的LoD是[[3, 4, 2]]，这是一个单层的LoD，那么构造出的LoDTensor就包含3个序列，其长度分别为3、4和2。
+
+注意LoD是个列表的列表
 
-整个程序的入口如下：
 
 ```python
-def main(use_cuda, is_local=True):
-    if use_cuda and not fluid.core.is_compiled_with_cuda():
-        return
+lod = [[3, 4, 2]]
+base_shape = [1]
+
+# 构造假数据作为输入，整数随机数的范围是[low, high]
+word = fluid.create_random_int_lodtensor(
+    lod, base_shape, place, low=0, high=word_dict_len - 1)
+pred = fluid.create_random_int_lodtensor(
+    lod, base_shape, place, low=0, high=pred_dict_len - 1)
+ctx_n2 = fluid.create_random_int_lodtensor(
+    lod, base_shape, place, low=0, high=word_dict_len - 1)
+ctx_n1 = fluid.create_random_int_lodtensor(
+    lod, base_shape, place, low=0, high=word_dict_len - 1)
+ctx_0 = fluid.create_random_int_lodtensor(
+    lod, base_shape, place, low=0, high=word_dict_len - 1)
+ctx_p1 = fluid.create_random_int_lodtensor(
+    lod, base_shape, place, low=0, high=word_dict_len - 1)
+ctx_p2 = fluid.create_random_int_lodtensor(
+    lod, base_shape, place, low=0, high=word_dict_len - 1)
+mark = fluid.create_random_int_lodtensor(
+    lod, base_shape, place, low=0, high=mark_dict_len - 1)
+```
 
-    # Directory for saving the trained model
-    save_dirname = "label_semantic_roles.inference.model"
+使用fluid.io.load_inference_model加载inference_program，feed_target_names是模型的输入变量的名称，fetch_targets是预测对象。
 
-    train(use_cuda, save_dirname, is_local)
-    infer(use_cuda, save_dirname)
+```python
+[inference_program, feed_target_names,
+ fetch_targets] = fluid.io.load_inference_model(save_dirname, exe)
+```
+构造feed字典 {feed_target_name: feed_target_data}，results是由预测目标构成的列表
 
+```python
+assert feed_target_names[0] == 'word_data'
+assert feed_target_names[1] == 'verb_data'
+assert feed_target_names[2] == 'ctx_n2_data'
+assert feed_target_names[3] == 'ctx_n1_data'
+assert feed_target_names[4] == 'ctx_0_data'
+assert feed_target_names[5] == 'ctx_p1_data'
+assert feed_target_names[6] == 'ctx_p2_data'
+assert feed_target_names[7] == 'mark_data'
+```
+执行预测
 
-main(use_cuda=False)
+```python
+results = exe.run(inference_program,
+                  feed={
+                      feed_target_names[0]: word,
+                      feed_target_names[1]: pred,
+                      feed_target_names[2]: ctx_n2,
+                      feed_target_names[3]: ctx_n1,
+                      feed_target_names[4]: ctx_0,
+                      feed_target_names[5]: ctx_p1,
+                      feed_target_names[6]: ctx_p2,
+                      feed_target_names[7]: mark
+                  },
+                  fetch_list=fetch_targets,
+                  return_numpy=False)
 ```
 
+输出结果
+
+```python
+print(results[0].lod())
+np_data = np.array(results[0])
+print("Inference Shape: ", np_data.shape)
+```
+
+
 ## 总结
 
 语义角色标注是许多自然语言理解任务的重要中间步骤。这篇教程中我们以语义角色标注任务为例，介绍如何利用PaddlePaddle进行序列标注任务。教程中所介绍的模型来自我们发表的论文\[[10](#参考文献)\]。由于 CoNLL 2005 SRL任务的训练数据目前并非完全开放，教程中只使用测试数据作为示例。在这个过程中，我们希望减少对其它自然语言处理工具的依赖，利用神经网络数据驱动、端到端学习的能力，得到一个和传统方法可比、甚至更好的模型。在论文中我们证实了这种可能性。关于模型更多的信息和讨论可以在论文中找到。

07.label_semantic_roles/index.cn.html

@@ -193,7 +193,7 @@ conll05st-release/
 4. 构造以BIO法表示的标记；
 5. 依据词典获取词对应的整数索引。
 
-预处理完成之后一条训练样本包含9个特征，分别是：句子序列、谓词、谓词上下文（占 5 列）、谓词上下区域标志、标注序列。下表是一条训练样本的示例。
+预处理完成之后一条训练样本数据包含9个域，分别是：句子序列、谓词、谓词上下文（占 5 列）、谓词上下区域标志、标注序列。下表是一条训练样本的示例。
 
 | 句子序列 | 谓词 | 谓词上下文（窗口 = 5） | 谓词上下文区域标记 | 标注序列 |
 |---|---|---|---|---|
@@ -248,243 +248,239 @@ print('pred_dict_len: ', pred_dict_len)
 - 定义输入数据维度及模型超参数。
 
 ```python
-mark_dict_len = 2   # 谓上下文区域标志的维度，是一个0-1 2值特征，因此维度为2
-word_dim = 32       # 词向量维度
-mark_dim = 5        # 谓词上下文区域通过词表被映射为一个实向量，这个是相邻的维度
-hidden_dim = 512    # LSTM隐层向量的维度 ： 512 / 4
-depth = 8           # 栈式LSTM的深度
-mix_hidden_lr = 1e-3
+mark_dict_len = 2    # 谓上下文区域标志的维度，是一个0-1 2值特征，因此维度为2
+word_dim = 32        # 词向量维度
+mark_dim = 5         # 谓词上下文区域通过词表被映射为一个实向量，这个是相邻的维度
+hidden_dim = 512     # LSTM隐层向量的维度 ： 512 / 4
+depth = 8            # 栈式LSTM的深度
+mix_hidden_lr = 1e-3 # linear_chain_crf层的基础学习率
 
-IS_SPARSE = True
-PASS_NUM = 10
-BATCH_SIZE = 10
+IS_SPARSE = True     # 是否以稀疏方式更新embedding
+PASS_NUM = 10        # 训练轮数
+BATCH_SIZE = 10      # batch size 大小
 
 embedding_name = 'emb'
 ```
 
-这里需要特别说明的是hidden_dim = 512指定了LSTM隐层向量的维度为128维，关于这一点请参考PaddlePaddle官方文档中[lstmemory](http://www.paddlepaddle.org/doc/ui/api/trainer_config_helpers/layers.html#lstmemory)的说明。
+这里需要特别说明的是，参数 `hidden_dim = 512` 实际指定了LSTM隐层向量的维度为128，关于这一点请参考PaddlePaddle官方文档中[dynamic_lstm](http://www.paddlepaddle.org/documentation/docs/zh/1.2/api_cn/layers_cn.html#dynamic-lstm)的说明。
 
 - 如上文提到，我们用基于英文维基百科训练好的词向量来初始化序列输入、谓词上下文总共6个特征的embedding层参数，在训练中不更新。
 
 ```python
-# 这里加载PaddlePaddle上版保存的二进制模型
+# 这里加载PaddlePaddle保存的二进制参数
 def load_parameter(file_name, h, w):
     with open(file_name, 'rb') as f:
         f.read(16)  # skip header.
         return np.fromfile(f, dtype=np.float32).reshape(h, w)
 ```
 
-- 8个LSTM单元以“正向/反向”的顺序对所有输入序列进行学习。
-
-```python  
-def db_lstm(word, predicate, ctx_n2, ctx_n1, ctx_0, ctx_p1, ctx_p2, mark,
-            **ignored):
-    # 8 features
-    predicate_embedding = fluid.layers.embedding(
-        input=predicate,
-        size=[pred_dict_len, word_dim],
-        dtype='float32',
-        is_sparse=IS_SPARSE,
-        param_attr='vemb')
-
-    mark_embedding = fluid.layers.embedding(
-        input=mark,
-        size=[mark_dict_len, mark_dim],
-        dtype='float32',
-        is_sparse=IS_SPARSE)
-
-    word_input = [word, ctx_n2, ctx_n1, ctx_0, ctx_p1, ctx_p2]
-    # Since word vector lookup table is pre-trained, we won't update it this time.
-    # trainable being False prevents updating the lookup table during training.
-    emb_layers = [
-        fluid.layers.embedding(
-            size=[word_dict_len, word_dim],
-            input=x,
-            param_attr=fluid.ParamAttr(
-                name=embedding_name, trainable=False)) for x in word_input
-    ]
-    emb_layers.append(predicate_embedding)
-    emb_layers.append(mark_embedding)
-
-    # 8 LSTM units are trained through alternating left-to-right / right-to-left order
-    # denoted by the variable `reverse`.
-    hidden_0_layers = [
-        fluid.layers.fc(input=emb, size=hidden_dim, act='tanh')
-        for emb in emb_layers
-    ]
-
-    hidden_0 = fluid.layers.sums(input=hidden_0_layers)
-
-    lstm_0 = fluid.layers.dynamic_lstm(
-        input=hidden_0,
+## 训练模型
+
+- 我们根据网络拓扑结构和模型参数来进行训练，在构造时还需指定优化方法，这里使用最基本的SGD方法(momentum设置为0)，同时设定了学习率、正则等。
+
+定义训练过程的超参数
+```python
+use_cuda = False #在cpu上执行训练
+save_dirname = "label_semantic_roles.inference.model" #训练得到的模型参数保存在文件中
+is_local = True
+```
+
+### 数据输入层定义
+定义了模型输入特征的格式，包括句子序列、谓词、谓词上下文的5个特征、和谓词上下区域标志
+
+```python
+# 句子序列
+word = fluid.layers.data(
+    name='word_data', shape=[1], dtype='int64', lod_level=1)
+
+# 谓词
+predicate = fluid.layers.data(
+    name='verb_data', shape=[1], dtype='int64', lod_level=1)
+
+# 谓词上下文5个特征
+ctx_n2 = fluid.layers.data(
+    name='ctx_n2_data', shape=[1], dtype='int64', lod_level=1)
+ctx_n1 = fluid.layers.data(
+    name='ctx_n1_data', shape=[1], dtype='int64', lod_level=1)
+ctx_0 = fluid.layers.data(
+    name='ctx_0_data', shape=[1], dtype='int64', lod_level=1)
+ctx_p1 = fluid.layers.data(
+    name='ctx_p1_data', shape=[1], dtype='int64', lod_level=1)
+ctx_p2 = fluid.layers.data(
+    name='ctx_p2_data', shape=[1], dtype='int64', lod_level=1)
+
+# 谓词上下区域标志
+mark = fluid.layers.data(
+    name='mark_data', shape=[1], dtype='int64', lod_level=1)
+```
+### 定义网络结构
+首先预训练并定义模型输入层
+
+```python
+#预训练谓词和谓词上下区域标志
+predicate_embedding = fluid.layers.embedding(
+    input=predicate,
+    size=[pred_dict_len, word_dim],
+    dtype='float32',
+    is_sparse=IS_SPARSE,
+    param_attr='vemb')
+
+mark_embedding = fluid.layers.embedding(
+    input=mark,
+    size=[mark_dict_len, mark_dim],
+    dtype='float32',
+    is_sparse=IS_SPARSE)
+
+#句子序列和谓词上下文5个特征并预训练
+word_input = [word, ctx_n2, ctx_n1, ctx_0, ctx_p1, ctx_p2]
+# 因词向量是预训练好的，这里不再训练embedding表，
+# 参数属性trainable设置成False阻止了embedding表在训练过程中被更新
+emb_layers = [
+    fluid.layers.embedding(
+        size=[word_dict_len, word_dim],
+        input=x,
+        param_attr=fluid.ParamAttr(
+            name=embedding_name, trainable=False)) for x in word_input
+]
+#加入谓词和谓词上下区域标志的预训练结果
+emb_layers.append(predicate_embedding)
+emb_layers.append(mark_embedding)
+```
+定义8个LSTM单元以“正向/反向”的顺序对所有输入序列进行学习。
+
+```python
+# 共有8个LSTM单元被训练，每个单元的方向为从左到右或从右到左，
+# 由参数`is_reverse`确定
+# 第一层栈结构
+hidden_0_layers = [
+    fluid.layers.fc(input=emb, size=hidden_dim, act='tanh')
+    for emb in emb_layers
+]
+
+hidden_0 = fluid.layers.sums(input=hidden_0_layers)
+
+lstm_0 = fluid.layers.dynamic_lstm(
+    input=hidden_0,
+    size=hidden_dim,
+    candidate_activation='relu',
+    gate_activation='sigmoid',
+    cell_activation='sigmoid')
+
+# 用直连的边来堆叠L-LSTM、R-LSTM
+input_tmp = [hidden_0, lstm_0]
+
+# 其余的栈结构
+for i in range(1, depth):
+    mix_hidden = fluid.layers.sums(input=[
+        fluid.layers.fc(input=input_tmp[0], size=hidden_dim, act='tanh'),
+        fluid.layers.fc(input=input_tmp[1], size=hidden_dim, act='tanh')
+    ])
+
+    lstm = fluid.layers.dynamic_lstm(
+        input=mix_hidden,
         size=hidden_dim,
         candidate_activation='relu',
         gate_activation='sigmoid',
-        cell_activation='sigmoid')
-
-    # stack L-LSTM and R-LSTM with direct edges
-    input_tmp = [hidden_0, lstm_0]
-
-    # In PaddlePaddle, state features and transition features of a CRF are implemented
-    # by a fully connected layer and a CRF layer seperately. The fully connected layer
-    # with linear activation learns the state features, here we use fluid.layers.sums
-    # (fluid.layers.fc can be uesed as well), and the CRF layer in PaddlePaddle:
-    # fluid.layers.linear_chain_crf only
-    # learns the transition features, which is a cost layer and is the last layer of the network.
-    # fluid.layers.linear_chain_crf outputs the log probability of true tag sequence
-    # as the cost by given the input sequence and it requires the true tag sequence
-    # as target in the learning process.
-
-    for i in range(1, depth):
-        mix_hidden = fluid.layers.sums(input=[
-            fluid.layers.fc(input=input_tmp[0], size=hidden_dim, act='tanh'),
-            fluid.layers.fc(input=input_tmp[1], size=hidden_dim, act='tanh')
-        ])
-
-        lstm = fluid.layers.dynamic_lstm(
-            input=mix_hidden,
-            size=hidden_dim,
-            candidate_activation='relu',
-            gate_activation='sigmoid',
-            cell_activation='sigmoid',
-            is_reverse=((i % 2) == 1))
-
-        input_tmp = [mix_hidden, lstm]
-
-    # 取最后一个栈式LSTM的输出和这个LSTM单元的输入到隐层映射，
-    # 经过一个全连接层映射到标记字典的维度，来学习 CRF 的状态特征
-    feature_out = fluid.layers.sums(input=[
-        fluid.layers.fc(input=input_tmp[0], size=label_dict_len, act='tanh'),
-        fluid.layers.fc(input=input_tmp[1], size=label_dict_len, act='tanh')
-    ])
+        cell_activation='sigmoid',
+        is_reverse=((i % 2) == 1))
+
+    input_tmp = [mix_hidden, lstm]
+
+# 取最后一个栈式LSTM的输出和这个LSTM单元的输入到隐层映射，
+# 经过一个全连接层映射到标记字典的维度，来学习 CRF 的状态特征
+feature_out = fluid.layers.sums(input=[
+    fluid.layers.fc(input=input_tmp[0], size=label_dict_len, act='tanh'),
+    fluid.layers.fc(input=input_tmp[1], size=label_dict_len, act='tanh')
+])
+
+# 标注序列
+target = fluid.layers.data(
+    name='target', shape=[1], dtype='int64', lod_level=1)
+
+# 学习 CRF 的转移特征
+crf_cost = fluid.layers.linear_chain_crf(
+    input=feature_out,
+    label=target,
+    param_attr=fluid.ParamAttr(
+        name='crfw', learning_rate=mix_hidden_lr))
+
+
+avg_cost = fluid.layers.mean(crf_cost)
+
+# 使用最基本的SGD优化方法(momentum设置为0)
+sgd_optimizer = fluid.optimizer.SGD(
+    learning_rate=fluid.layers.exponential_decay(
+        learning_rate=0.01,
+        decay_steps=100000,
+        decay_rate=0.5,
+        staircase=True))
+
+sgd_optimizer.minimize(avg_cost)
+
 
-    return feature_out
 ```
 
-## 训练模型
+数据介绍部分提到CoNLL 2005训练集付费，这里我们使用测试集训练供大家学习。conll05.test()每次产生一条样本，包含9个特征，shuffle和组完batch后作为训练的输入。
 
-- 我们根据网络拓扑结构和模型参数来构造出trainer用来训练，在构造时还需指定优化方法，这里使用最基本的SGD方法(momentum设置为0)，同时设定了学习率、正则等。
+```python
+crf_decode = fluid.layers.crf_decoding(
+    input=feature_out, param_attr=fluid.ParamAttr(name='crfw'))
 
-- 数据介绍部分提到CoNLL 2005训练集付费，这里我们使用测试集训练供大家学习。conll05.test()每次产生一条样本，包含9个特征，shuffle和组完batch后作为训练的输入。
+train_data = paddle.batch(
+    paddle.reader.shuffle(
+        paddle.dataset.conll05.test(), buf_size=8192),
+    batch_size=BATCH_SIZE)
 
-- 通过feeding来指定每一个数据和data_layer的对应关系。 例如 下面feeding表示: conll05.test()产生数据的第0列对应word_data层的特征。
+place = fluid.CUDAPlace(0) if use_cuda else fluid.CPUPlace()
 
-- 可以使用event_handler回调函数来观察训练过程，或进行测试等。这里我们打印了训练过程的cost，该回调函数是trainer.train函数里设定。
+```
+通过feeder来指定每一个数据和data_layer的对应关系, 下面的feeder表示 conll05.test()产生数据的第0列对应的data_layer是 `word`。
 
-- 通过trainer.train函数训练
+```python
+feeder = fluid.DataFeeder(
+    feed_list=[
+        word, ctx_n2, ctx_n1, ctx_0, ctx_p1, ctx_p2, predicate, mark, target
+    ],
+    place=place)
+exe = fluid.Executor(place)
+```
+开始训练
 
 ```python
-def train(use_cuda, save_dirname=None, is_local=True):
-    # define network topology
-
-    # 句子序列
-    word = fluid.layers.data(
-        name='word_data', shape=[1], dtype='int64', lod_level=1)
-
-    # 谓词
-    predicate = fluid.layers.data(
-        name='verb_data', shape=[1], dtype='int64', lod_level=1)
-
-    # 谓词上下文5个特征
-    ctx_n2 = fluid.layers.data(
-        name='ctx_n2_data', shape=[1], dtype='int64', lod_level=1)
-    ctx_n1 = fluid.layers.data(
-        name='ctx_n1_data', shape=[1], dtype='int64', lod_level=1)
-    ctx_0 = fluid.layers.data(
-        name='ctx_0_data', shape=[1], dtype='int64', lod_level=1)
-    ctx_p1 = fluid.layers.data(
-        name='ctx_p1_data', shape=[1], dtype='int64', lod_level=1)
-    ctx_p2 = fluid.layers.data(
-        name='ctx_p2_data', shape=[1], dtype='int64', lod_level=1)
-
-    # 谓词上下区域标志
-    mark = fluid.layers.data(
-        name='mark_data', shape=[1], dtype='int64', lod_level=1)
-
-    # define network topology
-    feature_out = db_lstm(**locals())
-
-    # 标注序列
-    target = fluid.layers.data(
-        name='target', shape=[1], dtype='int64', lod_level=1)
-
-    # 学习 CRF 的转移特征
-    crf_cost = fluid.layers.linear_chain_crf(
-        input=feature_out,
-        label=target,
-        param_attr=fluid.ParamAttr(
-            name='crfw', learning_rate=mix_hidden_lr))
-
-    avg_cost = fluid.layers.mean(crf_cost)
-
-    sgd_optimizer = fluid.optimizer.SGD(
-        learning_rate=fluid.layers.exponential_decay(
-            learning_rate=0.01,
-            decay_steps=100000,
-            decay_rate=0.5,
-            staircase=True))
-
-    sgd_optimizer.minimize(avg_cost)
-
-    # The CRF decoding layer is used for evaluation and inference.
-    # It shares weights with CRF layer.  The sharing of parameters among multiple layers
-    # is specified by using the same parameter name in these layers. If true tag sequence
-    # is provided in training process, `fluid.layers.crf_decoding` calculates labelling error
-    # for each input token and sums the error over the entire sequence.
-    # Otherwise, `fluid.layers.crf_decoding`  generates the labelling tags.
-    crf_decode = fluid.layers.crf_decoding(
-        input=feature_out, param_attr=fluid.ParamAttr(name='crfw'))
-
-    train_data = paddle.batch(
-        paddle.reader.shuffle(
-            paddle.dataset.conll05.test(), buf_size=8192),
-        batch_size=BATCH_SIZE)
-
-    place = fluid.CUDAPlace(0) if use_cuda else fluid.CPUPlace()
-
-
-    feeder = fluid.DataFeeder(
-        feed_list=[
-            word, ctx_n2, ctx_n1, ctx_0, ctx_p1, ctx_p2, predicate, mark, target
-        ],
-        place=place)
-    exe = fluid.Executor(place)
-
-    def train_loop(main_program):
-        exe.run(fluid.default_startup_program())
-        embedding_param = fluid.global_scope().find_var(
-            embedding_name).get_tensor()
-        embedding_param.set(
-            load_parameter(conll05.get_embedding(), word_dict_len, word_dim),
-            place)
-
-        start_time = time.time()
-        batch_id = 0
-        for pass_id in six.moves.xrange(PASS_NUM):
-            for data in train_data():
-                cost = exe.run(main_program,
-                               feed=feeder.feed(data),
-                               fetch_list=[avg_cost])
-                cost = cost[0]
-
-                if batch_id % 10 == 0:
-                    print("avg_cost: " + str(cost))
-                    if batch_id != 0:
-                        print("second per batch: " + str((time.time(
-                        ) - start_time) / batch_id))
-                    # Set the threshold low to speed up the CI test
-                    if float(cost) < 60.0:
-                        if save_dirname is not None:
-                            fluid.io.save_inference_model(save_dirname, [
-                                'word_data', 'verb_data', 'ctx_n2_data',
-                                'ctx_n1_data', 'ctx_0_data', 'ctx_p1_data',
-                                'ctx_p2_data', 'mark_data'
-                            ], [feature_out], exe)
-                        return
-
-                batch_id = batch_id + 1
-
-    train_loop(fluid.default_main_program())
+main_program = fluid.default_main_program()
+
+exe.run(fluid.default_startup_program())
+embedding_param = fluid.global_scope().find_var(
+    embedding_name).get_tensor()
+embedding_param.set(
+    load_parameter(conll05.get_embedding(), word_dict_len, word_dim),
+    place)
+
+start_time = time.time()
+batch_id = 0
+for pass_id in six.moves.xrange(PASS_NUM):
+    for data in train_data():
+        cost = exe.run(main_program,
+                       feed=feeder.feed(data),
+                       fetch_list=[avg_cost])
+        cost = cost[0]
+
+        if batch_id % 10 == 0:
+            print("avg_cost: " + str(cost))
+            if batch_id != 0:
+                print("second per batch: " + str((time.time(
+                ) - start_time) / batch_id))
+            # Set the threshold low to speed up the CI test
+            if float(cost) < 60.0:
+                if save_dirname is not None:
+                    fluid.io.save_inference_model(save_dirname, [
+                        'word_data', 'verb_data', 'ctx_n2_data',
+                        'ctx_n1_data', 'ctx_0_data', 'ctx_p1_data',
+                        'ctx_p2_data', 'mark_data'
+                    ], [feature_out], exe)
+                break
+
+        batch_id = batch_id + 1
 ```
 
 
@@ -492,99 +488,88 @@ def train(use_cuda, save_dirname=None, is_local=True):
 
 训练完成之后，需要依据某个我们关心的性能指标选择最优的模型进行预测，可以简单的选择测试集上标记错误最少的那个模型。以下我们给出一个使用训练后的模型进行预测的示例。
 
+首先设置预测过程的参数
+
 ```python
-def infer(use_cuda, save_dirname=None):
-    if save_dirname is None:
-        return
-
-    place = fluid.CUDAPlace(0) if use_cuda else fluid.CPUPlace()
-    exe = fluid.Executor(place)
-
-    inference_scope = fluid.core.Scope()
-    with fluid.scope_guard(inference_scope):
-        # Use fluid.io.load_inference_model to obtain the inference program desc,
-        # the feed_target_names (the names of variables that will be fed
-        # data using feed operators), and the fetch_targets (variables that
-        # we want to obtain data from using fetch operators).
-        [inference_program, feed_target_names,
-         fetch_targets] = fluid.io.load_inference_model(save_dirname, exe)
-
-        # Setup inputs by creating LoDTensors to represent sequences of words.
-        # Here each word is the basic element of these LoDTensors and the shape of
-        # each word (base_shape) should be [1] since it is simply an index to
-        # look up for the corresponding word vector.
-        # Suppose the length_based level of detail (lod) info is set to [[3, 4, 2]],
-        # which has only one lod level. Then the created LoDTensors will have only
-        # one higher level structure (sequence of words, or sentence) than the basic
-        # element (word). Hence the LoDTensor will hold data for three sentences of
-        # length 3, 4 and 2, respectively.
-        # Note that lod info should be a list of lists.
-        lod = [[3, 4, 2]]
-        base_shape = [1]
-        # The range of random integers is [low, high]
-        word = fluid.create_random_int_lodtensor(
-            lod, base_shape, place, low=0, high=word_dict_len - 1)
-        pred = fluid.create_random_int_lodtensor(
-            lod, base_shape, place, low=0, high=pred_dict_len - 1)
-        ctx_n2 = fluid.create_random_int_lodtensor(
-            lod, base_shape, place, low=0, high=word_dict_len - 1)
-        ctx_n1 = fluid.create_random_int_lodtensor(
-            lod, base_shape, place, low=0, high=word_dict_len - 1)
-        ctx_0 = fluid.create_random_int_lodtensor(
-            lod, base_shape, place, low=0, high=word_dict_len - 1)
-        ctx_p1 = fluid.create_random_int_lodtensor(
-            lod, base_shape, place, low=0, high=word_dict_len - 1)
-        ctx_p2 = fluid.create_random_int_lodtensor(
-            lod, base_shape, place, low=0, high=word_dict_len - 1)
-        mark = fluid.create_random_int_lodtensor(
-            lod, base_shape, place, low=0, high=mark_dict_len - 1)
-
-        # Construct feed as a dictionary of {feed_target_name: feed_target_data}
-        # and results will contain a list of data corresponding to fetch_targets.
-        assert feed_target_names[0] == 'word_data'
-        assert feed_target_names[1] == 'verb_data'
-        assert feed_target_names[2] == 'ctx_n2_data'
-        assert feed_target_names[3] == 'ctx_n1_data'
-        assert feed_target_names[4] == 'ctx_0_data'
-        assert feed_target_names[5] == 'ctx_p1_data'
-        assert feed_target_names[6] == 'ctx_p2_data'
-        assert feed_target_names[7] == 'mark_data'
-
-        results = exe.run(inference_program,
-                          feed={
-                              feed_target_names[0]: word,
-                              feed_target_names[1]: pred,
-                              feed_target_names[2]: ctx_n2,
-                              feed_target_names[3]: ctx_n1,
-                              feed_target_names[4]: ctx_0,
-                              feed_target_names[5]: ctx_p1,
-                              feed_target_names[6]: ctx_p2,
-                              feed_target_names[7]: mark
-                          },
-                          fetch_list=fetch_targets,
-                          return_numpy=False)
-        print(results[0].lod())
-        np_data = np.array(results[0])
-        print("Inference Shape: ", np_data.shape)
+use_cuda = False #在cpu上进行预测
+save_dirname = "label_semantic_roles.inference.model" #调用训练好的模型进行预测
+
+place = fluid.CUDAPlace(0) if use_cuda else fluid.CPUPlace()
+exe = fluid.Executor(place)
 ```
+设置输入，用LoDTensor来表示输入的词序列，这里每个词的形状 base_shape都是[1]，是因为每个词都是用一个id来表示的。假如基于长度的LoD是[[3, 4, 2]]，这是一个单层的LoD，那么构造出的LoDTensor就包含3个序列，其长度分别为3、4和2。
+
+注意LoD是个列表的列表
 
-整个程序的入口如下：
 
 ```python
-def main(use_cuda, is_local=True):
-    if use_cuda and not fluid.core.is_compiled_with_cuda():
-        return
+lod = [[3, 4, 2]]
+base_shape = [1]
+
+# 构造假数据作为输入，整数随机数的范围是[low, high]
+word = fluid.create_random_int_lodtensor(
+    lod, base_shape, place, low=0, high=word_dict_len - 1)
+pred = fluid.create_random_int_lodtensor(
+    lod, base_shape, place, low=0, high=pred_dict_len - 1)
+ctx_n2 = fluid.create_random_int_lodtensor(
+    lod, base_shape, place, low=0, high=word_dict_len - 1)
+ctx_n1 = fluid.create_random_int_lodtensor(
+    lod, base_shape, place, low=0, high=word_dict_len - 1)
+ctx_0 = fluid.create_random_int_lodtensor(
+    lod, base_shape, place, low=0, high=word_dict_len - 1)
+ctx_p1 = fluid.create_random_int_lodtensor(
+    lod, base_shape, place, low=0, high=word_dict_len - 1)
+ctx_p2 = fluid.create_random_int_lodtensor(
+    lod, base_shape, place, low=0, high=word_dict_len - 1)
+mark = fluid.create_random_int_lodtensor(
+    lod, base_shape, place, low=0, high=mark_dict_len - 1)
+```
 
-    # Directory for saving the trained model
-    save_dirname = "label_semantic_roles.inference.model"
+使用fluid.io.load_inference_model加载inference_program，feed_target_names是模型的输入变量的名称，fetch_targets是预测对象。
 
-    train(use_cuda, save_dirname, is_local)
-    infer(use_cuda, save_dirname)
+```python
+[inference_program, feed_target_names,
+ fetch_targets] = fluid.io.load_inference_model(save_dirname, exe)
+```
+构造feed字典 {feed_target_name: feed_target_data}，results是由预测目标构成的列表
 
+```python
+assert feed_target_names[0] == 'word_data'
+assert feed_target_names[1] == 'verb_data'
+assert feed_target_names[2] == 'ctx_n2_data'
+assert feed_target_names[3] == 'ctx_n1_data'
+assert feed_target_names[4] == 'ctx_0_data'
+assert feed_target_names[5] == 'ctx_p1_data'
+assert feed_target_names[6] == 'ctx_p2_data'
+assert feed_target_names[7] == 'mark_data'
+```
+执行预测
 
-main(use_cuda=False)
+```python
+results = exe.run(inference_program,
+                  feed={
+                      feed_target_names[0]: word,
+                      feed_target_names[1]: pred,
+                      feed_target_names[2]: ctx_n2,
+                      feed_target_names[3]: ctx_n1,
+                      feed_target_names[4]: ctx_0,
+                      feed_target_names[5]: ctx_p1,
+                      feed_target_names[6]: ctx_p2,
+                      feed_target_names[7]: mark
+                  },
+                  fetch_list=fetch_targets,
+                  return_numpy=False)
 ```
 
+输出结果
+
+```python
+print(results[0].lod())
+np_data = np.array(results[0])
+print("Inference Shape: ", np_data.shape)
+```
+
+
 ## 总结
 
 语义角色标注是许多自然语言理解任务的重要中间步骤。这篇教程中我们以语义角色标注任务为例，介绍如何利用PaddlePaddle进行序列标注任务。教程中所介绍的模型来自我们发表的论文\[[10](#参考文献)\]。由于 CoNLL 2005 SRL任务的训练数据目前并非完全开放，教程中只使用测试数据作为示例。在这个过程中，我们希望减少对其它自然语言处理工具的依赖，利用神经网络数据驱动、端到端学习的能力，得到一个和传统方法可比、甚至更好的模型。在论文中我们证实了这种可能性。关于模型更多的信息和讨论可以在论文中找到。

07.label_semantic_roles/train.py

@@ -104,7 +104,7 @@ def db_lstm(word, predicate, ctx_n2, ctx_n1, ctx_0, ctx_p1, ctx_p2, mark,
 
 
 def train(use_cuda, save_dirname=None, is_local=True):
-    # define network topology
+    # define data layers
     word = fluid.layers.data(
         name='word_data', shape=[1], dtype='int64', lod_level=1)
     predicate = fluid.layers.data(

08.machine_translation/README.cn.md

@@ -54,9 +54,9 @@
 ### 编码器-解码器框架
 
 编码器-解码器（Encoder-Decoder）\[[2](#参考文献)\]框架用于解决由一个任意长度的源序列到另一个任意长度的目标序列的变换问题。即编码阶段将整个源序列编码成一个向量，解码阶段通过最大化预测序列概率，从中解码出整个目标序列。编码和解码的过程通常都使用RNN实现。
-![encoder_decoder](./image/encoder_decoder.png)
+
 <div align="center">
-<img src ="https://github.com/PaddlePaddle/book/blob/develop/08.machine_translation/image/encoder_decoder.png?raw=true" width="400"><br/>
+<img src ="https://github.com/PaddlePaddle/book/blob/develop/08.machine_translation/image/encoder_decoder.png?raw=true" width="700"><br/>
 图3. 编码器-解码器框架
 </div>
 
@@ -82,7 +82,7 @@
 机器翻译任务的训练过程中，解码阶段的目标是最大化下一个正确的目标语言词的概率。思路是：
 1. 每一个时刻，根据源语言句子的编码信息（又叫上下文向量，context vector）$c$、真实目标语言序列的第$i$个词$u_i$和$i$时刻RNN的隐层状态$z_i$，计算出下一个隐层状态$z_{i+1}$。计算公式如下：
 $$z_{i+1}=\phi_{\theta '} \left ( c,u_i,z_i \right )$$
-其中$\phi _{\theta '}$是一个非线性激活函数；$c=q\mathbf{h}$是源语言句子的上下文向量，在不使用注意力机制时，如果[编码器](#编码器)的输出是源语言句子编码后的最后一个元素，则可以定义$c=h_T$；$u_i$是目标语言序列的第$i$个单词，$u_0$是目标语言序列的开始标记`<s>`，表示解码开始；$z_i$是$i$时刻解码RNN的隐层状态，$z_0$是一个全零的向量。
+其中$\phi _{\theta '}$是一个非线性激活函数；$c$是源语言句子的上下文向量，在不使用注意力机制时，如果[编码器](#编码器)的输出是源语言句子编码后的最后一个元素，则可以定义$c=h_T$；$u_i$是目标语言序列的第$i$个单词，$u_0$是目标语言序列的开始标记`<s>`，表示解码开始；$z_i$是$i$时刻解码RNN的隐层状态，$z_0$是一个全零的向量。
 
 2. 将$z_{i+1}$通过`softmax`归一化，得到目标语言序列的第$i+1$个单词的概率分布$p_{i+1}$。概率分布公式如下：
 $$p\left ( u_{i+1}|u_{&lt;i+1},\mathbf{x} \right )=softmax(W_sz_{i+1}+b_z)$$
@@ -160,33 +160,35 @@ except ImportError:
     from paddle.fluid.trainer import *
     from paddle.fluid.inferencer import *
 
-dict_size = 30000
-source_dict_dim = target_dict_dim = dict_size
-hidden_dim = 32
-word_dim = 16
-batch_size = 2
-max_length = 8
-topk_size = 50
-beam_size = 2
+dict_size = 30000 # 字典维度
+source_dict_dim = target_dict_dim = dict_size # 源/目标语言字典维度
+hidden_dim = 32 # 编码器中的隐层大小
+word_dim = 16 # 词向量维度
+batch_size = 2 # batch 中的样本数
+max_length = 8 # 生成句子的最大长度
+beam_size = 2 # 柱宽度
 
-decoder_size = hidden_dim
+decoder_size = hidden_dim # 解码器中的隐层大小
 ```
 
 然后如下实现编码器框架：
 
    ```python
    def encoder(is_sparse):
+    # 定义源语言id序列的输入数据
     src_word_id = pd.data(
         name="src_word_id", shape=[1], dtype='int64', lod_level=1)
+    # 将上述编码映射到低维语言空间的词向量
     src_embedding = pd.embedding(
         input=src_word_id,
         size=[dict_size, word_dim],
         dtype='float32',
         is_sparse=is_sparse,
         param_attr=fluid.ParamAttr(name='vemb'))
-
+    # LSTM层：fc + dynamic_lstm
     fc1 = pd.fc(input=src_embedding, size=hidden_dim * 4, act='tanh')
     lstm_hidden0, lstm_0 = pd.dynamic_lstm(input=fc1, size=hidden_dim * 4)
+    # 取源语言序列编码后的最后一个状态
     encoder_out = pd.sequence_last_step(input=lstm_hidden0)
     return encoder_out
    ```
@@ -195,6 +197,7 @@ decoder_size = hidden_dim
 
 ```python
    def train_decoder(context, is_sparse):
+    # 定义目标语言id序列的输入数据，并映射到低维语言空间的词向量
     trg_language_word = pd.data(
         name="target_language_word", shape=[1], dtype='int64', lod_level=1)
     trg_embedding = pd.embedding(
@@ -205,17 +208,22 @@ decoder_size = hidden_dim
         param_attr=fluid.ParamAttr(name='vemb'))
 
     rnn = pd.DynamicRNN()
-    with rnn.block():
+    with rnn.block(): # 使用 DynamicRNN 定义每一步的计算
+        # 获取当前步目标语言输入的词向量
         current_word = rnn.step_input(trg_embedding)
+        # 获取隐层状态
         pre_state = rnn.memory(init=context)
+        # 解码器计算单元：单层前馈网络
         current_state = pd.fc(input=[current_word, pre_state],
                               size=decoder_size,
                               act='tanh')
-
+        # 计算归一化的单词预测概率
         current_score = pd.fc(input=current_state,
                               size=target_dict_dim,
                               act='softmax')
+        # 更新RNN的隐层状态
         rnn.update_memory(pre_state, current_state)
+        # 输出预测概率
         rnn.output(current_score)
 
     return rnn()
@@ -226,14 +234,14 @@ decoder_size = hidden_dim
 ```python
 def decode(context, is_sparse):
     init_state = context
+    # 定义解码过程循环计数变量
     array_len = pd.fill_constant(shape=[1], dtype='int64', value=max_length)
     counter = pd.zeros(shape=[1], dtype='int64', force_cpu=True)
 
-    # fill the first element with init_state
+    # 定义 tensor array 用以保存各个时间步的内容，并写入初始id，score和state
     state_array = pd.create_array('float32')
     pd.array_write(init_state, array=state_array, i=counter)
 
-    # ids, scores as memory
     ids_array = pd.create_array('int64')
     scores_array = pd.create_array('float32')
 
@@ -244,34 +252,35 @@ def decode(context, is_sparse):
     pd.array_write(init_ids, array=ids_array, i=counter)
     pd.array_write(init_scores, array=scores_array, i=counter)
 
+    # 定义循环终止条件变量
     cond = pd.less_than(x=counter, y=array_len)
-
+    # 定义 while_op
     while_op = pd.While(cond=cond)
-    with while_op.block():
+    with while_op.block(): # 定义每一步的计算
+        # 获取解码器在当前步的输入，包括上一步选择的id，对应的score和上一步的state
         pre_ids = pd.array_read(array=ids_array, i=counter)
         pre_state = pd.array_read(array=state_array, i=counter)
         pre_score = pd.array_read(array=scores_array, i=counter)
 
-        # expand the lod of pre_state to be the same with pre_score
+        # 更新输入的state为上一步选择id对应的state
         pre_state_expanded = pd.sequence_expand(pre_state, pre_score)
-
+        # 同训练模式下解码器中的计算逻辑，包括获取输入向量，解码器计算单元计算和
+        # 归一化单词预测概率的计算
         pre_ids_emb = pd.embedding(
             input=pre_ids,
             size=[dict_size, word_dim],
             dtype='float32',
             is_sparse=is_sparse)
-
-        # use rnn unit to update rnn
         current_state = pd.fc(input=[pre_state_expanded, pre_ids_emb],
                               size=decoder_size,
                               act='tanh')
         current_state_with_lod = pd.lod_reset(x=current_state, y=pre_score)
-        # use score to do beam search
         current_score = pd.fc(input=current_state_with_lod,
                               size=target_dict_dim,
                               act='softmax')
         topk_scores, topk_indices = pd.topk(current_score, k=beam_size)
-        # calculate accumulated scores after topk to reduce computation cost
+
+        # 计算累计得分，进行beam search
         accu_scores = pd.elementwise_add(
             x=pd.log(topk_scores), y=pd.reshape(pre_score, shape=[-1]), axis=0)
         selected_ids, selected_scores = pd.beam_search(
@@ -284,14 +293,12 @@ def decode(context, is_sparse):
             level=0)
 
         pd.increment(x=counter, value=1, in_place=True)
-
-        # update the memories
+        # 将 search 结果和对应的隐层状态写入 tensor array 中
         pd.array_write(current_state, array=state_array, i=counter)
         pd.array_write(selected_ids, array=ids_array, i=counter)
         pd.array_write(selected_scores, array=scores_array, i=counter)
 
-        # update the break condition: up to the max length or all candidates of
-        # source sentences have ended.
+        # 更新循环终止条件
         length_cond = pd.less_than(x=counter, y=array_len)
         finish_cond = pd.logical_not(pd.is_empty(x=selected_ids))
         pd.logical_and(x=length_cond, y=finish_cond, out=cond)

08.machine_translation/index.cn.html

@@ -96,9 +96,9 @@
 ### 编码器-解码器框架
 
 编码器-解码器（Encoder-Decoder）\[[2](#参考文献)\]框架用于解决由一个任意长度的源序列到另一个任意长度的目标序列的变换问题。即编码阶段将整个源序列编码成一个向量，解码阶段通过最大化预测序列概率，从中解码出整个目标序列。编码和解码的过程通常都使用RNN实现。
-![encoder_decoder](./image/encoder_decoder.png)
+
 <div align="center">
-<img src ="https://github.com/PaddlePaddle/book/blob/develop/08.machine_translation/image/encoder_decoder.png?raw=true" width="400"><br/>
+<img src ="https://github.com/PaddlePaddle/book/blob/develop/08.machine_translation/image/encoder_decoder.png?raw=true" width="700"><br/>
 图3. 编码器-解码器框架
 </div>
 
@@ -124,7 +124,7 @@
 机器翻译任务的训练过程中，解码阶段的目标是最大化下一个正确的目标语言词的概率。思路是：
 1. 每一个时刻，根据源语言句子的编码信息（又叫上下文向量，context vector）$c$、真实目标语言序列的第$i$个词$u_i$和$i$时刻RNN的隐层状态$z_i$，计算出下一个隐层状态$z_{i+1}$。计算公式如下：
 $$z_{i+1}=\phi_{\theta '} \left ( c,u_i,z_i \right )$$
-其中$\phi _{\theta '}$是一个非线性激活函数；$c=q\mathbf{h}$是源语言句子的上下文向量，在不使用注意力机制时，如果[编码器](#编码器)的输出是源语言句子编码后的最后一个元素，则可以定义$c=h_T$；$u_i$是目标语言序列的第$i$个单词，$u_0$是目标语言序列的开始标记`<s>`，表示解码开始；$z_i$是$i$时刻解码RNN的隐层状态，$z_0$是一个全零的向量。
+其中$\phi _{\theta '}$是一个非线性激活函数；$c$是源语言句子的上下文向量，在不使用注意力机制时，如果[编码器](#编码器)的输出是源语言句子编码后的最后一个元素，则可以定义$c=h_T$；$u_i$是目标语言序列的第$i$个单词，$u_0$是目标语言序列的开始标记`<s>`，表示解码开始；$z_i$是$i$时刻解码RNN的隐层状态，$z_0$是一个全零的向量。
 
 2. 将$z_{i+1}$通过`softmax`归一化，得到目标语言序列的第$i+1$个单词的概率分布$p_{i+1}$。概率分布公式如下：
 $$p\left ( u_{i+1}|u_{&lt;i+1},\mathbf{x} \right )=softmax(W_sz_{i+1}+b_z)$$
@@ -202,33 +202,35 @@ except ImportError:
     from paddle.fluid.trainer import *
     from paddle.fluid.inferencer import *
 
-dict_size = 30000
-source_dict_dim = target_dict_dim = dict_size
-hidden_dim = 32
-word_dim = 16
-batch_size = 2
-max_length = 8
-topk_size = 50
-beam_size = 2
+dict_size = 30000 # 字典维度
+source_dict_dim = target_dict_dim = dict_size # 源/目标语言字典维度
+hidden_dim = 32 # 编码器中的隐层大小
+word_dim = 16 # 词向量维度
+batch_size = 2 # batch 中的样本数
+max_length = 8 # 生成句子的最大长度
+beam_size = 2 # 柱宽度
 
-decoder_size = hidden_dim
+decoder_size = hidden_dim # 解码器中的隐层大小
 ```
 
 然后如下实现编码器框架：
 
    ```python
    def encoder(is_sparse):
+    # 定义源语言id序列的输入数据
     src_word_id = pd.data(
         name="src_word_id", shape=[1], dtype='int64', lod_level=1)
+    # 将上述编码映射到低维语言空间的词向量
     src_embedding = pd.embedding(
         input=src_word_id,
         size=[dict_size, word_dim],
         dtype='float32',
         is_sparse=is_sparse,
         param_attr=fluid.ParamAttr(name='vemb'))
-
+    # LSTM层：fc + dynamic_lstm
     fc1 = pd.fc(input=src_embedding, size=hidden_dim * 4, act='tanh')
     lstm_hidden0, lstm_0 = pd.dynamic_lstm(input=fc1, size=hidden_dim * 4)
+    # 取源语言序列编码后的最后一个状态
     encoder_out = pd.sequence_last_step(input=lstm_hidden0)
     return encoder_out
    ```
@@ -237,6 +239,7 @@ decoder_size = hidden_dim
 
 ```python
    def train_decoder(context, is_sparse):
+    # 定义目标语言id序列的输入数据，并映射到低维语言空间的词向量
     trg_language_word = pd.data(
         name="target_language_word", shape=[1], dtype='int64', lod_level=1)
     trg_embedding = pd.embedding(
@@ -247,17 +250,22 @@ decoder_size = hidden_dim
         param_attr=fluid.ParamAttr(name='vemb'))
 
     rnn = pd.DynamicRNN()
-    with rnn.block():
+    with rnn.block(): # 使用 DynamicRNN 定义每一步的计算
+        # 获取当前步目标语言输入的词向量
         current_word = rnn.step_input(trg_embedding)
+        # 获取隐层状态
         pre_state = rnn.memory(init=context)
+        # 解码器计算单元：单层前馈网络
         current_state = pd.fc(input=[current_word, pre_state],
                               size=decoder_size,
                               act='tanh')
-
+        # 计算归一化的单词预测概率
         current_score = pd.fc(input=current_state,
                               size=target_dict_dim,
                               act='softmax')
+        # 更新RNN的隐层状态
         rnn.update_memory(pre_state, current_state)
+        # 输出预测概率
         rnn.output(current_score)
 
     return rnn()
@@ -268,14 +276,14 @@ decoder_size = hidden_dim
 ```python
 def decode(context, is_sparse):
     init_state = context
+    # 定义解码过程循环计数变量
     array_len = pd.fill_constant(shape=[1], dtype='int64', value=max_length)
     counter = pd.zeros(shape=[1], dtype='int64', force_cpu=True)
 
-    # fill the first element with init_state
+    # 定义 tensor array 用以保存各个时间步的内容，并写入初始id，score和state
     state_array = pd.create_array('float32')
     pd.array_write(init_state, array=state_array, i=counter)
 
-    # ids, scores as memory
     ids_array = pd.create_array('int64')
     scores_array = pd.create_array('float32')
 
@@ -286,34 +294,35 @@ def decode(context, is_sparse):
     pd.array_write(init_ids, array=ids_array, i=counter)
     pd.array_write(init_scores, array=scores_array, i=counter)
 
+    # 定义循环终止条件变量
     cond = pd.less_than(x=counter, y=array_len)
-
+    # 定义 while_op
     while_op = pd.While(cond=cond)
-    with while_op.block():
+    with while_op.block(): # 定义每一步的计算
+        # 获取解码器在当前步的输入，包括上一步选择的id，对应的score和上一步的state
         pre_ids = pd.array_read(array=ids_array, i=counter)
         pre_state = pd.array_read(array=state_array, i=counter)
         pre_score = pd.array_read(array=scores_array, i=counter)
 
-        # expand the lod of pre_state to be the same with pre_score
+        # 更新输入的state为上一步选择id对应的state
         pre_state_expanded = pd.sequence_expand(pre_state, pre_score)
-
+        # 同训练模式下解码器中的计算逻辑，包括获取输入向量，解码器计算单元计算和
+        # 归一化单词预测概率的计算
         pre_ids_emb = pd.embedding(
             input=pre_ids,
             size=[dict_size, word_dim],
             dtype='float32',
             is_sparse=is_sparse)
-
-        # use rnn unit to update rnn
         current_state = pd.fc(input=[pre_state_expanded, pre_ids_emb],
                               size=decoder_size,
                               act='tanh')
         current_state_with_lod = pd.lod_reset(x=current_state, y=pre_score)
-        # use score to do beam search
         current_score = pd.fc(input=current_state_with_lod,
                               size=target_dict_dim,
                               act='softmax')
         topk_scores, topk_indices = pd.topk(current_score, k=beam_size)
-        # calculate accumulated scores after topk to reduce computation cost
+
+        # 计算累计得分，进行beam search
         accu_scores = pd.elementwise_add(
             x=pd.log(topk_scores), y=pd.reshape(pre_score, shape=[-1]), axis=0)
         selected_ids, selected_scores = pd.beam_search(
@@ -326,14 +335,12 @@ def decode(context, is_sparse):
             level=0)
 
         pd.increment(x=counter, value=1, in_place=True)
-
-        # update the memories
+        # 将 search 结果和对应的隐层状态写入 tensor array 中
         pd.array_write(current_state, array=state_array, i=counter)
         pd.array_write(selected_ids, array=ids_array, i=counter)
         pd.array_write(selected_scores, array=scores_array, i=counter)
 
-        # update the break condition: up to the max length or all candidates of
-        # source sentences have ended.
+        # 更新循环终止条件
         length_cond = pd.less_than(x=counter, y=array_len)
         finish_cond = pd.logical_not(pd.is_empty(x=selected_ids))
         pd.logical_and(x=length_cond, y=finish_cond, out=cond)

README.cn.md

 # 深度学习入门
 
 [![Build Status](https://travis-ci.org/PaddlePaddle/book.svg?branch=develop)](https://travis-ci.org/PaddlePaddle/book)
-[![Documentation Status](https://img.shields.io/badge/docs-latest-brightgreen.svg?style=flat)](http://www.paddlepaddle.org/docs/develop/book/01.fit_a_line/index.html)
-[![Documentation Status](https://img.shields.io/badge/中文文档-最新-brightgreen.svg)](http://www.paddlepaddle.org/docs/develop/book/01.fit_a_line/index.cn.html)
+[![Documentation Status](https://img.shields.io/badge/docs-latest-brightgreen.svg?style=flat)](https://github.com/PaddlePaddle/book/blob/develop/README.md)
+[![Documentation Status](https://img.shields.io/badge/中文文档-最新-brightgreen.svg)](https://github.com/PaddlePaddle/book/blob/develop/README.cn.md)
 
 1. [线性回归](http://www.paddlepaddle.org/documentation/book/zh/develop/01.fit_a_line/index.cn.html)
 1. [识别数字](http://www.paddlepaddle.org/documentation/book/zh/develop/02.recognize_digits/index.cn.html)
@@ -69,4 +69,4 @@ use_cuda = True
 **Note:** We also provide [English Readme](https://github.com/PaddlePaddle/book/blob/develop/README.md) for PaddlePaddle book.
 
 
-<a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/"><img alt="知识共享许可协议" style="border-width:0" src="https://i.creativecommons.org/l/by-sa/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" href="http://purl.org/dc/dcmitype/Text" property="dct:title" rel="dct:type">本教程</span> 由 <a xmlns:cc="http://creativecommons.org/ns#" href="http://book.paddlepaddle.org" property="cc:attributionName" rel="cc:attributionURL">PaddlePaddle</a> 创作，采用 <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">知识共享 署名-相同方式共享 4.0 国际 许可协议</a>进行许可。
+<a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/"><img alt="知识共享许可协议" style="border-width:0" src="https://i.creativecommons.org/l/by-sa/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" href="http://purl.org/dc/dcmitype/Text" property="dct:title" rel="dct:type">本教程</span> 由 <a xmlns:cc="http://creativecommons.org/ns#" href="http://www.paddlepaddle.org/" property="cc:attributionName" rel="cc:attributionURL">PaddlePaddle</a> 创作，采用 <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">知识共享 署名-相同方式共享 4.0 国际 许可协议</a>进行许可。

README.md

 # Deep Learning with PaddlePaddle
 
 [![Build Status](https://travis-ci.org/PaddlePaddle/book.svg?branch=develop)](https://travis-ci.org/PaddlePaddle/book)
-[![Documentation Status](https://img.shields.io/badge/docs-latest-brightgreen.svg?style=flat)](http://www.paddlepaddle.org/docs/develop/book/01.fit_a_line/index.html)
-[![Documentation Status](https://img.shields.io/badge/中文文档-最新-brightgreen.svg)](http://www.paddlepaddle.org/docs/develop/book/01.fit_a_line/index.cn.html)
+[![Documentation Status](https://img.shields.io/badge/docs-latest-brightgreen.svg?style=flat)](https://github.com/PaddlePaddle/book/blob/develop/README.md)
+[![Documentation Status](https://img.shields.io/badge/中文文档-最新-brightgreen.svg)](https://github.com/PaddlePaddle/book/blob/develop/README.cn.md)
 
 1. [Fit a Line](http://www.paddlepaddle.org/documentation/book/en/develop/01.fit_a_line/index.html)
 1. [Recognize Digits](http://www.paddlepaddle.org/documentation/book/en/develop/02.recognize_digits/index.html)
@@ -69,4 +69,4 @@ use_cuda = True
 Your contribution is welcome!  Please feel free to file Pull Requests to add your chapter as a directory under `/pending`. Once it is going stable, the community would like to move it to `/`.
 
 To write, run, and debug your chapters, you will need Python 2.x, Go >1.5. You can build the Docker image using [this script](https://github.com/PaddlePaddle/book/blob/develop/.tools/convert-markdown-into-ipynb-and-test.sh).
-This tutorial is contributed by <a xmlns:cc="http://creativecommons.org/ns#" href="http://book.paddlepaddle.org" property="cc:attributionName" rel="cc:attributionURL">PaddlePaddle</a>, and licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International License</a>.
+This tutorial is contributed by <a xmlns:cc="http://creativecommons.org/ns#" href="http://www.paddlepaddle.org/" property="cc:attributionName" rel="cc:attributionURL">PaddlePaddle</a>, and licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International License</a>.