fix summary api docs

2021-12-24 17:24:29 +08:00 · 2021-12-24 17:24:29 +08:00 · 011db43012
parent 47a3932a5c
commit 011db43012
4 changed files with 74 additions and 46 deletions
--- a/docs/api/api_python/mindspore.train.rst
+++ b/docs/api/api_python/mindspore.train.rst
@ -4,7 +4,7 @@ mindspore.train
 mindspore.train.summary
 ------------------------

-用户可以通过SummaryRecord来自定义回调函数或者在自定义训练循环中将需要的数据存储为summary文件和lineage文件，然后使用MindInsight进行可视化分析。
+使用SummaryRecord将需要的数据存储为summary文件和lineage文件，使用方法包括自定义回调函数和自定义训练循环。保存的summary文件使用MindInsight进行可视化分析。

 .. include:: mindspore.train/mindspore.train.summary.SummaryRecord.rst

--- a/docs/api/api_python/mindspore.train/mindspore.train.SummaryCollector.rst
+++ b/docs/api/api_python/mindspore.train/mindspore.train.SummaryCollector.rst
@ -3,7 +3,7 @@
    SummaryCollector可以收集一些常用信息。

    它可以帮助收集loss、学习率、计算图等。
-    SummaryCollector还可以允许summary算子将数据收集到summary文件中。
+    SummaryCollector还可以允许通过 `summary算子 <https://www.mindspore.cn/mindinsight/docs/zh-CN/master/summary_record.html#summarysummarycollector>`_ 将数据收集到summary文件中。

    .. note:: 
        - 不允许在回调列表中存在多个SummaryCollector实例。
@ -14,8 +14,8 @@
    **参数：**

    - **summary_dir** (str) - 收集的数据将存储到此目录。如果目录不存在，将自动创建。
-    - **collect_freq** (int) - 设置数据收集的频率，频率应大于零，单位为 `step` 。如果设置了频率，将在(current steps % freq)等于0时收集数据，并且将随时收集第一个step。需要注意的是，如果使用数据下沉模式，单位将变成 `epoch` 。不建议过于频繁地收集数据，因为这可能会影响性能。默认值：10。
-    - **collect_specified_data** (Union[None, dict]) - 对收集的数据进行自定义操作。默认情况下，如果该参数设为None，则默认收集所有数据。您可以使用字典自定义需要收集的数据类型。例如，您可以设置{'collect_metric':False}不去收集metrics。支持控制的数据如下。默认值：None。
+    - **collect_freq** (int) - 设置数据收集的频率，频率应大于零，单位为 `step` 。如果设置了频率，将在(current steps % freq)等于0时收集数据，并且将总是收集第一个step。需要注意的是，如果使用数据下沉模式，单位将变成 `epoch` 。不建议过于频繁地收集数据，因为这可能会影响性能。默认值：10。
+    - **collect_specified_data** (Union[None, dict]) - 对收集的数据进行自定义操作。您可以使用字典自定义需要收集的数据类型。例如，您可以设置{'collect_metric':False}不去收集metrics。支持控制的数据如下。默认值：None，默认收集所有数据。

      - **collect_metric** (bool) - 表示是否收集训练metrics，目前只收集loss。把第一个输出视为loss，并且算出其平均数。可选值：True/False。默认值：True。
      - **collect_graph** (bool) - 表示是否收集计算图。目前只收集训练计算图。可选值：True/False。默认值：True。
@ -23,13 +23,13 @@
      - **collect_eval_lineage** (bool) - 表示是否收集评估阶段的lineage数据，该字段将显示在MindInsight的lineage页面上。可选值：True/False。默认值：True。
      - **collect_input_data** (bool) - 表示是否为每次训练收集数据集。目前仅支持图像数据。如果数据集中有多列数据，则第一列应为图像数据。可选值：True/False。默认值：True。
      - **collect_dataset_graph** (bool) - 表示是否收集训练阶段的数据集图。可选值：True/False。默认值：True。
-      - **histogram_regular** (Union[str, None]) - 收集参数分布页面的权重和偏置，并在MindInsight中展示。此字段允许常规字符串控制要收集的参数。不建议一次收集太多参数，因为这会影响性能。注：如果收集的参数太多并且内存不足，训练将会失败。默认值：None，表示只收集前五个参数。
+      - **histogram_regular** (Union[str, None]) - 收集参数分布页面的权重和偏置，并在MindInsight中展示。此字段允许正则表达式控制要收集的参数。不建议一次收集太多参数，因为这会影响性能。注：如果收集的参数太多并且内存不足，训练将会失败。默认值：None，表示只收集前五个参数。
        
    - **keep_default_action** (bool) - 此字段影响 `collect_specified_data` 字段的收集行为。True：表示设置指定数据后，默认收集非指定数据。False：表示设置指定数据后，只收集指定数据，不收集其他数据。可选值：True/False，默认值：True。
-    - **custom_lineage_data** (Union[dict, None]) - 允许您自定义数据并将数据显示在MingInsight的lineage页面上。在自定义数据中，key支持str类型，value支持str、int和float类型。默认值：None，表示不存在自定义数据。
-    - **collect_tensor_freq** (Optional[int]) - 语义与 `collect_freq` 的相同，但仅控制TensorSummary。由于TensorSummary数据太大，无法与其他summary数据进行比较，因此此参数用于降低收集量。默认情况下，收集TensorSummary数据的最大step数量为20，但不会超过收集其他summary数据的step数量。例如，给定 `collect_freq=10` ，当总step数量为600时，TensorSummary将收集20个step，而收集其他summary数据时会收集61个step。但当总step数量为为20时，TensorSummary和其他summary将收集3个step。另外请注意，在并行模式下，会平均分配总的step数量，这会影响TensorSummary收集的step的数量。默认值：None，表示要遵循上述规则。
+    - **custom_lineage_data** (Union[dict, None]) - 允许您自定义数据并将数据显示在MindInsight的lineage页面上。在自定义数据中，key支持str类型，value支持str、int和float类型。默认值：None，表示不存在自定义数据。
+    - **collect_tensor_freq** (Optional[int]) - 语义与 `collect_freq` 的相同，但仅控制TensorSummary。由于TensorSummary数据太大，无法与其他summary数据进行比较，因此此参数用于降低收集量。默认情况下，收集TensorSummary数据的最大step数量为20，但不会超过收集其他summary数据的step数量。例如，给定 `collect_freq=10` ，当总step数量为600时，TensorSummary将收集20个step，而收集其他summary数据时会收集61个step。但当总step数量为20时，TensorSummary和其他summary将收集3个step。另外请注意，在并行模式下，会平均分配总的step数量，这会影响TensorSummary收集的step的数量。默认值：None，表示要遵循上述规则。
    - **max_file_size** (Optional[int]) - 可写入磁盘的每个文件的最大大小（以字节为单位）。例如，如果不大于4GB，则设置 `max_file_size=4*1024**3` 。默认值：None，表示无限制。
-    - **export_options** (Union[None, dict]) - 表示对导出的数据执行自定义操作。注：导出的文件的大小不受 `max_file_size` 的限制。您可以使用字典自定义导出的数据。例如，您可以设置{'tensor_format':'npy'}将tensor导出为NPY文件。支持控制的数据如下所示。默认值：None，表示不导出数据。
+    - **export_options** (Union[None, dict]) - 表示对导出的数据执行自定义操作。注：导出的文件的大小不受 `max_file_size` 的限制。您可以使用字典自定义导出的数据。例如，您可以设置{'tensor_format':'npy'}将tensor导出为`npy`文件。支持控制的数据如下所示。默认值：None，表示不导出数据。

      - **tensor_format** (Union[str, None]) - 自定义导出的tensor的格式。支持["npy", None]。默认值：None，表示不导出tensor。
        
--- a/docs/api/api_python/mindspore.train/mindspore.train.summary.SummaryRecord.rst
+++ b/docs/api/api_python/mindspore.train/mindspore.train.summary.SummaryRecord.rst
@ -2,24 +2,24 @@

    SummaryRecord用于记录summary数据和lineage数据。

-    该API将在一个指定的目录中创建summary文件和lineage文件，并将数据写入文件。
+    该方法将在一个指定的目录中创建summary文件和lineage文件，并将数据写入文件。

-    它通过执行 `record` 方法将数据写入文件。除了通过定义summary算子记录从网络获取的数据外，SummaryRecord还支持记录其他数据，这些数据可以通过调用 `add_value` 添加。
+    它通过执行 `record` 方法将数据写入文件。除了通过 `summary算子 <https://www.mindspore.cn/mindinsight/docs/zh-CN/master/summary_record.html#summarysummarycollector>`_ 记录网络的数据外，SummaryRecord还支持通过 `自定义回调函数和自定义训练循环 <https://www.mindspore.cn/mindinsight/docs/zh-CN/master/summary_record.html#callback>`_ 记录数据。

    .. note::
        - 确保在最后关闭SummaryRecord，否则进程不会退出。请参阅下面的示例部分，了解如何用两种方式正确关闭SummaryRecord。
-        - 每次只允许一个SummaryRecord实例，否则会导致数据写入异常。
+        - 每次训练只允许创建一个SummaryRecord实例，否则会导致数据写入异常。
        - SummaryRecord仅支持Linux系统。

    **参数：**

-    - **log_dir** (str) - `log_dir` 是用来保存summary的目录。
-    - **file_prefix** (str) - 文件的前缀。默认值：events。
-    - **file_suffix** (str) - 文件的后缀。默认值：_MS。
-    - **network** (Cell) - 通过网络获取用于保存图形summary的管道。默认值：None。
-    - **max_file_size** (int, optional) - 可写入磁盘的每个文件的最大大小（以字节为单位）。例如，如果不大于4GB，则设置 `max_file_size=4*1024**3` 。默认值：None，表示无限制。
+    - **log_dir** (str) - `log_dir` 是用来保存summary文件的目录。
+    - **file_prefix** (str) - 文件的前缀。默认值：`events`。
+    - **file_suffix** (str) - 文件的后缀。默认值：`_MS`。
+    - **network** (Cell) - 表示用于保存计算图的网络。默认值：None。
+    - **max_file_size** (int, 可选) - 可写入磁盘的每个文件的最大大小（以字节为单位）。例如，预期写入文件最大不超过4GB，则设置 `max_file_size=4*1024**3` 。默认值：None，表示无限制。
    - **raise_exception** (bool, 可选) - 设置在记录数据中发生RuntimeError或OSError异常时是否抛出异常。默认值：False，表示打印错误日志，不抛出异常。
-    - **export_options** (Union[None, dict]) - 可以将保存在summary中的数据导出，并使用字典自定义所需的数据和文件格式。注：导出的文件大小不受 `max_file_size` 的限制。例如，您可以设置{'tensor_format':'npy'}将Tensor导出为NPY文件。支持控制的数据如下所示。默认值：None，表示不导出数据。
+    - **export_options** (Union[None, dict]) - 可以将保存在summary中的数据导出，并使用字典自定义所需的数据和文件格式。注：导出的文件大小不受 `max_file_size` 的限制。例如，您可以设置{'tensor_format':'npy'}将Tensor导出为`npy`文件。支持导出的数据类型如下所示。默认值：None，表示不导出数据。

        - **tensor_format** (Union[str, None]) - 自定义导出的Tensor的格式。支持["npy", None]。默认值：None，表示不导出Tensor。

@ -27,9 +27,8 @@

    **异常：**

-    - **TypeError：** 参数类型不正确。
-    - **RuntimeError** ：运行时错误。
-    - **OSError：** 系统错误。
+    - **TypeError：** `max_file_size` 不是整型，或 `file_prefix` 和 `file_suffix` 不是字符串。
+    - **ValueError：** ：未开启可维可测功能，无法使用Summary，如需使用Summary功能，请在勿在编译MindSpore时设置 `-s on` 。

    **样例：**

@ -47,11 +46,22 @@

    .. py:method:: add_value(plugin, name, value)

-        添加稍后记录的值。
+        添加需要记录的值。

        **参数：**

        - **plugin** (str) - 数据类型标签。
+
+          - graph：代表添加的数据为计算图。
+          - scalar：代表添加的数据为标量。
+          - image：代表添加的数据为图片。
+          - tensor：代表添加的数据为张量。
+          - histogram：代表添加的数据为直方图。
+          - train_lineage：代表添加的数据为训练阶段的lineage数据。
+          - eval_lineage：代表添加的数据为评估阶段的lineage数据。
+          - dataset_graph：代表添加的数据为数据图。
+          - custom_lineage_data：代表添加的数据为自定义lineage数据。
+
        - **name** (str) - 数据名称。
        - **value** (Union[Tensor, GraphProto, TrainLineage, EvaluationLineage, DatasetGraph, UserDefinedInfo])： 待存储的值。

@ -61,12 +71,11 @@
          - 当plugin为"eval_lineage"时，参数值的数据类型应为"EvaluationLineage"对象。具体详情，请参见 mindspore/ccsrc/lineage.proto。
          - 当plugin为"dataset_graph"时，参数值的数据类型应为"DatasetGraph"对象。具体详情，请参见 mindspore/ccsrc/lineage.proto。
          - 当plugin为"custom_lineage_data"时，参数值的数据类型应为"UserDefinedInfo"对象。具体详情，请参见 mindspore/ccsrc/lineage.proto。
-          - 当plugin为"explainer"时，参数值的数据类型应为"Explain"对象。具体详情，请参见 mindspore/ccsrc/summary.proto。

        **异常：**

-        - **ValueError：** 参数值无效。
-        - **TypeError：** 参数类型错误。
+        - **ValueError：** `plugin` 的值不在可选值内。
+        - **TypeError：** `name` 不是非空字符串，或当 `plugin` 为"scalar"、"image"、"tensor"或"histogram"时，`value` 的数据类型不是"Tensor"对象。

        **样例：**

@ -78,7 +87,7 @@

    .. py:method:: close()

-        将所有事件持久化并关闭SummaryRecord。请使用with语句或try…finally语句进行自动关闭。
+        将缓冲区中的数据立刻写入文件并关闭SummaryRecord。请使用with语句或try…finally语句进行自动关闭。

        **样例：**

@ -91,7 +100,7 @@

    .. py:method:: flush()

-        将事件文件持久化到磁盘。
+        刷新缓冲区，将缓冲区中的数据立刻写入文件。

        调用该函数以确保所有挂起事件都已写入到磁盘。

@ -124,18 +133,17 @@

        **参数：**

-        - **step** (int) - 表示训练step的编号。
-        - **train_network** (Cell) - 表示用于保存图形的备用网络。默认值：None，表示当原始网络图为None时，不保存图形summary。
-        - **plugin_filter** (Optional[Callable[[str], bool]]) - 过滤器函数，用于通过返回False来过滤正在写入的插件。默认值：None。
+        - **step** (int) - 表示当前的step。
+        - **train_network** (Cell) - 表示用于保存计算图的训练网络。默认值：None，表示当原始网络的图为None时，不保存计算图。
+        - **plugin_filter** (Callable[[str], bool]) - 过滤器函数，用于过滤需要写入的标签项。默认值：None。

        **返回：**

-        bool，表示记录进程是否成功。
+        bool，表示记录是否成功。

        **异常：**

-        - **TypeError：** 参数类型错误。
-        - **RuntimeError：** 磁盘空间不足。
+        - **TypeError：** `step` 不为整型，或 `train_network` 的类型不为`mindspore.nn.Cell <https://www.mindspore.cn/docs/api/zh-CN/master/api_python/nn/mindspore.nn.Cell.html?highlight=MindSpore.nn.cell#mindspore-nn-cell>`_ 。

        **样例：**

@ -148,15 +156,17 @@

    .. py:method:: set_mode(mode)

-        设置训练阶段。不同的训练阶段会影响数据记录。
+        设置模型运行状态。不同的状态会影响记录数据的内容。

        **参数：**

-        - **mode** (str) - 待设置的模式，为"train"或"eval"。当模式为"eval"时，`summary_record` 不记录summary算子的数据。
+        - **mode** (str) - 待设置的网络阶段，可选值为"train"或"eval"。
+          - train：代表训练阶段。
+          - eval：代表推理阶段，此时 `summary_record` 不会记录summary算子的数据。

        **异常：**

-        **ValueError：** 无法识别模式。
+        **ValueError：** `mode` 的值不在可选值内。

        **样例：**

--- a/mindspore/python/mindspore/train/summary/summary_record.py
+++ b/mindspore/python/mindspore/train/summary/summary_record.py
@ -128,7 +128,8 @@ class SummaryRecord:
              - npy: export tensor as npy file.

    Raises:
-        TypeError: If the parameter type is incorrect.
+        TypeError: `max_file_size` is not int or `file_prefix` and `file_suffix` is not string.
+        ValueError: The Summary is not supported, please without `-s on` and recompile source.

    Examples:
        >>> from mindspore.train.summary import SummaryRecord
@ -211,14 +212,18 @@ class SummaryRecord:

    def set_mode(self, mode):
        """
-        Set the training phase. Different training phases affect data recording.
+        Set the model running phase. Different phases affect data recording.

        Args:
            mode (str): The mode to be set, which should be 'train' or 'eval'. When the mode is 'eval',
                summary_record will not record the data of summary operators.

+                - train：the model running phase is train mode.
+                - eval：the model running phase is eval mode，When the mode is 'eval',
+                  summary_record will not record the data of summary operators.
+
        Raises:
-            ValueError: When the mode is not recognized.
+            ValueError: `mode` is not in the optional value.

        Examples:
            >>> from mindspore.train.summary import SummaryRecord
@ -236,7 +241,18 @@ class SummaryRecord:
        Add value to be recorded later.

        Args:
-            plugin (str): The value of the plugin.
+            plugin (str): The plugin of the value.
+
+                - graph: the value is a computational graph.
+                - scalar: the value is a scalar.
+                - image: the value is an image.
+                - tensor: the value is a tensor.
+                - histogram: the value is a histogram.
+                - train_lineage: the value is a lineage data for the training phase.
+                - eval_lineage: the value is a lineage data for the evaluation phase.
+                - dataset_graph: the value is a dataset graph.
+                - custom_lineage_data: the value is a customized lineage data.
+
            name (str): The value of the name.
            value (Union[Tensor, GraphProto, TrainLineage, EvaluationLineage, DatasetGraph, UserDefinedInfo]): \
                The value to store.
@ -253,9 +269,11 @@ class SummaryRecord:
                  see mindspore/ccsrc/lineage.proto.
                - The data type of value should be a 'UserDefinedInfo' object when the plugin is 'custom_lineage_data',
                  see mindspore/ccsrc/lineage.proto.
+
        Raises:
-            ValueError: If the parameter value is invalid.
-            TypeError: If the parameter type is error.
+            ValueError: `plugin` is not in the optional value。
+            TypeError: `name` is not non-empty string，or the data type of value is not 'Tensor' object when the plugin
+                is 'scalar', 'image', 'tensor' or 'histogram'.

        Examples:
            >>> from mindspore import Tensor
@ -299,14 +317,14 @@ class SummaryRecord:
            train_network (Cell): The spare network for saving graph.
                Default: None, it means just do not save the graph summary when the original network graph is None.
            plugin_filter (Optional[Callable[[str], bool]]): The filter function, \
-                which is used to filter out plugins from being written by returning False. Default: None.
+                which is used to filter out which plugin should be written. Default: None.

        Returns:
            bool, whether the record process is successful or not.

        Raises:
-            TypeError: If the parameter type is error.
-            RuntimeError: If the disk space is insufficient.
+            TypeError: `step` is not int，or `train_network` is not `mindspore.nn.Cell \
+            <https://www.mindspore.cn/docs/api/en/master/api_python/nn/mindspore.nn.Cell.html#mindspore-nn-cell>`_ 。

        Examples:
            >>> from mindspore.train.summary import SummaryRecord
@ -387,7 +405,7 @@ class SummaryRecord:

    def flush(self):
        """
-        Flush the event file to disk.
+        Flush the buffer and write files to disk.

        Call it to make sure that all pending events have been written to disk.

@ -404,7 +422,7 @@ class SummaryRecord:

    def close(self):
        """
-        Flush all events and close summary records. Please use the statement to autoclose.
+        Flush the buffer and write files to disk and close summary records. Please use the statement to autoclose.

        Examples:
            >>> from mindspore.train.summary import SummaryRecord