Merge pull request #283 from PaddlePaddle/readme

add infer and save models

02.recognize_digits/README.en.md

@@ -131,6 +131,7 @@ PaddlePaddle provides a Python module, `paddle.dataset.mnist`, which downloads a
 A PaddlePaddle program starts from importing the API package:
 
 ```python
+import gzip
 import paddle.v2 as paddle
 ```
 
@@ -249,6 +250,10 @@ def event_handler_plot(event):
             cost_ploter.plot()
         step += 1
     if isinstance(event, paddle.event.EndPass):
+        # save parameters
+        with gzip.open('params_pass_%d.tar.gz' % event.pass_id, 'w') as f:
+            parameters.to_tar(f)
+
         result = trainer.test(reader=paddle.batch(
             paddle.dataset.mnist.test(), batch_size=128))
         cost_ploter.append(test_title, step, result.cost)
@@ -265,6 +270,10 @@ def event_handler(event):
             print "Pass %d, Batch %d, Cost %f, %s" % (
                 event.pass_id, event.batch_id, event.cost, event.metrics)
     if isinstance(event, paddle.event.EndPass):
+        # save parameters
+        with gzip.open('params_pass_%d.tar.gz' % event.pass_id, 'w') as f:
+            parameters.to_tar(f)
+
         result = trainer.test(reader=paddle.batch(
             paddle.dataset.mnist.test(), batch_size=128))
         print "Test with Pass %d, Cost %f, %s\n" % (
@@ -280,7 +289,7 @@ trainer.train(
             paddle.dataset.mnist.train(), buf_size=8192),
         batch_size=128),
     event_handler=event_handler_plot,
-    num_passes=100)
+    num_passes=5)
 ```
 
 During training, `trainer.train` invokes `event_handler` for certain events. This gives us a chance to print the training progress.
@@ -305,14 +314,38 @@ print 'The classification accuracy is %.2f%%' % (100 - float(best[2]) * 100)
 
 Usually, with MNIST data, the softmax regression model achieves an accuracy around 92.34%, the MLP 97.66%, and the convolution network around 99.20%. Convolution layers have been widely considered a great invention for image processing.
 
+## Application
+
+After training is done, user can use the trained model to classify images. The following code shows how to inference MNIST images through `paddle.infer` interface.
+
+```python
+from PIL import Image
+import numpy as np
+def load_image(file):
+    im = Image.open(file).convert('L')
+    im = im.resize((28, 28), Image.ANTIALIAS)
+    im = np.array(im).astype(np.float32).flatten()
+    im = im / 255.0
+    return im
+test_data = []
+test_data.append((load_image('image/infer_3.png'),))
+
+probs = paddle.infer(
+    output_layer=predict, parameters=parameters, input=test_data)
+lab = np.argsort(-probs) # probs and lab are the results of one batch data
+print "Label of image/infer_3.png is: %d" % lab[0][0]
+```
+
 
 ## Conclusion
+
 This tutorial describes a few common deep learning models using **Softmax regression**, **Multilayer Perceptron Network**, and **Convolutional Neural Network**. Understanding these models is crucial for future learning; the subsequent tutorials derive more sophisticated networks by building on top of them.
 
 When our model evolves from a simple softmax regression to a slightly complex Convolutional Neural Network, the recognition accuracy on the MNIST data set achieves a large improvement in accuracy. This is due to the Convolutional layers' local connections and parameter sharing. While learning new models in the future, we encourage the readers to understand the key ideas that lead a new model to improve the results of an old one.
 
 Moreover, this tutorial introduces the basic flow of PaddlePaddle model design, which starts with a *dataprovider*, a model layer construction, and finally training and prediction. Motivated readers can leverage the flow used in this MNIST handwritten digit classification example and experiment with different data and network architectures to train models for classification tasks of their choice.
 
+
 ## References
 
 1. LeCun, Yann, Léon Bottou, Yoshua Bengio, and Patrick Haffner. ["Gradient-based learning applied to document recognition."](http://ieeexplore.ieee.org/abstract/document/726791/) Proceedings of the IEEE 86, no. 11 (1998): 2278-2324.

02.recognize_digits/README.md

@@ -132,6 +132,7 @@ PaddlePaddle在API中提供了自动加载[MNIST](http://yann.lecun.com/exdb/mni
 首先，加载PaddlePaddle的V2 api包。
 
 ```python
+import gzip
 import paddle.v2 as paddle
 ```
 其次，定义三个不同的分类器：
@@ -254,6 +255,10 @@ def event_handler_plot(event):
             cost_ploter.plot()
         step += 1
     if isinstance(event, paddle.event.EndPass):
+        # save parameters
+        with gzip.open('params_pass_%d.tar.gz' % event.pass_id, 'w') as f:
+            parameters.to_tar(f)
+
         result = trainer.test(reader=paddle.batch(
             paddle.dataset.mnist.test(), batch_size=128))
         cost_ploter.append(test_title, step, result.cost)
@@ -269,6 +274,10 @@ def event_handler(event):
             print "Pass %d, Batch %d, Cost %f, %s" % (
                 event.pass_id, event.batch_id, event.cost, event.metrics)
     if isinstance(event, paddle.event.EndPass):
+        # save parameters
+        with gzip.open('params_pass_%d.tar.gz' % event.pass_id, 'w') as f:
+            parameters.to_tar(f)
+
         result = trainer.test(reader=paddle.batch(
             paddle.dataset.mnist.test(), batch_size=128))
         print "Test with Pass %d, Cost %f, %s\n" % (
@@ -284,7 +293,7 @@ trainer.train(
             paddle.dataset.mnist.train(), buf_size=8192),
         batch_size=128),
     event_handler=event_handler_plot,
-    num_passes=100)
+    num_passes=5)
 ```
 
 训练过程是完全自动的，event_handler里打印的日志类似如下所示：
@@ -300,6 +309,29 @@ trainer.train(
 
 训练之后，检查模型的预测准确度。用 MNIST 训练的时候，一般 softmax回归模型的分类准确率为约为 92.34%，多层感知器为97.66%，卷积神经网络可以达到 99.20%。
 
+
+## 应用模型
+
+可以使用训练好的模型对手写体数字图片进行分类，下面程序展示了如何使用paddle.infer接口进行推断。
+
+```python
+from PIL import Image
+import numpy as np
+def load_image(file):
+    im = Image.open(file).convert('L')
+    im = im.resize((28, 28), Image.ANTIALIAS)
+    im = np.array(im).astype(np.float32).flatten()
+    im = im / 255.0
+    return im
+test_data = []
+test_data.append((load_image('image/infer_3.png'),))
+
+probs = paddle.infer(
+    output_layer=predict, parameters=parameters, input=test_data)
+lab = np.argsort(-probs) # probs and lab are the results of one batch data
+print "Label of image/infer_3.png is: %d" % lab[0][0]
+```
+
 ## 总结
 
 本教程的softmax回归、多层感知器和卷积神经网络是最基础的深度学习模型，后续章节中复杂的神经网络都是从它们衍生出来的，因此这几个模型对之后的学习大有裨益。同时，我们也观察到从最简单的softmax回归变换到稍复杂的卷积神经网络的时候，MNIST数据集上的识别准确率有了大幅度的提升，原因是卷积层具有局部连接和共享权重的特性。在之后学习新模型的时候，希望大家也要深入到新模型相比原模型带来效果提升的关键之处。此外，本教程还介绍了PaddlePaddle模型搭建的基本流程，从dataprovider的编写、网络层的构建，到最后的训练和预测。对这个流程熟悉以后，大家就可以用自己的数据，定义自己的网络模型，并完成自己的训练和预测任务了。

02.recognize_digits/index.en.html

@@ -173,6 +173,7 @@
 A PaddlePaddle program starts from importing the API package:
 
 ```python
+import gzip
 import paddle.v2 as paddle
 ```
 
@@ -291,6 +292,10 @@
             cost_ploter.plot()
         step += 1
     if isinstance(event, paddle.event.EndPass):
+        # save parameters
+        with gzip.open('params_pass_%d.tar.gz' % event.pass_id, 'w') as f:
+            parameters.to_tar(f)
+
         result = trainer.test(reader=paddle.batch(
             paddle.dataset.mnist.test(), batch_size=128))
         cost_ploter.append(test_title, step, result.cost)
@@ -307,6 +312,10 @@
             print "Pass %d, Batch %d, Cost %f, %s" % (
                 event.pass_id, event.batch_id, event.cost, event.metrics)
     if isinstance(event, paddle.event.EndPass):
+        # save parameters
+        with gzip.open('params_pass_%d.tar.gz' % event.pass_id, 'w') as f:
+            parameters.to_tar(f)
+
         result = trainer.test(reader=paddle.batch(
             paddle.dataset.mnist.test(), batch_size=128))
         print "Test with Pass %d, Cost %f, %s\n" % (
@@ -322,7 +331,7 @@
             paddle.dataset.mnist.train(), buf_size=8192),
         batch_size=128),
     event_handler=event_handler_plot,
-    num_passes=100)
+    num_passes=5)
 ```
 
 During training, `trainer.train` invokes `event_handler` for certain events. This gives us a chance to print the training progress.
@@ -347,14 +356,38 @@
 
 Usually, with MNIST data, the softmax regression model achieves an accuracy around 92.34%, the MLP 97.66%, and the convolution network around 99.20%. Convolution layers have been widely considered a great invention for image processing.
 
+## Application
+
+After training is done, user can use the trained model to classify images. The following code shows how to inference MNIST images through `paddle.infer` interface.
+
+```python
+from PIL import Image
+import numpy as np
+def load_image(file):
+    im = Image.open(file).convert('L')
+    im = im.resize((28, 28), Image.ANTIALIAS)
+    im = np.array(im).astype(np.float32).flatten()
+    im = im / 255.0
+    return im
+test_data = []
+test_data.append((load_image('image/infer_3.png'),))
+
+probs = paddle.infer(
+    output_layer=predict, parameters=parameters, input=test_data)
+lab = np.argsort(-probs) # probs and lab are the results of one batch data
+print "Label of image/infer_3.png is: %d" % lab[0][0]
+```
+
 
 ## Conclusion
+
 This tutorial describes a few common deep learning models using **Softmax regression**, **Multilayer Perceptron Network**, and **Convolutional Neural Network**. Understanding these models is crucial for future learning; the subsequent tutorials derive more sophisticated networks by building on top of them.
 
 When our model evolves from a simple softmax regression to a slightly complex Convolutional Neural Network, the recognition accuracy on the MNIST data set achieves a large improvement in accuracy. This is due to the Convolutional layers' local connections and parameter sharing. While learning new models in the future, we encourage the readers to understand the key ideas that lead a new model to improve the results of an old one.
 
 Moreover, this tutorial introduces the basic flow of PaddlePaddle model design, which starts with a *dataprovider*, a model layer construction, and finally training and prediction. Motivated readers can leverage the flow used in this MNIST handwritten digit classification example and experiment with different data and network architectures to train models for classification tasks of their choice.
 
+
 ## References
 
 1. LeCun, Yann, Léon Bottou, Yoshua Bengio, and Patrick Haffner. ["Gradient-based learning applied to document recognition."](http://ieeexplore.ieee.org/abstract/document/726791/) Proceedings of the IEEE 86, no. 11 (1998): 2278-2324.

02.recognize_digits/index.html

@@ -174,6 +174,7 @@
 首先，加载PaddlePaddle的V2 api包。
 
 ```python
+import gzip
 import paddle.v2 as paddle
 ```
 其次，定义三个不同的分类器：
@@ -296,6 +297,10 @@
             cost_ploter.plot()
         step += 1
     if isinstance(event, paddle.event.EndPass):
+        # save parameters
+        with gzip.open('params_pass_%d.tar.gz' % event.pass_id, 'w') as f:
+            parameters.to_tar(f)
+
         result = trainer.test(reader=paddle.batch(
             paddle.dataset.mnist.test(), batch_size=128))
         cost_ploter.append(test_title, step, result.cost)
@@ -311,6 +316,10 @@
             print "Pass %d, Batch %d, Cost %f, %s" % (
                 event.pass_id, event.batch_id, event.cost, event.metrics)
     if isinstance(event, paddle.event.EndPass):
+        # save parameters
+        with gzip.open('params_pass_%d.tar.gz' % event.pass_id, 'w') as f:
+            parameters.to_tar(f)
+
         result = trainer.test(reader=paddle.batch(
             paddle.dataset.mnist.test(), batch_size=128))
         print "Test with Pass %d, Cost %f, %s\n" % (
@@ -326,7 +335,7 @@
             paddle.dataset.mnist.train(), buf_size=8192),
         batch_size=128),
     event_handler=event_handler_plot,
-    num_passes=100)
+    num_passes=5)
 ```
 
 训练过程是完全自动的，event_handler里打印的日志类似如下所示：
@@ -342,6 +351,29 @@
 
 训练之后，检查模型的预测准确度。用 MNIST 训练的时候，一般 softmax回归模型的分类准确率为约为 92.34%，多层感知器为97.66%，卷积神经网络可以达到 99.20%。
 
+
+## 应用模型
+
+可以使用训练好的模型对手写体数字图片进行分类，下面程序展示了如何使用paddle.infer接口进行推断。
+
+```python
+from PIL import Image
+import numpy as np
+def load_image(file):
+    im = Image.open(file).convert('L')
+    im = im.resize((28, 28), Image.ANTIALIAS)
+    im = np.array(im).astype(np.float32).flatten()
+    im = im / 255.0
+    return im
+test_data = []
+test_data.append((load_image('image/infer_3.png'),))
+
+probs = paddle.infer(
+    output_layer=predict, parameters=parameters, input=test_data)
+lab = np.argsort(-probs) # probs and lab are the results of one batch data
+print "Label of image/infer_3.png is: %d" % lab[0][0]
+```
+
 ## 总结
 
 本教程的softmax回归、多层感知器和卷积神经网络是最基础的深度学习模型，后续章节中复杂的神经网络都是从它们衍生出来的，因此这几个模型对之后的学习大有裨益。同时，我们也观察到从最简单的softmax回归变换到稍复杂的卷积神经网络的时候，MNIST数据集上的识别准确率有了大幅度的提升，原因是卷积层具有局部连接和共享权重的特性。在之后学习新模型的时候，希望大家也要深入到新模型相比原模型带来效果提升的关键之处。此外，本教程还介绍了PaddlePaddle模型搭建的基本流程，从dataprovider的编写、网络层的构建，到最后的训练和预测。对这个流程熟悉以后，大家就可以用自己的数据，定义自己的网络模型，并完成自己的训练和预测任务了。

02.recognize_digits/train.py

@@ -1,3 +1,6 @@
+import gzip
+from PIL import Image
+import numpy as np
 import paddle.v2 as paddle
 
 
@@ -80,6 +83,10 @@ def event_handler(event):
                 print "Pass %d, Batch %d, Cost %f, %s" % (
                     event.pass_id, event.batch_id, event.cost, event.metrics)
         if isinstance(event, paddle.event.EndPass):
+            # save parameters
+            with gzip.open('params_pass_%d.tar.gz' % event.pass_id, 'w') as f:
+                parameters.to_tar(f)
+
             result = trainer.test(reader=paddle.batch(
                 paddle.dataset.mnist.test(), batch_size=128))
             print "Test with Pass %d, Cost %f, %s\n" % (
@@ -92,13 +99,28 @@ def event_handler(event):
             paddle.reader.shuffle(paddle.dataset.mnist.train(), buf_size=8192),
             batch_size=128),
         event_handler=event_handler,
-        num_passes=100)
+        num_passes=5)
 
     # find the best 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%%' % (100 - float(best[2]) * 100)
 
+    def load_image(file):
+        im = Image.open(file).convert('L')
+        im = im.resize((28, 28), Image.ANTIALIAS)
+        im = np.array(im).astype(np.float32).flatten()
+        im = im / 255.0
+        return im
+
+    test_data = []
+    test_data.append((load_image('image/infer_3.png'), ))
+
+    probs = paddle.infer(
+        output_layer=predict, parameters=parameters, input=test_data)
+    lab = np.argsort(-probs)  # probs and lab are the results of one batch data
+    print "Label of image/infer_3.png is: %d" % lab[0][0]
+
 
 if __name__ == '__main__':
     main()