Complete single_node train

source/user_guides/howto/prepare_data/feeding_data.rst

@@ -38,6 +38,8 @@ PaddlePaddle Fluid支持使用 :ref:`api_fluid_layers_data` 配置数据层；
 
 2. Fluid中目前使用 :code:`int64` 表示类别标签。
 
+.. _user_guide_feed_data_to_executor:
+
 传递训练数据给执行器
 ####################
 

source/user_guides/howto/training/single_node.rst

@@ -43,6 +43,19 @@
 参数随机初始化
 ==============
 
+用户配置完模型后，参数初始化操作会被写入到
+:code:`fluid.default_startup_program()` 中。使用 :ref:`api_fluid_Executor` 运行
+这一程序，即可在全局 :ref:`api_fluid_Scope` 中随机初始化参数。例如:
+
+.. code-blocks:: python
+
+   exe = fluid.Executor(fluid.CUDAPlace(0))
+   exe.run(program=fluid.default_startup_program())
+
+值得注意的是: 如果使用多GPU训练，参数需要先在GPU0上初始化，再经由
+:ref:`api_fluid_ParallelExecutor` 分发到多张显卡上。
+
+
 载入预定义参数
 ==============
 
@@ -53,15 +66,55 @@
 单卡训练
 ########
 
+执行单卡训练可以使用 :ref:`api_fluid_Executor` 中的 :code:`run()` 方法，运行训练
+:ref:`api_fluid_Program` 即可。在运行的时候，用户可以通过 :code:`run(feed=...)`
+参数传入数据；用户可以通过 :code:`run(fetch=...)` 获取持久的数据。例如:
+
+.. code-blocks:: python
+
+   ...
+   loss = fluid.layers.mean(...)
+
+   exe = fluid.Executor(...)
+   # the result is an numpy array
+   result = exe.run(feed={"image": ..., "label": ...}, fetch_list=[loss])
+
+这里有几点注意事项:
+
+1. feed的数据格式，请参考文章 :ref:`user_guide_feed_data_to_executor`。
+2. :code:`Executor.run` 的返回值是 :code:`fetch_list=[...]` 的variable值。被fetch
+   的Variable必须是persistable的。 :code:`fetch_list` 可以传入Variable的列表，
+   也可以传入Varialbe的名字列表。当只Fetch一个对象时，返回值是一个元素。否则，
+   返回一个列表。
+3. 如果需要取回的数据包含序列信息，可以设置
+   :code:`exe.run(return_numpy=False, ...)` 直接返回 :ref:`api_guide_lod_tensor`
+   。用户可以直接访问 :ref:`api_guide_lod_tensor` 中的信息。
 
 多卡训练
 ########
 
+执行多卡训练可以使用 :ref:`api_fluid_ParallelExecutor` 运行训练
+:ref:`api_fluid_Program`。例如:
 
-边训练边测试
-############
+.. code-blocks:: python
 
+   train_exe = fluid.ParallelExecutor(use_cuda=True, loss_name=loss.name,
+                                main_program=fluid.default_main_program())
+   train_exe.run(fetch_list=[loss.name], feed={...})
+
+这里有几点注意事项:
+
+1. :code:`ParallelExecutor` 的构造函数需要指明要执行的 :ref:`api_fluid_Program` ，
+  并在执行过程中不能修改。
+2. :code:`ParallelExecutor` 需要明确指定是否使用 CUDA 显卡进行训练。在显卡训练
+  模式下会占用全部显卡。用户可以配置 `CUDA_VISIBLE_DEVICES <http://www.acceleware.com/blog/cudavisibledevices-masking-gpus>`_ 来修改占用
+  的显卡。
 
 进阶使用
 ########
 
+.. toctree::
+   :maxdepth: 2
+
+   test_while_training
+   save_load_variables
\ No newline at end of file

source/user_guides/howto/training/test_while_training.rst

+##################
+训练过程中评测模型
+##################
+
+模型的测试评价与训练的 :ref:`api_fluid_Program` 不同。在测试评价中:
+
+1. 评价测试不进行反向传播，不优化更新参数。
+2. 评价测试执行的操作可以不同。
+   * 例如 BatchNorm 操作，在训练和测试时执行不同的算法。
+   * 评价模型与训练相比可以是完全不同的模型。
+
+生成测试 :ref:`api_fluid_Program`
+#################################
+
+通过克隆训练 :ref:`api_fluid_Program` 生成测试 :ref:`api_fluid_Program`
+=======================================================================
+
+:code:`Program.clone()` 方法可以复制出新的 :ref:`api_fluid_Program` 。 通过设置
+:code:`Program.clone(for_test=True)` 复制出用于测试的操作。简单的使用方法如下:
+
+.. code-blocks:: python
+
+   import paddle.fluid as fluid
+
+   img = fluid.layers.data(name="image", shape=[784])
+   prediction = fluid.layers.fc(
+     input=fluid.layers.fc(input=img, size=100, act='relu'),
+     size=10,
+     act='softmax'
+   )
+   label = fluid.layers.data(name="label", shape=[1], dtype="int64")
+   loss = fluid.layers.mean(fluid.layers.cross_entropy(input=prediction, label=label))
+   acc = fluid.layers.accuracy(input=prediction, label=label)
+
+   test_program = fluid.default_main_program().clone(for_test=True)
+
+   adam = fluid.optimizer.Adam(learning_rate=0.001)
+   adam.minimize(loss)
+
+在使用 :code:`Optimizer` 之前，将 :code:`fluid.default_main_program()` 复制
+成一个 :code:`test_program` 。之后使用测试数据运行 :code:`test_program`,
+就可以做到运行测试程序，而不影响训练结果。
+
+分别配置训练 :ref:`api_fluid_Program` 和测试 :ref:`api_fluid_Program`
+=====================================================================
+
+如果训练程序和测试程序相差较大时，用户也可以完全通过定义两个不同的
+:ref:`api_fluid_Program`，分别进行训练和测试。在PaddlePaddle Fluid中，
+所有的参数都有名字。如果两个不同的操作，甚至两个不同的网络使用了同样名字的参数，
+那么他们的值和内存空间都是共享的。
+
+PaddlePaddle Fluid中使用 :code:`fluid.unique_name` 包来随机初始化用户未定义的
+参数名称。通过 :code:`fluid.unique_name.guard` 可以确保多次调用某函数
+参数初始化的名称一致。
+
+例如:
+
+.. code-block:: python
+
+   import paddle.fluid as fluid
+
+   def network(is_test):
+       file_obj = fluid.layers.open_files(filenames=["test.recordio"] if is_test else ["train.recordio"], ...)
+       img, label = fluid.layers.read_file(file_obj)
+       hidden = fluid.layers.fc(input=img, size=100, act="relu")
+       hidden = fluid.layers.batch_norm(input=hidden, is_test=is_test)
+       ...
+       return loss
+
+   with fluid.unique_name.guard():
+       train_loss = network(is_test=False)
+       sgd = fluid.optimizer.SGD(0.001)
+       sgd.minimize(train_loss)
+
+   test_program = fluid.Program()
+   with fluid.unique_name.guard():
+       with fluid.program_gurad(test_program, fluid.Program()):
+           test_loss = network(is_test=True)
+
+   # fluid.default_main_program() is the train program
+   # fluid.test_program is the test program
+
+执行测试 :ref:`api_fluid_Program`
+#################################
+
+使用 :code:`Executor` 执行测试 :ref:`api_fluid_Program`
+=======================================================
+
+用户可以使用 :code:`Executor.run(program=...)` 来执行测试
+:ref:`api_fluid_Program`。
+
+例如
+
+.. code-block:: python
+
+   exe = fluid.Executor(fluid.CPUPlace())
+   test_acc = exe.run(program=test_program, feed=test_data_batch, fetch_list=[acc])
+   print 'Test accuracy is ', test_acc
+
+使用 :code:`ParallelExecutor` 执行测试 :ref:`api_fluid_Program`
+===============================================================
+
+用户可以使用训练用的 :code:`ParallelExecutor` 与测试 :ref:`api_fluid_Program`
+一起新建一个测试的 :code:`ParallelExecutor` ；再使用测试
+:code:`ParallelExecutor.run` 来执行测试。
+
+例如:
+
+.. code-block:: python
+
+   train_exec = fluid.ParallelExecutor(use_cuda=True, loss_name=loss.name)
+
+   test_exec = fluid.ParallelExecutor(use_cuda=True, share_vars_from=train_exec,
+                                      main_program=test_program)
+   test_acc = test_exec.run(fetch_list=[acc], ...)
+