Skip to content

Commit

Permalink
fix api docs stype (PaddlePaddle#4426)
Browse files Browse the repository at this point in the history
* fix api docs stype

* Update DataParallel_cn.rst

* Update Model_cn.rst

* Update add_n_cn.rst

* Update addmm_cn.rst

* Update GradScaler_cn.rst

* Update auto_cast_cn.rst

* Update decorate_cn.rst

* Update asin_cn.rst

* Update atan_cn.rst

* Update PyLayerContext_cn.rst

* Update PyLayer_cn.rst

* Update bincount_cn.rst

* Update cast_cn.rst

* Update ceil_cn.rst

* Update Event_cn.rst

* Update Model_cn.rst

* Update GradScaler_cn.rst

* Update zeros_cn.rst

* Update DataParallel_cn.rst

* Update where_cn.rst

* Update Tensor_cn.rst

* Update cudnn_cn.rst

* Update show_cn.rst

* Update PyLayerContext_cn.rst

* Update cuda_cn.rst

* Update PyLayer_cn.rst

* Update uniform_cn.rst

* Update transpose_cn.rst

* Update Callback_cn.rst

* Update trace_cn.rst

* Update clip_cn.rst

* Update tolist_cn.rst

* Update Event_cn.rst

* Update Stream_cn.rst

* Update current_stream_cn.rst

* Update synchronize_cn.rst

* Update is_compiled_with_cuda_cn.rst

* Update is_compiled_with_npu_cn.rst

* Update is_compiled_with_rocm_cn.rst

* Update is_compiled_with_xpu_cn.rst

* Update set_device_cn.rst

* Update diff_cn.rst

* Update dist_cn.rst

* Update Fleet_cn.rst

* Update UtilBase_cn.rst

* Update Categorical_cn.rst

* Update empty_cn.rst

* Update empty_like_cn.rst

* Update equal_all_cn.rst

* Update equal_cn.rst

* Update erf_cn.rst

* Update erf_cn.rst

* Update exp_cn.rst

* Update eye_cn.rst

* Update flatten_cn.rst

* Update floor_cn.rst

* Update full_cn.rst

* Update full_like_cn.rst

* Update gather_cn.rst

* update docs

* update docs

* update docs

* update docs

* update docs

* Update Categorical_cn.rst

* Update Normal_cn.rst

* Update Uniform_cn.rst

* Update gather_nd_cn.rst

* Update get_cuda_rng_state_cn.rst

* Update get_default_dtype_cn.rst

* Update get_flags_cn.rst

* Update grad_cn.rst

* Update grad_cn.rst

* Update greater_equal_cn.rst

* Update histogram_cn.rst

* Update in_dynamic_mode_cn.rst

* Update increment_cn.rst

* Update LookAhead_cn.rst

* Update LookAhead_cn.rst

* Update ModelAverage_cn.rst

* update jit docs

* update jit docs_2

* update linalg docs

* update metric docs

* Update AdamW_cn.rst

* update onnx&optimizer docs

* update profiler&regularizer docs

* update signal docs

* update static docs

* update text&utils&version docs

* update vision docs

* update vision docs

* update nn.* docs

* update nn.functional docs

* Update AdamW_cn.rst

* Update AdamW_cn.rst

* Update conv2d_transpose_cn.rst

* Update Categorical_cn.rst

* Update Adagrad_cn.rst

* Update cov_cn.rst

* Update eigh_cn.rst

* update linalg docs

* update docs

* Update AdamW_cn.rst

* Update Adadelta_cn.rst

* Update RMSProp_cn.rst

Co-authored-by: Ligoml <[email protected]>
Co-authored-by: Ligoml <[email protected]>
  • Loading branch information
3 people authored Mar 31, 2022
1 parent 95dab8f commit 5830039
Show file tree
Hide file tree
Showing 876 changed files with 10,198 additions and 5,403 deletions.
3 changes: 2 additions & 1 deletion docs/api/paddle/CPUPlace_cn.rst
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@ CPUPlace
``CPUPlace`` 是一个设备描述符,指定 ``CPUPlace`` 则 ``Tensor`` 将被自动分配在该设备上,并且模型将会运行在该设备上。

**代码示例**
代码示例
::::::::::::

.. code-block:: python
Expand Down
3 changes: 2 additions & 1 deletion docs/api/paddle/CUDAPinnedPlace_cn.rst
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,8 @@ CUDAPinnedPlace
``CUDAPinnedPlace`` 是一个设备描述符,它所指代的页锁定内存由 CUDA 函数 ``cudaHostAlloc()`` 在主机内存上分配,主机的操作系统将不会对这块内存进行分页和交换操作,可以通过直接内存访问技术访问,加速主机和 GPU 之间的数据拷贝。
有关 CUDA 的数据转移和 ``pinned memory``,参见 `官方文档 <https://docs.nvidia.com/cuda/cuda-c-best-practices-guide/index.html#pinned-memory>`_ 。

**代码示例**
代码示例
::::::::::::

.. code-block:: python
Expand Down
7 changes: 5 additions & 2 deletions docs/api/paddle/CUDAPlace_cn.rst
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,13 @@ CUDAPlace
可以通过 ``CUDA_VISIBLE_DEVICES`` 环境变量限制程序能够使用的 GPU 设备,程序启动时会遍历当前的可见设备,并从 0 开始为这些设备编号。
如果没有设置 ``CUDA_VISIBLE_DEVICES``,则默认所有的设备都是可见的,此时逻辑编号与实际编号是相同的。

参数:
参数
::::::::::::

- **id** (int,可选) - GPU的设备ID。如果为 ``None``,则默认会使用 id 为 0 的设备。默认值为 ``None``。

**代码示例**
代码示例
::::::::::::

.. code-block:: python
Expand Down
43 changes: 29 additions & 14 deletions docs/api/paddle/DataParallel_cn.rst
Original file line number Diff line number Diff line change
Expand Up @@ -22,58 +22,73 @@ DataParallel

其中 ``demo.py`` 脚本的代码可以是下面的示例代码。

参数:
参数
::::::::::::

- **Layer** (Layer) - 需要通过数据并行方式执行的模型。
- **strategy** (ParallelStrategy,可选) - (deprecated) 数据并行的策略,包括并行执行的环境配置。默认为None。
- **comm_buffer_size** (int,可选) - 它是通信调用(如NCCLAllReduce)时,参数梯度聚合为一组的内存大小(MB)。默认值:25。
- **last_comm_buffer_size** (float,可选)它限制通信调用中最后一个缓冲区的内存大小(MB)。减小最后一个通信缓冲区的大小有助于提高性能。默认值:1。默认值:1
- **find_unused_parameters** (bool, 可选) 是否在模型forward函数的返回值的所有张量中,遍历整个向后图。对于不包括在loss计算中的参数,其梯度将被预先标记为ready状态用于后续多卡间的规约操作。请注意,模型参数的所有正向输出必须参与loss的计算以及后续的梯度计算。 否则,将发生严重错误。请注意,将find_unused_parameters设置为True会影响计算性能, 因此,如果确定所有参数都参与了loss计算和自动反向图的构建,请将其设置为False。默认值:False。

返回:支持数据并行的 ``Layer``

返回类型:Layer实例
返回
::::::::::::
支持数据并行的 ``Layer``。

**代码示例**:
代码示例
::::::::::::
COPY-FROM: paddle.DataParallel:dp-example

.. Note::
目前数据并行不支持PyLayer自定义算子。如有此类需求,推荐先使用no_sync接口暂停多卡通信,然后在优化器前手动实现梯度同步;具体实现过程可参考下述示例。

**代码示例**:
代码示例
::::::::::::
COPY-FROM: paddle.DataParallel:dp-pylayer-example

.. py:function:: no_sync()
用于暂停梯度同步的上下文管理器。在no_sync()中参数梯度只会在模型上累加;直到with之外的第一个forward-backward,梯度才会被同步。

**代码示例**
代码示例
::::::::::::

COPY-FROM: paddle.DataParallel.no_sync

.. py:method:: state_dict(destination=None, include_sublayers=True)
方法
::::::::::::
state_dict(destination=None, include_sublayers=True)
'''''''''

获取当前层及其子层的所有parameters和持久的buffers。并将所有parameters和buffers存放在dict结构中。

参数:
**参数**

- **destination** (dict, 可选) - 如果提供 ``destination`` ,则所有参数和持久的buffers都将存放在 ``destination`` 中。 默认值:None。
- **include_sublayers** (bool, 可选) - 如果设置为True,则包括子层的参数和buffers。默认值:True。

返回:dict, 包含所有parameters和持久的buffers的dict
**返回**
dict, 包含所有parameters和持久的buffers的dict。

**代码示例**

COPY-FROM: paddle.DataParallel.state_dict


.. py:method:: set_state_dict(state_dict, use_structured_name=True)
set_state_dict(state_dict, use_structured_name=True)
'''''''''

根据传入的 ``state_dict`` 设置parameters和持久的buffers。 所有parameters和buffers将由 ``state_dict`` 中的 ``Tensor`` 设置。

参数:
**参数**

- **state_dict** (dict) - 包含所有parameters和可持久性buffers的dict。
- **use_structured_name** (bool, 可选) - 如果设置为True,将使用Layer的结构性变量名作为dict的key,否则将使用Parameter或者Buffer的变量名作为key。默认值:True。

返回:无

**返回**

**代码示例**

COPY-FROM: paddle.DataParallel.set_state_dict
COPY-FROM: paddle.DataParallel.set_state_dict
98 changes: 66 additions & 32 deletions docs/api/paddle/Model_cn.rst
Original file line number Diff line number Diff line change
Expand Up @@ -99,14 +99,18 @@ train_batch(inputs, labels=None)

在一个批次的数据上进行训练。

参数:
**参数**

- **inputs** (list) - 1维列表,每个元素都是一批次的输入数据,数据类型为 ``numpy.ndarray``。
- **labels** (list) - 1维列表,每个元素都是一批次的输入标签,数据类型为 ``numpy.ndarray`` 。默认值:None。

返回:如果没有定义评估函数,则返回包含了训练损失函数的值的列表;如果定义了评估函数,则返回一个元组(损失函数的列表,评估指标的列表)。
**返回**

如果没有定义评估函数,则返回包含了训练损失函数的值的列表;如果定义了评估函数,则返回一个元组(损失函数的列表,评估指标的列表)。


**代码示例**:
**代码示例**


.. code-block:: python
Expand Down Expand Up @@ -138,15 +142,18 @@ eval_batch(inputs, labels=None)

在一个批次的数据上进行评估。

参数:
**参数**


- **inputs** (list) - 1维列表,每个元素都是一批次的输入数据,数据类型为 ``numpy.ndarray`` 。
- **labels** (list) - 1维列表,每个元素都是一批次的输入标签,数据类型为 ``numpy.ndarray`` 。默认值:None。

返回:如果没有定义评估函数,则返回包含了预测损失函数的值的列表;如果定义了评估函数,则返回一个元组(损失函数的列表,评估指标的列表)。
**返回**

list,如果没有定义评估函数,则返回包含了预测损失函数的值的列表;如果定义了评估函数,则返回一个元组(损失函数的列表,评估指标的列表)。

返回类型:list

**代码示例**
**代码示例**

.. code-block:: python
Expand Down Expand Up @@ -179,14 +186,17 @@ predict_batch(inputs)

在一个批次的数据上进行测试。

参数:
**参数**


- **inputs** (list) - 1维列表,每个元素都是一批次的输入数据,数据类型为 ``numpy.ndarray`` 。

返回:一个列表,包含了模型的输出。
**返回**

一个列表,包含了模型的输出。

返回类型:list
**代码示例**

**代码示例**:

.. code-block:: python
Expand Down Expand Up @@ -219,13 +229,17 @@ save(path, training=True)
将模型的参数和训练过程中优化器的信息保存到指定的路径,以及推理所需的参数与文件。如果training=True,所有的模型参数都会保存到一个后缀为 ``.pdparams`` 的文件中。
所有的优化器信息和相关参数,比如 ``Adam`` 优化器中的 ``beta1`` , ``beta2`` ,``momentum`` 等,都会被保存到后缀为 ``.pdopt``。如果优化器比如SGD没有参数,则该不会产生该文件。如果training=False,则不会保存上述说的文件。只会保存推理需要的参数文件和模型文件。

参数:
**参数**


- **path** (str) - 保存的文件名前缀。格式如 ``dirname/file_prefix`` 或者 ``file_prefix`` 。
- **training** (bool,可选) - 是否保存训练的状态,包括模型参数和优化器参数等。如果为False,则只保存推理所需的参数与文件。默认值:True。

返回:None
**返回**

None

**代码示例**
**代码示例**

.. code-block:: python
Expand Down Expand Up @@ -275,14 +289,19 @@ load(path, skip_mismatch=False, reset_optimizer=False)

从指定的文件中载入模型参数和优化器参数,如果不想恢复优化器参数信息,优化器信息文件可以不存在。需要注意的是:参数名称的检索是根据保存模型时结构化的名字,当想要载入参数进行迁移学习时要保证预训练模型和当前的模型的参数有一样结构化的名字。

参数:
**参数**


- **path** (str) - 保存参数或优化器信息的文件前缀。格式如 ``path.pdparams`` 或者 ``path.pdopt`` ,后者是非必要的,如果不想恢复优化器信息。
- **skip_mismatch** (bool) - 是否需要跳过保存的模型文件中形状或名称不匹配的参数,设置为 ``False`` 时,当遇到不匹配的参数会抛出一个错误。默认值:False。
- **reset_optimizer** (bool) - 设置为 ``True`` 时,会忽略提供的优化器信息文件。否则会载入提供的优化器信息。默认值:False。

返回:None
**返回**

None

**代码示例**

**代码示例**:

.. code-block:: python
Expand All @@ -309,9 +328,11 @@ parameters(*args, **kwargs)
返回一个包含模型所有参数的列表。

返回:在静态图中返回一个包含 ``Parameter`` 的列表,在动态图中返回一个包含 ``ParamBase`` 的列表。
**返回**

在静态图中返回一个包含 ``Parameter`` 的列表,在动态图中返回一个包含 ``ParamBase`` 的列表。

**代码示例**
**代码示例**

.. code-block:: python
Expand All @@ -332,7 +353,8 @@ prepare(optimizer=None, loss=None, metrics=None, amp_configs=None)

配置模型所需的部件,比如优化器、损失函数和评价指标。

参数:
**参数**

- **optimizer** (Optimizer) - 当训练模型的,该参数必须被设定。当评估或测试的时候,该参数可以不设定。默认值:None。
- **loss** (Loss) - 当训练模型的,该参数必须被设定。默认值:None。
- **metrics** (Metric|list[Metric]) - 当该参数被设定时,所有给定的评估方法会在训练和测试时被运行,并返回对应的指标。默认值:None。
Expand All @@ -344,7 +366,8 @@ fit(train_data=None, eval_data=None, batch_size=1, epochs=1, eval_freq=1, log_fr

训练模型。当 ``eval_data`` 给定时,会在 ``eval_freq`` 个 ``epoch`` 后进行一次评估。

参数:
**参数**

- **train_data** (Dataset|DataLoader) - 一个可迭代的数据源,推荐给定一个 ``paddle paddle.io.Dataset`` 或 ``paddle.io.Dataloader`` 的实例。默认值:None。
- **eval_data** (Dataset|DataLoader) - 一个可迭代的数据源,推荐给定一个 ``paddle paddle.io.Dataset`` 或 ``paddle.io.Dataloader`` 的实例。当给定时,会在每个 ``epoch`` 后都会进行评估。默认值:None。
- **batch_size** (int) - 训练数据或评估数据的批大小,当 ``train_data`` 或 ``eval_data`` 为 ``DataLoader`` 的实例时,该参数会被忽略。默认值:1。
Expand All @@ -359,9 +382,11 @@ fit(train_data=None, eval_data=None, batch_size=1, epochs=1, eval_freq=1, log_fr
- **num_workers** (int) - 启动子进程用于读取数据的数量。当 ``train_data`` 和 ``eval_data`` 都为 ``DataLoader`` 的实例时,该参数会被忽略。默认值:0。
- **callbacks** (Callback|list[Callback]|None) - ``Callback`` 的一个实例或实例列表。该参数不给定时,默认会插入 ``ProgBarLogger`` 和 ``ModelCheckpoint`` 这两个实例。默认值:None。

返回:None
**返回**

None

**代码示例**
**代码示例**

1. 使用Dataset训练,并设置batch_size的例子。

Expand Down Expand Up @@ -447,17 +472,20 @@ evaluate(eval_data, batch_size=1, log_freq=10, verbose=2, num_workers=0, callbac

在输入数据上,评估模型的损失函数值和评估指标。

参数:
**参数**

- **eval_data** (Dataset|DataLoader) - 一个可迭代的数据源,推荐给定一个 ``paddle paddle.io.Dataset`` 或 ``paddle.io.Dataloader`` 的实例。默认值:None。
- **batch_size** (int) - 训练数据或评估数据的批大小,当 ``eval_data`` 为 ``DataLoader`` 的实例时,该参数会被忽略。默认值:1。
- **log_freq** (int) - 日志打印的频率,多少个 ``step`` 打印一次日志。默认值:1。
- **verbose** (int) - 可视化的模型,必须为0,1,2。当设定为0时,不打印日志,设定为1时,使用进度条的方式打印日志,设定为2时,一行一行地打印日志。默认值:2。
- **num_workers** (int) - 启动子进程用于读取数据的数量。当 ``eval_data`` 为 ``DataLoader`` 的实例时,该参数会被忽略。默认值:True。
- **callbacks** (Callback|list[Callback]|None) - ``Callback`` 的一个实例或实例列表。该参数不给定时,默认会插入 ``ProgBarLogger`` 和 ``ModelCheckpoint`` 这两个实例。默认值:None。

返回:dict, key是 ``prepare`` 时Metric的的名称,value是该Metric的值。
**返回**

dict, key是 ``prepare`` 时Metric的的名称,value是该Metric的值。

**代码示例**
**代码示例**

.. code-block:: python
Expand All @@ -484,16 +512,19 @@ predict(test_data, batch_size=1, num_workers=0, stack_outputs=False, callbacks=N

在输入数据上,预测模型的输出。

参数:
**参数**

- **test_data** (Dataset|DataLoader) - 一个可迭代的数据源,推荐给定一个 ``paddle paddle.io.Dataset`` 或 ``paddle.io.Dataloader`` 的实例。默认值:None。
- **batch_size** (int) - 训练数据或评估数据的批大小,当 ``eval_data`` 为 ``DataLoader`` 的实例时,该参数会被忽略。默认值:1。
- **num_workers** (int) - 启动子进程用于读取数据的数量。当 ``eval_data`` 为 ``DataLoader`` 的实例时,该参数会被忽略。默认值:True。
- **stack_outputs** (bool) - 是否将输出进行堆叠。默认值:False。
- **callbacks** (Callback|list[Callback]|None) - ``Callback`` 的一个实例或实例列表。默认值:None。

返回:模型的输出。
**返回**

**代码示例**:
模型的输出。

**代码示例**

.. code-block:: python
Expand Down Expand Up @@ -539,14 +570,17 @@ summary(input_size=None, batch_size=None, dtype=None)

打印网络的基础结构和参数信息。

参数:
**参数**

- **input_size** (tuple|InputSpec|list[tuple|InputSpec,可选) - 输入张量的大小。如果网络只有一个输入,那么该值需要设定为tuple或InputSpec。如果模型有多个输入。那么该值需要设定为list[tuple|InputSpec],包含每个输入的shape。如果该值没有设置,会将 ``self._inputs`` 作为输入。默认值:None。
- **batch_size** (int,可选) - 输入张量的批大小。默认值:None。
- **dtypes** (str,可选) - 输入张量的数据类型,如果没有给定,默认使用 ``float32`` 类型。默认值:None。

返回:字典:包含网络全部参数的大小和全部可训练参数的大小。
**返回**

字典:包含网络全部参数的大小和全部可训练参数的大小。

**代码示例**
**代码示例**

.. code-block:: python
Expand Down
7 changes: 5 additions & 2 deletions docs/api/paddle/NPUPlace_cn.rst
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,12 @@ NPUPlace
``dev_id`` 不同的 ``NPUPlace`` 所对应的内存不可相互访问。
这里编号指的是显卡实际的编号,而不是显卡的逻辑编号。

参数:
参数
::::::::::::

- **id** (int,可选) - NPU的设备ID。

**代码示例**
代码示例
::::::::::::

COPY-FROM: paddle.NPUPlace
11 changes: 8 additions & 3 deletions docs/api/paddle/ParamAttr_cn.rst
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,9 @@ ParamAttr

创建一个参数属性对象,用户可设置参数的名称、初始化方式、学习率、正则化规则、是否需要训练、梯度裁剪方式、是否做模型平均等属性。

参数:
参数
::::::::::::

- **name** (str,可选) - 参数的名称。默认值为None,表示框架自动创建参数的名称。
- **initializer** (Initializer,可选) - 参数的初始化方式。默认值为None,表示权重参数采用Xavier初始化方式,偏置参数采用全0初始化方式。
- **learning_rate** (float,可选) - 参数的学习率。实际参数的学习率等于全局学习率乘以参数的学习率,再乘以learning rate schedule的系数。
Expand All @@ -25,10 +27,13 @@ ParamAttr
- **do_model_average** (bool,可选) - 是否做模型平均。默认值为True。仅在 :ref:`ExponentialMovingAverage` 下使用。
- **need_clip** (bool,可选) - 参数是否需要进行梯度裁剪。默认值为True,表示该参数的梯度会根据优化器中设置的裁剪规则进行裁剪。

返回: 表示参数属性的对象。
返回
::::::::::::
表示参数属性的对象。


**代码示例**
代码示例
::::::::::::

.. code-block:: python
Expand Down
Loading

0 comments on commit 5830039

Please sign in to comment.