Merge pull request #16 from reyoung/feature/single_node_training

Feature/single node training

source/user_guides/howto/index.rst

@@ -5,5 +5,8 @@
 .. toctree::
    :maxdepth: 2 
 
+
    prepare_data/index
    configure_simple_model/index
+   training/index
+

source/user_guides/howto/prepare_data/feeding_data.rst

@@ -39,6 +39,8 @@ PaddlePaddle Fluid支持使用 :ref:`api_fluid_layers_data` 配置数据层；
 
 2. Fluid中用来做类别标签的数据类型是 :code:`int64`，并且标签从0开始。可用数据类型请参考 :ref:`user_guide_paddle_support_data_types`。
 
+.. _user_guide_feed_data_to_executor:
+
 传递训练数据给执行器
 ####################
 

source/user_guides/howto/training/foo.rst

-###
-FAQ
-###

source/user_guides/howto/training/index.rst

+############
+训练神经网络
+############
+
+PaddlePaddle Fluid支持单机训练，和多节点训练。每种训练模式下，都支持多种训练方法。
+
+.. toctree::
+   :maxdepth: 2
+
+   single_node
+   multi_node

source/user_guides/howto/training/multi_node.rst

+########
+多机训练
+########
\ No newline at end of file

source/user_guides/howto/training/save_load_variables.rst

+.. _user_guide_save_load_vars:
+
+##################
+保存与载入模型变量
+##################
+
+模型变量分类
+############
+
+在PaddlePaddle Fluid中，所有的模型变量都用 :ref:`api_fluid_Variable` 作为基类进行表示。
+在该基类之下，模型变量主要可以分为以下几种类别：
+
+1. 模型参数
+  模型参数是深度学习模型中被训练和学习的变量，在训练过程中，训练框架根据反向传播算法计算出每一个模型参数当前的梯度，
+  并用优化器根据梯度对参数进行更新。模型的训练过程本质上可以看做是模型参数不断迭代更新的过程。
+  在PaddlePaddle Fluid中，模型参数用 :code:`fluid.framework.Parameter` 来表示，
+  这是一个 :ref:`api_fluid_Variable` 的派生类，除了 :ref:`api_fluid_Variable` 具有的各项性质以外，
+  :code:`fluid.framework.Parameter` 还可以配置自身的初始化方法、更新率等属性。
+
+2. 长期变量
+  长期变量指的是在整个训练过程中持续存在、不会因为一个迭代的结束而被销毁的变量，例如动态调节的全局学习率等。
+  在PaddlePaddle Fluid中，长期变量通过将 :ref:`api_fluid_Variable` 的 :code:`persistable`
+  属性设置为 :code:`True` 来表示。所有的模型参数都是长期变量，但并非所有的长期变量都是模型参数。
+
+3. 临时变量
+  不属于上面两个类别的所有模型变量都是临时变量，这种类型的变量只在一个训练迭代中存在，在每一个迭代结束后，
+  所有的临时变量都会被销毁，然后在下一个迭代开始之前，又会先构造出新的临时变量供本轮迭代使用。
+  一般情况下模型中的大部分变量都属于这一类别，例如输入的训练数据、一个普通的layer的输出等等。
+
+
+
+如何保存模型变量
+################
+
+根据用途的不同，我们需要保存的模型变量也是不同的。例如，如果我们只是想保存模型用来进行以后的预测，
+那么只保存模型参数就够用了。但如果我们需要保存一个checkpoint以备将来恢复训练，
+那么我们应该将各种长期变量都保存下来，甚至还需要记录一下当前的epoch和step的id。
+因为一些模型变量虽然不是参数，但对于模型的训练依然必不可少。
+
+因此，根据需求的不同，我们提供了两套API来分别进行模型的参数和checkpoint的保存。
+
+保存模型用于对新样本的预测
+==========================
+
+如果我们保存模型的目的是用于对新样本的预测，那么只保存模型参数就足够了。我们可以使用
+:ref:`api_fluid_io_save_params` 接口来进行模型参数的保存。
+
+例如：
+
+.. code-block:: python
+
+    import paddle.fluid as fluid
+
+    exe = fluid.Executor(fluid.CPUPlace())
+    param_path = "./my_paddle_model"
+    prog = fluid.default_main_program()
+    fluid.io.save_params(executor=exe, dirname=param_path, main_program=None)
+
+上面的例子中，通过调用 :code:`fluid.io.save_params` 函数，PaddlePaddle Fluid会对默认
+:ref:`api_fluid_Program` 也就是 :code:`prog` 中的所有模型变量进行扫描，
+筛选出其中所有的模型参数，并将这些模型参数保存到指定的 :code:`param_path` 之中。
+
+
+保存checkpoint用于将来恢复训练
+==============================
+
+在训练过程中，我们可能希望在一些节点上将当前的训练状态保存下来，
+以便在将来需要的时候恢复训练环境继续进行训练。这一般被称作“checkpoint”。
+想要保存checkpoint，可以使用 :ref:`api_fluid_io_save_checkpoint` 接口。
+
+例如：
+
+.. code-block:: python
+
+    import paddle.fluid as fluid
+
+    exe = fluid.Executor(fluid.CPUPlace())
+    path = "./checkpoints"
+    prog = fluid.default_main_program()
+    trainer_args = {"epoch_id": 200,
+                    "step_id": 20} # just an example
+    fluid.io.save_checkpoint(executor=exe,
+                                checkpoint_dir=path,
+                                trainer_id=0,
+                                trainer_args=trainer_args,
+                                main_program=prog,
+                                max_num_checkpoints=3)
+
+上面的例子中，通过调用 :code:`fluid.io.save_checkpoint` 函数，PaddlePaddle Fluid会对默认
+:ref:`api_fluid_Program` 也就是 :code:`prog` 中的所有模型变量进行扫描，
+根据一系列内置的规则自动筛选出其中所有需要保存的变量，并将他们保存到指定的 :code:`path` 目录下。
+
+:code:`fluid.io.save_checkpoint` 的各个参数中， :code:`trainer_id` 在单机情况下设置为0即可； :code:`trainer_args`
+为一个Python dict，用于给定当前的epoch_id和step_id；
+:code:`max_num_checkpoints` 用于表示的最大checkpoint数量，
+如果目录中已经存在的checkpoint数量超过这个值，那最早的checkpoint将被删除。
+
+如何载入模型变量
+################
+
+与模型变量的保存相对应，我们提供了两套API来分别载入模型的参数和载入模型的checkpoint。
+
+载入模型用于对新样本的预测
+==========================
+
+对于通过 :code:`fluid.io.save_params` 保存的模型，可以使用 :code:`fluid.io.load_params`
+来进行载入。
+
+例如：
+
+.. code-block:: python
+
+    import paddle.fluid as fluid
+
+    exe = fluid.Executor(fluid.CPUPlace())
+    param_path = "./my_paddle_model"
+    prog = fluid.default_main_program()
+    fluid.io.load_params(executor=exe, dirname=param_path,
+                         main_program=prog)
+
+上面的例子中，通过调用 :code:`fluid.io.load_params` 函数，PaddlePaddle Fluid会对
+:code:`prog` 中的所有模型变量进行扫描，筛选出其中所有的模型参数，
+并尝试从 :code:`param_path` 之中读取加载它们。
+
+需要格外注意的是，这里的 :code:`prog` 必须和调用 :code:`fluid.io.save_params`
+时所用的 :code:`prog` 中的前向部分完全一致，且不能包含任何参数更新的操作。如果两者存在不一致，
+那么可能会导致一些变量未被正确加载；如果错误地包含了参数更新操作，那可能会导致正常预测过程中参数被更改。
+这两个 :ref:`api_fluid_Program` 之间的关系类似于训练 :ref:`api_fluid_Program`
+和测试 :ref:`api_fluid_Program` 之间的关系，详见： :ref:`user_guide_test_while_training`。
+
+另外，需特别注意运行 :code:`fluid.default_startup_program()` 必须在调用 :code:`fluid.io.load_params`
+之前。如果在之后运行，可能会覆盖已加载的模型参数导致错误。
+
+
+载入checkpoint用于恢复训练
+==========================
+
+对于通过 :code:`fluid.io.save_checkpoint` 保存的模型，可以使用 :code:`fluid.io.load_checkpoint`
+来进行载入。
+
+例如：
+
+.. code-block:: python
+
+    import paddle.fluid as fluid
+
+    exe = fluid.Executor(fluid.CPUPlace())
+    path = "./checkpoints"
+    prog = fluid.default_main_program()
+    fluid.io.load_checkpoint(executor=exe, checkpoint_dir=path,
+                             serial=9, main_program=prog)
+
+上面的例子中，通过调用 :code:`fluid.io.save_checkpoint` 函数，PaddlePaddle Fluid会对
+:code:`prog` 中的所有模型变量进行扫描，根据内置规则自动筛选出需要加载的变量，
+并尝试从 :code:`path` 之中加载它们。
+
+参数 :code:`serial` 用来标记具体要加载的checkpoint的版本号。在保存checkpoint的时候，
+一个checkpoint会被保存在一个子目录中，并在目录名上体现出自己的版本号。
+一般越大的版本号表示这个checkpoint越新。
+
+这里的 :code:`prog` 必须和调用 :code:`fluid.io.save_checkpoint` 时所用的 :code:`prog`
+完全一致，否则会导致变量加载错误或者未加载。另外，与 :code:`fluid.io.save_params` 类似，
+运行 :code:`fluid.default_startup_program()` 也必须在 :code:`fluid.io.load_checkpoint`
+之前进行。

source/user_guides/howto/training/single_node.rst

+########
+单机训练
+########
+
+准备工作
+########
+
+要进行PaddlePaddle Fluid单机训练，需要先 :ref:`user_guide_prepare_data` 和
+:ref:`user_guide_configure_simple_model` 。当\
+:ref:`user_guide_configure_simple_model` 完毕后，可以得到两个\
+:ref:`api_fluid_Program`， :code:`startup_program` 和 :code:`main_program`。
+默认情况下，可以使用 :ref:`api_fluid_default_startup_program` 与\ :ref:`api_fluid_default_main_program` 获得全局的 :ref:`api_fluid_Program`。
+
+例如:
+
+.. code-block:: python
+
+   import paddle.fluid as fluid
+
+   image = fluid.layers.data(name="image", shape=[784])
+   label = fluid.layers.data(name="label", shape=[1])
+   hidden = fluid.layers.fc(input=image, size=100, act='relu')
+   prediction = fluid.layers.fc(input=hidden, size=10, act='softmax')
+   loss = fluid.layers.mean(
+       fluid.layers.cross_entropy(
+           input=prediction,
+           label=label
+       )
+   )
+
+   sgd = fluid.optimizer.SGD(learning_rate=0.001)
+   sgd.minimize(loss)
+
+   # Here the fluid.default_startup_program() and fluid.default_main_program()
+   # has been constructed.
+
+在上述模型配置执行完毕后， :code:`fluid.default_startup_program()` 与\
+:code:`fluid.default_main_program()` 配置完毕了。
+
+初始化参数
+##########
+
+参数随机初始化
+==============
+
+用户配置完模型后，参数初始化操作会被写入到\
+:code:`fluid.default_startup_program()` 中。使用 :ref:`api_fluid_Executor` 运行
+这一程序，即可在全局 :ref:`api_fluid_global_scope` 中随机初始化参数。例如:
+
+.. code-block:: python
+
+   exe = fluid.Executor(fluid.CUDAPlace(0))
+   exe.run(program=fluid.default_startup_program())
+
+值得注意的是: 如果使用多GPU训练，参数需要先在GPU0上初始化，再经由\
+:ref:`api_fluid_ParallelExecutor` 分发到多张显卡上。
+
+
+载入预定义参数
+==============
+
+在神经网络训练过程中，经常会需要载入预定义模型，进而继续进行训练。\
+如何载入预定义参数，请参考 :ref:`user_guide_save_load_vars`。
+
+
+单卡训练
+########
+
+执行单卡训练可以使用 :ref:`api_fluid_Executor` 中的 :code:`run()` 方法，运行训练\
+:ref:`api_fluid_Program` 即可。在运行的时候，用户可以通过 :code:`run(feed=...)`\
+参数传入数据；用户可以通过 :code:`run(fetch=...)` 获取持久的数据。例如:\
+
+.. code-block:: 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的列表，\
+   也可以传入Variable的名字列表。:code:`Executor.run` 返回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-block:: 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` ,
+   并在执行过程中不能修改。默认值是 :ref:`api_fluid_default_main_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

source/user_guides/howto/training/test_while_training.rst

+.. _user_guide_test_while_training:
+
+##################
+训练过程中评测模型
+##################
+
+模型的测试评价与训练的 :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)` 复制含有用于测试的操作Program。简单的使用方法如下:
+
+.. code-block:: 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], ...)
+