high_level_api.ipynb

{
 "metadata": {
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.4-final"
  },
  "orig_nbformat": 2,
  "kernelspec": {
   "name": "python37464bitc4da1ac836094043840bff631bedbf7f",
   "display_name": "Python 3.7.4 64-bit"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2,
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 飞桨高层API使用指南\n",
    "\n",
    "## 1. 简介\n",
    "\n",
    "飞桨2.0全新推出高层API，是对飞桨API的进一步封装与升级，提供了更加简洁易用的API，进一步提升了飞桨的易学易用性，并增强飞桨的功能。\n",
    "\n",
    "飞桨高层API面向从深度学习小白到资深开发者的所有人群，对于AI初学者来说，使用高层API可以简单快速的构建深度学习项目，对于资深开发者来说，可以快速完成算法迭代。\n",
    "\n",
    "飞桨高层API具有以下特点：\n",
    "\n",
    "* 易学易用: 高层API是对普通动态图API的进一步封装和优化，同时保持与普通API的兼容性，高层API使用更加易学易用，同样的实现使用高层API可以节省大量的代码。\n",
    "* 低代码开发: 使用飞桨高层API的一个明显特点是，用户可编程代码量大大缩减。\n",
    "* 动静转换: 高层API支持动静转换，用户只需要改一行代码即可实现将动态图代码在静态图模式下训练，既方便用户使用动态图调试模型，又提升了模型训练效率。\n",
    "\n",
    "在功能增强与使用方式上，高层API有以下升级：\n",
    "\n",
    "* 模型训练方式升级: 高层API中封装了Model类，继承了Model类的神经网络可以仅用几行代码完成模型的训练。\n",
    "* 新增图像处理模块transform: 飞桨新增了图像预处理模块，其中包含数十种数据处理函数，基本涵盖了常用的数据处理、数据增强方法。\n",
    "* 提供常用的神经网络模型可供调用: 高层API中集成了计算机视觉领域和自然语言处理领域常用模型，包括但不限于mobilenet、resnet、yolov3、cyclegan、bert、transformer、seq2seq等等。同时发布了对应模型的预训练模型，用户可以直接使用这些模型或者在此基础上完成二次开发。\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. 安装并使用飞桨高层API\n",
    "\n",
    "飞桨高层API无需独立安装，只需要安装好paddlepaddle即可，安装完成后import paddle即可使用相关高层API，如：paddle.Model、视觉领域paddle.vision、NLP领域paddle.text。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "output_type": "execute_result",
     "data": {
      "text/plain": "'0.0.0'"
     },
     "metadata": {},
     "execution_count": 2
    }
   ],
   "source": [
    "import paddle\n",
    "import paddle.vision as vision\n",
    "import paddle.text as text\n",
    "\n",
    "paddle.__version__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. 目录\n",
    "\n",
    "本指南教学内容覆盖\n",
    "\n",
    "* 使用高层API提供的自带数据集进行相关深度学习任务训练。\n",
    "* 使用自定义数据进行数据集的定义、数据预处理和训练。\n",
    "* 如何在数据集定义和加载中应用数据增强相关接口。\n",
    "* 如何进行模型的组网。\n",
    "* 高层API进行模型训练的相关API使用。\n",
    "* 如何在fit接口满足需求的时候进行自定义，使用基础API来完成训练。\n",
    "* 如何使用多卡来加速训练。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. 数据集定义、加载和数据预处理\n",
    "\n",
    "对于深度学习任务，均是框架针对各种类型数字的计算，是无法直接使用原始图片和文本等文件来完成。那么就是涉及到了一项动作，就是将原始的各种数据文件进行处理加工，转换成深度学习任务可以使用的数据。\n",
    "\n",
    "### 3.1 框架自带数据集使用\n",
    "\n",
    "高层API将一些我们常用到的数据集作为领域API对用户进行开放，对应API所在目录为`paddle.vision.datasets`，那么我们先看下提供了哪些数据集。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "tags": []
   },
   "outputs": [
    {
     "output_type": "stream",
     "name": "stdout",
     "text": "视觉相关数据集： ['DatasetFolder', 'ImageFolder', 'MNIST', 'Flowers', 'Cifar10', 'Cifar100', 'VOC2012']\n自然语言相关数据集： ['Conll05st', 'Imdb', 'Imikolov', 'Movielens', 'MovieReviews', 'UCIHousing', 'WMT14', 'WMT16']\n"
    }
   ],
   "source": [
    "print('视觉相关数据集：', paddle.vision.datasets.__all__)\n",
    "print('自然语言相关数据集：', paddle.text.datasets.__all__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "这里我们是加载一个手写数字识别的数据集，用`mode`来标识是训练数据还是测试数据集。数据集接口会自动从远端下载数据集到本机缓存目录`~/.cache/paddle/dataset`。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 测试数据集\n",
    "train_dataset = vision.datasets.MNIST(mode='train')\n",
    "\n",
    "# 验证数据集\n",
    "val_dataset = vision.datasets.MNIST(mode='test')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.2 自定义数据集\n",
    "\n",
    "更多的时候我们是需要自己使用已有的相关数据来定义数据集，那么这里我们通过一个案例来了解如何进行数据集的定义，飞桨为用户提供了`paddle.io.Dataset`基类，让用户通过类的集成来快速实现数据集定义。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {
    "tags": []
   },
   "outputs": [
    {
     "output_type": "stream",
     "name": "stdout",
     "text": "=============train dataset=============\ntraindata1 label1\ntraindata2 label2\ntraindata3 label3\ntraindata4 label4\n=============evaluation dataset=============\ntestdata1 label1\ntestdata2 label2\ntestdata3 label3\ntestdata4 label4\n"
    }
   ],
   "source": [
    "from paddle.io import Dataset\n",
    "\n",
    "\n",
    "class MyDataset(Dataset):\n",
    "    \"\"\"\n",
    "    步骤一：继承paddle.io.Dataset类\n",
    "    \"\"\"\n",
    "    def __init__(self, mode='train'):\n",
    "        \"\"\"\n",
    "        步骤二：实现构造函数，定义数据读取方式，划分训练和测试数据集\n",
    "        \"\"\"\n",
    "        super(MyDataset, self).__init__()\n",
    "\n",
    "        if mode == 'train':\n",
    "            self.data = [\n",
    "                ['traindata1', 'label1'],\n",
    "                ['traindata2', 'label2'],\n",
    "                ['traindata3', 'label3'],\n",
    "                ['traindata4', 'label4'],\n",
    "            ]\n",
    "        else:\n",
    "            self.data = [\n",
    "                ['testdata1', 'label1'],\n",
    "                ['testdata2', 'label2'],\n",
    "                ['testdata3', 'label3'],\n",
    "                ['testdata4', 'label4'],\n",
    "            ]\n",
    "    \n",
    "    def __getitem__(self, index):\n",
    "        \"\"\"\n",
    "        步骤三：实现__getitem__方法，定义指定index时如何获取数据，并返回单条数据（训练数据，对应的标签）\n",
    "        \"\"\"\n",
    "        data = self.data[index][0]\n",
    "        label = self.data[index][1]\n",
    "\n",
    "        return data, label\n",
    "\n",
    "    def __len__(self):\n",
    "        \"\"\"\n",
    "        步骤四：实现__len__方法，返回数据集总数目\n",
    "        \"\"\"\n",
    "        return len(self.data)\n",
    "\n",
    "# 测试定义的数据集\n",
    "train_dataset = MyDataset(mode='train')\n",
    "val_dataset = MyDataset(mode='test')\n",
    "\n",
    "print('=============train dataset=============')\n",
    "for data, label in train_dataset:\n",
    "    print(data, label)\n",
    "\n",
    "print('=============evaluation dataset=============')\n",
    "for data, label in val_dataset:\n",
    "    print(data, label)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.3 数据增强\n",
    "\n",
    "训练过程中有时会遇到过拟合的问题，其中一个解决方法就是对训练数据做增强，对数据进行处理得到不同的图像，从而泛化数据集。数据增强API是定义在领域目录的transofrms下，这里我们介绍两种使用方式，一种是基于框架自带数据集，一种是基于自己定义的数据集。\n",
    "\n",
    "#### 3.3.1 框架自带数据集"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from paddle.vision.transforms import Compose, Resize, ColorJitter\n",
    "\n",
    "\n",
    "# 定义想要使用那些数据增强方式，这里用到了随机调整亮度、对比度和饱和度，改变图片大小\n",
    "transform = Compose([ColorJitter(), Resize(size=100)])\n",
    "\n",
    "# 通过transform参数传递定义好的数据增项方法即可完成对自带数据集的应用\n",
    "train_dataset = vision.datasets.MNIST(mode='train', transform=transform)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 3.3.2 自定义数据集\n",
    "\n",
    "针对自定义数据集使用数据增强有两种方式，一种是在数据集的构造函数中进行数据增强方法的定义，之后对__getitem__中返回的数据进行应用。另外一种方式也可以给自定义的数据集类暴漏一个构造参数，在实例化类的时候将数据增强方法传递进去。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from paddle.io import Dataset\n",
    "\n",
    "\n",
    "class MyDataset(Dataset):\n",
    "    def __init__(self, mode='train'):\n",
    "        super(MyDataset, self).__init__()\n",
    "\n",
    "        if mode == 'train':\n",
    "            self.data = [\n",
    "                ['traindata1', 'label1'],\n",
    "                ['traindata2', 'label2'],\n",
    "                ['traindata3', 'label3'],\n",
    "                ['traindata4', 'label4'],\n",
    "            ]\n",
    "        else:\n",
    "            self.data = [\n",
    "                ['testdata1', 'label1'],\n",
    "                ['testdata2', 'label2'],\n",
    "                ['testdata3', 'label3'],\n",
    "                ['testdata4', 'label4'],\n",
    "            ]\n",
    "\n",
    "        # 定义要使用的数据预处理方法，针对图片的操作\n",
    "        self.transform = Compose([ColorJitter(), Resize(size=100)])\n",
    "    \n",
    "    def __getitem__(self, index):\n",
    "        data = self.data[index][0]\n",
    "\n",
    "        # 在这里对训练数据进行应用\n",
    "        # 这里只是一个示例，测试时需要将数据集更换为图片数据进行测试\n",
    "        data = self.transform(data)\n",
    "\n",
    "        label = self.data[index][1]\n",
    "\n",
    "        return data, label\n",
    "\n",
    "    def __len__(self):\n",
    "        return len(self.data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. 模型组网\n",
    "\n",
    "针对高层API在模型组网上和基础API是统一的一套，无需投入额外的学习使用成本。那么这里我举几个简单的例子来做示例。\n",
    "\n",
    "### 4.1 Sequential组网\n",
    "\n",
    "针对顺序的线性网络结构我们可以直接使用Sequential来快速完成组网，可以减少类的定义等代码编写。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Sequential形式组网\n",
    "mnist = paddle.nn.Sequential(\n",
    "    paddle.nn.Flatten(),\n",
    "    paddle.nn.Linear(784, 512),\n",
    "    paddle.nn.ReLU(),\n",
    "    paddle.nn.Dropout(0.2),\n",
    "    paddle.nn.Linear(512, 10)\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 4.2 SubClass组网\n",
    "针对一些比较复杂的网络结构，就可以使用Layer子类定义的方式来进行模型代码编写，在`__init__`构造函数中进行组网Layer的声明，在`forward`中使用声明的Layer变量进行前向计算。子类组网方式也可以实现sublayer的复用，针对相同的layer可以在构造函数中一次性定义，在forward中多次调用。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Layer类继承方式组网\n",
    "class Mnist(paddle.nn.Layer):\n",
    "    def __init__(self):\n",
    "        super(Mnist, self).__init__()\n",
    "\n",
    "        self.flatten = paddle.nn.Flatten()\n",
    "        self.linear_1 = paddle.nn.Linear(784, 512)\n",
    "        self.linear_2 = paddle.nn.Linear(512, 10)\n",
    "        self.relu = paddle.nn.ReLU()\n",
    "        self.dropout = paddle.nn.Dropout(0.2)\n",
    "\n",
    "    def forward(self, inputs):\n",
    "        y = self.flatten(inputs)\n",
    "        y = self.linear_1(y)\n",
    "        y = self.relu(y)\n",
    "        y = self.dropout(y)\n",
    "        y = self.linear_2(y)\n",
    "\n",
    "        return y\n",
    "\n",
    "mnist = Mnist()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 4.3 模型封装\n",
    "\n",
    "定义好网络结构之后我们来使用`paddle.Model`完成模型的封装，将网络结构组合成一个可快速使用高层API进行训练、评估和预测的类。\n",
    "\n",
    "在封装的时候我们有两种场景，动态图训练模式和静态图训练模式。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 场景1：动态图模式\n",
    "\n",
    "# 启动动态图训练模式\n",
    "paddle.disable_static()\n",
    "# 使用GPU训练\n",
    "paddle.set_device('gpu')\n",
    "# 模型封装\n",
    "model = paddle.Model(mnist)\n",
    "\n",
    "\n",
    "# 场景2：静态图模式\n",
    "\n",
    "# input = paddle.static.InputSpec([None, 1, 28, 28], dtype='float32')\n",
    "# label = paddle.static.InputSpec([None, 1], dtype='int8')\n",
    "# model = paddle.Model(mnist, input, label)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 4.4 模型可视化\n",
    "\n",
    "在组建好我们的网络结构后，一般我们会想去对我们的网络结构进行一下可视化，逐层的去对齐一下我们的网络结构参数，看看是否符合我们的预期。这里可以通过`Model.summary`接口进行可视化展示。\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "model.summary((1, 28, 28))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "另外，summary接口有两种使用方式，下面我们通过两个示例来做展示，除了`Model.summary`这种配套`paddle.Model`封装使用的接口外，还有一套配合没有经过`paddle.Model`封装的方式来使用。可以直接将实例化好的Layer子类放到`paddle.summary`接口中进行可视化呈现。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "paddle.summary(mnist, (1, 28, 28))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "这里面有一个注意的点，有的用户可能会疑惑为什么要传递`(1, 28, 28)`这个input_size参数，因为在动态图中，网络定义阶段是还没有得到输入数据的形状信息，我们想要做网络结构的呈现就无从下手，那么我们通过告知接口网络结构的输入数据形状，这样网络可以通过逐层的计算推导得到完整的网络结构信息进行呈现。如果是动态图运行模式，那么就不需要给summary接口传递输入数据形状这个值了，因为在Model封装的时候我们已经定义好了InputSpec，其中包含了输入数据的形状格式。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. 模型训练\n",
    "\n",
    "网络结构通过`paddle.Model`接口封装成模型类后进行执行操作非常的简洁方便，可以直接通过调用`Model.fit`就可以完成训练过程。\n",
    "\n",
    "使用`Model.fit`接口启动训练前，我们先通过`Model.prepare`接口来对训练进行提前的配置准备工作，包括设置模型优化器，Loss计算方法，精度计算方法等。\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 为模型训练做准备，设置优化器，损失函数和精度计算方式\n",
    "model.prepare(paddle.optimizer.Adam(parameters=model.parameters()), \n",
    "              paddle.nn.CrossEntropyLoss(),\n",
    "              paddle.metric.Accuracy())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "做好模型训练的前期准备工作后，我们正式调用`fit()`接口来启动训练过程，需要指定一下至少3个关键参数：训练数据集，训练轮次和单次训练数据批次大小。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 启动模型训练，指定训练数据集，设置训练轮次，设置每次数据集计算的批次大小，设置日志格式\n",
    "model.fit(train_dataset, \n",
    "          epochs=10, \n",
    "          batch_size=32,\n",
    "          verbose=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 5.1 单机单卡\n",
    "\n",
    "我们把刚才单步教学的训练代码做一个整合，这个完整的代码示例就是我们的单机单卡训练程序。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# 启动动态图训练模式\n",
    "paddle.disable_static()\n",
    "\n",
    "# 使用GPU训练\n",
    "paddle.set_device('gpu')\n",
    "\n",
    "# 构建模型训练用的Model，告知需要训练哪个模型\n",
    "model = paddle.Model(mnist)\n",
    "\n",
    "# 为模型训练做准备，设置优化器，损失函数和精度计算方式\n",
    "model.prepare(paddle.optimizer.Adam(parameters=model.parameters()), \n",
    "              paddle.nn.CrossEntropyLoss(),\n",
    "              paddle.metric.Accuracy())\n",
    "\n",
    "# 启动模型训练，指定训练数据集，设置训练轮次，设置每次数据集计算的批次大小，设置日志格式\n",
    "model.fit(train_dataset, \n",
    "          epochs=10, \n",
    "          batch_size=32,\n",
    "          verbose=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 5.2 单机多卡\n",
    "\n",
    "对于高层API来实现单机多卡非常简单，整个训练代码和单机单卡没有差异。直接使用`paddle.distributed.launch`启动单机单卡的程序即可。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# train.py里面包含的就是单机单卡代码\n",
    "python -m paddle.distributed.launch train.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 5.3 自定义Loss\n",
    "\n",
    "有时我们会遇到特定任务的Loss计算方式在框架既有的Loss接口中不存在，或算法不符合自己的需求，那么期望能够自己来进行Loss的自定义，我们这里就会讲解介绍一下如何进行Loss的自定义操作，首先来看下面的代码：\n",
    "\n",
    "```python\n",
    "class SelfDefineLoss(paddle.nn.Layer):\n",
    "    \"\"\"\n",
    "    1. 继承paddle.nn.Layer\n",
    "    \"\"\"\n",
    "    def __init__(self):\n",
    "        \"\"\"\n",
    "        2. 构造函数根据自己的实际算法需求和使用需求进行参数定义即可\n",
    "        \"\"\"\n",
    "        super(SelfDefineLoss, self).__init__()\n",
    "\n",
    "    def forward(self, input, label):\n",
    "        \"\"\"\n",
    "        3. 实现forward函数，forward在调用时会传递两个参数：input和label\n",
    "            - input：单个或批次训练数据经过模型前向计算输出结果\n",
    "            - label：单个或批次训练数据对应的标签数据\n",
    "\n",
    "            接口返回值是一个Tensor，根据自定义的逻辑加和或计算均值后的损失\n",
    "        \"\"\"\n",
    "        # 使用Paddle中相关API自定义的计算逻辑\n",
    "        # output = xxxxx\n",
    "        # return output\n",
    "```\n",
    "\n",
    "那么了解完代码层面如果编写自定义代码后我们看一个实际的例子，下面是在图像分割示例代码中写的一个自定义Loss，当时主要是想使用自定义的softmax计算维度。\n",
    "\n",
    "```python\n",
    "class SoftmaxWithCrossEntropy(paddle.nn.Layer):\n",
    "    def __init__(self):\n",
    "        super(SoftmaxWithCrossEntropy, self).__init__()\n",
    "\n",
    "    def forward(self, input, label):\n",
    "        loss = F.softmax_with_cross_entropy(input, \n",
    "                                            label, \n",
    "                                            return_softmax=False,\n",
    "                                            axis=1)\n",
    "        return paddle.mean(loss)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 5.4 自定义Metric\n",
    "\n",
    "和Loss一样，如果遇到一些想要做个性化实现的操作时，我们也可以来通过框架完成自定义的评估计算方法，具体的实现方式如下：\n",
    "\n",
    "```python\n",
    "class SelfDefineMetric(paddle.metric.Metric):\n",
    "    \"\"\"\n",
    "    1. 继承paddle.metric.Metric\n",
    "    \"\"\"\n",
    "    def __init__(self):\n",
    "        \"\"\"\n",
    "        2. 构造函数实现，自定义参数即可\n",
    "        \"\"\"\n",
    "        super(SelfDefineMetric, self).__init__()\n",
    "\n",
    "    def name(self):\n",
    "        \"\"\"\n",
    "        3. 实现name方法，返回定义的评估指标名字\n",
    "        \"\"\"\n",
    "        return '自定义评价指标的名字'\n",
    "\n",
    "    def compute(self, ...)\n",
    "        \"\"\"\n",
    "        4. 本步骤可以省略，实现compute方法，这个方法主要用于`update`的加速，可以在这个方法中调用一些paddle实现好的Tensor计算API，编译到模型网络中一起使用低层C++ OP计算。\n",
    "        \"\"\"\n",
    "\n",
    "        return 自己想要返回的数据，会做为update的参数传入。\n",
    "\n",
    "    def update(self, ...):\n",
    "        \"\"\"\n",
    "        5. 实现update方法，用于单个batch训练时进行评估指标计算。\n",
    "        - 当`compute`类函数未实现时，会将模型的计算输出和标签数据的展平作为`update`的参数传入。\n",
    "        - 当`compute`类函数做了实现时，会将compute的返回结果作为`update`的参数传入。\n",
    "        \"\"\"\n",
    "        return acc value\n",
    "    \n",
    "    def accumulate(self):\n",
    "        \"\"\"\n",
    "        6. 实现accumulate方法，返回历史batch训练积累后计算得到的评价指标值。\n",
    "        每次`update`调用时进行数据积累，`accumulate`计算时对积累的所有数据进行计算并返回。\n",
    "        结算结果会在`fit`接口的训练日志中呈现。\n",
    "        \"\"\"\n",
    "        # 利用update中积累的成员变量数据进行计算后返回\n",
    "        return accumulated acc value\n",
    "\n",
    "    def reset(self):\n",
    "        \"\"\"\n",
    "        7. 实现reset方法，每个Epoch结束后进行评估指标的重置，这样下个Epoch可以重新进行计算。\n",
    "        \"\"\"\n",
    "        # do reset action\n",
    "```\n",
    "\n",
    "我们看一个框架中的具体例子，这个是框架中已提供的一个评估指标计算接口，这里就是按照上述说明中的实现方法进行了相关类继承和成员函数实现。\n",
    "\n",
    "```python\n",
    "from paddle.metric import Metric\n",
    "\n",
    "\n",
    "class Precision(Metric):\n",
    "    \"\"\"\n",
    "    Precision (also called positive predictive value) is the fraction of\n",
    "    relevant instances among the retrieved instances. Refer to\n",
    "    https://en.wikipedia.org/wiki/Evaluation_of_binary_classifiers\n",
    "\n",
    "    Noted that this class manages the precision score only for binary\n",
    "    classification task.\n",
    "    \n",
    "    ......\n",
    "\n",
    "    \"\"\"\n",
    "\n",
    "    def __init__(self, name='precision', *args, **kwargs):\n",
    "        super(Precision, self).__init__(*args, **kwargs)\n",
    "        self.tp = 0  # true positive\n",
    "        self.fp = 0  # false positive\n",
    "        self._name = name\n",
    "\n",
    "    def update(self, preds, labels):\n",
    "        \"\"\"\n",
    "        Update the states based on the current mini-batch prediction results.\n",
    "\n",
    "        Args:\n",
    "            preds (numpy.ndarray): The prediction result, usually the output\n",
    "                of two-class sigmoid function. It should be a vector (column\n",
    "                vector or row vector) with data type: 'float64' or 'float32'.\n",
    "            labels (numpy.ndarray): The ground truth (labels),\n",
    "                the shape should keep the same as preds.\n",
    "                The data type is 'int32' or 'int64'.\n",
    "        \"\"\"\n",
    "        if isinstance(preds, paddle.Tensor):\n",
    "            preds = preds.numpy()\n",
    "        elif not _is_numpy_(preds):\n",
    "            raise ValueError(\"The 'preds' must be a numpy ndarray or Tensor.\")\n",
    "\n",
    "        if isinstance(labels, paddle.Tensor):\n",
    "            labels = labels.numpy()\n",
    "        elif not _is_numpy_(labels):\n",
    "            raise ValueError(\"The 'labels' must be a numpy ndarray or Tensor.\")\n",
    "\n",
    "        sample_num = labels.shape[0]\n",
    "        preds = np.floor(preds + 0.5).astype(\"int32\")\n",
    "\n",
    "        for i in range(sample_num):\n",
    "            pred = preds[i]\n",
    "            label = labels[i]\n",
    "            if pred == 1:\n",
    "                if pred == label:\n",
    "                    self.tp += 1\n",
    "                else:\n",
    "                    self.fp += 1\n",
    "\n",
    "    def reset(self):\n",
    "        \"\"\"\n",
    "        Resets all of the metric state.\n",
    "        \"\"\"\n",
    "        self.tp = 0\n",
    "        self.fp = 0\n",
    "\n",
    "    def accumulate(self):\n",
    "        \"\"\"\n",
    "        Calculate the final precision.\n",
    "\n",
    "        Returns:\n",
    "            A scaler float: results of the calculated precision.\n",
    "        \"\"\"\n",
    "        ap = self.tp + self.fp\n",
    "        return float(self.tp) / ap if ap != 0 else .0\n",
    "\n",
    "    def name(self):\n",
    "        \"\"\"\n",
    "        Returns metric name\n",
    "        \"\"\"\n",
    "        return self._name\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 5.5 自定义Callback\n",
    "\n",
    "`fit`接口的callback参数支持我们传一个Callback类实例，用来在每轮训练和每个batch训练前后进行调用，可以通过callback收集到训练过程中的一些数据和参数，或者实现一些自定义操作。\n",
    "\n",
    "```python\n",
    "class SelfDefineCallback(paddle.callbacks.Callback):\n",
    "    \"\"\"\n",
    "    1. 继承paddle.callbacks.Callback\n",
    "    2. 按照自己的需求实现以下类成员方法：\n",
    "        def on_train_begin(self, logs=None)                 训练开始前，`Model.fit`接口中调用\n",
    "        def on_train_end(self, logs=None)                   训练结束后，`Model.fit`接口中调用\n",
    "        def on_eval_begin(self, logs=None)                  评估开始前，`Model.evaluate`接口调用\n",
    "        def on_eval_end(self, logs=None)                    评估结束后，`Model.evaluate`接口调用\n",
    "        def on_test_begin(self, logs=None)                  预测测试开始前，`Model.predict`接口中调用\n",
    "        def on_test_end(self, logs=None)                    预测测试结束后，`Model.predict`接口中调用 \n",
    "        def on_epoch_begin(self, epoch, logs=None)          每轮训练开始前，`Model.fit`接口中调用 \n",
    "        def on_epoch_end(self, epoch, logs=None)            每轮训练结束后，`Model.fit`接口中调用 \n",
    "        def on_train_batch_begin(self, step, logs=None)     单个Batch训练开始前，`Model.fit`和`Model.train_batch`接口中调用\n",
    "        def on_train_batch_end(self, step, logs=None)       单个Batch训练结束后，`Model.fit`和`Model.train_batch`接口中调用\n",
    "        def on_eval_batch_begin(self, step, logs=None)      单个Batch评估开始前，`Model.evalute`和`Model.eval_batch`接口中调用\n",
    "        def on_eval_batch_end(self, step, logs=None)        单个Batch评估结束后，`Model.evalute`和`Model.eval_batch`接口中调用\n",
    "        def on_test_batch_begin(self, step, logs=None)      单个Batch预测测试开始前，`Model.predict`和`Model.test_batch`接口中调用\n",
    "        def on_test_batch_end(self, step, logs=None)        单个Batch预测测试结束后，`Model.predict`和`Model.test_batch`接口中调用\n",
    "    \"\"\"\n",
    "    def __init__(self):\n",
    "        super(SelfDefineCallback, self).__init__()\n",
    "\n",
    "    按照需求定义自己的类成员方法\n",
    "```\n",
    "\n",
    "我们看一个框架中的实际例子，这是一个框架自带的ModelCheckpoint回调函数，方便用户在fit训练模型时自动存储每轮训练得到的模型。\n",
    "\n",
    "```python\n",
    "class ModelCheckpoint(Callback):\n",
    "    def __init__(self, save_freq=1, save_dir=None):\n",
    "        self.save_freq = save_freq\n",
    "        self.save_dir = save_dir\n",
    "\n",
    "    def on_epoch_begin(self, epoch=None, logs=None):\n",
    "        self.epoch = epoch\n",
    "\n",
    "    def _is_save(self):\n",
    "        return self.model and self.save_dir and ParallelEnv().local_rank == 0\n",
    "\n",
    "    def on_epoch_end(self, epoch, logs=None):\n",
    "        if self._is_save() and self.epoch % self.save_freq == 0:\n",
    "            path = '{}/{}'.format(self.save_dir, epoch)\n",
    "            print('save checkpoint at {}'.format(os.path.abspath(path)))\n",
    "            self.model.save(path)\n",
    "\n",
    "    def on_train_end(self, logs=None):\n",
    "        if self._is_save():\n",
    "            path = '{}/final'.format(self.save_dir)\n",
    "            print('save checkpoint at {}'.format(os.path.abspath(path)))\n",
    "            self.model.save(path)\n",
    "\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6. 模型评估\n",
    "\n",
    "对于训练好的模型进行评估操作可以使用`evaluate`接口来实现，事先定义好用于评估使用的数据集后，可以简单的调用`evaluate`接口即可完成模型评估操作，结束后根据prepare中loss和metric的定义来进行相关评估结果计算返回。\n",
    "\n",
    "返回格式是一个字典：\n",
    "* 只包含loss，`{'loss': xxx}`\n",
    "* 包含loss和一个评估指标，`{'loss': xxx, 'metric name': xxx}`\n",
    "* 包含loss和多个评估指标，`{'loss': xxx, 'metric name': xxx, 'metric name': xxx}`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "result = model.evaluate(val_dataset, verbose=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 7. 模型预测\n",
    "\n",
    "高层API中提供了`predict`接口来方便用户对训练好的模型进行预测验证，只需要基于训练好的模型将需要进行预测测试的数据放到接口中进行计算即可，接口会将经过模型计算得到的预测结果进行返回。\n",
    "\n",
    "返回格式是一个list，元素数目对应模型的输出数目：\n",
    "* 模型是单一输出：[(numpy_ndarray_1, numpy_ndarray_2, ..., numpy_ndarray_n)]\n",
    "* 模型是多输出：[(numpy_ndarray_1, numpy_ndarray_2, ..., numpy_ndarray_n), (numpy_ndarray_1, numpy_ndarray_2, ..., numpy_ndarray_n), ...]\n",
    "\n",
    "numpy_ndarray_n是对应原始数据经过模型计算后得到的预测数据，数目对应预测数据集的数目。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pred_result = model.predict(val_dataset)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 7.1 使用多卡进行预测\n",
    "\n",
    "有时我们需要进行预测验证的数据较多，单卡无法满足我们的时间诉求，那么`predict`接口也为用户支持实现了使用多卡模式来运行。\n",
    "\n",
    "使用起来也是超级简单，无需修改代码程序，只需要使用launch来启动对应的预测脚本即可。\n",
    "\n",
    "```bash\n",
    "$ python3 -m paddle.distributed.launch infer.py\n",
    "```\n",
    "\n",
    "infer.py里面就是包含model.predict的代码程序。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 8. 模型部署\n",
    "\n",
    "### 8.1 模型存储\n",
    "\n",
    "模型训练和验证达到我们的预期后，可以使用`save`接口来将我们的模型保存下来，用于后续模型的Fine-tuning（接口参数training=True）或推理部署（接口参数training=False）。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 保存用于推理部署的模型（training=False）\n",
    "model.save('~/model/mnist', training=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 8.2 预测部署\n",
    "\n",
    "有了用于推理部署的模型，就可以使用推理部署框架来完成预测服务部署，具体可以参见：[预测部署](https://www.paddlepaddle.org.cn/documentation/docs/zh/advanced_guide/inference_deployment/index_cn.html)， 包括服务端部署、移动端部署和模型压缩。"
   ]
  }
 ]
}