!26668 add api cn

Merge pull request !26668 from yingchen/code_docs_api6

docs/api/api_python/mindspore/mindspore.Parameter.rst

@@ -17,45 +17,43 @@
         - **name** (str)：参数的名称。默认值：None。
         - **requires_grad** (bool)：是否需要微分求梯度。默认值：True。
         - **layerwise_parallel** (bool)：在数据/混合并行模式下， `layerwise_parallel` 配置为True时，参数广播和梯度聚合时会过滤掉该参数。默认值：False。
-        - **parallel_optimizer** (bool)：用于在"semi_auto_parallel"或"auto_parallel"并行模式下区分参数是否进行优化器切分。仅在 `mindspore.context.set_auto_parallel_context()` 并行配置模块中设置 `enable_parallel_optimizer` 启用优化器并行时有效。默认值：True。
+        - **parallel_optimizer** (bool)：用于在 `semi_auto_parallel` 或 `auto_parallel` 并行模式下区分参数是否进行优化器切分。仅在 `mindspore.context.set_auto_parallel_context()` 并行配置模块中设置 `enable_parallel_optimizer` 启用优化器并行时有效。默认值：True。
 
     **样例：**
-    
-    .. code-block::
-
-        >>> import numpy as np
-        >>> from mindspore import Parameter, Tensor
-        >>> import mindspore.ops as ops
-        >>> import mindspore.nn as nn
-        >>> import mindspore
-        >>>
-        >>> class Net(nn.Cell)：
-        ...     def __init__(self)：
-        ...         super(Net, self).__init__()
-        ...         self.matmul = ops.MatMul()
-        ...         self.weight = Parameter(Tensor(np.ones((1, 2)), mindspore.float32), name="w", requires_grad=True)
-        ...
-        ...     def construct(self, x)：
-        ...         out = self.matmul(self.weight, x)
-        ...         return out
-        >>> net = Net()
-        >>> x = Tensor(np.ones((2, 1)), mindspore.float32)
-        >>> print(net(x))
-        [[2.]]
-        >>> net.weight.set_data(Tensor(np.zeros((1, 2)), mindspore.float32))
-        >>> print(net(x))
-        [[0.]]
+
+    >>> import numpy as np
+    >>> from mindspore import Parameter, Tensor
+    >>> import mindspore.ops as ops
+    >>> import mindspore.nn as nn
+    >>> import mindspore
+    >>>
+    >>> class Net(nn.Cell)：
+    ...     def __init__(self)：
+    ...         super(Net, self).__init__()
+    ...         self.matmul = ops.MatMul()
+    ...         self.weight = Parameter(Tensor(np.ones((1, 2)), mindspore.float32), name="w", requires_grad=True)
+    ...
+    ...     def construct(self, x)：
+    ...         out = self.matmul(self.weight, x)
+    ...         return out
+    >>> net = Net()
+    >>> x = Tensor(np.ones((2, 1)), mindspore.float32)
+    >>> print(net(x))
+    [[2.]]
+    >>> net.weight.set_data(Tensor(np.zeros((1, 2)), mindspore.float32))
+    >>> print(net(x))
+    [[0.]]
     
 
     .. py:method:: cache_enable
         :property: 
 
-        返回该参数是否开启缓存功能。
+        表示该参数是否开启缓存功能。
 
     .. py:method::  cache_shape
         :property:
 
-        如果开启缓存，则返回对应参数的缓存形状。
+        如果使用缓存，则返回对应参数的缓存shape。
 
     .. py:method:: clone(init='same')
 
@@ -63,20 +61,19 @@
 
         **参数：**
                 
-            - **init** (Union[Tensor, str, numbers.Number])：初始化参数的形状和数据类型。如果 `init` 是 `Tensor` 或 `numbers.Number` ，则克隆一个具有相同数值、形状和数据类型的新参数。 如果 `init` 是 `str` ，则 `init` 将继承 `Initializer` 模块中对应的同名的类。例如，如果 `init` 是'same'，则克隆一个具有相同数据、形状和数据类型的新参数。默认值：'same'。
+        **init** (Union[Tensor, str, numbers.Number])：初始化参数的形状和数据类型。如果 `init` 是 `Tensor` 或 `numbers.Number` ，则克隆一个具有相同数值、形状和数据类型的新参数。 如果 `init` 是 `str` ，则 `init` 将继承 `Initializer` 模块中对应的同名的类。例如，如果 `init` 是'same'，则克隆一个具有相同数据、形状和数据类型的新参数。默认值：'same'。
 
         **返回：**
 
-            `Parameter` ，返回克隆的新参数。
+        `Parameter` ，返回克隆的新参数。
         
 
     .. py:method:: comm_fusion
+        :property:
 
-        获取和设置与此参数对应的通信算子的融合类型（int）。
-
-        在"auto_parallel"和"semi_auto_parallel"模式下，一些用于参数或梯度聚合的通信算子将自动插入，此属性表示当前参数对应通信算子的融合类型。 `comm_fusion` 的值必须大于等于0。当 `comm_fusion` 的值为0时，算子不融合。
+        获取此参数的通信算子的融合类型（int）。
 
-        仅在Ascend环境的图模式下使用。
+        在 `AUTO_PARALLEL` 和 `SEMI_AUTO_PARALLEL` 模式下，一些用于参数或梯度聚合的通信算子将自动插入。fusion的值必须大于等于0。当fusion的值为0时，算子不会融合在一起。
         
 
     .. py:method:: data
@@ -90,27 +87,28 @@
 
         **参数：**
 
-            - **layout** (Union[None, tuple(list(int))])：参数切片。
-                
-            - **layout** [dev_mat, tensor_map, slice_shape]：默认值：None。
+        - **layout** (Union[None, tuple])：参数的layout信息。layout[dev_mat, tensor_map, slice_shape, filed_size, uniform_split, opt_shard_group]：默认值：None。仅在 `SEMI_AUTO_PARALLEL` 或 `AUTO_PARALLEL` 模式下layout不是None。
 
-                - **dev_mat** (list(int))：设备矩阵。
-                - **tensor_map** (list(int))：张量映射。
-                - **slice_shape** (list(int))：切片形状。
+            - **dev_mat** (list(int))：该参数的设备矩阵。
+            - **tensor_map** (list(int))：该参数的张量映射。
+            - **slice_shape** (list(int))：该参数的切片shape。
+            - **filed_size** (int)：该权重的行数。
+            - **uniform_split** (bool)：该参数是否进行均匀切分。
+            - **opt_shard_group** (str)：该参数进行优化器切分时的group。
 
-            - **set_sliced** (bool)：参数初始化时被设定为分片，则为True。默认值：False。
+        - **set_sliced** (bool)：参数初始化时被设定为分片，则为True。默认值：False。
 
         **异常：**
 
-            **RuntimeError：** 参数使用 `Initializer` 模块进行初始化，初始化后并行模式发生更改。
+        - **RuntimeError：** 参数使用 `Initializer` 模块进行初始化，初始化后并行模式发生更改。
+
+        - **ValueError：** `layout` 长度小于6。
 
-            **ValueError：** `layout` 长度小于3。
-            
-            **TypeError：** `layout` 不是元组。
+        - **TypeError：** `layout` 不是元组。
 
         **返回：**
 
-            初始化数据后的 `Parameter` 。如果当前 `Parameter` 已初始化，则更新 `Parameter` 数据。
+        初始化数据后的 `Parameter` 。如果当前 `Parameter` 已初始化，则更新 `Parameter` 数据。
         
 
     .. py:method:: is_init
@@ -124,7 +122,9 @@
     .. py:method:: layerwise_parallel
         :property:
 
-        在"data_parallel"或"hybrid_parallel"并行模式下，如果"layerwise_parallel"为True，参数广播和梯度聚合将不会应用到参数。
+        获取此参数的逐层并行状态（bool）。
+
+        在 `DATA_PARALLEL` 和 `HYBRID_PARALLEL` 模式下，如果 `layerwise_parallel` 为True，则广播和gradients通信将不会应用到参数。
         
 
     .. py:method:: name
@@ -135,21 +135,21 @@
     .. py:method:: parallel_optimizer
         :property:
 
-        用于在"semi_auto_parallel"或"auto_parallel"并行模式下区分参数是否进行优化器切分。仅在 `mindspore.context.set_auto_parallel_context()` 并行配置模块中设置 `enable_parallel_optimizer` 启用优化器并行时有效。默认值：True。
+        获取此参数的优化器并行状态（bool）。
+
+        用于在 `AUTO_PARALLEL` 和 `SEMI_AUTO_PARALLEL` 模式下过滤权重切分操作。当在 `mindspore.context.set_auto_parallel_context()` 中启用优化器并行时，它才有效。
         
 
     .. py:method:: parallel_optimizer_comm_recompute
         :property:
 
-        在优化器并行场景下，是否重新计算与此参数对应的通信算子。
+        获取此参数的优化器并行通信重计算状态（bool）。
 
-        在"auto_parallel"和"semi_auto_parallel"模式下使用优化器并行时，若参数被切分分布在不同卡上，框架会自动插入 :class:`mindspore.ops.AllGather` 通信算子用于参数汇聚。该接口用于控制 :class:`mindspore.ops.AllGather` 算子的二次计算属性。
+        在 `AUTO_PARALLEL` 和 `SEMI_AUTO_PARALLEL` 模式下，当使用并行优化器时，会自动插入一些 :class:`mindspore.ops.AllGather` 算子，用于参数聚合。它用于控制这些 :class:`mindspore.ops.AllGather` 算子的重计算属性。
 
         .. note::
-
-            仅支持Ascend下的Graph模式。
-
-            优化器并行场景下生成的 :class:`mindspore.ops.AllGather` 算子，建议使用 `cell.recompute(parallel_optimizer_comm_recompute=True/False)` 接口配置，不推荐直接使用本接口。
+            - 仅支持 `Graph` 模式。
+            - 建议使用(cell.recompute(parallel_optimizer_comm_recompute=True/False)去配置由优化器并行生成的 :class:`mindspore.ops.AllGather` 算子，而不是直接使用该接口。
         
 
     .. py:method:: requires_grad
@@ -163,42 +163,40 @@
 
         **参数：**
 
-            - **data** (Union[Tensor, int, float])：新数据。
-            - **slice_shape** (bool)：如果`slice_shape`设为True，则不检查 `data` 和当前参数shape的一致性。默认值：False。
+        - **data** (Union[Tensor, int, float])：新数据。
+        - **slice_shape** (bool)：如果 `slice_shape` 设为True，则不检查 `data` 和当前参数shape的一致性。默认值：False。
 
         **返回：**
     
-            完成数据设置的新参数。
+        完成数据设置的新参数。
         
 
     .. py:method:: set_param_fl(push_to_server=False, pull_from_server=False, requires_aggr=True)
 
-        设置参数和服务器的交互方式。
+        设置参数和服务器的互动方式。
 
         **参数：**
 
-            - **push_to_server** (bool)：表示是否将参数推送到服务器。默认值：False。
-            - **pull_from_server** (bool)：表示是否应从服务器中拉取参数。默认值：False。
-            - **requires_aggr** (bool)：表示是否应在服务器中聚合参数。默认值：True。
+        - **push_to_server** (bool)：表示是否将参数推送到服务器。默认值：False。
+        - **pull_from_server** (bool)：表示是否应从服务器中拉取参数。默认值：False。
+        - **requires_aggr** (bool)：表示是否应在服务器中聚合参数。默认值：True。
         
 
     .. py:method:: set_param_ps(init_in_server=False)
 
-        在Parameter Server模式下，表示训练参数是否在Server端初始化，以及是否由Server更新。
+        表示可训练参数是否由参数服务器更新，以及可训练参数是否在服务器上初始化。
 
-        .. note:: 仅在Parameter Server模式下有效。
+        .. note:: 仅当运行的任务处于参数服务器模式下有效。
 
         **参数：**
 
-            - **init_in_server** (bool)：表示训练参数初始化位置是否为Server端，以及是否通过Server进行更新。默认值：False。
-        
+        **init_in_server** (bool)：表示参数服务器更新的可训练参数是否在服务器上初始化。默认值：False。
 
     .. py:method:: sliced
         :property:
 
         获取参数的切片状态。
 
-
     .. py:method:: unique
         :property:
         

docs/api/api_python/mindspore/mindspore.build_searched_strategy.rst

@@ -0,0 +1,20 @@
+mindspore.build_searched_strategy
+==================================
+
+.. py:method:: mindspore.build_searched_strategy(strategy_filename)
+
+    构建网络中每个参数的策略，用于分布式推理。关于它的使用细节，请参考：`保存和加载模型（HyBrid Parallel模式） <https://www.mindspore.cn/docs/programming_guide/zh-CN/master/save_load_model_hybrid_parallel.html>`_。
+
+    **参数：**
+
+    **strategy_filename** (str)：策略文件的名称。
+
+    **返回：**
+
+    Dict，key为参数名，value为该参数的切片策略。
+
+    **异常：**
+
+    - **ValueError：** 策略文件不正确。
+    - **TypeError：** `strategy_filename` 不是str。
+    

docs/api/api_python/mindspore/mindspore.merge_sliced_parameter.rst

@@ -0,0 +1,40 @@
+mindspore.merge_sliced_parameter
+=================================
+
+.. py:method:: mindspore.merge_sliced_parameter(sliced_parameters, strategy=None)
+
+    将参数切片合并为一个完整的参数，用于分布式推理。关于它的细节，请参考：`保存和加载模型（HyBrid Parallel模式） <https://www.mindspore.cn/docs/programming_guide/zh-CN/master/save_load_model_hybrid_parallel.html>`_。
+
+    **参数：**
+
+    - **sliced_parameters** (list[Parameter])：参数切片，按rank id进行排列。
+    - **strategy** (Optional[dict])：参数切片策略，key为参数名称，value为该参数的切片策略。如果strategy为None，则只需按0轴顺序合并参数切片。默认值：None。
+
+    **返回：**
+
+    合并后的参数，包含所有数据。
+
+    **异常：**
+
+    - **ValueError：** 合并失败。
+    - **TypeError：** `sliced_parameters` 不正确或strategy不是dict。
+    - **KeyError：** 参数名称不在策略的key中。
+
+    **样例：**
+
+    >>> import numpy as np
+    >>> from mindspore import Tensor, merge_sliced_parameter, Parameter
+    >>>
+    >>> sliced_parameters = [
+    ...                      Parameter(Tensor(np.array([0.00023915, 0.00013939, -0.00098059])),
+    ...                                "network.embedding_table"),
+    ...                      Parameter(Tensor(np.array([0.00015815, 0.00015458, -0.00012125])),
+    ...                                "network.embedding_table"),
+    ...                      Parameter(Tensor(np.array([0.00042165, 0.00029692, -0.00007941])),
+    ...                                "network.embedding_table"),
+    ...                      Parameter(Tensor(np.array([0.00084451, 0.00089960, -0.00010431])),
+    ...                                "network.embedding_table")]
+    >>> merged_parameter = merge_sliced_parameter(sliced_parameters)
+    >>> print(merged_parameter)
+    Parameter (name=network.embedding_table, shape=(12,), dtype=Float64, requires_grad=True)
+    

docs/api/api_python/mindspore/mindspore.model.rst

@@ -0,0 +1,77 @@
+mindspore.Model
+================
+
+   .. py:method:: infer_predict_layout(*predict_data)
+
+      在 `AUTO_PARALLEL` 或 `SEMI_AUTO_PARALLEL` 模式下为预测网络生成参数layout，数据可以是单个或多个张量。
+
+      .. note:: 同一批次数据应放在一个张量中。
+
+      **参数** ：
+
+      **predict_data** (`Tensor`) – 单个或多个张量的预测数据。
+
+      **返回** ：
+
+      Dict，用于加载分布式checkpoint的参数layout字典。它总是作为 `load_distributed_checkpoint()` 函数的一个入参。
+
+      **异常** :
+
+      **RuntimeError** – 如果不是图模式（GRAPH_MODE）。
+
+      **样例：**
+
+      >>> # 该例子需要在多设备上运行。请参考mindpore.cn上的教程 > 分布式训练。
+      >>> import numpy as np
+      >>> import mindspore as ms
+      >>> from mindspore import Model, context, Tensor
+      >>> from mindspore.context import ParallelMode
+      >>> from mindspore.communication import init
+      >>> 
+      >>> context.set_context(mode=context.GRAPH_MODE)
+      >>> init()
+      >>> context.set_auto_parallel_context(full_batch=True, parallel_mode=ParallelMode.SEMI_AUTO_PARALLEL)
+      >>> input_data = Tensor(np.random.randint(0, 255, [1, 1, 32, 32]), ms.float32)
+      >>> model = Model(Net())
+      >>> model.infer_predict_layout(input_data)
+
+   .. py:method:: infer_train_layout(train_dataset, dataset_sink_mode=True, sink_size=-1)
+
+      在 `AUTO_PARALLEL` 或 `SEMI_AUTO_PARALLEL` 模式下为训练网络生成参数layout，当前只有数据下沉模式可支持使用。
+
+      .. warning:: 这是一个实验性的原型，可能会被改变和/或删除。
+
+      .. note:: 这是一个预编译函数。参数必须与model.train()函数相同。
+
+      **参数** ：
+
+      - **train_dataset** (`Dataset`) – 一个训练数据集迭代器。如果没有损失函数（loss_fn），返回一个包含多个数据的元组（data1, data2, data3, ...）并传递给网络。否则，返回一个元组（data, label），数据和标签将被分别传递给网络和损失函数。
+      - **dataset_sink_mode** (`bool`) – 决定是否以数据集下沉模式进行训练。默认值：True。配置项是PyNative模式或CPU时，训练模型流程使用的是数据不下沉（non-sink）模式。默认值：True。
+      - **sink_size** (`int`) – 控制每次数据下沉的数据量，如果 `sink_size` =-1，则每一次epoch下沉完整数据集。如果 `sink_size` >0，则每一次epoch下沉数据量为 `sink_size` 的数据集。如果 `dataset_sink_mode` 为False，则设置 `sink_size` 为无效。默认值：-1。
+
+
+      **返回** ：
+
+      Dict，用于加载分布式checkpoint的参数layout字典。
+
+      **样例：**
+
+      >>> # 该例子需要在多设备上运行。请参考mindpore.cn上的教程 > 分布式训练。
+      >>> import numpy as np
+      >>> import mindspore as ms
+      >>> from mindspore import Model, context, Tensor, nn, FixedLossScaleManager
+      >>> from mindspore.context import ParallelMode
+      >>> from mindspore.communication import init
+      >>> 
+      >>> context.set_context(mode=context.GRAPH_MODE)
+      >>> init()
+      >>> context.set_auto_parallel_context(parallel_mode=ParallelMode.SEMI_AUTO_PARALLEL)
+      >>> 
+      >>> # 如何构建数据集，请参考官方网站上关于【数据集】的章节。
+      >>> dataset = create_custom_dataset()
+      >>> net = Net()
+      >>> loss = nn.SoftmaxCrossEntropyWithLogits()
+      >>> loss_scale_manager = FixedLossScaleManager()
+      >>> optim = nn.Momentum(params=net.trainable_params(), learning_rate=0.1, momentum=0.9)
+      >>> model = Model(net, loss_fn=loss, optimizer=optim, metrics=None, loss_scale_manager=loss_scale_manager)
+      >>> layout_dict = model.infer_train_layout(dataset)