Update paddle/metrics (#2614) (#2617)

* Update paddle/metrics

* Fix format

* Update Metric format

doc/paddle/api/paddle/metric/Accuracy_cn.rst

-.. _cn_api_fluid_metrics_Accuracy:
-
-Accuracy
--------------------------------
-.. py:class:: paddle.fluid.metrics.Accuracy(name=None)
-
-
-
-
-该接口用来计算多个mini-batch的平均准确率。Accuracy对象有两个状态value和weight。Accuracy的定义参照 https://en.wikipedia.org/wiki/Accuracy_and_precision 。
-
-参数:
-    - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
-
-返回：初始化后的 ``Accuracy`` 对象
-
-返回类型：Accuracy
-
-**代码示例**
-
-.. code-block:: python
-
-        import paddle.fluid as fluid
-        # 假设有batch_size = 128
-        batch_size=128
-        accuracy_manager = fluid.metrics.Accuracy()
-        # 假设第一个batch的准确率为0.9
-        batch1_acc = 0.9
-        accuracy_manager.update(value = batch1_acc, weight = batch_size)
-        print("expect accuracy: %.2f, get accuracy: %.2f" % (batch1_acc, accuracy_manager.eval()))
-        # 假设第二个batch的准确率为0.8
-        batch2_acc = 0.8
-        accuracy_manager.update(value = batch2_acc, weight = batch_size)
-        #batch1和batch2的联合准确率为(batch1_acc * batch_size + batch2_acc * batch_size) / batch_size / 2
-        print("expect accuracy: %.2f, get accuracy: %.2f" % ((batch1_acc * batch_size + batch2_acc * batch_size) / batch_size / 2, accuracy_manager.eval()))
-        #重置accuracy_manager
-        accuracy_manager.reset()
-        #假设第三个batch的准确率为0.8
-        batch3_acc = 0.8
-        accuracy_manager.update(value = batch3_acc, weight = batch_size)
-        print("expect accuracy: %.2f, get accuracy: %.2f" % (batch3_acc, accuracy_manager.eval()))
-
-.. py:method:: update(value, weight)
-
-该函数使用输入的(value, weight)来累计更新Accuracy对象的对应状态，更新方式如下：
-
-    .. math::
-                   \\ \begin{array}{l}{\text { self. value }+=\text { value } * \text { weight }} \\ {\text { self. weight }+=\text { weight }}\end{array} \\
-
-参数：    
-    - **value** (float|numpy.array) – mini-batch的正确率
-    - **weight** (int|float) – mini-batch的大小
-
-返回：无
-
-.. py:method:: eval()
-
-该函数计算并返回累计的mini-batches的平均准确率。
-
-返回：累计的mini-batches的平均准确率
-
-返回类型：float或numpy.array
-

doc/paddle/api/paddle/metric/Auc_cn.rst

-.. _cn_api_fluid_metrics_Auc:
-
-Auc
--------------------------------
-.. py:class:: paddle.fluid.metrics.Auc(name, curve='ROC', num_thresholds=4095)
-
-
-
-
-**注意**：目前只用Python实现Auc，可能速度略慢
-
-该接口计算Auc，在二分类(binary classification)中广泛使用。相关定义参考 https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_the_curve 。
-
-该接口创建四个局部变量true_positives, true_negatives, false_positives和false_negatives，用于计算Auc。为了离散化AUC曲线，使用临界值的线性间隔来计算召回率和准确率的值。用false positive的召回值高度计算ROC曲线面积，用recall的准确值高度计算PR曲线面积。
-
-参数：
-    - **name** (str，可选) – 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
-    - **curve** (str) - 将要计算的曲线名的详情，曲线包括ROC（默认）或者PR（Precision-Recall-curve）。
-
-返回：初始化后的 ``Auc`` 对象
-
-返回类型：Auc
-
-**代码示例**：
-
-.. code-block:: python
-
-    import paddle.fluid as fluid
-    import numpy as np
-    # 初始化auc度量
-    auc_metric = fluid.metrics.Auc("ROC")
-
-    # 假设batch_size为128
-    batch_num = 100
-    batch_size = 128
-
-    for batch_id in range(batch_num):
-        
-        class0_preds = np.random.random(size = (batch_size, 1))
-        class1_preds = 1 - class0_preds
-         
-        preds = np.concatenate((class0_preds, class1_preds), axis=1)
-         
-        labels = np.random.randint(2, size = (batch_size, 1))
-        auc_metric.update(preds = preds, labels = labels)
-        
-        # 应为一个接近0.5的值，因为preds是随机指定的
-        print("auc for iteration %d is %.2f" % (batch_id, auc_metric.eval()))
-
-.. py:method:: update(preds, labels)
-
-用给定的预测值和标签更新Auc曲线。
-
-参数： 
-    - **preds** (numpy.array) - 维度为[batch_size, 2]，preds[i][j]表示将实例i划分为类别j的概率。
-    - **labels** (numpy.array) - 维度为[batch_size, 1]，labels[i]为0或1，代表实例i的标签。
-
-返回：无
-
-.. py:method:: eval()
-
-该函数计算并返回Auc值。
-
-返回：Auc值
-
-返回类型：float
-

doc/paddle/api/paddle/metric/metrics/Accuracy_cn.rst

@@ -5,55 +5,102 @@ Accuracy
 
 .. py:class:: paddle.metric.Accuracy()
 
+计算准确率(accuracy)。
 
-    Encapsulates accuracy metric logic.
-
-    参数
+参数：
 :::::::::
-        topk (int|tuple(int)): Number of top elements to look at
-            for computing accuracy. Default is (1,).
-        name (str, optional): String name of the metric instance. Default
-            is `acc`.
+    - **topk** (int|tuple(int)) - 计算准确率的top个数，默认是1。
+    - **name** (str, optional) - metric实例的名字，默认是'acc'。
+
+**代码示例**：
 
-    Example by standalone:
+    # 独立使用示例:
         
         .. code-block:: python
 
-        import numpy as np
-        import paddle
+            import numpy as np
+            import paddle
 
-        paddle.disable_static()
-        x = paddle.to_tensor(np.array([
-            [0.1, 0.2, 0.3, 0.4],
-            [0.1, 0.4, 0.3, 0.2],
-            [0.1, 0.2, 0.4, 0.3],
-            [0.1, 0.2, 0.3, 0.4]]))
-        y = paddle.to_tensor(np.array([[0], [1], [2], [3]]))
+            paddle.disable_static()
+            x = paddle.to_tensor(np.array([
+                [0.1, 0.2, 0.3, 0.4],
+                [0.1, 0.4, 0.3, 0.2],
+                [0.1, 0.2, 0.4, 0.3],
+                [0.1, 0.2, 0.3, 0.4]]))
+            y = paddle.to_tensor(np.array([[0], [1], [2], [3]]))
 
-        m = paddle.metric.Accuracy()
-        correct = m.compute(x, y)
-        m.update(correct)
-        res = m.accumulate()
-        print(res) # 0.75
+            m = paddle.metric.Accuracy()
+            correct = m.compute(x, y)
+            m.update(correct)
+            res = m.accumulate()
+            print(res) # 0.75
 
 
-    Example with Model API:
+    # 在Model API中的示例:
         
         .. code-block:: python
 
-        import paddle
+            import paddle
+
+            paddle.disable_static()
+            train_dataset = paddle.vision.datasets.MNIST(mode='train')
+
+            model = paddle.Model(paddle.vision.LeNet(classifier_activation=None))
+            optim = paddle.optimizer.Adam(
+                learning_rate=0.001, parameters=model.parameters())
+            model.prepare(
+                optim,
+                loss=paddle.nn.CrossEntropyLoss(),
+                metrics=paddle.metric.Accuracy())
+
+            model.fit(train_dataset, batch_size=64)
+
+
+.. py:function:: compute(pred, label, *args)
+
+计算top-k（topk中的最大值）的索引。
+
+参数：
+:::::::::
+    - **pred**  (Tensor) - 预测结果为是float64或float32类型的Tensor。
+    - **label**  (Tensor) - 真实的标签值是一个2D的Tensor，shape为[batch_size, 1], 数据类型为int64。
+
+返回: 一个Tensor，shape是[batch_size, topk], 值为0或1，1表示预测正确.
+
+
+.. py:function:: update(pred, label, *args)
+
+更新metric的状态（正确预测的个数和总个数），以便计算累积的准确率。返回当前step的准确率。
 
-        paddle.disable_static()
-        train_dataset = paddle.vision.datasets.MNIST(mode='train')
+参数:
+:::::::::
+    - **correct** (numpy.array | Tensor): 一个值为0或1的Tensor，shape是[batch_size, topk]。
+
+返回: 当前step的准确率。
+
+
+.. py:function:: reset()
+
+清空状态和计算结果。
+
+返回
+:::::::::
+  无
 
-        model = paddle.Model(paddle.vision.LeNet(classifier_activation=None))
-        optim = paddle.optimizer.Adam(
-            learning_rate=0.001, parameters=model.parameters())
-        model.prepare(
-            optim,
-            loss=paddle.nn.CrossEntropyLoss(),
-            metrics=paddle.metric.Accuracy())
 
-        model.fit(train_dataset, batch_size=64)
+.. py:function:: accumulate()
 
-    
+累积的统计指标，计算和返回准确率。
\ No newline at end of file
+
+返回
+:::::::::
+  准确率，一般是个标量 或 多个标量，和topk的个数一致。
+
+
+.. py:function:: name()
+
+返回Metric实例的名字, 参考上述name，默认是'acc'。
+
+返回
+:::::::::
+  评估的名字，string类型。

doc/paddle/api/paddle/metric/metrics/Auc_cn.rst

@@ -5,85 +5,108 @@ Auc
 
 .. py:class:: paddle.metric.Auc()
 
+**注意**：目前只用Python实现Auc，可能速度略慢
 
-    The auc metric is for binary classification.
-    Refer to https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_the_curve.
-    Please notice that the auc metric is implemented with python, which may be a little bit slow.
+该接口计算Auc，在二分类(binary classification)中广泛使用。相关定义参考 https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_the_curve 。
 
-    The `auc` function creates four local variables, `true_positives`,
-    `true_negatives`, `false_positives` and `false_negatives` that are used to
-    compute the AUC. To discretize the AUC curve, a linearly spaced set of
-    thresholds is used to compute pairs of recall and precision values. The area
-    under the ROC-curve is therefore computed using the height of the recall
-    values by the false positive rate, while the area under the PR-curve is the
-    computed using the height of the precision values by the recall.
+该接口创建四个局部变量true_positives, true_negatives, false_positives和false_negatives，用于计算Auc。为了离散化AUC曲线，使用临界值的线性间隔来计算召回率和准确率的值。用false positive的召回值高度计算ROC曲线面积，用recall的准确值高度计算PR曲线面积。
 
-    参数
+
+参数：
 :::::::::
-        curve (str): Specifies the mode of the curve to be computed,
-            'ROC' or 'PR' for the Precision-Recall-curve. Default is 'ROC'.
-        num_thresholds (int): The number of thresholds to use when
-            discretizing the roc curve. Default is 4095.
-            'ROC' or 'PR' for the Precision-Recall-curve. Default is 'ROC'.
-        name (str, optional): String name of the metric instance. Default
-            is `auc`.
+    - **curve** (str) - 将要计算的曲线名的模式，包括'ROC'（默认）或者'PR'（Precision-Recall-curve）。
+    - **num_thresholds** (int) - 离散化AUC曲线的整数阈值数，默认是4095。
+    - **name** (str，可选) – metric实例的名字，默认是'auc'。
 
-    "NOTE: only implement the ROC curve type via Python now."
+**代码示例**：
 
-    Example by standalone:
-        .. code-block:: python
+    # 独立使用示例:
 
-        import numpy as np
-        import paddle
+        .. code-block:: python
 
-        m = paddle.metric.Auc()
-        
-        n = 8
-        class0_preds = np.random.random(size = (n, 1))
-        class1_preds = 1 - class0_preds
-        
-        preds = np.concatenate((class0_preds, class1_preds), axis=1)
-        labels = np.random.randint(2, size = (n, 1))
-        
-        m.update(preds=preds, labels=labels)
-        res = m.accumulate()
+            import numpy as np
+            import paddle
+    
+            m = paddle.metric.Auc()
+            
+            n = 8
+            class0_preds = np.random.random(size = (n, 1))
+            class1_preds = 1 - class0_preds
+            
+            preds = np.concatenate((class0_preds, class1_preds), axis=1)
+            labels = np.random.randint(2, size = (n, 1))
+            
+            m.update(preds=preds, labels=labels)
+            res = m.accumulate()
 
 
-    Example with Model API:
+    # 在Model API中的示例:
         
         .. code-block:: python
 
-        import numpy as np
-        import paddle
-        import paddle.nn as nn
-        
-        class Data(paddle.io.Dataset):
-            def __init__(self):
-                super(Data, self).__init__()
-                self.n = 1024
-                self.x = np.random.randn(self.n, 10).astype('float32')
-                self.y = np.random.randint(2, size=(self.n, 1)).astype('int64')
-        
-            def __getitem__(self, idx):
-                return self.x[idx], self.y[idx]
-        
-            def __len__(self):
-                return self.n
-        
-        paddle.disable_static()
-        model = paddle.Model(nn.Sequential(
-            nn.Linear(10, 2), nn.Softmax())
-        )
-        optim = paddle.optimizer.Adam(
-            learning_rate=0.001, parameters=model.parameters())
-        
-        def loss(x, y):
-            return nn.functional.nll_loss(paddle.log(x), y)
-        
-        model.prepare(
-            optim,
-            loss=loss,
-            metrics=paddle.metric.Auc())
-        data = Data()
-        model.fit(data, batch_size=16)
-    
+            import numpy as np
+            import paddle
+            import paddle.nn as nn
+            
+            class Data(paddle.io.Dataset):
+                def __init__(self):
+                    super(Data, self).__init__()
+                    self.n = 1024
+                    self.x = np.random.randn(self.n, 10).astype('float32')
+                    self.y = np.random.randint(2, size=(self.n, 1)).astype('int64')
+            
+                def __getitem__(self, idx):
+                    return self.x[idx], self.y[idx]
+            
+                def __len__(self):
+                    return self.n
+            
+            paddle.disable_static()
+            model = paddle.Model(nn.Sequential(
+                nn.Linear(10, 2), nn.Softmax())
+            )
+            optim = paddle.optimizer.Adam(
+                learning_rate=0.001, parameters=model.parameters())
+            
+            def loss(x, y):
+                return nn.functional.nll_loss(paddle.log(x), y)
+            
+            model.prepare(
+                optim,
+                loss=loss,
+                metrics=paddle.metric.Auc())
+            data = Data()
+            model.fit(data, batch_size=16)
+    
\ No newline at end of file
+
+.. py:function:: update(pred, label, *args)
+
+更新AUC计算的状态。
+
+参数:
+:::::::::
+    - **preds** (numpy.array | Tensor): 一个shape为[batch_size, 2]的Numpy数组或Tensor，preds[i][j]表示第i个样本类别为j的概率。
+    - **labels** (numpy.array | Tensor): 一个shape为[batch_size, 1]的Numpy数组或Tensor，labels[i]是0或1，表示第i个样本的类别。
+
+返回: 无。
+
+
+.. py:function:: reset()
+
+清空状态和计算结果。
+
+返回：无
+
+
+.. py:function:: accumulate()
+
+累积的统计指标，计算和返回AUC值。
+
+返回：AUC值，一个标量。
+
+
+.. py:function:: name()
+
+返回Metric实例的名字, 参考上述的name，默认是'auc'。
+
+返回: 评估的名字，string类型。

doc/paddle/api/paddle/metric/metrics/Metric_cn.rst

@@ -6,71 +6,114 @@ Metric
 .. py:class:: paddle.metric.Metric()
 
 
-    Base class for metric, encapsulates metric logic and APIs
-    Usage:
-        
+评估器metric的基类。
+
+用法:
+    
+    .. code-block:: text
+
         m = SomeMetric()
         for prediction, label in ...:
             m.update(prediction, label)
         m.accumulate()
+    
+:code:`compute` 接口的进阶用法:
+
+在 :code:`compute` 中可以使用PaddlePaddle内置的算子进行评估器的状态，而不是通过
+Python/NumPy, 这样可以加速计算。:code:`update` 接口将 :code:`compute` 的输出作为
+输入，内部采用Python/NumPy计算。
+
+:code: `Metric` 计算流程如下 （在{}中的表示模型和评估器的计算）:
+
+    .. code-block:: text
+
+             inputs & labels              || ------------------
+                   |                      ||
+                {model}                   ||
+                   |                      ||
+            outputs & labels              ||
+                   |                      ||    tensor data
+            {Metric.compute}              ||
+                   |                      ||
+          metric states(tensor)           ||
+                   |                      ||
+            {fetch as numpy}              || ------------------
+                   |                      ||
+          metric states(numpy)            ||    numpy data
+                   |                      ||
+            {Metric.update}               \/ ------------------
+
+**代码示例**
+
+以 计算正确率的 :code: `Accuracy` 为例，该评估器的输入为 :code: `pred` 和
+:code: `label`, 可以在 :code:`compute` 中通过 :code: `pred` 和 :code: `label`
+先计算正确预测的矩阵。 例如，预测结果包含10类，:code: `pred` 的shape是[N, 10]，
+:code: `label` 的shape是[N, 1], N是batch size，我们需要计算top-1和top-5的准
+确率，可以在:code: `compute` 中计算每个样本的top-5得分，正确预测的矩阵的shape
+是[N, 5].
+
         
-    Advanced usage for :code:`compute`:
-
-    Metric calculation can be accelerated by calculating metric states
-    from model outputs and labels by build-in operators not by Python/NumPy
-    in :code:`compute`, metric states will be fetched as NumPy array and
-    call :code:`update` with states in NumPy format.
-    Metric calculated as follows (operations in Model and Metric are
-    indicated with curly brackets, while data nodes not):
-                 inputs & labels              || ------------------
-                       |                      ||
-                    {model}                   ||
-                       |                      ||
-                outputs & labels              ||
-                       |                      ||    tensor data
-                {Metric.compute}              ||
-                       |                      ||
-              metric states(tensor)           ||
-                       |                      ||
-                {fetch as numpy}              || ------------------
-                       |                      ||
-              metric states(numpy)            ||    numpy data
-                       |                      ||
-                {Metric.update}               \/ ------------------
-    代码示例
-:::::::::
-        
-        For :code:`Accuracy` metric, which takes :code:`pred` and :code:`label`
-        as inputs, we can calculate the correct prediction matrix between
-        :code:`pred` and :code:`label` in :code:`compute`.
-        For examples, prediction results contains 10 classes, while :code:`pred`
-        shape is [N, 10], :code:`label` shape is [N, 1], N is mini-batch size,
-        and we only need to calculate accurary of top-1 and top-5, we could
-        calculate the correct prediction matrix of the top-5 scores of the
-        prediction of each sample like follows, while the correct prediction
-        matrix shape is [N, 5].
-
-        .. code-block:: python
-            def compute(pred, label):
-                # sort prediction and slice the top-5 scores
-                pred = paddle.argsort(pred, descending=True)[:, :5]
-                # calculate whether the predictions are correct
-                correct = pred == label
-                return paddle.cast(correct, dtype='float32')
-
-        With the :code:`compute`, we split some calculations to OPs (which
-        may run on GPU devices, will be faster), and only fetch 1 tensor with
-        shape as [N, 5] instead of 2 tensors with shapes as [N, 10] and [N, 1].
-        :code:`update` can be define as follows:
-
-        .. code-block:: python
-            def update(self, correct):
-                accs = []
-                for i, k in enumerate(self.topk):
-                    num_corrects = correct[:, :k].sum()
-                    num_samples = len(correct)
-                    accs.append(float(num_corrects) / num_samples)
-                    self.total[i] += num_corrects
-                    self.count[i] += num_samples
-                return accs
-    
+    .. code-block:: python
+        def compute(pred, label):
+            # sort prediction and slice the top-5 scores
+            pred = paddle.argsort(pred, descending=True)[:, :5]
+            # calculate whether the predictions are correct
+            correct = pred == label
+            return paddle.cast(correct, dtype='float32')
+
+在:code:`compute` 中的计算，使用内置的算子(可以跑在GPU上，是的速度更快)。
+作为:code:`update` 的输入，该接口计算如下: 
+
+    .. code-block:: python
+        def update(self, correct):
+            accs = []
+            for i, k in enumerate(self.topk):
+                num_corrects = correct[:, :k].sum()
+                num_samples = len(correct)
+                accs.append(float(num_corrects) / num_samples)
+                self.total[i] += num_corrects
+                self.count[i] += num_samples
+            return accs
+
+.. py:function:: reset()
+
+清空状态和计算结果。
+
+返回：无
+
+
+.. py:function:: update(*args)
+
+
+更新状态。如果定义了:code:`compute` ，:code:`update` 的输入是:code:`compute` 的输出。
+如果没有定义，则输入是网络的输出**output**和标签**label**，
+如: :code:`update(output1, output2, ..., label1, label2,...)` .
+
+也可以参考 :code:`update` 。
+
+
+.. py:function:: accumulate()
+
+累积的统计指标，计算和返回评估结果。
+
+返回：评估结果，一般是个标量 或 多个标量。
+
+
+.. py:function:: name()
+
+返回Metric的名字, 一般通过__init__构造函数传入。
+
+返回: 评估的名字，string类型。
+
+
+.. py:function:: compute()
+
+此接口可以通过PaddlePaddle内置的算子计算metric的状态，可以加速metric的计算，
+为可选的高阶接口。
+
+如果这个接口定义了，输入是网络的输出 **outputs** 和 标签 **labels** , 定义如:
+:code:`compute(output1, output2, ..., label1, label2,...)` 。
\ No newline at end of file
+如果这个接口没有定义, 默认的行为是直接将输入参数返回给 :code: `update` ，则其
+定义如: :code:`update(output1, output2, ..., label1, label2,...)` 。
+
+也可以参考 :code:`compute` 。

doc/paddle/api/paddle/metric/metrics/Precision_cn.rst

@@ -6,68 +6,99 @@ Precision
 .. py:class:: paddle.metric.Precision()
 
 
-    Precision (also called positive predictive value) is the fraction of
-    relevant instances among the retrieved instances. Refer to
-    https://en.wikipedia.org/wiki/Evaluation_of_binary_classifiers
+精确率Precision(也称为 positive predictive value,正预测值)是被预测为正样例中实际为正的比例。 https://en.wikipedia.org/wiki/Evaluation_of_binary_classifiers 该类管理二分类任务的precision分数。
 
-    Noted that this class manages the precision score only for binary
-    classification task.
+**注意**：这个metric只能用来评估二分类。
 
-    参数
+
+参数:
 :::::::::
-        name (str, optional): String name of the metric instance.
-            Default is `precision`.
+    - **name** (str，可选) – metric实例的名字，默认是'precision'。
+
 
-    Example by standalone:
+**代码示例**
+
+    # 独立使用示例:
         
         .. code-block:: python
 
-        import numpy as np
-        import paddle
-
-        x = np.array([0.1, 0.5, 0.6, 0.7])
-        y = np.array([0, 1, 1, 1])
+            import numpy as np
+            import paddle
 
-        m = paddle.metric.Precision()
-        m.update(x, y)
-        res = m.accumulate()
-        print(res) # 1.0
+            x = np.array([0.1, 0.5, 0.6, 0.7])
+            y = np.array([0, 1, 1, 1])
 
+            m = paddle.metric.Precision()
+            m.update(x, y)
+            res = m.accumulate()
+            print(res) # 1.0
 
-    Example with Model API:
+    # 在Model API中的示例:
         
         .. code-block:: python
 
-        import numpy as np
-        
-        import paddle
-        import paddle.nn as nn
-        
-        class Data(paddle.io.Dataset):
-            def __init__(self):
-                super(Data, self).__init__()
-                self.n = 1024
-                self.x = np.random.randn(self.n, 10).astype('float32')
-                self.y = np.random.randint(2, size=(self.n, 1)).astype('float32')
-        
-            def __getitem__(self, idx):
-                return self.x[idx], self.y[idx]
-        
-            def __len__(self):
-                return self.n
+            import numpy as np
+            
+            import paddle
+            import paddle.nn as nn
+            
+            class Data(paddle.io.Dataset):
+                def __init__(self):
+                    super(Data, self).__init__()
+                    self.n = 1024
+                    self.x = np.random.randn(self.n, 10).astype('float32')
+                    self.y = np.random.randint(2, size=(self.n, 1)).astype('float32')
+            
+                def __getitem__(self, idx):
+                    return self.x[idx], self.y[idx]
+            
+                def __len__(self):
+                    return self.n
   
-        paddle.disable_static()
-        model = paddle.Model(nn.Sequential(
-            nn.Linear(10, 1),
-            nn.Sigmoid()
-        ))
-        optim = paddle.optimizer.Adam(
-            learning_rate=0.001, parameters=model.parameters())
-        model.prepare(
-            optim,
-            loss=nn.BCELoss(),
-            metrics=paddle.metric.Precision())
-        
-        data = Data()
-        model.fit(data, batch_size=16)
-    
+            paddle.disable_static()
+            model = paddle.Model(nn.Sequential(
+                nn.Linear(10, 1),
+                nn.Sigmoid()
+            ))
+            optim = paddle.optimizer.Adam(
+                learning_rate=0.001, parameters=model.parameters())
+            model.prepare(
+                optim,
+                loss=nn.BCELoss(),
+                metrics=paddle.metric.Precision())
+            
+            data = Data()
+            model.fit(data, batch_size=16)
+    
\ No newline at end of file
+
+.. py:function:: update(preds, labels, *args)
+
+更新Precision的状态。
+
+参数:
+:::::::::
+    - **preds** (numpy.array | Tensor): 预测输出结果通常是sigmoid函数的输出，是一个数据类型为float64或float32的向量。
+    - **labels** (numpy.array | Tensor): 真实标签的shape和:code: `preds` 相同，数据类型为int32或int64。
+
+返回: 无。
+
+
+.. py:function:: reset()
+
+清空状态和计算结果。
+
+返回：无
+
+
+.. py:function:: accumulate()
+
+累积的统计指标，计算和返回precision值。
+
+返回：precision值，一个标量。
+
+
+.. py:function:: name()
+
+返回Metric实例的名字, 参考上述的name，默认是'precision'。
+
+返回: 评估的名字，string类型。

doc/paddle/api/paddle/metric/metrics/Recall_cn.rst

@@ -6,71 +6,99 @@ Recall
 .. py:class:: paddle.metric.Recall()
 
 
-    Recall (also known as sensitivity) is the fraction of
-    relevant instances that have been retrieved over the
-    total amount of relevant instances
+召回率Recall（也称为敏感度）是指得到的相关实例数占相关实例总数的比例。https://en.wikipedia.org/wiki/Precision_and_recall 该类管理二分类任务的召回率。
 
-    Refer to:
-    https://en.wikipedia.org/wiki/Precision_and_recall
+**注意**：这个metric只能用来评估二分类。
 
-    Noted that this class manages the recall score only for
-    binary classification task.
 
-    参数
+参数
 :::::::::
-        name (str, optional): String name of the metric instance.
-            Default is `recall`.
+    - **name** (str，可选) – metric实例的名字，默认是'recall'。
 
-    Example by standalone:
+
+**代码示例**
+
+    # 独立使用示例:
         
         .. code-block:: python
 
-        import numpy as np
-        import paddle
+            import numpy as np
+            import paddle
 
-        x = np.array([0.1, 0.5, 0.6, 0.7])
-        y = np.array([1, 0, 1, 1])
+            x = np.array([0.1, 0.5, 0.6, 0.7])
+            y = np.array([1, 0, 1, 1])
 
-        m = paddle.metric.Recall()
-        m.update(x, y)
-        res = m.accumulate()
-        print(res) # 2.0 / 3.0
+            m = paddle.metric.Recall()
+            m.update(x, y)
+            res = m.accumulate()
+            print(res) # 2.0 / 3.0
 
-
-    Example with Model API:
+    # 在Model API中的示例:
         
         .. code-block:: python
 
-        import numpy as np
-        
-        import paddle
-        import paddle.nn as nn
-        
-        class Data(paddle.io.Dataset):
-            def __init__(self):
-                super(Data, self).__init__()
-                self.n = 1024
-                self.x = np.random.randn(self.n, 10).astype('float32')
-                self.y = np.random.randint(2, size=(self.n, 1)).astype('float32')
-        
-            def __getitem__(self, idx):
-                return self.x[idx], self.y[idx]
-        
-            def __len__(self):
-                return self.n
-        
-        paddle.disable_static()
-        model = paddle.Model(nn.Sequential(
-            nn.Linear(10, 1),
-            nn.Sigmoid()
-        ))
-        optim = paddle.optimizer.Adam(
-            learning_rate=0.001, parameters=model.parameters())
-        model.prepare(
-            optim,
-            loss=nn.BCELoss(),
-            metrics=[paddle.metric.Precision(), paddle.metric.Recall()])
-        
-        data = Data()
-        model.fit(data, batch_size=16)
-    
+            import numpy as np
+            
+            import paddle
+            import paddle.nn as nn
+            
+            class Data(paddle.io.Dataset):
+                def __init__(self):
+                    super(Data, self).__init__()
+                    self.n = 1024
+                    self.x = np.random.randn(self.n, 10).astype('float32')
+                    self.y = np.random.randint(2, size=(self.n, 1)).astype('float32')
+            
+                def __getitem__(self, idx):
+                    return self.x[idx], self.y[idx]
+            
+                def __len__(self):
+                    return self.n
+            
+            paddle.disable_static()
+            model = paddle.Model(nn.Sequential(
+                nn.Linear(10, 1),
+                nn.Sigmoid()
+            ))
+            optim = paddle.optimizer.Adam(
+                learning_rate=0.001, parameters=model.parameters())
+            model.prepare(
+                optim,
+                loss=nn.BCELoss(),
+                metrics=[paddle.metric.Precision(), paddle.metric.Recall()])
+            
+            data = Data()
+            model.fit(data, batch_size=16)
+    
\ No newline at end of file
+
+.. py:function:: update(preds, labels, *args)
+
+更新Recall的状态。
+
+参数:
+:::::::::
+    - **preds** (numpy.array | Tensor): 预测输出结果通常是sigmoid函数的输出，是一个数据类型为float64或float32的向量。
+    - **labels** (numpy.array | Tensor): 真实标签的shape和:code: `preds` 相同，数据类型为int32或int64。
+
+返回: 无。
+
+
+.. py:function:: reset()
+
+清空状态和计算结果。
+
+返回：无
+
+
+.. py:function:: accumulate()
+
+累积的统计指标，计算和返回recall值。
+
+返回：precision值，一个标量。
+
+
+.. py:function:: name()
+
+返回Metric实例的名字, 参考上述的name，默认是'recall'。
+
+返回: 评估的名字，string类型。