mindspore-Ecosystem
/
mindspore
21
0
Fork 27
Code Issues Pull Requests 6 Projects Releases Wiki Activity

!27220 update api format 

Merge pull request !27220 from yingchen/code_docs_1204
This commit is contained in:
i-robot 2021-12-04 07:05:27 +00:00 committed by Gitee
parent 908e0f6b4c 9b800a3a36
commit fe0e61e6cd
54 changed files with 2055 additions and 1887 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/api/api_python/dataset/mindspore.dataset.CLUEDataset.rst
View File

@ -94,4 +94,6 @@ mindspore.dataset.CLUEDataset
howpublished = {https://github.com/CLUEbenchmark/CLUE}
}
.. include:: mindspore.dataset.Dataset.rst
.. include:: mindspore.dataset.Dataset.rst
.. include:: mindspore.dataset.Dataset.zip.rst

51
docs/api/api_python/dataset/mindspore.dataset.CSVDataset.rst
View File

@ -1,32 +1,39 @@
mindspore.dataset.CSVDataset
=============================
Class mindspore.dataset.CSVDataset(dataset_files, field_delim=',', column_defaults=None, column_names=None, num_samples=None, num_parallel_workers=None, shuffle=<Shuffle.GLOBAL: 'global'>, num_shards=None, shard_id=None, cache=None)
.. py:class:: mindspore.dataset.CSVDataset(dataset_files, field_delim=',', column_defaults=None, column_names=None, num_samples=None, num_parallel_workers=None, shuffle=<Shuffle.GLOBAL: 'global'>, num_shards=None, shard_id=None, cache=None)
读取和解析逗号分隔值（CSV）数据文件作为源数据集。
生成的数据集的列取决于源CSV文件。
读取和解析逗号分隔值（CSV）数据文件作为源数据集。生成的数据集的列取决于源CSV文件。
**参数：**
- **dataset_files** (Union[str, list[str]])：数据集文件路径，支持单文件路径字符串、多文件路径字符串列表或可被glob库模式匹配的字符串，文件列表将在内部进行字典排序。
- **field_delim** (str，可选)：指定用于分隔字段的分隔符（默认为','）。
- **column_defaults** (list，可选)：以列表形式指定每个CSV字段的数据类型（默认为None），有效的类型包括float、int或string。如果未指定该列表，则所有列的数据类型将被视为string。
- **column_names** (list[str]，可选)：指定数据集生成的列名（默认值为None）。如果未指定该列表，则将CSV文件第一行的字段作为列名生成。
- **num_samples** (int，可选)：指定从数据集中读取的样本数（默认为None，即读取所有样本）。
- **num_parallel_workers** (int，可选)：指定读取数据的工作线程数(默认值None，即使用mindspore.dataset.config中配置的线程数）。
- **shuffle** (Union[bool, Shuffle level], 可选)：每个epoch中数据混洗的模式（默认为为mindspore.dataset.Shuffle.GLOBAL）。
如果为False，则不混洗；如果为True，等同于将`shuffle`设置为mindspore.dataset.Shuffle.GLOBAL。另外也可以传入枚举变量设置shuffle级别：
- Shuffle.GLOBAL：混洗文件和样本。
- Shuffle.FILES：仅混洗文件。
- **num_shards** (int, 可选)：指定分布式训练时将数据集进行划分的分片数（默认值None）。指定此参数后, `num_samples` 表示每个分片的最大样本数。
- **shard_id** (int, 可选)：指定分布式训练时使用的分片ID号（默认值None）。只有当指定了 `num_shards` 时才能指定此参数。
- **cache** (DatasetCache, 可选)：数据缓存客户端实例，用于加快数据集处理速度（默认为None，不使用缓存）。
- **dataset_files** (Union[str, list[str]])：数据集文件路径，支持单文件路径字符串、多文件路径字符串列表或可被glob库模式匹配的字符串，文件列表将在内部进行字典排序。
- **field_delim** (str，可选)：指定用于分隔字段的分隔符（默认为','）。
- **column_defaults** (list，可选)：以列表形式指定每个CSV字段的数据类型（默认为None），有效的类型包括float、int或string。如果未指定该列表，则所有列的数据类型将被视为string。
- **column_names** (list[str]，可选)：指定数据集生成的列名（默认值为None）。如果未指定该列表，则将CSV文件第一行的字段作为列名生成。
- **num_samples** (int，可选)：指定从数据集中读取的样本数（默认为None，即读取所有样本）。
- **num_parallel_workers** (int，可选)：指定读取数据的工作线程数(默认值None，即使用mindspore.dataset.config中配置的线程数）。
- **shuffle** (Union[bool, Shuffle level], 可选)：每个epoch中数据混洗的模式（默认为为mindspore.dataset.Shuffle.GLOBAL）。如果为False，则不混洗；如果为True，等同于将 `shuffle` 设置为mindspore.dataset.Shuffle.GLOBAL。另外也可以传入枚举变量设置shuffle级别：
- Shuffle.GLOBAL：混洗文件和样本。
- Shuffle.FILES：仅混洗文件。
- **num_shards** (int, 可选)：指定分布式训练时将数据集进行划分的分片数（默认值None）。指定此参数后, `num_samples` 表示每个分片的最大样本数。
- **shard_id** (int, 可选)：指定分布式训练时使用的分片ID号（默认值None）。只有当指定了 `num_shards` 时才能指定此参数。
- **cache** (DatasetCache, 可选)：数据缓存客户端实例，用于加快数据集处理速度（默认为None，不使用缓存）。
**异常：**
- **RuntimeError**：参数`dataset_files` 所指的文件无效或不存在。
- **RuntimeError**：参数`num_parallel_workers` 超过系统最大线程数。
- **RuntimeError**：指定了`num_shards`参数，但是未指定`shard_id`参数。
- **RuntimeError**：指定了`shard_id`参数，但是未指定`num_shards`参数。
- **RuntimeError**：参数 `dataset_files` 所指的文件无效或不存在。
- **RuntimeError**：参数 `num_parallel_workers` 超过系统最大线程数。
- **RuntimeError**：指定了 `num_shards` 参数，但是未指定 `shard_id` 参数。
- **RuntimeError**：指定了 `shard_id` 参数，但是未指定 `num_shards` 参数。
**样例：**
>>> csv_dataset_dir = ["/path/to/csv_dataset_file"] # 此列表可以包含1个或多个CSV文件
>>> dataset = ds.CSVDataset(dataset_files=csv_dataset_dir, column_names=['col1', 'col2', 'col3', 'col4'])
>>> csv_dataset_dir = ["/path/to/csv_dataset_file"] # 此列表可以包含1个或多个CSV文件
>>> dataset = ds.CSVDataset(dataset_files=csv_dataset_dir, column_names=['col1', 'col2', 'col3', 'col4'])
.. include:: mindspore.dataset.Dataset.rst
.. include:: mindspore.dataset.Dataset.zip.rst

98
docs/api/api_python/dataset/mindspore.dataset.CelebADataset.rst
View File

@ -1,46 +1,44 @@
mindspore.dataset.CelebADataset
===============================
Class mindspore.dataset.CelebADataset(dataset_dir, num_parallel_workers=None, shuffle=None, usage='all', sampler=None, decode=False, extensions=None, num_samples=None, num_shards=None, shard_id=None, cache=None)
.. py:class:: mindspore.dataset.CelebADataset(dataset_dir, num_parallel_workers=None, shuffle=None, usage='all', sampler=None, decode=False, extensions=None, num_samples=None, num_shards=None, shard_id=None, cache=None)
用于读取和解析CelebA数据集的源数据文件。
目前仅支持读取解析标注文件`list_attr_celeba.txt`作为数据集的标注。
用于读取和解析CelebA数据集的源数据文件。目前仅支持读取解析标注文件 `list_attr_celeba.txt` 作为数据集的标注。
生成的数据集有两列：:py:obj:`[image, attr]`。
列:py:obj:`image` 的数据类型为uint8。
列:py:obj:`attr` 的数据类型为uint32，并以one-hot编码的形式生成。
生成的数据集有两列：`[image, attr]`。列: `image` 的数据类型为uint8。列: `attr` 的数据类型为uint32，并以one-hot编码的形式生成。
**参数：**
- **dataset_dir** (str)：包含数据集文件的根目录路径。
- **num_parallel_workers** (int，可选)：指定读取数据的工作线程数（默认值None，即使用mindspore.dataset.config中配置的线程数）。
- **shuffle** (bool，可选)：是否混洗数据集（默认为None，下表中会展示不同配置的预期行为）。
- **usage** (str，可选)：指定数据集的子集，可取值为'train'，'valid'，'test'或'all'。（默认值为'all'，即全部样本图片）。
- **sampler** (Sampler，可选)：指定从数据集中选取样本的采样器（默认为None，下表中会展示不同配置的预期行为）。
- **decode** (bool，可选)：是否对读取的图像进行解码操作（默认为False）。
- **extensions** (list[str]，可选)：指定文件扩展后缀，仅读取这些后缀的文件到数据集中（默认为None）。
- **num_samples** (int，可选)：指定从数据集中读取的样本数（可以小于数据集总数，默认值为None，即全部样本图片)。
- **num_shards** (int, 可选)：指定分布式训练时将数据集进行划分的分片数（默认值None）。指定此参数后, `num_samples` 表示每个分片的最大样本数。
- **shard_id** (int, 可选)：指定分布式训练时使用的分片ID号（默认值None）。只有当指定了 `num_shards` 时才能指定此参数。
- **cache** (DatasetCache, 可选)：数据缓存客户端实例，用于加快数据集处理速度（默认为None，不使用缓存）。
- **dataset_dir** (str)：包含数据集文件的根目录路径。
- **num_parallel_workers** (int，可选)：指定读取数据的工作线程数（默认值None，即使用mindspore.dataset.config中配置的线程数）。
- **shuffle** (bool，可选)：是否混洗数据集（默认为None，下表中会展示不同配置的预期行为）。
- **usage** (str，可选)：指定数据集的子集，可取值为'train'，'valid'，'test'或'all'。（默认值为'all'，即全部样本图片）。
- **sampler** (Sampler，可选)：指定从数据集中选取样本的采样器（默认为None，下表中会展示不同配置的预期行为）。
- **decode** (bool，可选)：是否对读取的图像进行解码操作（默认为False）。
- **extensions** (list[str]，可选)：指定文件扩展后缀，仅读取这些后缀的文件到数据集中（默认为None）。
- **num_samples** (int，可选)：指定从数据集中读取的样本数（可以小于数据集总数，默认值为None，即全部样本图片)。
- **num_shards** (int, 可选)：指定分布式训练时将数据集进行划分的分片数（默认值None）。指定此参数后, `num_samples` 表示每个分片的最大样本数。
- **shard_id** (int, 可选)：指定分布式训练时使用的分片ID号（默认值None）。只有当指定了 `num_shards` 时才能指定此参数。
- **cache** (DatasetCache, 可选)：数据缓存客户端实例，用于加快数据集处理速度（默认为None，不使用缓存）。
**异常：**
- **RuntimeError**：参数`dataset_dir`不包含任何数据文件。
- **RuntimeError**：参数`num_parallel_workers`超过系统最大线程数。
- **RuntimeError**: 同时指定了`sampler`和`shuffle`。
- **RuntimeError**: 同时指定了`sampler`和`num_shards`。
- **RuntimeError**: 指定了`num_shards`参数，但是未指定`shard_id`参数。
- **RuntimeError**: 指定了`shard_id`参数，但是未指定`num_shards`参数。
- **ValueError**: `shard_id`参数错误（小于0或者大于等于 `num_shards`）。
**注：**
- 此数据集可以指定`sampler`参数，但`sampler` 和 `shuffle` 是互斥的。下表展示了几种合法的输入参数及预期的行为。
- **RuntimeError**：参数 `dataset_dir` 不包含任何数据文件。
- **RuntimeError**：参数 `num_parallel_workers` 超过系统最大线程数。
- **RuntimeError**: 同时指定了 `sampler` 和 `shuffle` 。
- **RuntimeError**: 同时指定了 `sampler` 和 `num_shards` 。
- **RuntimeError**: 指定了 `num_shards` 参数，但是未指定 `shard_id` 参数。
- **RuntimeError**: 指定了 `shard_id` 参数，但是未指定 `num_shards` 参数。
- **ValueError**: `shard_id` 参数错误（小于0或者大于等于 `num_shards` ）。
.. list-table:: 配置`sampler`和`shuffle`的不同组合得到的预期排序结果
.. note:: 此数据集可以指定 `sampler` 参数，但 `sampler` 和 `shuffle` 是互斥的。下表展示了几种合法的输入参数及预期的行为。
.. list-table:: 配置 `sampler` 和 `shuffle` 的不同组合得到的预期排序结果
:widths: 25 25 50
:header-rows: 1
* - 参数`sampler`
- 参数`shuffle`
* - 参数 `sampler`
- 参数 `shuffle`
- 预期数据顺序
* - None
- None
@ -51,31 +49,33 @@ Class mindspore.dataset.CelebADataset(dataset_dir, num_parallel_workers=None, sh
* - None
- False
- 顺序排列
* - 参数`sampler`
* - 参数 `sampler`
- None
- 由`sampler`行为定义的顺序
* - 参数`sampler`
- 由 `sampler` 行为定义的顺序
* - 参数 `sampler`
- True
- 不允许
* - 参数`sampler`
* - 参数 `sampler`
- False
- 不允许
**示例：**
>>> celeba_dataset_dir = "/path/to/celeba_dataset_directory"
>>>
>>> # 从CelebA数据集中随机读取5个样本图片
>>> dataset = ds.CelebADataset(dataset_dir=celeba_dataset_dir, usage='train', num_samples=5)
>>>
>>> # 注：在生成的数据集对象中，每一次迭代得到的数据行都有"image"和"attr" 两个键
**样例：**
>>> celeba_dataset_dir = "/path/to/celeba_dataset_directory"
>>>
>>> # 从CelebA数据集中随机读取5个样本图片
>>> dataset = ds.CelebADataset(dataset_dir=celeba_dataset_dir, usage='train', num_samples=5)
>>>
>>> # 注：在生成的数据集对象中，每一次迭代得到的数据行都有"image"和"attr" 两个键
**关于CelebA数据集：**
CelebFaces Attributes Dataset（CelebA）数据集是一个大规模的人脸属性数据集，拥有超过20万名人图像，每个图像都有40个属性标注。
此数据集包含了大量不同姿态、各种背景的人脸图像，种类丰富、数量庞大、标注充分。数据集总体包含：
* 10177个不同的身份
* 202599张人脸图像
* 每张图像拥有5个五官位置标注，40个属性标签。
CelebFaces Attributes Dataset（CelebA）数据集是一个大规模的人脸属性数据集，拥有超过20万名人图像，每个图像都有40个属性标注。此数据集包含了大量不同姿态、各种背景的人脸图像，种类丰富、数量庞大、标注充分。数据集总体包含：
- 10177个不同的身份
- 202599张人脸图像
- 每张图像拥有5个五官位置标注，40个属性标签。
此数据集可用于各种计算机视觉任务的训练和测试，包括人脸识别、人脸检测、五官定位、人脸编辑和合成等。
原始CelebA数据集结构：
@ -128,3 +128,11 @@ Class mindspore.dataset.CelebADataset(dataset_dir, num_parallel_workers=None, sh
bibsource = {dblp computer science bibliography, https://dblp.org},
howpublished = {http://mmlab.ie.cuhk.edu.hk/projects/CelebA.html}
}
.. include:: mindspore.dataset.Dataset.add_sampler.rst
.. include:: mindspore.dataset.Dataset.rst
.. include:: mindspore.dataset.Dataset.use_sampler.rst
.. include:: mindspore.dataset.Dataset.zip.rst

147
docs/api/api_python/dataset/mindspore.dataset.CocoDataset.rst
View File

@ -1,56 +1,56 @@
mindspore.dataset.CocoDataset
==============================
Class mindspore.dataset.CocoDataset(dataset_dir, annotation_file, task='Detection', num_samples=None, num_parallel_workers=None, shuffle=None, decode=False, sampler=None, num_shards=None, shard_id=None, cache=None, extra_metadata=False)
.. py:class:: mindspore.dataset.CocoDataset(dataset_dir, annotation_file, task='Detection', num_samples=None, num_parallel_workers=None, shuffle=None, decode=False, sampler=None, num_shards=None, shard_id=None, cache=None, extra_metadata=False)
用于读取和解析COCO数据集的源数据文件。
该API支持解析COCO2017数据集，支持四种类型的机器学习任务，分别是目标检测、关键点检测、物体分割和全景分割。
用于读取和解析COCO数据集的源数据文件。该API支持解析COCO2017数据集，支持四种类型的机器学习任务，分别是目标检测、关键点检测、物体分割和全景分割。
根据不同`task`参数设置，生成数据集具有不同的输出列：
- `task` = :py:obj:`Detection`, 输出列: :py:obj:`[image, dtype=uint8]`, :py:obj:`[bbox, dtype=float32]`, :py:obj:`[category_id, dtype=uint32]`, :py:obj:`[iscrowd, dtype=uint32]`.
- `task` = :py:obj:`Stuff`, 输出列: :py:obj:`[image, dtype=uint8]`, :py:obj:`[segmentation,dtype=float32]`, :py:obj:`[iscrowd,dtype=uint32]`.
- `task` = :py:obj:`Keypoint`, 输出列: :py:obj:`[image, dtype=uint8]`, :py:obj:`[keypoints, dtype=float32]`, :py:obj:`[num_keypoints, dtype=uint32]`.
- `task` = :py:obj:`Panoptic`, 输出列: :py:obj:`[image, dtype=uint8]`, :py:obj:`[bbox, dtype=float32]`, :py:obj:`[category_id, dtype=uint32]`, :py:obj:`[iscrowd, dtype=uint32]`, :py:obj:`[area, dtype=uint32]`.
根据不同 `task` 参数设置，生成数据集具有不同的输出列：
- `task` = `Detection`, 输出列: `[image, dtype=uint8]`, `[bbox, dtype=float32]`, `[category_id, dtype=uint32]`, `[iscrowd, dtype=uint32]`。
- `task` = `Stuff`, 输出列: `[image, dtype=uint8]`, `[segmentation,dtype=float32]`, `[iscrowd,dtype=uint32]`。
- `task` = `Keypoint`, 输出列: `[image, dtype=uint8]`, `[keypoints, dtype=float32]`, `[num_keypoints, dtype=uint32]`。
- `task` = `Panoptic`, 输出列: `[image, dtype=uint8]`, `[bbox, dtype=float32]`, `[category_id, dtype=uint32]`, `[iscrowd, dtype=uint32]`, `[area, dtype=uint32]`。
**参数：**
- **dataset_dir** (str)：包含数据集文件的根目录路径。
- **annotation_file** (str)：数据集标注JSON文件的路径。
- **task** (str，可选)：指定COCO数据的任务类型。支持的任务类型包括：`Detection`、`Stuff`、`Panoptic`和`Keypoint`（默认为`Detection`）。
- **num_samples** (int，可选)：指定从数据集中读取的样本数（可以小于数据集总数，默认值为None，即全部样本图片)。
- **num_parallel_workers** (int，可选)：指定读取数据的工作线程数（默认值None，即使用mindspore.dataset.config中配置的线程数）。
- **shuffle** (bool，可选)：是否混洗数据集（默认为None，下表中会展示不同配置的预期行为）。
- **decode** (bool，可选)：是否对读取的图像进行解码操作（默认为False）。
- **sampler** (Sampler，可选)：指定从数据集中选取样本的采样器（默认为None，下表中会展示不同配置的预期行为）。
- **num_shards** (int, 可选)：指定分布式训练时将数据集进行划分的分片数（默认值None）。指定此参数后, `num_samples` 表示每个分片的最大样本数。
- **shard_id** (int, 可选)：指定分布式训练时使用的分片ID号（默认值None）。只有当指定了 `num_shards` 时才能指定此参数。
- **cache** (DatasetCache, 可选)：数据缓存客户端实例，用于加快数据集处理速度（默认为None，不使用缓存）。
- **extra_metadata** (bool，可选)：用于指定是否额外输出一列数据用于表示图像元信息。如果为True，则将额外输出一列数据，名为:py:obj:`[_meta-filename, dtype=string]` （默认值为False）。
- **dataset_dir** (str)：包含数据集文件的根目录路径。
- **annotation_file** (str)：数据集标注JSON文件的路径。
- **task** (str，可选)：指定COCO数据的任务类型。支持的任务类型包括：`Detection` 、 `Stuff` 、 `Panoptic` 和 `Keypoint` （默认为 `Detection` ）。
- **num_samples** (int，可选)：指定从数据集中读取的样本数（可以小于数据集总数，默认值为None，即全部样本图片)。
- **num_parallel_workers** (int，可选)：指定读取数据的工作线程数（默认值None，即使用mindspore.dataset.config中配置的线程数）。
- **shuffle** (bool，可选)：是否混洗数据集（默认为None，下表中会展示不同配置的预期行为）。
- **decode** (bool，可选)：是否对读取的图像进行解码操作（默认为False）。
- **sampler** (Sampler，可选)：指定从数据集中选取样本的采样器（默认为None，下表中会展示不同配置的预期行为）。
- **num_shards** (int, 可选)：指定分布式训练时将数据集进行划分的分片数（默认值None）。指定此参数后, `num_samples` 表示每个分片的最大样本数。
- **shard_id** (int, 可选)：指定分布式训练时使用的分片ID号（默认值None）。只有当指定了 `num_shards` 时才能指定此参数。
- **cache** (DatasetCache, 可选)：数据缓存客户端实例，用于加快数据集处理速度（默认为None，不使用缓存）。
- **extra_metadata** (bool，可选)：用于指定是否额外输出一列数据用于表示图像元信息。如果为True，则将额外输出一列数据，名为 `[_meta-filename, dtype=string]` （默认值为False）。
**异常：**
- **RuntimeError**: 参数`dataset_dir`不包含任何数据文件。
- **RuntimeError**: 参数`num_parallel_workers`超过系统最大线程数。
- **RuntimeError**: 同时指定了`sampler`和`shuffle`。
- **RuntimeError**: 同时指定了`sampler`和`num_shards`。
- **RuntimeError**: 指定了`num_shards`参数，但是未指定`shard_id`参数。
- **RuntimeError**: 指定了`shard_id`参数，但是未指定`num_shards`参数。
- **RuntimeError**: 解析JSON文件失败。
- **ValueError**： 指定的任务不为`Detection`，`Stuff`，`Panoptic`或`Keypoint`。
- **ValueError**： 参数`annotation_file`对应的文件不存在。
- **ValueError**： 参数`dataset_dir`路径不存在。
- **ValueError**: 参数`shard_id`错误（小于0或者大于等于 `num_shards`）。
**注：**
- 当指定`extra_metadata`为True时，除非显式使用`rename`算子以删除元信息列明的前缀('_meta-')，
否则迭代的数据行中不会出现'[_meta-filename, dtype=string]'列。
- CocoDataset的`sampler`参数不支持指定PKSampler。
- 此数据集可以指定`sampler`参数，但`sampler` 和 `shuffle` 是互斥的。下表展示了几种合法的输入参数及预期的行为。
- **RuntimeError**: 参数 `dataset_dir` 不包含任何数据文件。
- **RuntimeError**: 参数 `num_parallel_workers` 超过系统最大线程数。
- **RuntimeError**: 同时指定了 `sampler` 和 `shuffle` 。
- **RuntimeError**: 同时指定了 `sampler` 和 `num_shards` 。
- **RuntimeError**: 指定了 `num_shards` 参数，但是未指定 `shard_id` 参数。
- **RuntimeError**: 指定了 `shard_id` 参数，但是未指定 num_shards` 参数。
- **RuntimeError**: 解析JSON文件失败。
- **ValueError**： 指定的任务不为 `Detection` ， `Stuff` ， `Panoptic` 或 `Keypoint`。
- **ValueError**： 参数 `annotation_file` 对应的文件不存在。
- **ValueError**： 参数 `dataset_dir` 路径不存在。
- **ValueError**: 参数 `shard_id` 错误（小于0或者大于等于 `num_shards` ）。
.. list-table:: 配置`sampler`和`shuffle`的不同组合得到的预期排序结果
.. note::
- 当指定 `extra_metadata` 为True时，除非显式使用 `rename` 算子以删除元信息列明的前缀('_meta-')，否则迭代的数据行中不会出现'[_meta-filename, dtype=string]'列。
- CocoDataset的 `sampler` 参数不支持指定PKSampler。
- 此数据集可以指定 `sampler` 参数，但 `sampler` 和 `shuffle` 是互斥的。下表展示了几种合法的输入参数及预期的行为。
.. list-table:: 配置 `sampler` 和 `shuffle` 的不同组合得到的预期排序结果
:widths: 25 25 50
:header-rows: 1
* - 参数`sampler`
- 参数`shuffle`
* - 参数 `sampler`
- 参数 `shuffle`
- 预期数据顺序
* - None
- None
@ -61,47 +61,46 @@ Class mindspore.dataset.CocoDataset(dataset_dir, annotation_file, task='Detectio
* - None
- False
- 顺序排列
* - 参数`sampler`
- None
* - 参数 `sampler`
- No ne
- 由`sampler`行为定义的顺序
* - 参数`sampler`
* - 参数 `sampler`
- True
- 不允许
* - 参数`sampler`
* - 参数 `sampler`
- False
- 不允许
**样例：**
>>> coco_dataset_dir = "/path/to/coco_dataset_directory/images"
>>> coco_annotation_file = "/path/to/coco_dataset_directory/annotation_file"
>>>
>>> # 1）读取COCO数据集中`Detection`任务中的数据。
>>> dataset = ds.CocoDataset(dataset_dir=coco_dataset_dir,
... annotation_file=coco_annotation_file,
... task='Detection')
>>>
>>> # 2）读取COCO数据集中`Stuff`任务中的数据。
>>> dataset = ds.CocoDataset(dataset_dir=coco_dataset_dir,
... annotation_file=coco_annotation_file,
... task='Stuff')
>>>
>>> # 3）读取COCO数据集中`Panoptic`任务中的数据。
>>> dataset = ds.CocoDataset(dataset_dir=coco_dataset_dir,
... annotation_file=coco_annotation_file,
... task='Panoptic')
>>>
>>> # 4）读取COCO数据集中`Keypoint`任务中的数据。
>>> dataset = ds.CocoDataset(dataset_dir=coco_dataset_dir,
... annotation_file=coco_annotation_file,
... task='Keypoint')
>>>
>>> # 在生成的COCO数据集对象中，每一次迭代得到的数据行都有"image"和"annotation"两个键。
>>> coco_dataset_dir = "/path/to/coco_dataset_directory/images"
>>> coco_annotation_file = "/path/to/coco_dataset_directory/annotation_file"
>>>
>>> # 1）读取COCO数据集中`Detection`任务中的数据。
>>> dataset = ds.CocoDataset(dataset_dir=coco_dataset_dir,
... annotation_file=coco_annotation_file,
... task='Detection')
>>>
>>> # 2）读取COCO数据集中`Stuff`任务中的数据。
>>> dataset = ds.CocoDataset(dataset_dir=coco_dataset_dir,
... annotation_file=coco_annotation_file,
... task='Stuff')
>>>
>>> # 3）读取COCO数据集中`Panoptic`任务中的数据。
>>> dataset = ds.CocoDataset(dataset_dir=coco_dataset_dir,
... annotation_file=coco_annotation_file,
... task='Panoptic')
>>>
>>> # 4）读取COCO数据集中`Keypoint`任务中的数据。
>>> dataset = ds.CocoDataset(dataset_dir=coco_dataset_dir,
... annotation_file=coco_annotation_file,
... task='Keypoint')
>>>
>>> # 在生成的COCO数据集对象中，每一次迭代得到的数据行都有"image"和"annotation"两个键。
**关于COCO数据集：**
Microsoft Common Objects in Context（COCO）是一个大型数据集，该数据集专门为目标检测，语义分割和字幕生成任务而设计。
它拥有330K张图像（标记数量大于200K个）、1500000个目标实例、80个目标类别、91个对象类别、每张图片均有5个字幕、带关键点标注的人有250000个。
与流行的ImageNet数据集相比，COCO的类别较少，但每个类别中的图片样本非常多。
Microsoft Common Objects in Context（COCO）是一个大型数据集，该数据集专门为目标检测，语义分割和字幕生成任务而设计。它拥有330K张图像（标记数量大于200K个）、1500000个目标实例、80个目标类别、91个对象类别、每张图片均有5个字幕、带关键点标注的人有250000个。与流行的ImageNet数据集相比，COCO的类别较少，但每个类别中的图片样本非常多。
您可以解压缩原始COCO-2017数据集文件如下目录结构，并通过MindSpore的API读取。
@ -148,3 +147,11 @@ Class mindspore.dataset.CocoDataset(dataset_dir, annotation_file, task='Detectio
biburl = {https://dblp.org/rec/journals/corr/LinMBHPRDZ14.bib},
bibsource = {dblp computer science bibliography, https://dblp.org}
}
.. include:: mindspore.dataset.Dataset.add_sampler.rst
.. include:: mindspore.dataset.Dataset.rst
.. include:: mindspore.dataset.Dataset.use_sampler.rst
.. include:: mindspore.dataset.Dataset.zip.rst

44
docs/api/api_python/dataset/mindspore.dataset.Dataset.rst
View File

@ -111,6 +111,33 @@
... element_length_function, pad_info,
... pad_to_bucket_boundary)
.. py:method:: build_sentencepiece_vocab(columns, vocab_size, character_coverage, model_type, params)
用于从源数据集对象创建句子词表的函数。
**参数：**
- **columns** (list[str])：指定从哪一列中获取单词。
- **vocab_size** (int)：词汇表大小。
- **character_coverage** (int)：模型涵盖的字符百分比，必须介于0.98和1.0之间。默认值如0.9995，适用于具有丰富字符集的语言，如日语或中文字符集；1.0适用于其他字符集较小的语言，比如英语或拉丁文。
- **model_type** (SentencePieceModel)：模型类型，枚举值包括unigram（默认值）、bpe、char及word。当类型为word时，输入句子必须预先标记。
- **params** (dict)：依据原始数据内容构建祠表的附加参数，无附加参数时取值可以是空字典。
**返回：**
SentencePieceVocab，从数据集构建的词汇表。
**样例：**
>>> from mindspore.dataset.text import SentencePieceModel
>>>
>>> # DE_C_INTER_SENTENCEPIECE_MODE 是一个映射字典
>>> from mindspore.dataset.text.utils import DE_C_INTER_SENTENCEPIECE_MODE
>>> dataset = ds.TextFileDataset("/path/to/sentence/piece/vocab/file", shuffle=False)
>>> dataset = dataset.build_sentencepiece_vocab(["text"], 5000, 0.9995,
... DE_C_INTER_SENTENCEPIECE_MODE[SentencePieceModel.UNIGRAM],
... {})
..py:method:: build_vocab(columns, freq_range, top_k, special_tokens, special_first)
基于数据集对象创建词汇表。
@ -882,20 +909,3 @@
**返回：**
str，流水线的JSON字符串。
..py:method:: zip(datasets)
将数据集和输入的数据集或者数据集元组按列进行合并压缩。输入数据集中的列名必须不同。
**参数：**
**datasets** (Union[tuple, class Dataset]) - 数据集对象的元组或单个数据集对象与当前数据集一起合并压缩。
**返回：**
ZipDataset，合并压缩后的数据集对象。
**样例：**
>>> # 创建一个数据集，它将dataset和dataset_1进行合并
>>> dataset = dataset.zip(dataset_1)

16
docs/api/api_python/dataset/mindspore.dataset.Dataset.zip.rst Normal file
View File

@ -0,0 +1,16 @@
..py:method:: zip(datasets)
将数据集和输入的数据集或者数据集元组按列进行合并压缩。输入数据集中的列名必须不同。
**参数：**
**datasets** (Union[tuple, class Dataset]) - 数据集对象的元组或单个数据集对象与当前数据集一起合并压缩。
**返回：**
ZipDataset，合并压缩后的数据集对象。
**样例：**
>>> # 创建一个数据集，它将dataset和dataset_1进行合并
>>> dataset = dataset.zip(dataset_1)

196
docs/api/api_python/dataset/mindspore.dataset.GeneratorDataset.rst
View File

@ -1,50 +1,49 @@
mindspore.dataset.GeneratorDataset
===================================
Class mindspore.dataset.GeneratorDataset(source, column_names=None, column_types=None, schema=None, num_samples=None, num_parallel_workers=1, shuffle=None, sampler=None, num_shards=None, shard_id=None, python_multiprocessing=True, max_rowsize=6)
.. py:class:: mindspore.dataset.GeneratorDataset(source, column_names=None, column_types=None, schema=None, num_samples=None, num_parallel_workers=1, shuffle=None, sampler=None, num_shards=None, shard_id=None, python_multiprocessing=True, max_rowsize=6)
通过调用Python数据源从Python中生成数据作为源数据集。
生成的数据集的列名和列类型取决于用户定义的Python数据源。
通过调用Python数据源从Python中生成数据作为源数据集。生成的数据集的列名和列类型取决于用户定义的Python数据源。
**参数：**
- **source** (Union[Callable, Iterable, Random Accessible])：
一个Python的可调用对象，可以是一个可迭代的Python对象，或支持随机访问的Python对象。
要求传入的可调用对象，可以通过`source().next()`的方式返回一个由NumPy数组构成的元组。
要求传入的可迭代对象，可以通过`iter(source).next()`的方式返回一个由NumPy数组构成的元组。
要求传入的支持随机访问对象，可以通过`source[idx]`的方式返回一个由NumPy数组构成的元组。
- **column_names** (Union[str, list[str]]，可选)：指定数据集生成的列名（默认值为None），用户必须提供此参数或通过参数`schema`指定列名。
- **column_types** ((list[mindspore.dtype]，可选)：指定生成数据集各个数据列的数据类型（默认为None）。
如果未指定该参数，则自动推断类型；如果指定了该参数，将在数据输出时做类型匹配检查。
- **schema** (Union[Schema, str]，可选)：读取模式策略，用于指定读取数据列的数据类型、数据维度等信息，支持传入JSON文件或`Schema`对象的路径。
对于数据集生成的列名，用户需要提供`column_names`或`schema`进行指定，如果同时指定两者，则将优先从`schema`获取列名信息。
- **num_samples** (int，可选)：指定从数据集中读取的样本数（默认为None）。
- **num_parallel_workers** (int，可选)：指定读取数据的工作线程数（默认值为1）。
- **shuffle** (bool，可选)：是否混洗数据集。只有输入的`source`参数带有可随机访问属性（__getitem__）时，才可以指定该参数。（默认值为None，下表中会展示不同配置的预期行为）。
- **sampler** (Union[Sampler, Iterable]，可选)：指定从数据集中选取样本的采样器。只有输入的`source`参数带有可随机访问属性（__getitem__）时，才可以指定该参数（默认值为None，下表中会展示不同配置的预期行为）。
- **num_shards** (int, 可选): 分布式训练时，将数据集划分成指定的分片数（默认值None）。指定此参数后，`num_samples` 表示每个分片的最大样本数。需要输入`data`支持可随机访问才能指定该参数。
- **shard_id** (int, 可选): 分布式训练时，指定使用的分片ID号（默认值None）。只有当指定了 `num_shards` 时才能指定此参数。
- **python_multiprocessing** (bool，可选)：启用Python多进程模式加速运算（默认为True）。当传入Python对象的计算量很大时，开启此选项可能会有较好效果。
- **max_rowsize** (int，可选)：指定在多进程之间复制数据时，共享内存分配的最大空间（数量级为MB，默认为6MB），仅当参数`python_multiprocessing`设为True时，此参数才会生效。
- **source** (Union[Callable, Iterable, Random Accessible])：
一个Python的可调用对象，可以是一个可迭代的Python对象，或支持随机访问的Python对象。
要求传入的可调用对象，可以通过 `source().next()` 的方式返回一个由NumPy数组构成的元组。
要求传入的可迭代对象，可以通过 `iter(source).next()` 的方式返回一个由NumPy数组构成的元组。
要求传入的支持随机访问对象，可以通过 `source[idx]` 的方式返回一个由NumPy数组构成的元组。
- **column_names** (Union[str, list[str]]，可选)：指定数据集生成的列名（默认值为None），用户必须提供此参数或通过参数 `schema` 指定列名。
- **column_types** ((list[mindspore.dtype]，可选)：指定生成数据集各个数据列的数据类型（默认为None）。
如果未指定该参数，则自动推断类型；如果指定了该参数，将在数据输出时做类型匹配检查。
- **schema** (Union[Schema, str]，可选)：读取模式策略，用于指定读取数据列的数据类型、数据维度等信息，支持传入JSON文件或 `schema` 对象的路径。
对于数据集生成的列名，用户需要提供 `column_names` 或 `schema` 进行指定，如果同时指定两者，则将优先从 `schema` 获取列名信息。
- **num_samples** (int，可选)：指定从数据集中读取的样本数（默认为None）。
- **num_parallel_workers** (int，可选)：指定读取数据的工作线程数（默认值为1）。
- **shuffle** (bool，可选)：是否混洗数据集。只有输入的 `source` 参数带有可随机访问属性（__getitem__）时，才可以指定该参数。（默认值为None，下表中会展示不同配置的预期行为）。
- **sampler** (Union[Sampler, Iterable]，可选)：指定从数据集中选取样本的采样器。只有输入的 `source` 参数带有可随机访问属性（__getitem__）时，才可以指定该参数（默认值为None，下表中会展示不同配置的预期行为）。
- **num_shards** (int, 可选): 分布式训练时，将数据集划分成指定的分片数（默认值None）。指定此参数后，`num_samples` 表示每个分片的最大样本数。需要输入 `data` 支持可随机访问才能指定该参数。
- **shard_id** (int, 可选): 分布式训练时，指定使用的分片ID号（默认值None）。只有当指定了 `num_shards` 时才能指定此参数。
- **python_multiprocessing** (bool，可选)：启用Python多进程模式加速运算（默认为True）。当传入Python对象的计算量很大时，开启此选项可能会有较好效果。
- **max_rowsize** (int，可选)：指定在多进程之间复制数据时，共享内存分配的最大空间（数量级为MB，默认为6MB），仅当参数 `python_multiprocessing` 设为True时，此参数才会生效。
**异常：**
- **RuntimeError**：Python对象`source`在执行期间引发异常。
- **RuntimeError**：参数`column_names`指定的列名数量与`source`的输出数据数量不匹配。
- **RuntimeError**：参数`num_parallel_workers`超过最大线程数。
- **RuntimeError**: 同时指定了`sampler`和`shuffle`。
- **RuntimeError**: 同时指定了`sampler`和`num_shards`。
- **RuntimeError**: 指定了`num_shards`参数，但是未指定`shard_id`参数。
- **RuntimeError**: 指定了`shard_id`参数，但是未指定`num_shards`参数。
- **ValueError**: `shard_id`参数错误（小于0或者大于等于 `num_shards`）。
- **RuntimeError**：Python对象 `source` 在执行期间引发异常。
- **RuntimeError**：参数 `column_names` 指定的列名数量与 `source` 的输出数据数量不匹配。
- **RuntimeError**：参数 `num_parallel_workers` 超过最大线程数。
- **RuntimeError**: 同时指定了 `sampler` 和 `shuffle` 。
- **RuntimeError**: 同时指定了 `sampler` 和 `num_shards` 。
- **RuntimeError**: 指定了 `num_shards` 参数，但是未指定 `shard_id` 参数。
- **RuntimeError**: 指定了 `shard_id` 参数，但是未指定 `num_shards` 参数。
- **ValueError**: `shard_id` 参数错误（小于0或者大于等于 `num_shards` ）。
**注：**
- 此数据集可以指定`sampler`参数，但`sampler` 和 `shuffle` 是互斥的。下表展示了几种合法的输入参数及预期的行为。
.. note:: 此数据集可以指定 `sampler` 参数，但 `sampler` 和 `shuffle` 是互斥的。下表展示了几种合法的输入参数及预期的行为。
.. list-table:: 配置`sampler`和`shuffle`的不同组合得到的预期排序结果
.. list-table:: 配置 `sampler` 和 `shuffle` 的不同组合得到的预期排序结果
:widths: 25 25 50
:header-rows: 1
* - 参数`sampler`
- 参数`shuffle`
* - 参数 `sampler`
- 参数 `shuffle`
- 预期数据顺序
* - None
- None
@ -55,70 +54,79 @@ Class mindspore.dataset.GeneratorDataset(source, column_names=None, column_types
* - None
- False
- 顺序排列
* - 参数`sampler`
* - 参数 `sampler`
- None
- 由`sampler`行为定义的顺序
* - 参数`sampler`
- 由 `sampler` 行为定义的顺序
* - 参数 `sampler`
- True
- 不允许
* - 参数`sampler`
* - 参数 `sampler`
- False
- 不允许
**样例：**
>>> import numpy as np
>>>
>>> # 1）定义一个Python生成器作为GeneratorDataset的可调用对象。
>>> def generator_multidimensional():
... for i in range(64):
... yield (np.array([[i, i + 1], [i + 2, i + 3]]),)
>>>
>>> dataset = ds.GeneratorDataset(source=generator_multidimensional, column_names=["multi_dimensional_data"])
>>>
>>> # 2）定义一个Python生成器返回多列数据，作为GeneratorDataset的可调用对象。
>>> def generator_multi_column():
... for i in range(64):
... yield np.array([i]), np.array([[i, i + 1], [i + 2, i + 3]])
>>>
>>> dataset = ds.GeneratorDataset(source=generator_multi_column, column_names=["col1", "col2"])
>>>
>>> # 3）定义一个可迭代数据集对象，作为GeneratorDataset的可调用对象。
>>> class MyIterable:
... def __init__(self):
... self._index = 0
... self._data = np.random.sample((5, 2))
... self._label = np.random.sample((5, 1))
...
... def __next__(self):
... if self._index >= len(self._data):
... raise StopIteration
... else:
... item = (self._data[self._index], self._label[self._index])
... self._index += 1
... return item
...
... def __iter__(self):
... self._index = 0
... return self
...
... def __len__(self):
... return len(self._data)
>>>
>>> dataset = ds.GeneratorDataset(source=MyIterable(), column_names=["data", "label"])
>>>
>>> # 4）定义一个支持随机访问数据集对象，作为GeneratorDataset的可调用对象。
>>> class MyAccessible:
... def __init__(self):
... self._data = np.random.sample((5, 2))
... self._label = np.random.sample((5, 1))
...
... def __getitem__(self, index):
... return self._data[index], self._label[index]
...
... def __len__(self):
... return len(self._data)
>>>
>>> dataset = ds.GeneratorDataset(source=MyAccessible(), column_names=["data", "label"])
>>>
>>> # 注意，Python的list、dict、tuple也是支持随机可访问的，同样可以作为GeneratorDataset的输入
>>> dataset = ds.GeneratorDataset(source=[(np.array(0),), (np.array(1),), (np.array(2),)], column_names=["col"])
>>> import numpy as np
>>>
>>> # 1）定义一个Python生成器作为GeneratorDataset的可调用对象。
>>> def generator_multidimensional():
... for i in range(64):
... yield (np.array([[i, i + 1], [i + 2, i + 3]]),)
>>>
>>> dataset = ds.GeneratorDataset(source=generator_multidimensional, column_names=["multi_dimensional_data"])
>>>
>>> # 2）定义一个Python生成器返回多列数据，作为GeneratorDataset的可调用对象。
>>> def generator_multi_column():
... for i in range(64):
... yield np.array([i]), np.array([[i, i + 1], [i + 2, i + 3]])
>>>
>>> dataset = ds.GeneratorDataset(source=generator_multi_column, column_names=["col1", "col2"])
>>>
>>> # 3）定义一个可迭代数据集对象，作为GeneratorDataset的可调用对象。
>>> class MyIterable:
... def __init__(self):
... self._index = 0
... self._data = np.random.sample((5, 2))
... self._label = np.random.sample((5, 1))
...
... def __next__(self):
... if self._index >= len(self._data):
... raise StopIteration
... else:
... item = (self._data[self._index], self._label[self._index])
... self._index += 1
... return item
...
... def __iter__(self):
... self._index = 0
... return self
...
... def __len__(self):
... return len(self._data)
>>>
>>> dataset = ds.GeneratorDataset(source=MyIterable(), column_names=["data", "label"])
>>>
>>> # 4）定义一个支持随机访问数据集对象，作为GeneratorDataset的可调用对象。
>>> class MyAccessible:
... def __init__(self):
... self._data = np.random.sample((5, 2))
... self._label = np.random.sample((5, 1))
...
... def __getitem__(self, index):
... return self._data[index], self._label[index]
...
... def __len__(self):
... return len(self._data)
>>>
>>> dataset = ds.GeneratorDataset(source=MyAccessible(), column_names=["data", "label"])
>>>
>>> # 注意，Python的list、dict、tuple也是支持随机可访问的，同样可以作为GeneratorDataset的输入
>>> dataset = ds.GeneratorDataset(source=[(np.array(0),), (np.array(1),), (np.array(2),)], column_names=["col"])
.. include:: mindspore.dataset.Dataset.add_sampler.rst
.. include:: mindspore.dataset.Dataset.rst
.. include:: mindspore.dataset.Dataset.use_sampler.rst
.. include:: mindspore.dataset.Dataset.zip.rst

8
docs/api/api_python/dataset/mindspore.dataset.ImageFolderDataset.rst
View File

@ -101,4 +101,10 @@ mindspore.dataset.ImageFolderDataset
├── classN
├── ...
.. include:: mindspore.dataset.Dataset.rst
.. include:: mindspore.dataset.Dataset.add_sampler.rst
.. include:: mindspore.dataset.Dataset.rst
.. include:: mindspore.dataset.Dataset.use_sampler.rst
.. include:: mindspore.dataset.Dataset.zip.rst

89
docs/api/api_python/dataset/mindspore.dataset.ManifestDataset.rst
View File

@ -1,47 +1,47 @@
mindspore.dataset.ManifestDataset
==================================
Class mindspore.dataset.ManifestDataset(dataset_file, usage='train', num_samples=None, num_parallel_workers=None, shuffle=None, sampler=None, class_indexing=None, decode=False, num_shards=None, shard_id=None, cache=None)
.. py:class:: mindspore.dataset.ManifestDataset(dataset_file, usage='train', num_samples=None, num_parallel_workers=None, shuffle=None, sampler=None, class_indexing=None, decode=False, num_shards=None, shard_id=None, cache=None)
读取Manifest文件作为源数据集。
生成的数据集有两列：:py:obj:`[image, label]`。
列:py:obj:`image` 的数据类型为uint8类型。
列:py:obj:`label` 的数据类型是uint64类型的标量。
生成的数据集有两列： `[image, label]`。列 `image` 的数据类型为uint8类型。列 `label` 的数据类型是uint64类型的标量。
**参数：**
- **dataset_file** (str)：数据集文件的目录路径。
- **usage** (str，可选)：指定数据集的子集，可取值为'train'、'eval'和'inference' （默认为'train'）。
- **num_samples** (int，可选)：指定从数据集中读取的样本数（默认值为None，即全部样本图片)。
- **num_parallel_workers** (int，可选)：指定读取数据的工作线程数（默认值None，即使用mindspore.dataset.config中配置的线程数）。
- **shuffle** (bool，可选)：是否混洗数据集（默认为None，下表中会展示不同配置的预期行为）。
- **sampler** (Sampler，可选)：指定从数据集中选取样本的采样器（默认为None，下表中会展示不同配置的预期行为）。
- **class_indexing** (dict，可选)：指定文件夹名称到类标签的映射，要求映射规则为str到int（默认为None，文件夹名称将按字母顺序排列，每类都有一个唯一的索引，从0开始）。
- **decode** (bool, 可选)：是否对读取的图像进行解码操作（默认为False）。
- **num_shards** (int, 可选): 分布式训练时，将数据集划分成指定的分片数（默认值None）。指定此参数后，`num_samples` 表示每个分片的最大样本数。
- **shard_id** (int, 可选): 分布式训练时，指定使用的分片ID号（默认值None）。只有当指定了 `num_shards` 时才能指定此参数。
- **cache** (DatasetCache, 可选)：数据缓存客户端实例，用于加快数据集处理速度（默认为None，不使用缓存）。
- **dataset_file** (str)：数据集文件的目录路径。
- **usage** (str，可选)：指定数据集的子集，可取值为'train'、'eval'和'inference' （默认为'train'）。
- **num_samples** (int，可选)：指定从数据集中读取的样本数（默认值为None，即全部样本图片)。
- **num_parallel_workers** (int，可选)：指定读取数据的工作线程数（默认值None，即使用mindspore.dataset.config中配置的线程数）。
- **shuffle** (bool，可选)：是否混洗数据集（默认为None，下表中会展示不同配置的预期行为）。
- **sampler** (Sampler，可选)：指定从数据集中选取样本的采样器（默认为None，下表中会展示不同配置的预期行为）。
- **class_indexing** (dict，可选)：指定文件夹名称到类标签的映射，要求映射规则为str到int（默认为None，文件夹名称将按字母顺序排列，每类都有一个唯一的索引，从0开始）。
- **decode** (bool, 可选)：是否对读取的图像进行解码操作（默认为False）。
- **num_shards** (int, 可选): 分布式训练时，将数据集划分成指定的分片数（默认值None）。指定此参数后，`num_samples` 表示每个分片的最大样本数。
- **shard_id** (int, 可选): 分布式训练时，指定使用的分片ID号（默认值None）。只有当指定了 `num_shards` 时才能指定此参数。
- **cache** (DatasetCache, 可选)：数据缓存客户端实例，用于加快数据集处理速度（默认为None，不使用缓存）。
**异常：**
- **RuntimeError**：参数`dataset_files`不存在或无效。
- **RuntimeError**：参数`num_parallel_workers`超过系统最大线程数。
- **RuntimeError**：同时指定了`sampler`和`shuffle`。
- **RuntimeError**：同时指定了`sampler`和`num_shards`或`shard_id`。
- **RuntimeError**: 指定了`num_shards`参数，但是未指定`shard_id`参数。
- **RuntimeError**: 指定了`shard_id`参数，但是未指定`num_shards`参数。
- **RuntimeError**：参数`class_indexing`的类型不是字典。
- **ValueError**: `shard_id`参数错误（小于0或者大于等于 `num_shards`）。
**注：**
- 如果`decode`参数指定为False，则`image`列的shape为[image_size]，否则为[H,W,C]。
- 此数据集可以指定`sampler`参数，但`sampler` 和 `shuffle` 是互斥的。下表展示了几种合法的输入参数及预期的行为。
- **RuntimeError**：参数 `dataset_files` 不存在或无效。
- **RuntimeError**：参数 `num_parallel_workers` 超过系统最大线程数。
- **RuntimeError**：同时指定了 `sampler` 和 `shuffle` 。
- **RuntimeError**：同时指定了 `sampler` 和 `num_shards` 或 `shard_id`。
- **RuntimeError**: 指定了 `num_shards` 参数，但是未指定 `shard_id` 参数。
- **RuntimeError**: 指定了 `shard_id` 参数，但是未指定 `num_shards` 参数。
- **RuntimeError**：参数 `class_indexing` 的类型不是字典。
- **ValueError**: `shard_id` 参数错误（小于0或者大于等于 `num_shards`）。
.. list-table:: 配置`sampler`和`shuffle`的不同组合得到的预期排序结果
.. note::
- 如果 `decode` 参数指定为False，则 `image` 列的shape为[image_size]，否则为[H,W,C]。
- 此数据集可以指定 `sampler` 参数，但 `sampler` 和 `shuffle` 是互斥的。下表展示了几种合法的输入参数及预期的行为。
.. list-table:: 配置 `sampler` 和 `shuffle` 的不同组合得到的预期排序结果
:widths: 25 25 50
:header-rows: 1
* - 参数`sampler`
- 参数`shuffle`
* - 参数 `sampler`
- 参数 `shuffle`
- 预期数据顺序
* - None
- None
@ -52,21 +52,30 @@ Class mindspore.dataset.ManifestDataset(dataset_file, usage='train', num_samples
* - None
- False
- 顺序排列
* - 参数`sampler`
* - 参数 `sampler`
- None
- 由`sampler`行为定义的顺序
* - 参数`sampler`
- 由 `sampler` 行为定义的顺序
* - 参数 `sampler`
- True
- 不允许
* - 参数`sampler`
* - 参数 `sampler`
- False
- 不允许
**样例：**
>>> manifest_dataset_dir = "/path/to/manifest_dataset_file"
>>>
>>> # 1）使用八个线程读取Manifest数据集文件，并指定读取"train"子集数据
>>> dataset = ds.ManifestDataset(dataset_file=manifest_dataset_dir, usage="train", num_parallel_workers=8)
>>>
>>> # 2） 对Manifest数据集进行分布式训练，并将数据集拆分为2个分片，当前数据集仅加载分片ID号为0的数据
>>> dataset = ds.ManifestDataset(dataset_file=manifest_dataset_dir, num_shards=2, shard_id=0)
>>> manifest_dataset_dir = "/path/to/manifest_dataset_file"
>>>
>>> # 1）使用八个线程读取Manifest数据集文件，并指定读取"train"子集数据
>>> dataset = ds.ManifestDataset(dataset_file=manifest_dataset_dir, usage="train", num_parallel_workers=8)
>>>
>>> # 2） 对Manifest数据集进行分布式训练，并将数据集拆分为2个分片，当前数据集仅加载分片ID号为0的数据
>>> dataset = ds.ManifestDataset(dataset_file=manifest_dataset_dir, num_shards=2, shard_id=0)
.. include:: mindspore.dataset.Dataset.add_sampler.rst
.. include:: mindspore.dataset.Dataset.rst
.. include:: mindspore.dataset.Dataset.use_sampler.rst
.. include:: mindspore.dataset.Dataset.zip.rst

81
docs/api/api_python/dataset/mindspore.dataset.MindDataset.rst
View File

@ -1,47 +1,45 @@
mindspore.dataset.MindDataset
==============================
Class mindspore.dataset.MindDataset(dataset_file, columns_list=None, num_parallel_workers=None, shuffle=None, num_shards=None, shard_id=None, sampler=None, padded_sample=None, num_padded=None, num_samples=None, cache=None)
.. py:class:: mindspore.dataset.MindDataset(dataset_file, columns_list=None, num_parallel_workers=None, shuffle=None, num_shards=None, shard_id=None, sampler=None, padded_sample=None, num_padded=None, num_samples=None, cache=None)
读取和解析MindRecord数据文件作为源数据集。
生成的数据集的列名和列类型取决于MindRecord文件中的保存的列名与类型。
读取和解析MindRecord数据文件作为源数据集。生成的数据集的列名和列类型取决于MindRecord文件中的保存的列名与类型。
**参数：**
- **dataset_file** (Union[str, list[str]])：MindRecord文件路径，支持单文件路径字符串、多文件路径字符串列表。
如果`dataset_file`的类型是字符串，则它代表一组具有相同前缀名的MindRecord文件，同一路径下具有相同前缀名的其他MindRecord文件将会被自动寻找并加载。
如果`dataset_file`的类型是列表，则它表示所需读取的MindRecord数据文件。
- **columns_list** (list[str]，可选)：指定从MindRecord文件中读取的数据列（默认为None，读取所有列）。
- **num_parallel_workers** (int，可选)：指定读取数据的工作线程数（默认值None，即使用mindspore.dataset.config中配置的线程数）。
- **shuffle** (Union[bool, Shuffle level], 可选)：每个epoch中数据混洗的模式（默认为为mindspore.dataset.Shuffle.GLOBAL）。
如果为False，则不混洗；如果为True，等同于将`shuffle`设置为mindspore.dataset.Shuffle.GLOBAL。另外也可以传入枚举变量设置shuffle级别：
- Shuffle.GLOBAL：混洗文件和样本。
- Shuffle.FILES：仅混洗文件。
- Shuffle.INFILE：保持读入文件的序列，仅混洗每个文件中的数据。
- **num_shards** (int, 可选): 分布式训练时，将数据集划分成指定的分片数（默认值None）。指定此参数后，`num_samples` 表示每个分片的最大样本数。
- **shard_id** (int, 可选): 分布式训练时，指定使用的分片ID号（默认值None）。只有当指定了 `num_shards` 时才能指定此参数。
- **sampler** (Sampler，可选)：指定从数据集中选取样本的采样器（默认为None，下表中会展示不同配置的预期行为）。
当前此数据集仅支持以下采样器：SubsetRandomSampler、PkSampler、RandomSampler、SequentialSampler和DistributedSampler。
- **padded_sample** (dict，可选): 指定额外添加到数据集的样本，可用于在分布式训练时补齐分片数据，注意字典的键名需要与column_list指定的列名相同。
- **num_padded** (int，可选)：指定额外添加的数据集样本的数量。在分布式训练时可用于为数据集补齐样本，使得总样本数量可被num_shards整除。
- **num_samples** (int，可选)：指定从数据集中读取的样本数（默认值为None，表示所有样本)。
- **cache** (DatasetCache, 可选)：数据缓存客户端实例，用于加快数据集处理速度（默认为None，不使用缓存）。
- **dataset_file** (Union[str, list[str]])：MindRecord文件路径，支持单文件路径字符串、多文件路径字符串列表。如果 `dataset_file` 的类型是字符串，则它代表一组具有相同前缀名的MindRecord文件，同一路径下具有相同前缀名的其他MindRecord文件将会被自动寻找并加载。如果 `dataset_file` 的类型是列表，则它表示所需读取的MindRecord数据文件。
- **columns_list** (list[str]，可选)：指定从MindRecord文件中读取的数据列（默认为None，读取所有列）。
- **num_parallel_workers** (int，可选)：指定读取数据的工作线程数（默认值None，即使用mindspore.dataset.config中配置的线程数）。
- **shuffle** (Union[bool, Shuffle level], 可选)：每个epoch中数据混洗的模式（默认为为mindspore.dataset.Shuffle.GLOBAL）。如果为False，则不混洗；如果为True，等同于将 `shuffle` 设置为mindspore.dataset.Shuffle.GLOBAL。另外也可以传入枚举变量设置shuffle级别：
- Shuffle.GLOBAL：混洗文件和样本。
- Shuffle.FILES：仅混洗文件。
- Shuffle.INFILE：保持读入文件的序列，仅混洗每个文件中的数据。
- **num_shards** (int, 可选): 分布式训练时，将数据集划分成指定的分片数（默认值None）。指定此参数后，`num_samples` 表示每个分片的最大样本数。
- **shard_id** (int, 可选): 分布式训练时，指定使用的分片ID号（默认值None）。只有当指定了 `num_shards` 时才能指定此参数。
- **sampler** (Sampler，可选)：指定从数据集中选取样本的采样器（默认为None，下表中会展示不同配置的预期行为）。当前此数据集仅支持以下采样器：SubsetRandomSampler、PkSampler、RandomSampler、SequentialSampler和DistributedSampler。
- **padded_sample** (dict，可选): 指定额外添加到数据集的样本，可用于在分布式训练时补齐分片数据，注意字典的键名需要与 `column_list` 指定的列名相同。
- **num_padded** (int，可选)：指定额外添加的数据集样本的数量。在分布式训练时可用于为数据集补齐样本，使得总样本数量可被 `num_shards` 整除。
- **num_samples** (int，可选)：指定从数据集中读取的样本数（默认值为None，表示所有样本)。
- **cache** (DatasetCache, 可选)：数据缓存客户端实例，用于加快数据集处理速度（默认为None，不使用缓存）。
**异常：**
- **RuntimeError**：参数`dataset_files`无效或不存在。
- **RuntimeError**：参数`num_parallel_workers`超过最大线程数。
- **RuntimeError**：指定了`num_shards`，但`shard_id`为None。
- **RuntimeError**：指定了`shard_id`，但`num_shards`为None。
- **ValueError**: `shard_id`参数错误（小于0或者大于等于 `num_shards`）。
**注：**
- 此数据集可以指定`sampler`参数，但`sampler` 和 `shuffle` 是互斥的。下表展示了几种合法的输入参数及预期的行为。
- **RuntimeError**：参数 `dataset_files` 无效或不存在。
- **RuntimeError**：参数 `num_parallel_workers` 超过最大线程数。
- **RuntimeError**：指定了 `num_shards` ，但 `shard_id` 为None。
- **RuntimeError**：指定了 `shard_id` ，但 `num_shards` 为None。
- **ValueError**: `shard_id` 参数错误（小于0或者大于等于 `num_shards` ）。
.. list-table:: 配置`sampler`和`shuffle`的不同组合得到的预期排序结果
.. note:: 此数据集可以指定 `sampler` 参数，但 `sampler` 和 `shuffle` 是互斥的。下表展示了几种合法的输入参数及预期的行为。
.. list-table:: 配置 `sampler` 和 `shuffle` 的不同组合得到的预期排序结果
:widths: 25 25 50
:header-rows: 1
* - 参数`sampler`
- 参数`shuffle`
* - 参数 `sampler`
- 参数 `shuffle`
- 预期数据顺序
* - None
- None
@ -52,16 +50,25 @@ Class mindspore.dataset.MindDataset(dataset_file, columns_list=None, num_paralle
* - None
- False
- 顺序排列
* - 参数`sampler`
* - 参数 `sampler`
- None
- 由`sampler`行为定义的顺序
* - 参数`sampler`
- 由 `sampler` 行为定义的顺序
* - 参数 `sampler`
- True
- 不允许
* - 参数`sampler`
* - 参数 `sampler`
- False
- 不允许
**样例：**
>>> mind_dataset_dir = ["/path/to/mind_dataset_file"] # 此列表可以包含1个或多个MindRecord文件
>>> dataset = ds.MindDataset(dataset_file=mind_dataset_dir)
>>> mind_dataset_dir = ["/path/to/mind_dataset_file"] # 此列表可以包含1个或多个MindRecord文件
>>> dataset = ds.MindDataset(dataset_file=mind_dataset_dir)
.. include:: mindspore.dataset.Dataset.add_sampler.rst
.. include:: mindspore.dataset.Dataset.rst
.. include:: mindspore.dataset.Dataset.use_sampler.rst
.. include:: mindspore.dataset.Dataset.zip.rst

8
docs/api/api_python/dataset/mindspore.dataset.MnistDataset.rst
View File

@ -94,4 +94,10 @@ mindspore.dataset.MnistDataset
howpublished = {http://yann.lecun.com/exdb/mnist}
}
.. include:: mindspore.dataset.Dataset.rst
.. include:: mindspore.dataset.Dataset.add_sampler.rst
.. include:: mindspore.dataset.Dataset.rst
.. include:: mindspore.dataset.Dataset.use_sampler.rst
.. include:: mindspore.dataset.Dataset.zip.rst

6
docs/api/api_python/dataset/mindspore.dataset.NumpySlicesDataset.rst
View File

@ -73,4 +73,10 @@ mindspore.dataset.NumpySlicesDataset
>>> df = pd.read_csv(filepath_or_buffer=csv_dataset_dir[0])
>>> dataset = ds.NumpySlicesDataset(data=dict(df), shuffle=False)
.. include:: mindspore.dataset.Dataset.add_sampler.rst
.. include:: mindspore.dataset.Dataset.rst
.. include:: mindspore.dataset.Dataset.use_sampler.rst
.. include:: mindspore.dataset.Dataset.zip.rst

6
docs/api/api_python/dataset/mindspore.dataset.PaddedDataset.rst
View File

@ -21,4 +21,10 @@ mindspore.dataset.PaddedDataset
>>> data = [{'image': np.zeros(1, np.uint8)}, {'image': np.zeros(2, np.uint8)}]
>>> dataset = ds.PaddedDataset(padded_samples=data)
.. include:: mindspore.dataset.Dataset.add_sampler.rst
.. include:: mindspore.dataset.Dataset.rst
.. include:: mindspore.dataset.Dataset.use_sampler.rst
.. include:: mindspore.dataset.Dataset.zip.rst

89
docs/api/api_python/dataset/mindspore.dataset.TFRecordDataset.rst
View File

@ -1,53 +1,54 @@
mindspore.dataset.TFRecordDataset
=================================
Class mindspore.dataset.TFRecordDataset(dataset_files, schema=None, columns_list=None, num_samples=None, num_parallel_workers=None, shuffle=<Shuffle.GLOBAL: 'global'>, num_shards=None, shard_id=None, shard_equal_rows=False, cache=None)
.. py:class:: mindspore.dataset.TFRecordDataset(dataset_files, schema=None, columns_list=None, num_samples=None, num_parallel_workers=None, shuffle=<Shuffle.GLOBAL: 'global'>, num_shards=None, shard_id=None, shard_equal_rows=False, cache=None)
读取和解析以TFData格式存储的数据集文件作为源数据集。
生成的数据集的列名和列类型取决于TFRecord文件中的保存的列名与类型。
读取和解析以TFData格式存储的数据集文件作为源数据集。生成的数据集的列名和列类型取决于TFRecord文件中的保存的列名与类型。
**参数：**
- **dataset_files** (Union[str, list[str]])：数据集文件路径，支持单文件路径字符串、多文件路径字符串列表或可被glob库模式匹配的字符串，文件列表将在内部进行字典排序。
- **schema** (Union[str, Schema]，可选)：读取模式策略，用于指定读取数据列的数据类型、数据维度等信息。
支持传入JSON文件或`Schema`对象的路径（默认为None，将使用TFData文件中的元数据构造`Schema`对象）。
- **columns_list** (list[str]，可选)：指定从TFRecord文件中读取的数据列（默认为None，读取所有列）。
- **num_samples** (int，可选)：指定从数据集中读取的样本数（默认为None）。
如果`num_samples`为None，并且numRows字段（由参数`schema`定义）不存在，则读取所有数据集；
如果`num_samples`为None，并且numRows字段（由参数`schema`定义）的值大于0，则读取numRows条数据；
如果`num_samples`和numRows字段（由参数`schema`定义）的值都大于0，仅有参数`num_samples`生效且读取给定数量的数据。
- **num_parallel_workers** (int，可选)：指定读取数据的工作线程数（默认值None，即使用mindspore.dataset.config中配置的线程数）。
- **shuffle** (Union[bool, Shuffle level], 可选)：每个epoch中数据混洗的模式（默认为为mindspore.dataset.Shuffle.GLOBAL）。
如果为False，则不混洗；如果为True，等同于将`shuffle`设置为mindspore.dataset.Shuffle.GLOBAL。另外也可以传入枚举变量设置shuffle级别：
- Shuffle.GLOBAL：混洗文件和样本。
- Shuffle.FILES：仅混洗文件。
- **num_shards** (int, 可选): 分布式训练时，将数据集划分成指定的分片数（默认值None）。指定此参数后，`num_samples` 表示每个分片的最大样本数。
- **shard_id** (int, 可选): 分布式训练时，指定使用的分片ID号（默认值None）。只有当指定了 `num_shards` 时才能指定此参数。
- **shard_equal_rows** (bool，可选)： 分布式训练时，为所有分片获取等量的数据行数（默认为False）。
如果`shard_equal_rows`为False，则可能会使得每个分片的数据条目不相等，从而导致分布式训练失败。
因此当每个TFRecord文件的数据数量不相等时，建议将此参数设置为True。注意，只有当指定了 `num_shards` 时才能指定此参数。
- **cache** (DatasetCache, 可选)：数据缓存客户端实例，用于加快数据集处理速度（默认为None，不使用缓存）。
- **dataset_files** (Union[str, list[str]])：数据集文件路径，支持单文件路径字符串、多文件路径字符串列表或可被glob库模式匹配的字符串，文件列表将在内部进行字典排序。
- **schema** (Union[str, Schema]，可选)：读取模式策略，用于指定读取数据列的数据类型、数据维度等信息。支持传入JSON文件或 `Schema` 对象的路径（默认为None，将使用TFData文件中的元数据构造 `Schema` 对象）。
- **columns_list** (list[str]，可选)：指定从TFRecord文件中读取的数据列（默认为None，读取所有列）。
- **num_samples** (int，可选)：指定从数据集中读取的样本数（默认为None）。如果 `num_samples` 为None，并且numRows字段（由参数 `schema` 定义）不存在，则读取所有数据集；如果 `num_samples` 为None，并且numRows字段（由参数 `schema` 定义）的值大于0，则读取numRows条数据；如果 `num_samples` 和numRows字段（由参数 `schema` 定义）的值都大于0，仅有参数 `num_samples` 生效且读取给定数量的数据。
- **num_parallel_workers** (int，可选)：指定读取数据的工作线程数（默认值None，即使用mindspore.dataset.config中配置的线程数）。
- **shuffle** (Union[bool, Shuffle level], 可选)：每个epoch中数据混洗的模式（默认为为mindspore.dataset.Shuffle.GLOBAL）。如果为False，则不混洗；如果为True，等同于将 `shuffle` 设置为mindspore.dataset.Shuffle.GLOBAL。另外也可以传入枚举变量设置shuffle级别：
- Shuffle.GLOBAL：混洗文件和样本。
- Shuffle.FILES：仅混洗文件。
- **num_shards** (int, 可选): 分布式训练时，将数据集划分成指定的分片数（默认值None）。指定此参数后，`num_samples` 表示每个分片的最大样本数。
- **shard_id** (int, 可选): 分布式训练时，指定使用的分片ID号（默认值None）。只有当指定了 `num_shards` 时才能指定此参数。
- **shard_equal_rows** (bool，可选)： 分布式训练时，为所有分片获取等量的数据行数（默认为False）。如果 `shard_equal_rows` 为False，则可能会使得每个分片的数据条目不相等，从而导致分布式训练失败。因此当每个TFRecord文件的数据数量不相等时，建议将此参数设置为True。注意，只有当指定了 `num_shards` 时才能指定此参数。
- **cache** (DatasetCache, 可选)：数据缓存客户端实例，用于加快数据集处理速度（默认为None，不使用缓存）。
**异常：**
- **RuntimeError**：参数`dataset_files`无效或不存在。
- **RuntimeError**：参数`num_parallel_workers`超过最大线程数。
- **RuntimeError**：指定了`num_shards`，但`shard_id`为None。
- **RuntimeError**：指定了`shard_id`，但`num_shards`为None。
- **ValueError**：参数`shard_id`无效（小于0或者大于等于`num_shards`）。
**示例：**
>>> from mindspore import dtype as mstype
>>>
>>> tfrecord_dataset_dir = ["/path/to/tfrecord_dataset_file"] # 此列表可以包含1个或多个TFRecord文件
>>> tfrecord_schema_file = "/path/to/tfrecord_schema_file"
>>>
>>> # 1) 从tfrecord_dataset_dir路径的文件读取数据集。
>>> # 由于未指定Schema，则将TFRecord文件数据的第一行的元数据将用作Schema。
>>> dataset = ds.TFRecordDataset(dataset_files=tfrecord_dataset_dir)
>>>
>>> # 2) 用户使用自定义的Schema从tfrecord_dataset_dir路径的文件读取数据集。
>>> schema = ds.Schema()
>>> schema.add_column(name='col_1d', de_type=mstype.int64, shape=[2])
>>> dataset = ds.TFRecordDataset(dataset_files=tfrecord_dataset_dir, schema=schema)
>>>
>>> # 3) 用户通过传入JSON文件构造Schema，从tfrecord_dataset_dir路径的文件读取数据集。
>>> dataset = ds.TFRecordDataset(dataset_files=tfrecord_dataset_dir, schema=tfrecord_schema_file)
- **RuntimeError**：参数 `dataset_files` 无效或不存在。
- **RuntimeError**：参数 `num_parallel_workers` 超过最大线程数。
- **RuntimeError**：指定了 `num_shards` ，但 `shard_id` 为None。
- **RuntimeError**：指定了 `shard_id` ，但 `num_shards` 为None。
- **ValueError**：参数 `shard_id` 无效（小于0或者大于等于 `num_shards` ）。
**样例：**
>>> from mindspore import dtype as mstype
>>>
>>> tfrecord_dataset_dir = ["/path/to/tfrecord_dataset_file"] # 此列表可以包含1个或多个TFRecord文件
>>> tfrecord_schema_file = "/path/to/tfrecord_schema_file"
>>>
>>> # 1) 从tfrecord_dataset_dir路径的文件读取数据集。
>>> # 由于未指定Schema，则将TFRecord文件数据的第一行的元数据将用作Schema。
>>> dataset = ds.TFRecordDataset(dataset_files=tfrecord_dataset_dir)
>>>
>>> # 2) 用户使用自定义的Schema从tfrecord_dataset_dir路径的文件读取数据集。
>>> schema = ds.Schema()
>>> schema.add_column(name='col_1d', de_type=mstype.int64, shape=[2])
>>> dataset = ds.TFRecordDataset(dataset_files=tfrecord_dataset_dir, schema=schema)
>>>
>>> # 3) 用户通过传入JSON文件构造Schema，从tfrecord_dataset_dir路径的文件读取数据集。
>>> dataset = ds.TFRecordDataset(dataset_files=tfrecord_dataset_dir, schema=tfrecord_schema_file)
.. include:: mindspore.dataset.Dataset.rst
.. include:: mindspore.dataset.Dataset.zip.rst

45
docs/api/api_python/dataset/mindspore.dataset.TextFileDataset.rst
View File

@ -1,29 +1,36 @@
mindspore.dataset.TextFileDataset
==================================
Class mindspore.dataset.TextFileDataset(dataset_files, num_samples=None, num_parallel_workers=None, shuffle=<Shuffle.GLOBAL: 'global'>, num_shards=None, shard_id=None, cache=None)
.. py:class:: mindspore.dataset.TextFileDataset(dataset_files, num_samples=None, num_parallel_workers=None, shuffle=<Shuffle.GLOBAL: 'global'>, num_shards=None, shard_id=None, cache=None)
用于读取和解析文本格式的文件作为源数据集。
生成的数据集有一个数据列：py:obj:`[text]`，类型为string。
用于读取和解析文本格式的文件作为源数据集。生成的数据集有一个数据列: `[text]` ，类型为string。
**参数：**
- **dataset_files** (Union[str, list[str]])：数据集文件路径，支持单文件路径字符串、多文件路径字符串列表或可被glob库模式匹配的字符串，文件列表将在内部进行字典排序。
- **num_samples** (int，可选)：指定从数据集中读取的样本数（默认为None，即读取所有样本）。
- **num_parallel_workers** (int，可选)：指定读取数据的工作线程数(默认值None，即使用mindspore.dataset.config中配置的线程数）。
- **shuffle** (Union[bool, Shuffle level], 可选)：每个epoch中数据混洗的模式（默认为为mindspore.dataset.Shuffle.GLOBAL）。
如果为False，则不混洗；如果为True，等同于将`shuffle`设置为mindspore.dataset.Shuffle.GLOBAL。另外也可以传入枚举变量设置shuffle级别：
- Shuffle.GLOBAL：混洗文件和样本。
- Shuffle.FILES：仅混洗文件。
- **num_shards** (int, 可选)：指定分布式训练时将数据集进行划分的分片数（默认值None）。指定此参数后, `num_samples` 表示每个分片的最大样本数。
- **shard_id** (int, 可选)：指定分布式训练时使用的分片ID号（默认值None）。只有当指定了 `num_shards` 时才能指定此参数。
- **cache** (DatasetCache, 可选)：数据缓存客户端实例，用于加快数据集处理速度（默认为None，不使用缓存）。
- **dataset_files** (Union[str, list[str]])：数据集文件路径，支持单文件路径字符串、多文件路径字符串列表或可被glob库模式匹配的字符串，文件列表将在内部进行字典排序。
- **num_samples** (int，可选)：指定从数据集中读取的样本数（默认为None，即读取所有样本）。
- **num_parallel_workers** (int，可选)：指定读取数据的工作线程数(默认值None，即使用mindspore.dataset.config中配置的线程数）。
- **shuffle** (Union[bool, Shuffle level], 可选)：每个epoch中数据混洗的模式（默认为为mindspore.dataset.Shuffle.GLOBAL）。如果为False，则不混洗；如果为True，等同于将 `shuffle` 设置为mindspore.dataset.Shuffle.GLOBAL。另外也可以传入枚举变量设置shuffle级别：
- Shuffle.GLOBAL：混洗文件和样本。
- Shuffle.FILES：仅混洗文件。
- **num_shards** (int, 可选)：指定分布式训练时将数据集进行划分的分片数（默认值None）。指定此参数后, `num_samples` 表示每个分片的最大样本数。
- **shard_id** (int, 可选)：指定分布式训练时使用的分片ID号（默认值None）。只有当指定了 `num_shards` 时才能指定此参数。
- **cache** (DatasetCache, 可选)：数据缓存客户端实例，用于加快数据集处理速度（默认为None，不使用缓存）。
**异常：**
- **RuntimeError**：`dataset_files` 所指的文件无效或不存在。
- **RuntimeError**：`num_parallel_workers` 超过系统最大线程数。
- **RuntimeError**：指定了`num_shards`参数，但是未指定`shard_id`参数。
- **RuntimeError**：指定了`shard_id`参数，但是未指定`num_shards`参数。
- **RuntimeError**： `dataset_files` 所指的文件无效或不存在。
- **RuntimeError**： `num_parallel_workers` 超过系统最大线程数。
- **RuntimeError**：指定了 `num_shards` 参数，但是未指定 `shard_id` 参数。
- **RuntimeError**：指定了 `shard_id` 参数，但是未指定 `num_shards` 参数。
**样例：**
>>> text_file_dataset_dir = ["/path/to/text_file_dataset_file"] # # 此列表可以包含1个或多个文本文件
>>> dataset = ds.TextFileDataset(dataset_files=text_file_dataset_dir)
>>> text_file_dataset_dir = ["/path/to/text_file_dataset_file"] # # 此列表可以包含1个或多个文本文件
>>> dataset = ds.TextFileDataset(dataset_files=text_file_dataset_dir)
.. include:: mindspore.dataset.Dataset.rst
.. include:: mindspore.dataset.Dataset.zip.rst

14
docs/api/api_python/dataset/mindspore.dataset.VOCDataset.rst
View File

@ -15,8 +15,7 @@ mindspore.dataset.VOCDataset
- **dataset_dir** (str): 包含数据集文件的根目录的路径。
- **task** (str, 可选): 指定读取VOC数据的任务类型，现在只支持 `Segmentation` 或 `Detection` （默认值 `Segmentation` ）。
- **usage** (str, 可选): 指定数据集的子集（默认值 `train` ）。如果 `task` 参数为 `Segmentation` ，则将在./ImageSets/Segmentation/usage + ".txt"中加载数据集图像和标注信息；如果 `task` 参数为 `Detection` ，则将在./ImageSets/Main/usage + ".txt"中加载数据集图像和标注信息；如果未设置任务和用法，默认将加载./ImageSets/Segmentation/train.txt中的数据集图像和标注信息。
- **class_indexing** (dict, 可选): 指定标签名称到类标签的映射，要求映射规则为str到int，
仅在 `Detection` 任务中有效（默认值None，文件夹名称将按字母顺序排列，每类都有一个唯一的索引，从0开始)。
- **class_indexing** (dict, 可选): 指定标签名称到类标签的映射，要求映射规则为str到int，仅在 `Detection` 任务中有效（默认值None，文件夹名称将按字母顺序排列，每类都有一个唯一的索引，从0开始)。
- **num_samples** (int, 可选): 指定从数据集中读取的样本数（默认值为None，所有图像样本）。
- **num_parallel_workers** (int, 可选): 指定读取数据的工作线程数（默认值None，即使用mindspore.dataset.config中配置的线程数）。
- **shuffle** (bool, 可选): 是否混洗数据集（默认为None，下表中会展示不同配置的预期行为）。
@ -44,8 +43,7 @@ mindspore.dataset.VOCDataset
- **ValueError**: `shard_id` 参数错误（小于0或者大于等于 `num_shards` ）。
.. note::
- 当指定 `extra_metadata` 为True时，除非显式使用rename算子以删除元信息列明的前缀('_meta-')，
否则迭代的数据行中不会出现'[_meta-filename, dtype=string]'列。
- 当指定 `extra_metadata` 为True时，除非显式使用rename算子以删除元信息列明的前缀('_meta-')，否则迭代的数据行中不会出现'[_meta-filename, dtype=string]'列。
- 此数据集可以指定 `sampler` 参数，但 `sampler` 和 `shuffle` 是互斥的。下表展示了几种合法的输入参数及预期的行为。
.. list-table:: 配置 `sampler` 和 `shuffle` 的不同组合得到的预期排序结果
@ -144,4 +142,10 @@ mindspore.dataset.VOCDataset
howpublished = {http://host.robots.ox.ac.uk/pascal/VOC/voc2012/index.html}
}
.. include:: mindspore.dataset.Dataset.rst
.. include:: mindspore.dataset.Dataset.add_sampler.rst
.. include:: mindspore.dataset.Dataset.rst
.. include:: mindspore.dataset.Dataset.use_sampler.rst
.. include:: mindspore.dataset.Dataset.zip.rst

3
docs/api/api_python/dataset/mindspore.dataset.WaitedDSCallback.rst
View File

@ -41,8 +41,7 @@ mindspore.dataset.WaitedDSCallback
.. py:method:: ds_epoch_begin(ds_run_context)
内部方法，不能被调用或者重写。通过重写mindspore.dataset.DSCallback.ds_epoch_begin
实现与mindspore.train.callback.Callback.epoch_end回调同步。
内部方法，不能被调用或者重写。通过重写mindspore.dataset.DSCallback.ds_epoch_begin 实现与mindspore.train.callback.Callback.epoch_end回调同步。
**参数：**

26
docs/api/api_python/dataset/mindspore.dataset.build_sentencepiece_vocab.rst
View File

@ -1,26 +0,0 @@
.. py:method:: build_sentencepiece_vocab(columns, vocab_size, character_coverage, model_type, params)
用于从源数据集对象创建句子词表的函数。
**参数：**
- **columns** (list[str])：指定从哪一列中获取单词。
- **vocab_size** (int)：词汇表大小。
- **character_coverage** (int)：模型涵盖的字符百分比，必须介于0.98和1.0之间。默认值如0.9995，适用于具有丰富字符集的语言，如日语或中文字符集；1.0适用于其他字符集较小的语言，比如英语或拉丁文。
- **model_type** (SentencePieceModel)：模型类型，枚举值包括unigram（默认值）、bpe、char及word。当类型为word时，输入句子必须预先标记。
- **params** (dict)：依据原始数据内容构建祠表的附加参数，无附加参数时取值可以是空字典。
**返回：**
SentencePieceVocab，从数据集构建的词汇表。
**样例：**
>>> from mindspore.dataset.text import SentencePieceModel
>>>
>>> # DE_C_INTER_SENTENCEPIECE_MODE 是一个映射字典
>>> from mindspore.dataset.text.utils import DE_C_INTER_SENTENCEPIECE_MODE
>>> dataset = ds.TextFileDataset("/path/to/sentence/piece/vocab/file", shuffle=False)
>>> dataset = dataset.build_sentencepiece_vocab(["text"], 5000, 0.9995,
... DE_C_INTER_SENTENCEPIECE_MODE[SentencePieceModel.UNIGRAM],
... {})

8
docs/api/api_python/dataset/mindspore.dataset.cifar100dataset.rst
View File

@ -96,4 +96,10 @@ mindspore.dataset.Cifar100Dataset
howpublished = {http://www.cs.toronto.edu/~kriz/cifar.html}
}
.. include:: mindspore.dataset.Dataset.rst
.. include:: mindspore.dataset.Dataset.add_sampler.rst
.. include:: mindspore.dataset.Dataset.rst
.. include:: mindspore.dataset.Dataset.use_sampler.rst
.. include:: mindspore.dataset.Dataset.zip.rst

8
docs/api/api_python/dataset/mindspore.dataset.cifar10dataset.rst
View File

@ -103,4 +103,10 @@ mindspore.dataset.Cifar10Dataset
howpublished = {http://www.cs.toronto.edu/~kriz/cifar.html}
}
.. include:: mindspore.dataset.Dataset.rst
.. include:: mindspore.dataset.Dataset.add_sampler.rst
.. include:: mindspore.dataset.Dataset.rst
.. include:: mindspore.dataset.Dataset.use_sampler.rst
.. include:: mindspore.dataset.Dataset.zip.rst

18
docs/api/api_python/dataset/mindspore.dataset.rst
View File

@ -1,18 +0,0 @@
mindspore.dataset
该模块提供了加载和处理各种通用数据集的API，如MNIST、CIFAR-10、CIFAR-100、VOC、COCO、ImageNet、CelebA、CLUE等，
也支持加载业界标准格式的数据集，包括MindRecord、TFRecord、Manifest等。此外，用户还可以使用此模块定义和加载自己的数据集。
该模块还提供了在加载时进行数据采样的API，如SequentialSample、RandomSampler、DistributedSampler等。
大多数数据集可以通过指定参数`cache`启用缓存服务，以提升整体数据处理效率。
请注意Windows平台上还不支持缓存服务，因此在Windows上加载和处理数据时，请勿使用。更多介绍和限制，
请参考`Single-Node Tensor Cache <https://www.mindspore.cn/docs/programming_guide/zh-CN/master/cache.html>`_。
在API示例中，常用的模块导入方法如下：
.. code-block::
import mindspore.dataset as ds
from mindspore.dataset.transforms import c_transforms

77
docs/api/api_python/mindspore.context_ps.txt
View File

@ -1,77 +0,0 @@
get_ps_context(attr_key)
根据key获取参数服务器训练模式上下文中的属性值。
参数：
attr_key (str)：属性的key。
- enable_ps (bool)：表示是否启用参数服务器训练模式。
- config_file_path (string)：配置文件路径，用于容灾恢复等。
- scheduler_manage_port (int)：调度器HTTP端口，对外开放用于接收和处理用户扩容/缩容等请求。
- enable_ssl (bool)：设置是否打开SSL认证。
- client_password (str)：用于解密客户端证书密钥的密码。
- server_password (str)：用于解密服务端证书密钥的密码。
返回：
根据key返回属性值。
异常：
ValueError：输入key不是参数服务器训练模式上下文中的属性。
样例：
>>> context.get_ps_context(enable_ps)
reset_ps_context()
将参数服务器训练模式上下文中的属性重置为默认值。各字段的含义及其默认值见'set_ps_context'接口。
样例：
>>> context.reset_ps_context()
set_ps_context(**kwargs)
设置参数服务器训练模式的上下文。
注：
需要给参数服务器训练模式设置其他的环境变量。
这些环境变量如下所示：
MS_SERVER_NUM：表示参数服务器数量。
MS_WORKER_NUM：表示工作进程数量。
MS_SCHED_HOST：表示调度器IP地址。
MS_SCHED_PORT：表示调度器开启的监听端口。
MS_ROLE：表示进程角色，角色列表如下：
MS_SCHED：表示调度器。
MS_WORKER：表示工作进程。
MS_PSERVER/MS_SERVER：表示参数服务器。
参数：
enable_ps (bool)：表示是否启用参数服务器训练模式。
只有在enable_ps设置为True后，环境变量才会生效。
默认值：False。
config_file_path (string)：配置文件路径，用于容灾恢复等。
默认值：''。
scheduler_manage_port (int)：调度器HTTP端口，对外开放用于接收和处理用户扩容/缩容等请求。
默认值：11202。
enable_ssl (bool)：设置是否打开SSL认证。
默认值：True。
client_password (str)：用于解密客户端证书密钥的密码。
默认值：''。
server_password (str)：用于解密服务端证书密钥的密码。
默认值：''。
异常：
ValueError：输入key不是参数服务器训练模式上下文中的属性。
样例：
>>> context.set_ps_context(enable_ps=True, enable_ssl=True, client_password='123456', server_password='123456')

431
docs/api/api_python/mindspore/mindspore.context.txt
View File

@ -1,33 +1,18 @@
mindspore.context
=================
.. py:class:: mindspore.context
MindSpore上下文，用于配置当前执行环境，包括执行模式、执行后端和其他特性开关。
get_context(attr_key)
根据输入key获取上下文中的属性值。
如果某些属性没有设置，则会自动获取这些属性。
参数：
attr_key (str)：属性的key。
返回：
Object，表示给定属性key的值。
异常：
ValueError：输入key不是上下文中的属性。
样例：
>>> context.get_context("device_target")
>>> context.get_context("device_id")
set_context(**kwargs)
.. py:function:: set_context(**kwargs)
设置运行环境的上下文。
在运行程序之前，应配置上下文。如果没有配置，默认情况下将根据设备目标进行自动设置。
注：
设置属性时，必须输入属性名称。
初始化网络后不建议更改模式，因为某些操作在图模式和PyNative模式下是不同的。默认值：GRAPH_MODE。
.. note::
设置属性时，必须输入属性名称。初始化网络后不建议更改模式，因为某些操作在图模式和PyNative模式下是不同的。默认值：GRAPH_MODE。
某些配置适用于特定的设备，有关详细信息，请参见下表：
@ -87,133 +72,309 @@ set_context(**kwargs)
| | load_compile_cache | CPU/GPU/Ascend |
+-------------------------+------------------------------+----------------------------+
参数：
device_id (int)：表示目标设备的ID，其值必须在[0, device_num_per_host-1]范围中，且device_num_per_host的值不应超过4096。默认值：0。
device_target (str)：表示待运行的目标设备，支持Ascend、GPU和CPU。
如果未设置设备目标，则使用MindSpore包的版本。
max_device_memory (str)：设置设备可用的最大内存。
目前，仅在GPU上支持。格式为“xxGB”。默认值：1024GB。
实际使用的内存大小是设备的可用内存和max_device_memory值中的最小值。
variable_memory_max_size (str)：设置可变内存的最大值。默认值：30GB。
设置此参数后，框架使用的最大内存受配置值的限制。
save_graphs (bool)：表示是否保存图形。默认值：False。
当`save_graphs`属性设为True时，`save_graphs_path`属性用于设置中间编译图的存储路径。默认情况下，图形保存在当前目录下。
save_graphs_path (str)：表示保存图形的路径。默认值："."。
如果指定的目录不存在，系统将自动创建该目录。
在分布式训练中，图形将被保存到`save_graphs_path/rank_${rank_id}/`目录下。`rank_id`为集群中当前设备的ID。
enable_dump (bool)：此参数已弃用，将在下一版本中删除。
save_dump_path (str)：此参数已弃用，将在下一版本中删除。
enable_profiling (bool)：此参数已弃用，将在下一版本中删除。
请使用mindspore.profiler.Profiler API。
profiling_options (str)：此参数已弃用，将在下一版本中删除。
请使用mindspore.profiler.Profiler API。
print_file_path (str)：表示用于保存打印数据的路径。如果设置了该参数，默认将打印数据保存到文件中。如果不设置print_file_path，则显示该屏幕。
如果保存的文件已经存在，将添加时间戳后缀到文件中。将数据保存到文件中，解决了在产生大量数据时屏幕打印中数据丢失的问题。
如果没有设置该参数，则会报错：prompt to set the upper absolute path。
env_config_path (str)：通过context.set_context(env_config_path="./mindspore_config.json")来配置DFX的路径。
**参数：**
- **device_id** (int)：表示目标设备的ID，其值必须在[0, device_num_per_host-1]范围中，且 `device_num_per_host` 的值不应超过4096。默认值：0。
- **device_target** (str)：表示待运行的目标设备，支持Ascend、GPU和CPU。如果未设置设备目标，则使用MindSpore包的版本。
- **max_device_memory** (str)：设置设备可用的最大内存。目前，仅在GPU上支持。格式为“xxGB”。默认值：1024GB。实际使用的内存大小是设备的可用内存和 `max_device_memory` 值中的最小值。
- **variable_memory_max_size** (str)：设置可变内存的最大值。默认值：30GB。设置此参数后，框架使用的最大内存受配置值的限制。
- **save_graphs** (bool)：表示是否保存图形。默认值：False。当 `save_graphs` 属性设为True时， `save_graphs_path` 属性用于设置中间编译图的存储路径。默认情况下，图形保存在当前目录下。
- **save_graphs_path** (str)：表示保存图形的路径。默认值："."。如果指定的目录不存在，系统将自动创建该目录。在分布式训练中，图形将被保存到 `save_graphs_path/rank_${rank_id}/` 目录下。 `rank_id` 为集群中当前设备的ID。
- **enable_dump** (bool)：此参数已弃用，将在下一版本中删除。
- **save_dump_path** (str)：此参数已弃用，将在下一版本中删除。
- **enable_profiling** (bool)：此参数已弃用，将在下一版本中删除。请使用mindspore.profiler.Profiler API。
- **profiling_options** (str)：此参数已弃用，将在下一版本中删除。请使用mindspore.profiler.Profiler API。
- **print_file_path** (str)：表示用于保存打印数据的路径。如果设置了该参数，默认将打印数据保存到文件中。如果不设置 `print_file_path` ，则显示该屏幕。如果保存的文件已经存在，将添加时间戳后缀到文件中。将数据保存到文件中，解决了在产生大量数据时屏幕打印中数据丢失的问题。如果没有设置该参数，则会报错：prompt to set the upper absolute path。
- **env_config_path** (str)：通过context.set_context(env_config_path="./mindspore_config.json")来配置DFX的路径。
配置Running Data Recorder：
配置Running Data Recorder：
- **enable**：表示在发生故障时是否启用Running Data Recorder去收集和保存训练中的关键数据。设置为True时，将打开Running Data Recorder。设置为False时，将关闭Running Data Recorder。
- **path**：设置Running Data Recorder保存数据的路径。当前路径必须是一个绝对路径。
- enable：表示在发生故障时是否启用Running Data Recorder去收集和保存训练中的关键数据。设置为True时，将打开Running Data Recorder。
设置为False时，将关闭Running Data Recorder。
- path：设置Running Data Recorder保存数据的路径。当前路径必须是一个绝对路径。
内存重用：
内存重用：
- **mem_Reuse**：表示内存复用功能是否打开。设置为True时，将打开内存复用功能。设置为False时，将关闭内存复用功能。
- mem_Reuse：表示内存复用功能是否打开。设置为True时，将打开内存复用功能。设置为False时，将关闭内存复用功能。
- **precompile_only** (bool)：表示是否仅预编译网络。默认值：False。设置为True时，仅编译网络，而不执行网络。
- **reserve_class_name_in_scope** (bool)：表示是否将网络类名称保存到所属作用域中。默认值：True。每个节点都有一个作用域。子节点的作用域是其父节点。如果 `reserve_class_name_in_scope` 设置为True，则类名将保存在作用域中的关键字“net-”之后。例如：
precompile_only (bool)：表示是否仅预编译网络。默认值：False。
设置为True时，仅编译网络，而不执行网络。
reserve_class_name_in_scope (bool)：表示是否将网络类名称保存到所属作用域中。默认值：True。
每个节点都有一个作用域。子节点的作用域是其父节点。如果reserve_class_name_in_scope设置为True，则类名将保存在作用域中的关键字“net-”之后。
例如：
Default/net-Net1/net-Net2 (reserve_class_name_in_scope=True)
Default/net-Net1/net-Net2 (reserve_class_name_in_scope=True)
Default/net/net (reserve_class_name_in_scope=False)
Default/net/net (reserve_class_name_in_scope=False)
- **pynative_synchronize** (bool)：表示是否在PyNative模式下启动设备同步执行。默认值：False。设置为False时，将在设备上异步执行算子。当算子执行出错时，将无法定位特定错误脚本代码的位置。当设置为True时，将在设备上同步执行算子。这将降低程序的执行性能。此时，当算子执行出错时，可以根据错误的调用栈来定位错误脚本代码的位置。
- **mode** (int)：表示在GRAPH_MODE(0)或PYNATIVE_MODE(1)模式中的运行。默认值：GRAPH_MODE(0)。GRAPH_MODE或PYNATIVE_MODE可以通过 `mode` 属性设置，两种模式都支持所有后端。默认模式为GRAPH_MODE。
- **enable_graph_kernel** (bool)：表示是否启用图算融合去优化网络执行性能。默认值：False。表示是否启用图算融合去优化网络执行性能。如果 `enable_graph_kernel` 设置为True，则可以启用加速。有关图算融合的详细信息，请查看`使能图算融合`（https://www.mindspore.cn/docs/programming_guide/zh-CN/master/enable_graph_kernel_fusion.html）。
- **graph_kernel_flags** (str)：图算融合的优化选项，当与enable_graph_kernel冲突时，它的优先级更高。其仅适用于有经验的用户。例如，context.set_context(graph_kernel_flags="--opt_level=2 --dump_as_text")。一些常用选项：
pynative_synchronize (bool)：表示是否在PyNative模式下启动设备同步执行。
默认值：False。设置为False时，将在设备上异步执行算子。
当算子执行出错时，将无法定位特定错误脚本代码的位置。当设置为True时，将在设备上同步执行算子。这将降低程序的执行性能。此时，当算子执行出错时，可以根据错误的调用栈来定位错误脚本代码的位置。
mode (int)：表示在GRAPH_MODE(0)或PYNATIVE_MODE(1)模式中的运行。默认值：GRAPH_MODE(0)。
GRAPH_MODE或PYNATIVE_MODE可以通过`mode`属性设置，两种模式都支持所有后端。默认模式为GRAPH_MODE。
enable_graph_kernel (bool)：表示是否启用图算融合去优化网络执行性能。
默认值：False。
表示是否启用图算融合去优化网络执行性能。
如果enable_graph_kernel设置为True，则可以启用加速。
有关图算融合的详细信息，请查看`使能图算融合`（https://www.mindspore.cn/docs/programming_guide/zh-CN/master/enable_graph_kernel_fusion.html）。
graph_kernel_flags (str) –
图算融合的优化选项，当与enable_graph_kernel冲突时，它的优先级更高。其仅适用于有经验的用户。
例如，context.set_context(graph_kernel_flags="--opt_level=2 --dump_as_text")。一些常用选项：
- **opt_level**：设置优化级别。默认值：2。当opt_level的值大于0时，启动图算融合。可选值包括：
- opt_level：设置优化级别。
默认值：2。当opt_level的值大于0时，启动图算融合。
可选值包括：
- 0：关闭图算融合。
- 1：启动算子的基本融合。
- 2：包括级别1的所有优化，并打开更多的优化，如CSE优化算法、算术简化等。
- 3：包括级别2的所有优化，并打开更多的优化，如SitchingFusion、ParallelFusion等。在某些场景下，该级别的优化激进且不稳定。使用此级别时要小心。
- 0：关闭图算融合。
- 1：启动算子的基本融合。
- 2：包括级别1的所有优化，并打开更多的优化，如CSE优化算法、算术简化等。
- 3：包括级别2的所有优化，并打开更多的优化，如SitchingFusion、ParallelFusion等。
在某些场景下，该级别的优化激进且不稳定。使用此级别时要小心。
- **dump_as_text**：将详细信息转储为文本文件。默认值：False。
- dump_as_text：将详细信息转储为文本文件。默认值：False。
有关更多选项，可以参考实现代码。
有关更多选项，可以参考实现代码。
enable_reduce_precision (bool)：表示是否开启降低精度计算。默认值：True。
设置为True时，不支持用户指定的精度，且精度将自动更改。
设置为False时，如果未指定用例的精度，则会报错并退出。
auto_tune_mode (str)：表示算子构建时的自动调整模式，以获得最佳的切分性能。
默认值：NO_TUNE。其值必须在【'RL', 'GA', 'RL,GA'】范围中。
- **enable_reduce_precision** (bool)：表示是否开启降低精度计算。默认值：True。设置为True时，不支持用户指定的精度，且精度将自动更改。设置为False时，如果未指定用例的精度，则会报错并退出。
- **auto_tune_mode** (str)：表示算子构建时的自动调整模式，以获得最佳的切分性能。默认值：NO_TUNE。其值必须在['RL', 'GA', 'RL,GA']范围中。
- RL：强化学习调优。
- GA：遗传算法调优。
- RL，GA：当RL和GA优化同时打开时，工具会根据网络模型中的不同算子类型自动选择RL或GA。RL和GA的顺序没有区别。
（自动选择）。
- RL：强化学习调优。
- GA：遗传算法调优。
- RL，GA：当RL和GA优化同时打开时，工具会根据网络模型中的不同算子类型自动选择RL或GA。RL和GA的顺序没有区别。（自动选择）。
有关启用算子调优工具设置的更多信息，请查看`使能算子调优工具`（https://www.mindspore.cn/docs/programming_guide/zh-CN/master/enable_auto_tune.html）。
check_bprop (bool)：表示是否检查反向传播节点，以确保反向传播节点输出的形状(shape)和数据类型与输入参数相同。默认值：False。
max_call_depth (int)：指定函数调用的最大深度。其值必须为正整数。默认值：1000。
当嵌套Cell太深或子图数量太多时，需要设置max_call_depth参数。如果max_call_depth的值比以前的大，则应把系统最大堆栈深度设得更大，否则可能会因为系统堆栈溢出而引发`core dumped`异常。
enable_sparse (bool)：表示是否启用稀疏特征。默认值：False。
有关稀疏特征和稀疏张量的详细信息，请查看`稀疏张量`（https://www.mindspore.cn/docs/programming_guide/zh-CN/master/tensor.html#sparse-tensor）。
grad_for_scalar (bool)： 表示是否获取标量梯度。默认值：False。
当grad_for_scalar设置为True时，则衍生函数的标量输入。
默认值为False。由于后端目前不支持伸缩操作，所以该接口只支持在前端可推演的简单操作。
enable_compile_cache (bool)：表示是否加载或者保存前端编译的图。当enable_compile_cache被设置为True时，在第一次执行的过程中，一个硬件无关的编译缓存会被生成并且导出为一个MINDIR文件。
当该网络被再次执行时，如果enable_compile_cache仍然为True并且网络脚本没有被更改，那么这个编译缓存会被加载。注意目前只支持有限的Python脚本更改的自动检测，这意味着可能有正确性风险。默认值：False。
这是一个实验原型，可能会被更改或者删除。
compile_cache_path (str)：保存前端图编译缓存的路径。默认值："."。如果目录不存在，系统会自动创建这个目录。缓存会被保存到如下目录：`compile_cache_path/rank_${rank_id}/`。
`rank_id`是集群上当前设备的ID。
有关启用算子调优工具设置的更多信息，请查看 `使能算子调优工具 <https://www.mindspore.cn/docs/programming_guide/zh-CN/master/enable_auto_tune.html>`_。
异常：
ValueError：输入key不是上下文中的属性。
- **check_bprop** (bool)：表示是否检查反向传播节点，以确保反向传播节点输出的形状(shape)和数据类型与输入参数相同。默认值：False。
- **max_call_depth** (int)：指定函数调用的最大深度。其值必须为正整数。默认值：1000。当嵌套Cell太深或子图数量太多时，需要设置 `max_call_depth` 参数。如果 `max_call_depth` 的值比以前的大，则应把系统最大堆栈深度设得更大，否则可能会因为系统堆栈溢出而引发 `core dumped` 异常。
- **enable_sparse** (bool)：表示是否启用稀疏特征。默认值：False。有关稀疏特征和稀疏张量的详细信息，请查看 `稀疏张量 <https://www.mindspore.cn/docs/programming_guide/zh-CN/master/tensor.html#sparse-tensor>`_。
- **grad_for_scalar** (bool)： 表示是否获取标量梯度。默认值：False。当 `grad_for_scalar` 设置为True时，则衍生函数的标量输入。默认值为False。由于后端目前不支持伸缩操作，所以该接口只支持在前端可推演的简单操作。
- **enable_compile_cache** (bool)：表示是否加载或者保存前端编译的图。当 `enable_compile_cache` 被设置为True时，在第一次执行的过程中，一个硬件无关的编译缓存会被生成并且导出为一个MINDIR文件。当该网络被再次执行时，如果 `enable_compile_cache` 仍然为True并且网络脚本没有被更改，那么这个编译缓存会被加载。注意目前只支持有限的Python脚本更改的自动检测，这意味着可能有正确性风险。默认值：False。这是一个实验原型，可能会被更改或者删除。
- **compile_cache_path** (str)：保存前端图编译缓存的路径。默认值："."。如果目录不存在，系统会自动创建这个目录。缓存会被保存到如下目录：`compile_cache_path/rank_${rank_id}/`。`rank_id` 是集群上当前设备的ID。
样例：
>>> context.set_context(mode=context.PYNATIVE_MODE)
>>> context.set_context(precompile_only=True)
>>> context.set_context(device_target="Ascend")
>>> context.set_context(device_id=0)
>>> context.set_context(save_graphs=True, save_graphs_path="./model.ms")
>>> context.set_context(enable_reduce_precision=True)
>>> context.set_context(enable_dump=True, save_dump_path=".")
>>> context.set_context(enable_graph_kernel=True)
>>> context.set_context(graph_kernel_flags="--opt_level=2 --dump_as_text")
>>> context.set_context(reserve_class_name_in_scope=True)
>>> context.set_context(variable_memory_max_size="6GB")
>>> context.set_context(enable_profiling=True,
... profiling_options='{"output":"/home/data/output","training_trace":"on"}')
>>> context.set_context(check_bprop=True)
>>> context.set_context(max_device_memory="3.5GB")
>>> context.set_context(print_file_path="print.pb")
>>> context.set_context(enable_sparse=True)
>>> context.set_context(max_call_depth=80)
>>> context.set_context(env_config_path="./env_config.json")
>>> context.set_context(auto_tune_mode="GA,RL")
>>> context.set_context(grad_for_scalar=True)
>>> context.set_context(save_compile_cache=True)
>>> context.set_context(load_compile_cache=True)
>>> context.set_context(pynative_synchronize=True)
**异常：**
**ValueError**：输入key不是上下文中的属性。
**样例：**
>>> context.set_context(mode=context.PYNATIVE_MODE)
>>> context.set_context(precompile_only=True)
>>> context.set_context(device_target="Ascend")
>>> context.set_context(device_id=0)
>>> context.set_context(save_graphs=True, save_graphs_path="./model.ms")
>>> context.set_context(enable_reduce_precision=True)
>>> context.set_context(enable_dump=True, save_dump_path=".")
>>> context.set_context(enable_graph_kernel=True)
>>> context.set_context(graph_kernel_flags="--opt_level=2 --dump_as_text")
>>> context.set_context(reserve_class_name_in_scope=True)
>>> context.set_context(variable_memory_max_size="6GB")
>>> context.set_context(enable_profiling=True,
... profiling_options='{"output":"/home/data/output","training_trace":"on"}')
>>> context.set_context(check_bprop=True)
>>> context.set_context(max_device_memory="3.5GB")
>>> context.set_context(print_file_path="print.pb")
>>> context.set_context(enable_sparse=True)
>>> context.set_context(max_call_depth=80)
>>> context.set_context(env_config_path="./env_config.json")
>>> context.set_context(auto_tune_mode="GA,RL")
>>> context.set_context(grad_for_scalar=True)
>>> context.set_context(save_compile_cache=True)
>>> context.set_context(load_compile_cache=True)
>>> context.set_context(pynative_synchronize=True)
.. py:function:: get_context(attr_key)
根据输入key获取上下文中的属性值。如果某些属性没有设置，则会自动获取这些属性。
**参数：**
**attr_key** (str)：属性的key。
**返回：**
Object，表示给定属性key的值。
**异常：**
**ValueError**：输入key不是上下文中的属性。
**样例：**
>>> context.get_context("device_target")
>>> context.get_context("device_id")
.. py:function:: set_auto_parallel_context(**kwargs)
配置自动并行，仅在Ascend和GPU上有效。
应在init之前配置自动并行。
.. note::
配置时，必须输入配置的名称。如果某个程序具有不同并行模式下的任务，则需要再为下一个任务设置新的并行模式之前，调用reset_auto_parallel_context()接口来重置配置。若要设置或更改并行模式，必须在创建任何Initializer之前调用接口，否则，在编译网络时，可能会出现RuntimeError。
某些配置适用于特定的并行模式，有关详细信息，请参见下表：
=========================== ===========================
Common AUTO_PARALLEL
=========================== ===========================
device_num gradient_fp32_sync
global_rank loss_repeated_mean
gradients_mean auto_parallel_search_mode
parallel_mode strategy_ckpt_load_file
all_reduce_fusion_config strategy_ckpt_save_file
enable_parallel_optimizer dataset_strategy
\ pipeline_stages
\ grad_accumulation_step
=========================== ===========================
**参数：**
- **device_num** (int)：表示可用设备的编号，必须在[1,4096]范围中。默认值：1。
- **global_rank** (int)：表示全局RANK的ID，必须在[0,4095]范围中。默认值：0。
- **gradients_mean** (bool)：表示是否在梯度的 AllReduce后执行平均算子。stand_alone不支持gradients_mean。默认值：False。
- **gradient_fp32_sync** (bool)：在FP32中运行梯度的 AllReduce。stand_alone、data_parallel和hybrid_parallel不支持gradient_fp32_sync。默认值：True。
- **parallel_mode** (str)：有五种并行模式，分别是stand_alone、data_parallel、hybrid_parallel、semi_auto_parallel和auto_parallel。默认值：stand_alone。
- stand_alone：单卡模式。
- data_parallel：数据并行模式。
- hybrid_parallel：手动实现数据并行和模型并行。
- semi_auto_parallel：半自动并行模式。
- auto_parallel：自动并行模式。
- **auto_parallel_search_mode** (str)：表示有两种策略搜索模式，分别是recursive_programming和dynamic_programming。默认值：dynamic_programming。
- recursive_programming：表示双递归搜索模式。
- dynamic_programming：表示动态规划搜索模式。
- **parameter_broadcast** (bool)：表示在训练前是否广播参数。在训练之前，为了使所有设备的网络初始化参数值相同，请将设备0上的参数广播到其他设备。不同并行模式下的参数广播不同。在data_parallel模式下，除layerwise_parallel属性为True的参数外，所有参数都会被广播。在hybrid_parallel、semi_auto_parallel和auto_parallel模式下，分段参数不参与广播。默认值：False。
- **strategy_ckpt_load_file** (str)：表示用于加载并行策略checkpoint的路径。默认值：''。
- **strategy_ckpt_save_file** (str)：表示用于保存并行策略checkpoint的路径。默认值：''。
- **full_batch** (bool)：如果在auto_parallel模式下加载整个batch数据集，则此参数应设置为True。默认值：False。目前不建议使用该接口，建议使用dataset_strategy来替换它。
- **dataset_strategy** (Union[str, tuple])：表示数据集分片策略。默认值：data_parallel。dataset_strategy="data_parallel"等于full_batch=False，dataset_strategy="full_batch"等于full_batch=True。对于通过模型并列策略加载到网络的数据集，如ds_stra ((1, 8)、(1, 8))，需要使用set_auto_parallel_context(dataset_strategy=ds_stra)。
- **enable_parallel_optimizer** (bool)：这是一个开发中的特性，它可以为数据并行训练对权重更新计算进行分片，以节省时间和内存。目前，自动和半自动并行模式支持Ascend和GPU中的所有优化器。数据并行模式仅支持Ascend中的`Lamb`和`AdamWeightDecay`。默认值：False。
- **all_reduce_fusion_config** (list)：通过参数索引设置 AllReduce 融合策略。仅支持ReduceOp.SUM和HCCL_WORLD_GROUP/NCCL_WORLD_GROUP。没有默认值。如果不设置，则关闭算子融合。
- **pipeline_stages** (int)：设置pipeline并行的阶段信息。这表明了设备如何单独分布在pipeline上。所有的设备将被划分为pipeline_stags个阶段。目前，这只能在启动semi_auto_parallel模式的情况下使用。默认值：1。
- **grad_accumulation_step** (int)：在自动和半自动并行模式下设置梯度的累积step。其值应为正整数。默认值：1。
**异常：**
**ValueError**：输入key不是自动并行上下文中的属性。
**样例：**
>>> context.set_auto_parallel_context(device_num=8)
>>> context.set_auto_parallel_context(global_rank=0)
>>> context.set_auto_parallel_context(gradients_mean=True)
>>> context.set_auto_parallel_context(gradient_fp32_sync=False)
>>> context.set_auto_parallel_context(parallel_mode="auto_parallel")
>>> context.set_auto_parallel_context(auto_parallel_search_mode="dynamic_programming")
>>> context.set_auto_parallel_context(parameter_broadcast=False)
>>> context.set_auto_parallel_context(strategy_ckpt_load_file="./strategy_stage1.ckpt")
>>> context.set_auto_parallel_context(strategy_ckpt_save_file="./strategy_stage1.ckpt")
>>> context.set_auto_parallel_context(dataset_strategy=((1, 8), (1, 8)))
>>> context.set_auto_parallel_context(enable_parallel_optimizer=False)
>>> context.set_auto_parallel_context(all_reduce_fusion_config=[8, 160])
>>> context.set_auto_parallel_context(pipeline_stages=2)
.. py:function:: get_auto_parallel_context(attr_key)
根据key获取自动并行的配置。
**参数：**
**attr_key** (str)：配置的key。
**返回：**
根据key返回配置的值。
**异常：**
**ValueError**：输入key不在自动并行的配置列表中。
.. py:function:: reset_auto_parallel_context()
重置自动并行的配置为默认值。
- device_num：1。
- global_rank：0。
- gradients_mean：False。
- gradient_fp32_sync：True。
- parallel_mode：'stand_alone'。
- auto_parallel_search_mode：'dynamic_programming'。
- parameter_broadcast：False。
- strategy_ckpt_load_file：''。
- strategy_ckpt_save_file：''。
- full_batch：False。
- enable_parallel_optimizer：False。
- pipeline_stages：1。
.. py:class:: mindspore.context.ParallelMode
并行模式。
有五种并行模式，分别是STAND_ALONE、DATA_PARALLEL、HYBRID_PARALLEL、SEMI_AUTO_PARALLEL和AUTO_PARALLEL。默认值：STAND_ALONE。
- STAND_ALONE：单卡模式。
- DATA_PARALLEL：数据并行模式。
- HYBRID_PARALLEL：手动实现数据并行和模型并行。
- SEMI_AUTO_PARALLEL：半自动并行模式。
- AUTO_PARALLEL：自动并行模式。
MODE_LIST：表示所有支持的并行模式的列表。
.. py:function:: set_ps_context(**kwargs)
设置参数服务器训练模式的上下文。
.. note::
需要给参数服务器训练模式设置其他的环境变量。些环境变量如下所示：
- MS_SERVER_NUM：表示参数服务器数量。
- MS_WORKER_NUM：表示工作进程数量。
- MS_SCHED_HOST：表示调度器IP地址。
- MS_SCHED_PORT：表示调度器开启的监听端口。
- MS_ROLE：表示进程角色，角色列表如下：
- MS_SCHED：表示调度器。
- MS_WORKER：表示工作进程。
- MS_PSERVER/MS_SERVER：表示参数服务器。
**参数：**
- **enable_ps** (bool)：表示是否启用参数服务器训练模式。只有在enable_ps设置为True后，环境变量才会生效。默认值：False。
- **config_file_path** (string)：配置文件路径，用于容灾恢复等。默认值：''。
- **scheduler_manage_port** (int)：调度器HTTP端口，对外开放用于接收和处理用户扩容/缩容等请求。默认值：11202。
- **enable_ssl** (bool)：设置是否打开SSL认证。默认值：True。
- **client_password** (str)：用于解密客户端证书密钥的密码。默认值：''。
- **server_password** (str)：用于解密服务端证书密钥的密码。默认值：''。
**异常：**
**ValueError**：输入key不是参数服务器训练模式上下文中的属性。
**样例：**
>>> context.set_ps_context(enable_ps=True, enable_ssl=True, client_password='123456', server_password='123456')
.. py:function:: get_ps_context(attr_key)
根据key获取参数服务器训练模式上下文中的属性值。
**参数：**
**attr_key** (str)：属性的key。
- enable_ps (bool)：表示是否启用参数服务器训练模式。
- config_file_path (string)：配置文件路径，用于容灾恢复等。
- scheduler_manage_port (int)：调度器HTTP端口，对外开放用于接收和处理用户扩容/缩容等请求。
- enable_ssl (bool)：设置是否打开SSL认证。
- client_password (str)：用于解密客户端证书密钥的密码。
- server_password (str)：用于解密服务端证书密钥的密码。
**返回：**
根据key返回属性值。
**异常：**
ValueError：输入key不是参数服务器训练模式上下文中的属性。
**样例：**
>>> context.get_ps_context(enable_ps)
.. py:function:: reset_ps_context()
将参数服务器训练模式上下文中的属性重置为默认值。各字段的含义及其默认值见'set_ps_context'接口。
**样例：**
>>> context.reset_ps_context()

2
docs/api/api_python/mindspore/mindspore.model.rst
View File

@ -188,7 +188,7 @@
>>> init()
>>> context.set_auto_parallel_context(parallel_mode=ParallelMode.SEMI_AUTO_PARALLEL)
>>>
>>> # 如何构建数据集，请参考官方网站上关于【数据集】的章节。
>>> # 如何构建数据集，请参考官方网站上关于[数据集]的章节。
>>> dataset = create_custom_dataset()
>>> net = Net()
>>> loss = nn.SoftmaxCrossEntropyWithLogits()

95
docs/api/api_python/nn/mindspore.nn.AdamOffload.txt
View File

@ -1,10 +1,11 @@
Class mindspore.nn.AdamOffload(params, learning_rate=1e-3, beta1=0.9, beta2=0.999, eps=1e-08, use_locking=False, use_nesterov=False, weight_decay=0.0, loss_scale=1.0)
mindspore.nn.AdamOffload
=========================
此优化器在主机CPU上运行Adam优化算法，设备上仅执行网络参数的更新，最大限度地降低内存成本。
虽然会增加性能开销，但优化器可以运行更大的模型。
.. py:class:: mindspore.nn.AdamOffload(params, learning_rate=1e-3, beta1=0.9, beta2=0.999, eps=1e-08, use_locking=False, use_nesterov=False, weight_decay=0.0, loss_scale=1.0)
此优化器在主机CPU上运行Adam优化算法，设备上仅执行网络参数的更新，最大限度地降低内存成本。虽然会增加性能开销，但优化器可以运行更大的模型。
Adam算法参见`Adam: A Method for Stochastic Optimization <https://arxiv.org/abs/1412.6980>`_。
Adam算法参见 `Adam: A Method for Stochastic Optimization <https://arxiv.org/abs/1412.6980>`_。
更新公式如下：
@ -16,14 +17,14 @@ Class mindspore.nn.AdamOffload(params, learning_rate=1e-3, beta1=0.9, beta2=0.99
w_{t+1} = w_{t} - l * \frac{m_{t+1}}{\sqrt{v_{t+1}} + \epsilon}
\end{array}
:math:`m`代表第一个矩向量`moment1`，:math:`v`代表第二个矩向量`moment2`，:math:`g`代表`gradients`，:math:`l`代表缩放因子，:math:`\beta_1,\beta_2`代表`beta1`和`beta2`，:math:`t`代表当前step，:math:`beta_1^t`和:math:`beta_2^t`代表`beta1_power`和`beta2_power`，:math:`\alpha`代表`learning_rate`，:math:`w`代表`params`，:math:`\epsilon`代表`eps`。
:math:`m` 代表第一个矩向量 `moment1` ，:math:`v` 代表第二个矩向量 `moment2`，:math:`g` 代表 `gradients`，:math:`l` 代表缩放因子，:math:`\beta_1,\beta_2` 代表 `beta1` 和 `beta2`，:math:`t` 代表当前step，:math:`beta_1^t` 和 :math:`beta_2^t` 代表 `beta1_power` 和 `beta2_power`，:math:`\alpha` 代表 `learning_rate`，:math:`w` 代表 `params`，:math:`\epsilon` 代表 `eps` 。
.. note::
此优化器目前仅支持图模式。
.. note::此优化器目前仅支持图模式。
.. include:: mindspore.nn.optim_note_weight_decay.rst
参数：
**参数：**
- **params** (Union[list[Parameter], list[dict]]) - 必须是 `Parameter` 组成的列表或字典组成的列表。当列表元素是字典时，字典的键可以是"params"、"lr"、"weight_decay"、和"order_params"：
.. include:: mindspore.nn.optim_group_param.rst
@ -36,58 +37,58 @@ Class mindspore.nn.AdamOffload(params, learning_rate=1e-3, beta1=0.9, beta2=0.99
- **learning_rate (Union[float, Tensor, Iterable, LearningRateSchedule]): 默认值：1e-3。
.. include:: mindspore.nn.optim_arg_dynamic_lr.rst
- **beta1** (float) - `moment1` 的指数衰减率。参数范围（0.0,1.0）。默认值：0.9。
- **beta2** (float) - `moment2` 的指数衰减率。参数范围（0.0,1.0）。默认值：0.999。
- **eps** (float) - 将添加到分母中，以提高数值稳定性。必须大于0。默认值：1e-8。
- **use_locking** (bool) - 是否对参数更新加锁保护。如果为True，则 `w` 、`m` 和 `v` 的更新将受到锁保护。如果为False，则结果不可预测。默认值：False。
- **use_nesterov** (bool) - 是否使用Nesterov Accelerated Gradient (NAG)算法更新梯度。如果为True，使用NAG更新梯度。如果为False，则在不使用NAG的情况下更新梯度。默认值：False。
- **weight_decay** (float) - 权重衰减（L2 penalty）。必须大于等于0。默认值：0.0。
.. include:: mindspore.nn.optim_arg_loss_scale.rst
**输入：**
输入：
- **gradients** (tuple[Tensor])：`params`的梯度，shape与`params`相同。
**gradients** (tuple[Tensor])：`params`的梯度，shape与`params`相同。
输出：
Tensor[bool]，值为True。
**输出：**
异常：
TypeError：`learning_rate`不是int、float、Tensor、Iterable或LearningRateSchedule。
TypeError：`parameters`的元素不是Parameter或字典。
TypeError：`beta1`、`beta2`、`eps`或`loss_scale`不是float。
TypeError：`weight_decay`不是float或int。
TypeError：`use_locking`或`use_nesterov`不是bool。
ValueError：`loss_scale`或`eps`不大于0。
ValueError：`beta1`、`beta2`不在（0.0,1.0）范围内。
ValueError：`weight_decay`小于0。
Tensor[bool]，值为True。
支持平台：
``Ascend`` ``GPU`` ``CPU``
**异常：**
示例：
>>> net = Net()
>>> #1) 所有参数使用相同的学习率和权重衰减
>>> optim = nn.AdamOffload(params=net.trainable_params())
>>>
>>> #2) 使用参数分组并设置不同的值
>>> conv_params = list(filter(lambda x: 'conv' in x.name, net.trainable_params()))
>>> no_conv_params = list(filter(lambda x: 'conv' not in x.name, net.trainable_params()))
>>> group_params = [{'params': conv_params, 'weight_decay': 0.01},
... {'params': no_conv_params, 'lr': 0.01},
... {'order_params': net.trainable_params()}]
>>> optim = nn.AdamOffload(group_params, learning_rate=0.1, weight_decay=0.0)
>>> # conv_params参数组将使用优化器中的学习率0.1、该组的权重衰减0.01。
>>> # no_conv_params参数组将使用该组的学习率0.01、优化器中的权重衰减0.0。
>>> # 优化器按照"order_params"配置的参数顺序更新参数。
>>>
>>> loss = nn.SoftmaxCrossEntropyWithLogits()
>>> model = Model(net, loss_fn=loss, optimizer=optim)
- **TypeError**：`learning_rate` 不是int、float、Tensor、Iterable或LearningRateSchedule。
- **TypeError**：`parameters` 的元素不是Parameter或字典。
- **TypeError**：`beta1` 、 `beta2` 、 `eps `或 `loss_scale` 不是float。
- **TypeError**：`weight_decay` 不是float或int。
- **TypeError**：`use_locking` 或 `use_nesterov` 不是bool。
- **ValueError**：`loss_scale` 或 `eps` 不大于0。
- **ValueError**：`beta1` 、 `beta2` 不在（0.0,1.0）范围内。
- **ValueError**：`weight_decay` 小于0。
**支持平台：**
``Ascend`` ``GPU`` ``CPU``
**样例：**
>>> net = Net()
>>> #1) 所有参数使用相同的学习率和权重衰减
>>> optim = nn.AdamOffload(params=net.trainable_params())
>>>
>>> #2) 使用参数分组并设置不同的值
>>> conv_params = list(filter(lambda x: 'conv' in x.name, net.trainable_params()))
>>> no_conv_params = list(filter(lambda x: 'conv' not in x.name, net.trainable_params()))
>>> group_params = [{'params': conv_params, 'weight_decay': 0.01},
... {'params': no_conv_params, 'lr': 0.01},
... {'order_params': net.trainable_params()}]
>>> optim = nn.AdamOffload(group_params, learning_rate=0.1, weight_decay=0.0)
>>> # conv_params参数组将使用优化器中的学习率0.1、该组的权重衰减0.01。
>>> # no_conv_params参数组将使用该组的学习率0.01、优化器中的权重衰减0.0。
>>> # 优化器按照"order_params"配置的参数顺序更新参数。
>>>
>>> loss = nn.SoftmaxCrossEntropyWithLogits()
>>> model = Model(net, loss_fn=loss, optimizer=optim)

104
docs/api/api_python/nn/mindspore.nn.AdamWeightDecay.txt
View File

@ -1,4 +1,7 @@
Class mindspore.nn.AdamWeightDecay(params, learning_rate=1e-3, beta1=0.9, beta2=0.999, eps=1e-06, weight_decay=0.0)
mindspore.nn.AdamWeightDecay
==============================
.. py:class:: mindspore.nn.AdamWeightDecay(params, learning_rate=1e-3, beta1=0.9, beta2=0.999, eps=1e-06, weight_decay=0.0)
实现权重衰减Adam算法。
@ -17,71 +20,74 @@ Class mindspore.nn.AdamWeightDecay(params, learning_rate=1e-3, beta1=0.9, beta2=
w_{t+1} = w_{t} - lr * update
\end{array}
:math:`m`表示第1矩向量`moment1`,:math:`v`表示第2矩向量`moment2`，:math:`g`表示`gradients`，:math:`lr`表示`learning_rate`，:math:`\beta_1, \beta_2`表示`beta1`和`beta2`,:math:`t`表示当前step，:math:`w`表示`params`。
:math:`m` 表示第1矩向量 `moment1` , :math:`v` 表示第2矩向量 `moment2`， :math:`g` 表示 `gradients` ，:math:`lr` 表示 `learning_rate` ，:math:`\beta_1, \beta_2` 表示 `beta1` 和 `beta2` ,:math:`t` 表示当前step，:math:`w` 表示 `params`。
.. note::
.. include:: mindspore.nn.optim_note_loss_scale.rst
.. include:: mindspore.nn.optim_note_weight_decay.rst
参数：
params (Union[list[Parameter], list[dict]]) - 必须是 `Parameter` 组成的列表或字典组成的列表。当列表元素是字典时，字典的键可以是"params"、"lr"、"weight_decay"、和"order_params"：
**参数：**
.. include:: mindspore.nn.optim_group_param.rst
- **params** (Union[list[Parameter], list[dict]]) - 必须是 `Parameter` 组成的列表或字典组成的列表。当列表元素是字典时，字典的键可以是"params"、"lr"、"weight_decay"、和"order_params"：
.. include:: mindspore.nn.optim_group_lr.rst
.. include:: mindspore.nn.optim_group_weight_decay.rst
.. include:: mindspore.nn.optim_group_order.rst
.. include:: mindspore.nn.optim_group_param.rst
.. include:: mindspore.nn.optim_group_lr.rst
.. include:: mindspore.nn.optim_group_weight_decay.rst
.. include:: mindspore.nn.optim_group_order.rst
learning_rate (Union[float, Tensor, Iterable, LearningRateSchedule]): 默认值：1e-3。
- **learning_rate** (Union[float, Tensor, Iterable, LearningRateSchedule]): 默认值：1e-3。
.. include:: mindspore.nn.optim_arg_dynamic_lr.rst
.. include:: mindspore.nn.optim_arg_dynamic_lr.rst
beta1 (float)：`moment1` 的指数衰减率。参数范围（0.0,1.0）。默认值：0.9。
- **beta1** (float)：`moment1` 的指数衰减率。参数范围（0.0,1.0）。默认值：0.9。
- **beta2** (float)：`moment2` 的指数衰减率。参数范围（0.0,1.0）。默认值：0.999。
- **eps** (float)：将添加到分母中，以提高数值稳定性。必须大于0。默认值：1e-6。
- **weight_decay** (float)：权重衰减（L2 penalty）。必须大于等于0。默认值：0.0。
beta2 (float)：`moment2` 的指数衰减率。参数范围（0.0,1.0）。默认值：0.999。
**输入：**
eps (float)：将添加到分母中，以提高数值稳定性。必须大于0。默认值：1e-6。
**gradients** (tuple[Tensor])：`params`的梯度，shape与`params`相同。
weight_decay (float)：权重衰减（L2 penalty）。必须大于等于0。默认值：0.0。
**输出：**
输入：
- **gradients** (tuple[Tensor])：`params`的梯度，shape与`params`相同。
**tuple**[bool]，所有元素都为True。
输出：
tuple[bool]，所有元素都为True。
**异常：**
异常：
TypeError：`learning_rate`不是int、float、Tensor、Iterable或LearningRateSchedule。
TypeError：`parameters`的元素不是Parameter或字典。
TypeError：`beta1`、`beta2`或`eps`不是float。
TypeError：`weight_decay`不是float或int。
ValueError：`eps`小于等于0。
ValueError：`beta1`、`beta2`不在（0.0,1.0）范围内。
ValueError：`weight_decay`小于0。
- **TypeError**：`learning_rate` 不是int、float、Tensor、Iterable或LearningRateSchedule。
- **TypeError**：`parameters` 的元素不是Parameter或字典。
- **TypeError**：`beta1` 、 `beta2` 或 `eps` 不是float。
- **TypeError**：`weight_decay` 不是float或int。
- **ValueError**：`eps` 小于等于0。
- **ValueError**：`beta1` 、 `beta2` 不在（0.0,1.0）范围内。
- **ValueError**：`weight_decay` 小于0。
支持平台：
``Ascend`` ``GPU`` ``CPU``
**支持平台：**
示例：
>>> net = Net()
>>> #1) 所有参数使用相同的学习率和权重衰减
>>> optim = nn.AdamWeightDecay(params=net.trainable_params())
>>>
>>> #2) 使用参数分组并设置不同的值
>>> conv_params = list(filter(lambda x: 'conv' in x.name, net.trainable_params()))
>>> no_conv_params = list(filter(lambda x: 'conv' not in x.name, net.trainable_params()))
>>> group_params = [{'params': conv_params, 'weight_decay': 0.01},
... {'params': no_conv_params, 'lr': 0.01},
... {'order_params': net.trainable_params()}]
>>> optim = nn.AdamWeightDecay(group_params, learning_rate=0.1, weight_decay=0.0)
>>> # conv_params参数组将使用优化器中的学习率0.1、该组的权重衰减0.01。
>>> # no_conv_params参数组将使用该组的学习率0.01、优化器中的权重衰减0.0。
>>> # 优化器按照"order_params"配置的参数顺序更新参数。
>>>
>>> loss = nn.SoftmaxCrossEntropyWithLogits()
>>> model = Model(net, loss_fn=loss, optimizer=optim)
``Ascend`` ``GPU`` ``CPU``
**样例：**
>>> net = Net()
>>> #1) 所有参数使用相同的学习率和权重衰减
>>> optim = nn.AdamWeightDecay(params=net.trainable_params())
>>>
>>> #2) 使用参数分组并设置不同的值
>>> conv_params = list(filter(lambda x: 'conv' in x.name, net.trainable_params()))
>>> no_conv_params = list(filter(lambda x: 'conv' not in x.name, net.trainable_params()))
>>> group_params = [{'params': conv_params, 'weight_decay': 0.01},
... {'params': no_conv_params, 'lr': 0.01},
... {'order_params': net.trainable_params()}]
>>> optim = nn.AdamWeightDecay(group_params, learning_rate=0.1, weight_decay=0.0)
>>> # conv_params参数组将使用优化器中的学习率0.1、该组的权重衰减0.01。
>>> # no_conv_params参数组将使用该组的学习率0.01、优化器中的权重衰减0.0。
>>> # 优化器按照"order_params"配置的参数顺序更新参数。
>>>
>>> loss = nn.SoftmaxCrossEntropyWithLogits()
>>> model = Model(net, loss_fn=loss, optimizer=optim)

93
docs/api/api_python/nn/mindspore.nn.DynamicLossScaleUpdateCell.txt
View File

@ -1,58 +1,63 @@
Class mindspore.nn.DynamicLossScaleUpdateCell(loss_scale_value, scale_factor, scale_window)
mindspore.nn.DynamicLossScaleUpdateCell
=======================================
.. py:class:: mindspore.nn.DynamicLossScaleUpdateCell(loss_scale_value, scale_factor, scale_window)
用于动态地更新梯度放大系数(loss scale)的神经元。
使用梯度放大功能进行训练时，初始梯度放大系数值为`loss_scale_value`。
在每个训练步骤中，当出现溢出时，通过计算公式`loss_scale`/`scale_factor`减小梯度放大系数。
如果连续`scale_window`步（step）未溢出，则将通过`loss_scale` * `scale_factor`增大梯度放大系数。
使用梯度放大功能进行训练时，初始梯度放大系数值为 `loss_scale_value`。在每个训练步骤中，当出现溢出时，通过计算公式 `loss_scale`/`scale_factor` 减小梯度放大系数。如果连续 `scale_window` 步（step）未溢出，则将通过 `loss_scale` * `scale_factor` 增大梯度放大系数。
该类是:class:`mindspore.nn.DynamicLossScaleManager`的`get_update_cell`方法的返回值。
训练过程中，类:class:`mindspore.TrainOneStepWithLossScaleCell`会调用该Cell来更新梯度放大系数。
该类是 :class:`mindspore.nn.DynamicLossScaleManager` 的 `get_update_cell` 方法的返回值。训练过程中，类 :class:`mindspore.TrainOneStepWithLossScaleCell` 会调用该Cell来更新梯度放大系数。
参数：
loss_scale_value (float)：初始的梯度放大系数。
scale_factor (int)：增减系数。
scale_window (int)：未溢出时，增大梯度放大系数的最大连续训练步数。
**参数：**
输入：
- **loss_scale** (Tensor)：训练期间的梯度放大系数，shape为:math:`()`。
- **overflow** (bool)：是否发生溢出。
- **loss_scale_value** (float)：初始的梯度放大系数。
- **scale_factor** (int)：增减系数。
- **scale_window** (int)：未溢出时，增大梯度放大系数的最大连续训练步数。
输出：
Bool，即输入`overflow`。
**输入：**
支持平台：
``Ascend`` ``GPU``
- **loss_scale** (Tensor)：训练期间的梯度放大系数，shape为 :math:`()`。
- **overflow** (bool)：是否发生溢出。
示例：
>>> import numpy as np
>>> from mindspore import Tensor, Parameter, nn
>>> import mindspore.ops as ops
>>>
>>> class Net(nn.Cell):
... def __init__(self, in_features, out_features)：
... super(Net, self).__init__()
... self.weight = Parameter(Tensor(np.ones([in_features, out_features]).astype(np.float32)),
... name='weight')
... self.matmul = ops.MatMul()
...
... def construct(self, x)：
... output = self.matmul(x, self.weight)
... return output
...
>>> in_features, out_features = 16, 10
>>> net = Net(in_features, out_features)
>>> loss = nn.MSELoss()
>>> optimizer = nn.Momentum(net.trainable_params(), learning_rate=0.1, momentum=0.9)
>>> net_with_loss = nn.WithLossCell(net, loss)
>>> manager = nn.DynamicLossScaleUpdateCell(loss_scale_value=2**12, scale_factor=2, scale_window=1000)
>>> train_network = nn.TrainOneStepWithLossScaleCell(net_with_loss, optimizer, scale_sense=manager)
>>> input = Tensor(np.ones([out_features, in_features]), mindspore.float32)
>>> labels = Tensor(np.ones([out_features,]), mindspore.float32)
>>> output = train_network(input, labels)
**输出：**
Bool，即输入`overflow`。
**支持平台：**
``Ascend`` ``GPU``
**样例：**
>>> import numpy as np
>>> from mindspore import Tensor, Parameter, nn
>>> import mindspore.ops as ops
>>>
>>> class Net(nn.Cell):
... def __init__(self, in_features, out_features)：
... super(Net, self).__init__()
... self.weight = Parameter(Tensor(np.ones([in_features, out_features]).astype(np.float32)),
... name='weight')
... self.matmul = ops.MatMul()
...
... def construct(self, x)：
... output = self.matmul(x, self.weight)
... return output
...
>>> in_features, out_features = 16, 10
>>> net = Net(in_features, out_features)
>>> loss = nn.MSELoss()
>>> optimizer = nn.Momentum(net.trainable_params(), learning_rate=0.1, momentum=0.9)
>>> net_with_loss = nn.WithLossCell(net, loss)
>>> manager = nn.DynamicLossScaleUpdateCell(loss_scale_value=2**12, scale_factor=2, scale_window=1000)
>>> train_network = nn.TrainOneStepWithLossScaleCell(net_with_loss, optimizer, scale_sense=manager)
>>> input = Tensor(np.ones([out_features, in_features]), mindspore.float32)
>>> labels = Tensor(np.ones([out_features,]), mindspore.float32)
>>> output = train_network(input, labels)
get_loss_scale()
.. py:method:: get_loss_scale()
获取当前梯度放大系数。

117
docs/api/api_python/nn/mindspore.nn.FTRL.txt
View File

@ -1,10 +1,11 @@
Class mindspore.nn.FTRL(*args, **kwargs)
mindspore.nn. mindspore.nn.FTRL
================================
.. py:class:: mindspore.nn.FTRL(*args, **kwargs)
使用ApplyFtrl算子实现FTRL算法。
FTRL是一种在线凸优化算法，根据损失函数自适应地选择正则化函数。
详见论文`Adaptive Bound Optimization for Online Convex Optimization <https://arxiv.org/abs/1002.4908>`_。
工程文档参阅`Ad Click Prediction: a View from the Trenches <https://www.eecs.tufts.edu/~dsculley/papers/ad-click-prediction.pdf>`_。
FTRL是一种在线凸优化算法，根据损失函数自适应地选择正则化函数。详见论文 `Adaptive Bound Optimization for Online Convex Optimization <https://arxiv.org/abs/1002.4908>`_。工程文档参阅 `Ad Click Prediction: a View from the Trenches <https://www.eecs.tufts.edu/~dsculley/papers/ad-click-prediction.pdf>`_。
更新公式如下：
@ -23,81 +24,81 @@ Class mindspore.nn.FTRL(*args, **kwargs)
\end{cases}\\
\end{array}
:math:`m`表示累加器，:math:`g`表示`grads`，:math:`t`表示当前step，:math:`u`表示需要更新的线性系数，:math:`p`表示`lr_power`，:math:`\alpha`表示`learning_rate`，:math:`\omega`表示`params`。
:math:`m` 表示累加器，:math:`g` 表示 `grads`， :math:`t` 表示当前step，:math:`u` 表示需要更新的线性系数，:math:`p` 表示` lr_power`，:math:`\alpha` 表示 `learning_rate` ，:math:`\omega` 表示 `params` 。
.. note::
.. include:: mindspore.nn.optim_note_sparse.rst
.. include:: mindspore.nn.optim_note_weight_decay.rst
参数：
params (Union[list[Parameter], list[dict]]) - 必须是 `Parameter` 组成的列表或字典组成的列表。当列表元素是字典时，字典的键可以是"params"、"lr"、"weight_decay"、"grad_centralization"和"order_params"：
**参数：**
- **params** (Union[list[Parameter], list[dict]]) - 必须是 `Parameter` 组成的列表或字典组成的列表。当列表元素是字典时，字典的键可以是"params"、"lr"、"weight_decay"、"grad_centralization"和"order_params"：
.. include:: mindspore.nn.optim_group_param.rst
.. include:: mindspore.nn.optim_group_param.rst
- **lr** - 学习率当前不支持参数分组。
- **lr** - 学习率当前不支持参数分组。
.. include:: mindspore.nn.optim_group_weight_decay.rst
.. include:: mindspore.nn.optim_group_weight_decay.rst
.. include:: mindspore.nn.optim_group_gc.rst
.. include:: mindspore.nn.optim_group_gc.rst
.. include:: mindspore.nn.optim_group_order.rst
.. include:: mindspore.nn.optim_group_order.rst
- **initial_accum** (float)：累加器 `m` 的初始值，必须大于等于零。默认值：0.1。
- **learning_rate** (float)：学习速率值必须为零或正数，当前不支持动态学习率。默认值：0.001。
- **lr_power** (float)：学习率的幂值，控制训练期间学习率的下降方式，必须小于或等于零。如果lr_power为零，则使用固定的学习率。默认值：-0.5。
- **l1** (float)：l1正则化强度，必须大于等于零。默认值：0.0。
- **l2** (float)：l2正则化强度，必须大于等于零。默认值：0.0。
- **use_locking** (bool)：如果为True，则更新操作使用锁保护。默认值：False。
initial_accum (float)：累加器`m`的初始值，必须大于等于零。默认值：0.1。
.. include:: mindspore.nn.optim_arg_loss_scale.rst
learning_rate (float)：学习速率值必须为零或正数，当前不支持动态学习率。默认值：0.001。
- **weight_decay** (Union[float, int])：要乘以权重的权重衰减值，必须为零或正值。默认值：0.0。
lr_power (float)：学习率的幂值，控制训练期间学习率的下降方式，必须小于或等于零。如果lr_power为零，则使用固定的学习率。默认值：-0.5。
**输入：**
l1 (float)：l1正则化强度，必须大于等于零。默认值：0.0。
l2 (float)：l2正则化强度，必须大于等于零。默认值：0.0。
use_locking (bool)：如果为True，则更新操作使用锁保护。默认值：False。
.. include:: mindspore.nn.optim_arg_loss_scale.rst
weight_decay (Union[float, int])：要乘以权重的权重衰减值，必须为零或正值。默认值：0.0。
输入：
- **grads** (tuple[Tensor])：优化器中`params`的梯度，shape与优化器中的`params`相同。
**grads** (tuple[Tensor])：优化器中 `params` 的梯度，shape与优化器中的 `params` 相同。
输出：
tuple[Parameter]，更新的参数，shape与`params`相同。
**输出：**
异常：
TypeError：`initial_accum`、`learning_rate`、`lr_power`、`l1`、`l2`或`loss_scale`不是float。
TypeError：`parameters`的元素不是Parameter或dict。
TypeError：`weight_decay`不是float或int。
TypeError：`use_nesterov`不是bool。
ValueError：`lr_power`大于0。
ValueError：`loss_scale`小于等于0。
ValueError：`initial_accum`、`l1`或`l2`小于0。
tuple[Parameter]，更新的参数，shape与`params`相同。
支持平台：
``Ascend`` ``GPU`` ``CPU``
**异常：**
示例：
>>> net = Net()
>>> #1) 所有参数使用相同的学习率和权重衰减
>>> optim = nn.FTRL(params=net.trainable_params())
>>>
>>> #2) 使用参数分组并设置不同的值
>>> conv_params = list(filter(lambda x: 'conv' in x.name, net.trainable_params()))
>>> no_conv_params = list(filter(lambda x: 'conv' not in x.name, net.trainable_params()))
>>> group_params = [{'params': conv_params, 'weight_decay': 0.01, 'grad_centralization':True},
... {'params': no_conv_params},
... {'order_params': net.trainable_params()}]
>>> optim = nn.FTRL(group_params, learning_rate=0.1, weight_decay=0.0)
>>> # conv_params参数组将使用优化器中的学习率0.1、该组的权重衰减0.01、该组的梯度中心化配置True。
>>> # no_conv_params参数组使用优化器中的学习率0.1、优化器中的权重衰减0.0、梯度中心化使用默认值False。
>>> # 优化器按照"order_params"配置的参数顺序更新参数。
>>>
>>>
>>> loss = nn.SoftmaxCrossEntropyWithLogits()
>>> model = Model(net, loss_fn=loss, optimizer=optim)
- **TypeError**：`initial_accum`、`learning_rate`、`lr_power`、`l1`、`l2` 或 `loss_scale` 不是float。
- **TypeError**：`parameters` 的元素不是Parameter或dict。
- **TypeError**：`weight_decay` 不是float或int。
- **TypeError**：`use_nesterov` 不是bool。
- **ValueError**：`lr_power` 大于0。
- **ValueError**：`loss_scale` 小于等于0。
- **ValueError**：`initial_accum`、`l1` 或 `l2` 小于0。
**支持平台：**
``Ascend`` ``GPU`` ``CPU``
**样例：**
>>> net = Net()
>>> #1) 所有参数使用相同的学习率和权重衰减
>>> optim = nn.FTRL(params=net.trainable_params())
>>>
>>> #2) 使用参数分组并设置不同的值
>>> conv_params = list(filter(lambda x: 'conv' in x.name, net.trainable_params()))
>>> no_conv_params = list(filter(lambda x: 'conv' not in x.name, net.trainable_params()))
>>> group_params = [{'params': conv_params, 'weight_decay': 0.01, 'grad_centralization':True},
... {'params': no_conv_params},
... {'order_params': net.trainable_params()}]
>>> optim = nn.FTRL(group_params, learning_rate=0.1, weight_decay=0.0)
>>> # conv_params参数组将使用优化器中的学习率0.1、该组的权重衰减0.01、该组的梯度中心化配置True。
>>> # no_conv_params参数组使用优化器中的学习率0.1、优化器中的权重衰减0.0、梯度中心化使用默认值False。
>>> # 优化器按照"order_params"配置的参数顺序更新参数。
>>>
>>>
>>> loss = nn.SoftmaxCrossEntropyWithLogits()
>>> model = Model(net, loss_fn=loss, optimizer=optim)
.. include::mindspore.nn.optim_target_unique_for_sparse.rst

83
docs/api/api_python/nn/mindspore.nn.FixedLossScaleUpdateCell.txt
View File

@ -1,51 +1,58 @@
Class mindspore.nn.FixedLossScaleUpdateCell(loss_scale_value)
mindspore.nn.FixedLossScaleUpdateCell
=======================================
.. py:class:: mindspore.nn.FixedLossScaleUpdateCell(loss_scale_value)
固定梯度放大系数的神经元。
该类是:class:`mindspore.nn.FixedLossScaleManager`的`get_update_cell`方法的返回值。
训练过程中，类:class:`mindspore.TrainOneStepWithLossScaleCell`会调用该Cell。
该类是 :class:`mindspore.nn.FixedLossScaleManager` 的 `get_update_cell` 方法的返回值。训练过程中，类 :class:`mindspore.TrainOneStepWithLossScaleCell` 会调用该Cell。
参数：
loss_scale_value (float)：初始梯度放大系数。
**参数：**
输入：
- **loss_scale** (Tensor)：训练期间的梯度放大系数，shape为:math:`()`，在当前类中，该值被忽略。
- **overflow** (bool)：是否发生溢出。
**loss_scale_value** (float)：初始梯度放大系数。
输出：
Bool，即输入`overflow`。
**输入：**
支持平台：
``Ascend`` ``GPU``
- **loss_scale** (Tensor)：训练期间的梯度放大系数，shape为 :math:`()`，在当前类中，该值被忽略。
- **overflow** (bool)：是否发生溢出。
示例：
>>> import numpy as np
>>> from mindspore import Tensor, Parameter, nn, ops
>>>
>>> class Net(nn.Cell):
... def __init__(self, in_features, out_features)：
... super(Net, self).__init__()
... self.weight = Parameter(Tensor(np.ones([in_features, out_features]).astype(np.float32)),
... name='weight')
... self.matmul = ops.MatMul()
...
... def construct(self, x)：
... output = self.matmul(x, self.weight)
... return output
...
>>> in_features, out_features = 16, 10
>>> net = Net(in_features, out_features)
>>> loss = nn.MSELoss()
>>> optimizer = nn.Momentum(net.trainable_params(), learning_rate=0.1, momentum=0.9)
>>> net_with_loss = nn.WithLossCell(net, loss)
>>> manager = nn.FixedLossScaleUpdateCell(loss_scale_value=2**12)
>>> train_network = nn.TrainOneStepWithLossScaleCell(net_with_loss, optimizer, scale_sense=manager)
>>> input = Tensor(np.ones([out_features, in_features]), mindspore.float32)
>>> labels = Tensor(np.ones([out_features,]), mindspore.float32)
>>> output = train_network(input, labels)
**输出：**
Bool，即输入`overflow`。
**支持平台：**
``Ascend`` ``GPU``
**样例：**
>>> import numpy as np
>>> from mindspore import Tensor, Parameter, nn, ops
>>>
>>> class Net(nn.Cell):
... def __init__(self, in_features, out_features)：
... super(Net, self).__init__()
... self.weight = Parameter(Tensor(np.ones([in_features, out_features]).astype(np.float32)),
... name='weight')
... self.matmul = ops.MatMul()
...
... def construct(self, x)：
... output = self.matmul(x, self.weight)
... return output
...
>>> in_features, out_features = 16, 10
>>> net = Net(in_features, out_features)
>>> loss = nn.MSELoss()
>>> optimizer = nn.Momentum(net.trainable_params(), learning_rate=0.1, momentum=0.9)
>>> net_with_loss = nn.WithLossCell(net, loss)
>>> manager = nn.FixedLossScaleUpdateCell(loss_scale_value=2**12)
>>> train_network = nn.TrainOneStepWithLossScaleCell(net_with_loss, optimizer, scale_sense=manager)
>>> input = Tensor(np.ones([out_features, in_features]), mindspore.float32)
>>> labels = Tensor(np.ones([out_features,]), mindspore.float32)
>>> output = train_network(input, labels)
get_loss_scale()
.. py:method:: get_loss_scale()
获取当前梯度放大系数。

63
docs/api/api_python/nn/mindspore.nn.InverseDecayLR.txt
View File

@ -1,4 +1,7 @@
Class mindspore.nn.InverseDecayLR(learning_rate, decay_rate, decay_steps, is_stair=False)
mindspore.nn.InverseDecayLR
=============================
.. py:class:: mindspore.nn.InverseDecayLR(learning_rate, decay_rate, decay_steps, is_stair=False)
基于逆时衰减函数计算学习率。
@ -12,39 +15,45 @@ Class mindspore.nn.InverseDecayLR(learning_rate, decay_rate, decay_steps, is_sta
.. math::
p = \frac{current\_step}{decay\_steps}
如果`is_stair`为True，则公式为：
如果 `is_stair` 为True，则公式为：
.. math::
p = floor(\frac{current\_step}{decay\_steps})
参数：
learning_rate (float)：学习率的初始值。
decay_rate (float)：衰减率。
decay_steps (int)：用于计算衰减学习率的值。
is_stair (bool)：如果为True，则学习率每`decay_steps`次衰减一次。默认值：False。
**参数：**
输入：
- **global_step** (Tensor)：当前step数。
- **learning_rate** (float)：学习率的初始值。
- **decay_rate** (float)：衰减率。
- **decay_steps** (int)：用于计算衰减学习率的值。
- **is_stair** (bool)：如果为True，则学习率每 `decay_steps` 次衰减一次。默认值：False。
输出：
Tensor。当前step的学习率值，shape为:math:`()`。
**输入：**
异常：
TypeError：`learning_rate`或`decay_rate`不是float。
TypeError：`decay_steps`不是int或`is_stair`不是bool。
ValueError：`decay_steps`小于1。
ValueError：`learning_rate`或`decay_rate`小于或等于0。
**global_step** (Tensor)：当前step数。
支持平台：
``Ascend`` ``GPU`` ``CPU``
**输出：**
示例：
>>> learning_rate = 0.1
>>> decay_rate = 0.9
>>> decay_steps = 4
>>> global_step = Tensor(2, mstype.int32)
>>> inverse_decay_lr = nn.InverseDecayLR(learning_rate, decay_rate, decay_steps, True)
>>> result = inverse_decay_lr(global_step)
>>> print(result)
0.1
Tensor。当前step的学习率值，shape为:math:`()`。
**异常：**
- **TypeError**：`learning_rate` 或 `decay_rate` 不是float。
- **TypeError**：`decay_steps` 不是int或 `is_stair` 不是bool。
- **ValueError**：`decay_steps` 小于1。
- **ValueError**：`learning_rate` 或 `decay_rate` 小于或等于0。
**支持平台：**
``Ascend`` ``GPU`` ``CPU``
**样例：**
>>> learning_rate = 0.1
>>> decay_rate = 0.9
>>> decay_steps = 4
>>> global_step = Tensor(2, mstype.int32)
>>> inverse_decay_lr = nn.InverseDecayLR(learning_rate, decay_rate, decay_steps, True)
>>> result = inverse_decay_lr(global_step)
>>> print(result)
0.1

48
docs/api/api_python/nn/mindspore.nn.LARS.txt
View File

@ -1,8 +1,11 @@
Class mindspore.nn.LARS(*args, **kwargs)
mindspore.nn.Lamb
==================
.. py:class:: mindspore.nn.LARS(*args, **kwargs)
使用LARSUpdate算子实现LARS算法。
LARS算法采用大量的优化技术。详见论文`LARGE BATCH TRAINING OF CONVOLUTIONAL NETWORKS <https://arxiv.org/abs/1708.03888>`_。
LARS算法采用大量的优化技术。详见论文 `LARGE BATCH TRAINING OF CONVOLUTIONAL NETWORKS <https://arxiv.org/abs/1708.03888>`_。
更新公式如下：
@ -24,27 +27,32 @@ Class mindspore.nn.LARS(*args, **kwargs)
:math:`\theta`表示`coefficient`，:math:`\omega`表示网络参数，:math:`g`表示`gradients`，:math:`t`表示当前step，:math:`\delta`表示`optimizer`配置的`weight_decay`，:math:`\alpha`表示`optimizer`配置的`learning_rate`，:math:`clip`表示`use_clip`。
参数：
optimizer (Optimizer)：待封装和修改梯度的MindSpore优化器。
epsilon (float)：将添加到分母中，提高数值稳定性。默认值：1e-05。
coefficient (float)：计算局部学习速率的信任系数。默认值：0.001。
use_clip (bool)：计算局部学习速率时是否裁剪。默认值：False。
lars_filter (Function)：用于指定使用LARS算法的网络参数。默认值：lambda x: 'LayerNorm' not in x.name and 'bias' not in x.name。
**参数：**
输入：
- **gradients** (tuple[Tensor])：优化器中`params`的梯度，shape与优化器中的`params`相同。
- **optimizer** (Optimizer)：待封装和修改梯度的MindSpore优化器。
- **epsilon** (float)：将添加到分母中，提高数值稳定性。默认值：1e-05。
- **coefficient** (float)：计算局部学习速率的信任系数。默认值：0.001。
- **use_clip** (bool)：计算局部学习速率时是否裁剪。默认值：False。
- **lars_filter** (Function)：用于指定使用LARS算法的网络参数。默认值：lambda x: 'LayerNorm' not in x.name and 'bias' not in x.name。
**输入：**
**gradients** (tuple[Tensor])：优化器中`params`的梯度，shape与优化器中的`params`相同。
输出：
Union[Tensor[bool], tuple[Parameter]]，取决于`optimizer`的输出。
**输出：**
支持平台：
``Ascend`` ``CPU``
Union[Tensor[bool], tuple[Parameter]]，取决于`optimizer`的输出。
示例：
>>> net = Net()
>>> loss = nn.SoftmaxCrossEntropyWithLogits()
>>> opt = nn.Momentum(net.trainable_params(), 0.1, 0.9)
>>> opt_lars = nn.LARS(opt, epsilon=1e-08, coefficient=0.02)
>>> model = Model(net, loss_fn=loss, optimizer=opt_lars, metrics=None)
**支持平台：**
``Ascend`` ``CPU``
**样例：**
>>> net = Net()
>>> loss = nn.SoftmaxCrossEntropyWithLogits()
>>> opt = nn.Momentum(net.trainable_params(), 0.1, 0.9)
>>> opt_lars = nn.LARS(opt, epsilon=1e-08, coefficient=0.02)
>>> model = Model(net, loss_fn=loss, optimizer=opt_lars, metrics=None)

106
docs/api/api_python/nn/mindspore.nn.Lamb.txt
View File

@ -1,9 +1,11 @@
Class mindspore.nn.Lamb(*args, **kwargs)
mindspore.nn.Lamb
==================
.. py:class:: mindspore.nn.Lamb(*args, **kwargs)
LAMB（Layer-wise Adaptive Moments optimizer for Batching training，用于批训练的分层自适应矩优化器）算法优化器。
LAMB是一种采用分层自适应批优化技术的优化算法。
详见论文`LARGE BATCH OPTIMIZATION FOR DEEP LEARNING: TRAINING BERT IN 76 MINUTES <https://arxiv.org/abs/1904.00962>`_。
LAMB是一种采用分层自适应批优化技术的优化算法。详见论文 `LARGE BATCH OPTIMIZATION FOR DEEP LEARNING: TRAINING BERT IN 76 MINUTES <https://arxiv.org/abs/1904.00962>`_。
LAMB优化器旨在不降低精度的情况下增加训练batch size，支持自适应逐元素更新和精确的分层校正。
@ -28,62 +30,66 @@ Class mindspore.nn.Lamb(*args, **kwargs)
.. include:: mindspore.nn.optim_note_loss_scale.rst
参数：
params (Union[list[Parameter], list[dict]]): 必须是 `Parameter` 组成的列表或字典组成的列表。当列表元素是字典时，字典的键可以是"params"、"lr"、"weight_decay"、"grad_centralization"和"order_params"：
**参数：**
.. include:: mindspore.nn.optim_group_param.rst
.. include:: mindspore.nn.optim_group_lr.rst
.. include:: mindspore.nn.optim_group_weight_decay.rst
.. include:: mindspore.nn.optim_group_gc.rst
.. include:: mindspore.nn.optim_group_order.rst
- **params** (Union[list[Parameter], list[dict]]): 必须是 `Parameter` 组成的列表或字典组成的列表。当列表元素是字典时，字典的键可以是"params"、"lr"、"weight_decay"、"grad_centralization"和"order_params"：
learning_rate (Union[float, Tensor, Iterable, LearningRateSchedule]):
.. include:: mindspore.nn.optim_arg_dynamic_lr.rst
.. include:: mindspore.nn.optim_group_param.rst
.. include:: mindspore.nn.optim_group_lr.rst
.. include:: mindspore.nn.optim_group_weight_decay.rst
.. include:: mindspore.nn.optim_group_gc.rst
.. include:: mindspore.nn.optim_group_order.rst
beta1 (float)：第一矩的指数衰减率。参数范围（0.0,1.0）。默认值：0.9。
- **learning_rate (Union[float, Tensor, Iterable, LearningRateSchedule]):
beta2 (float)：第二矩的指数衰减率。参数范围（0.0,1.0）。默认值：0.999。
.. include:: mindspore.nn.optim_arg_dynamic_lr.rst
eps (float)：将添加到分母中，以提高数值稳定性。必须大于0。默认值：1e-6。
- **beta1** (float)：第一矩的指数衰减率。参数范围（0.0,1.0）。默认值：0.9。
- **beta2** (float)：第二矩的指数衰减率。参数范围（0.0,1.0）。默认值：0.999。
- **eps** (float)：将添加到分母中，以提高数值稳定性。必须大于0。默认值：1e-6。
- **weight_decay** (float)：权重衰减（L2 penalty）。必须大于等于0。默认值：0.0。
weight_decay (float)：权重衰减（L2 penalty）。必须大于等于0。默认值：0.0。
**输入：**
输入：
- **gradients** (tuple[Tensor])：`params`的梯度，shape与`params`相同。
**gradients** (tuple[Tensor])：`params`的梯度，shape与`params`相同。
输出：
tuple[bool]，所有元素都为True。
**输出：**
异常：
TypeError：`learning_rate`不是int、float、Tensor、Iterable或LearningRateSchedule。
TypeError：`parameters`的元素不是Parameter或dict。
TypeError：`beta1`、`beta2`或`eps`不是float。
TypeError：`weight_decay`不是float或int。
ValueError：`eps`小于等于0。
ValueError：`beta1`、`beta2`不在（0.0,1.0）范围内。
ValueError：`weight_decay`小于0。
tuple[bool]，所有元素都为True。
支持平台：
``Ascend`` ``GPU`` ``CPU``
**异常：**
示例：
>>> net = Net()
>>> #1) 所有参数使用相同的学习率和权重衰减
>>> optim = nn.Lamb(params=net.trainable_params(), learning_rate=0.1)
>>>
>>> #2) 使用参数分组并设置不同的值
>>> poly_decay_lr = learning_rate_schedule.PolynomialDecayLR(learning_rate=0.1, end_learning_rate=0.01,
... decay_steps=4, power = 0.5)
>>> conv_params = list(filter(lambda x: 'conv' in x.name, net.trainable_params()))
>>> no_conv_params = list(filter(lambda x: 'conv' not in x.name, net.trainable_params()))
>>> group_params = [{'params': conv_params, 'weight_decay': 0.01, 'grad_centralization':True},
... {'params': no_conv_params, 'lr': poly_decay_lr},
... {'order_params': net.trainable_params(0.01)}]
>>> optim = nn.Lamb(group_params, learning_rate=0.1, weight_decay=0.0)
>>> # conv_params参数组将使用优化器中的学习率0.1、该组的权重衰减0.01、该组的梯度中心化配置True。
>>> # no_conv_params参数组将使用该组的衰减学习率、优化器中的权重衰减0.0、梯度中心化使用默认值False。
>>> # 优化器按照"order_params"配置的参数顺序更新参数。
>>>
>>> loss = nn.SoftmaxCrossEntropyWithLogits()
>>> model = Model(net, loss_fn=loss, optimizer=optim)
- **TypeError**：`learning_rate`不是int、float、Tensor、Iterable或LearningRateSchedule。
- **TypeError**：`parameters`的元素不是Parameter或dict。
- **TypeError**：`beta1`、`beta2`或`eps`不是float。
- **TypeError**：`weight_decay`不是float或int。
- **ValueError**：`eps`小于等于0。
- **ValueError**：`beta1`、`beta2`不在（0.0,1.0）范围内。
- **ValueError**：`weight_decay`小于0。
**支持平台：**
``Ascend`` ``GPU`` ``CPU``
**样例：**
>>> net = Net()
>>> #1) 所有参数使用相同的学习率和权重衰减
>>> optim = nn.Lamb(params=net.trainable_params(), learning_rate=0.1)
>>>
>>> #2) 使用参数分组并设置不同的值
>>> poly_decay_lr = learning_rate_schedule.PolynomialDecayLR(learning_rate=0.1, end_learning_rate=0.01,
... decay_steps=4, power = 0.5)
>>> conv_params = list(filter(lambda x: 'conv' in x.name, net.trainable_params()))
>>> no_conv_params = list(filter(lambda x: 'conv' not in x.name, net.trainable_params()))
>>> group_params = [{'params': conv_params, 'weight_decay': 0.01, 'grad_centralization':True},
... {'params': no_conv_params, 'lr': poly_decay_lr},
... {'order_params': net.trainable_params(0.01)}]
>>> optim = nn.Lamb(group_params, learning_rate=0.1, weight_decay=0.0)
>>> # conv_params参数组将使用优化器中的学习率0.1、该组的权重衰减0.01、该组的梯度中心化配置True。
>>> # no_conv_params参数组将使用该组的衰减学习率、优化器中的权重衰减0.0、梯度中心化使用默认值False。
>>> # 优化器按照"order_params"配置的参数顺序更新参数。
>>>
>>> loss = nn.SoftmaxCrossEntropyWithLogits()
>>> model = Model(net, loss_fn=loss, optimizer=optim)

120
docs/api/api_python/nn/mindspore.nn.LazyAdam.txt
View File

@ -1,6 +1,9 @@
Class mindspore.nn.LazyAdam(*args, **kwargs)
mindspore.nn.LazyAdam
======================
通过Adaptive Moment Estimation (Adam)算法更新梯度。请参阅论文`Adam: A Method for Stochastic Optimization <https://arxiv.org/abs/1412.6980>`_。
.. py:class:: mindspore.nn.LazyAdam(*args, **kwargs)
通过Adaptive Moment Estimation (Adam)算法更新梯度。请参阅论文 `Adam: A Method for Stochastic Optimization <https://arxiv.org/abs/1412.6980>`_。
当梯度稀疏时，此优化器将使用Lazy Adam算法。
@ -14,80 +17,81 @@ Class mindspore.nn.LazyAdam(*args, **kwargs)
w_{t+1} = w_{t} - l * \frac{m_{t+1}}{\sqrt{v_{t+1}} + \epsilon}
\end{array}
:math:`m`代表第一个矩向量`moment1`，:math:`v`代表第二个矩向量`moment2`，:math:`g`代表`gradients`，:math:`l`代表缩放因子，:math:`\beta_1,\beta_2`代表`beta1`和`beta2`，:math:`t`代表当前step，:math:`beta_1^t`和:math:`beta_2^t`代表`beta1_power`和`beta2_power`，:math:`\alpha`代表``learning_rate`，:math:`w`代表`params`，:math:`\epsilon`代表`eps`。
:math:`m` 代表第一个矩向量 `moment1` ，:math:`v` 代表第二个矩向量 `moment2` ，:math:`g` 代表 `gradients` ，:math:`l` 代表缩放因子，:math:`\beta_1,\beta_2` 代表 `beta1` 和 `beta2` ，:math:`t` 代表当前step，:math:`beta_1^t` 和 :math:`beta_2^t` 代表 `beta1_power` 和 `beta2_power` ， :math:`\alpha` 代表 `learning_rate` ， :math:`w` 代表 `params` ， :math:`\epsilon` 代表 `eps`。
.. note::
.. include:: mindspore.nn.optim_note_sparse.rst
需要注意的是，梯度稀疏时该优化器只更新网络参数的当前的索引位置，稀疏行为不等同于Adam算法。
.. include:: mindspore.nn.optim_note_sparse.rst
.. include:: mindspore.nn.optim_note_weight_decay.rst
需要注意的是，梯度稀疏时该优化器只更新网络参数的当前的索引位置，稀疏行为不等同于Adam算法。
参数：
param (Union[list[Parameter], list[dict]]) - 必须是 `Parameter` 组成的列表或字典组成的列表。当列表元素是字典时，字典的键可以是"params"、"lr"、"weight_decay"、"grad_centralization"和"order_params"：
.. include:: mindspore.nn.optim_note_weight_decay.rst
.. include:: mindspore.nn.optim_group_param.rst
.. include:: mindspore.nn.optim_group_lr.rst
.. include:: mindspore.nn.optim_group_weight_decay.rst
.. include:: mindspore.nn.optim_group_gc.rst
.. include:: mindspore.nn.optim_group_order.rst
**参数：**
learning_rate (Union[float, Tensor, Iterable, LearningRateSchedule]): 默认值：1e-3。
.. include:: mindspore.nn.optim_dynamic_lr.rst
- **param** (Union[list[Parameter], list[dict]]) - 必须是 `Parameter` 组成的列表或字典组成的列表。当列表元素是字典时，字典的键可以是"params"、"lr"、"weight_decay"、"grad_centralization"和"order_params"：
beta1 (float)：`moment1` 的指数衰减率。参数范围（0.0,1.0）。默认值：0.9。
.. include:: mindspore.nn.optim_group_param.rst
.. include:: mindspore.nn.optim_group_lr.rst
.. include:: mindspore.nn.optim_group_weight_decay.rst
.. include:: mindspore.nn.optim_group_gc.rst
.. include:: mindspore.nn.optim_group_order.rst
beta2 (float)：moment2` 的指数衰减率。参数范围（0.0,1.0）。默认值：0.999。
- **learning_rate (Union[float, Tensor, Iterable, LearningRateSchedule]): 默认值：1e-3。
eps (float)：将添加到分母中，以提高数值稳定性。必须大于0。默认值：1e-8。
.. include:: mindspore.nn.optim_dynamic_lr.rst
use_locking (bool)：是否对参数更新加锁保护。如果为True，则 `w` 、`m` 和 `v` 的Tensor更新将受到锁的保护。如果为False，则结果不可预测。默认值：False。
- **beta1 (float)：`moment1` 的指数衰减率。参数范围（0.0,1.0）。默认值：0.9。
- **beta2 (float)：moment2` 的指数衰减率。参数范围（0.0,1.0）。默认值：0.999。
- **eps (float)：将添加到分母中，以提高数值稳定性。必须大于0。默认值：1e-8。
- **use_locking (bool)：是否对参数更新加锁保护。如果为True，则 `w` 、`m` 和 `v` 的Tensor更新将受到锁的保护。如果为False，则结果不可预测。默认值：False。
- **use_nesterov (bool)：是否使用Nesterov Accelerated Gradient (NAG)算法更新梯度。如果为True，使用NAG更新梯度。如果为False，则在不使用NAG的情况下更新梯度。默认值：False。
- **weight_decay (Union[float, int])：权重衰减（L2 penalty）。必须大于等于0。默认值：0.0。
use_nesterov (bool)：是否使用Nesterov Accelerated Gradient (NAG)算法更新梯度。如果为True，使用NAG更新梯度。如果为False，则在不使用NAG的情况下更新梯度。默认值：False。
.. include:: mindspore.nn.optim_arg_loss_scale.rst
weight_decay (Union[float, int])：权重衰减（L2 penalty）。必须大于等于0。默认值：0.0。
**输入：**
.. include:: mindspore.nn.optim_arg_loss_scale.rst
**gradients** (tuple[Tensor])：`params` 的梯度，shape与 `params` 相同。
输入：
- **gradients** (tuple[Tensor])：`params`的梯度，shape与`params`相同。
**输出：**
输出：
Tensor[bool]，值为True。
Tensor[bool]，值为True。
异常：
TypeError：`learning_rate`不是int、float、Tensor、Iterable或LearningRateSchedule。
TypeError：`parameters`的元素不是Parameter或字典。
TypeError：`beta1`、`beta2`、`eps`或`loss_scale`不是float。
TypeError：`weight_decay`不是float或int。
TypeError：`use_locking`或`use_nesterov`不是bool。
ValueError：`loss_scale`或`eps`小于或等于0。
ValueError：`beta1`、`beta2`不在（0.0,1.0）范围内。
ValueError：`weight_decay`小于0。
**异常：**
支持平台：
``Ascend`` ``GPU``
- **TypeError**：`learning_rate` 不是int、float、Tensor、Iterable或LearningRateSchedule。
- **TypeError**：`parameters` 的元素不是Parameter或字典。
- **TypeError**：`beta1`、`beta2`、`eps` 或 `loss_scale` 不是float。
- **TypeError**：`weight_decay` 不是float或int。
- **TypeError**：`use_locking` 或 `use_nesterov` 不是bool。
- **ValueError**：`loss_scale `或 `eps` 小于或等于0。
- **ValueError**：`beta1`、`beta2` 不在（0.0,1.0）范围内。
- **ValueError**：`weight_decay` 小于0。
示例：
>>> net = Net()
>>> #1) 所有参数使用相同的学习率和权重衰减
>>> optim = nn.LazyAdam(params=net.trainable_params())
>>>
>>> #2) 使用参数分组并设置不同的值
>>> conv_params = list(filter(lambda x: 'conv' in x.name, net.trainable_params()))
>>> no_conv_params = list(filter(lambda x: 'conv' not in x.name, net.trainable_params()))
>>> group_params = [{'params': conv_params, 'weight_decay': 0.01, 'grad_centralization':True},
... {'params': no_conv_params, 'lr': 0.01},
... {'order_params': net.trainable_params()}]
>>> optim = nn.LazyAdam(group_params, learning_rate=0.1, weight_decay=0.0)
>>> # conv_params参数组将使用优化器中的学习率0.1、该组的权重衰减0.01、该组的梯度中心化配置True。
>>> # no_conv_params参数组将使用该组的学习率0.01、优化器中的权重衰减0.0、梯度中心化使用默认值False。
>>> # 优化器按照"order_params"配置的参数顺序更新参数。
>>>
>>> loss = nn.SoftmaxCrossEntropyWithLogits()
>>> model = Model(net, loss_fn=loss, optimizer=optim)
**支持平台：**
``Ascend`` ``GPU``
**样例：**
>>> net = Net()
>>> #1) 所有参数使用相同的学习率和权重衰减
>>> optim = nn.LazyAdam(params=net.trainable_params())
>>>
>>> #2) 使用参数分组并设置不同的值
>>> conv_params = list(filter(lambda x: 'conv' in x.name, net.trainable_params()))
>>> no_conv_params = list(filter(lambda x: 'conv' not in x.name, net.trainable_params()))
>>> group_params = [{'params': conv_params, 'weight_decay': 0.01, 'grad_centralization':True},
... {'params': no_conv_params, 'lr': 0.01},
... {'order_params': net.trainable_params()}]
>>> optim = nn.LazyAdam(group_params, learning_rate=0.1, weight_decay=0.0)
>>> # conv_params参数组将使用优化器中的学习率0.1、该组的权重衰减0.01、该组的梯度中心化配置True。
>>> # no_conv_params参数组将使用该组的学习率0.01、优化器中的权重衰减0.0、梯度中心化使用默认值False。
>>> # 优化器按照"order_params"配置的参数顺序更新参数。
>>>
>>> loss = nn.SoftmaxCrossEntropyWithLogits()
>>> model = Model(net, loss_fn=loss, optimizer=optim)
.. include:: mindspore.nn.optim_target_unique_for_sparse.rst

63
docs/api/api_python/nn/mindspore.nn.NaturalExpDecayLR.txt
View File

@ -1,4 +1,7 @@
Class mindspore.nn.NaturalExpDecayLR(learning_rate, decay_rate, decay_steps, is_stair=False)
mindspore.nn.NaturalExpDecayLR
===============================
.. py:class:: mindspore.nn.NaturalExpDecayLR(learning_rate, decay_rate, decay_steps, is_stair=False)
基于自然指数衰减函数计算学习率。
@ -12,39 +15,45 @@ Class mindspore.nn.NaturalExpDecayLR(learning_rate, decay_rate, decay_steps, is_
.. math::
p = \frac{current\_step}{decay\_steps}
如果`is_stair`为True，则公式为：
如果 `is_stair` 为True，则公式为：
.. math::
p = floor(\frac{current\_step}{decay\_steps})
参数：
learning_rate (float)：学习率的初始值。
decay_rate (float)：衰减率。
decay_steps (int)：用于计算衰减学习率的值。
is_stair (bool)：如果为True，则学习率每`decay_steps`次衰减一次。默认值：False。
**参数：**
输入：
- **global_step** （Tensor）：当前step数。
- **learning_rate** (float)：学习率的初始值。
- **decay_rate** (float)：衰减率。
- **decay_steps** (int)：用于计算衰减学习率的值。
- **is_stair** (bool)：如果为True，则学习率每 `decay_steps` 次衰减一次。默认值：False。
输出：
Tensor。当前step的学习率值，shape为 :math:`()`。
**输入：**
异常：
TypeError：`learning_rate`或`decay_rate`不是float。
TypeError：`decay_steps`不是int或`is_stair`不是bool。
ValueError：`decay_steps`小于1。
ValueError：`learning_rate`或`decay_rate`小于或等于0。
**global_step** （Tensor）：当前step数。
支持平台：
``Ascend`` ``GPU`` ``CPU``
**输出：**
示例：
>>> learning_rate = 0.1
>>> decay_rate = 0.9
>>> decay_steps = 4
>>> global_step = Tensor(2, mstype.int32)
>>> natural_exp_decay_lr = nn.NaturalExpDecayLR(learning_rate, decay_rate, decay_steps, True)
>>> result = natural_exp_decay_lr(global_step)
>>> print(result)
0.1
Tensor。当前step的学习率值，shape为 :math:`()`。
**异常：**
- **TypeError**：`learning_rate` 或 `decay_rate` 不是float。
- **TypeError**：`decay_steps` 不是int或 `is_stair` 不是bool。
- **ValueError**：`decay_steps` 小于1。
- **ValueError**：`learning_rate` 或 `decay_rate` 小于或等于0。
**支持平台：**
``Ascend`` ``GPU`` ``CPU``
**样例：**
>>> learning_rate = 0.1
>>> decay_rate = 0.9
>>> decay_steps = 4
>>> global_step = Tensor(2, mstype.int32)
>>> natural_exp_decay_lr = nn.NaturalExpDecayLR(learning_rate, decay_rate, decay_steps, True)
>>> result = natural_exp_decay_lr(global_step)
>>> print(result)
0.1

67
docs/api/api_python/nn/mindspore.nn.PolynomialDecayLR.txt
View File

@ -1,4 +1,7 @@
Class mindspore.nn.PolynomialDecayLR(learning_rate, end_learning_rate, decay_steps, power, update_decay_steps=False)
mindspore.nn.polynomial_decay_lr
====================================
.. py:class:: mindspore.nn.PolynomialDecayLR(learning_rate, end_learning_rate, decay_steps, power, update_decay_steps=False)
基于多项式衰减函数计算学习率。
@ -13,41 +16,47 @@ Class mindspore.nn.PolynomialDecayLR(learning_rate, end_learning_rate, decay_ste
.. math::
tmp\_step=min(current\_step, decay\_steps)
如果`update_decay_steps`为true，则每`decay_steps`更新`tmp_decay_step`的值。公式为：
如果 `update_decay_steps` 为true，则每 `decay_steps` 更新 `tmp_decay_step` 的值。公式为：
.. math::
tmp\_decay\_steps = decay\_steps * ceil(current\_step / decay\_steps)
参数：
learning_rate (float)：学习率的初始值。
end_learning_rate (float)：学习率的最终值。
decay_steps (int)：用于计算衰减学习率的值。
power (float)：用于计算衰减学习率的值。该参数必须大于0。
update_decay_steps (bool)：如果为True，则学习率每`decay_steps`次衰减一次。默认值：False。
**参数：**
输入：
- **global_step** （Tensor）：当前step数。
- **learning_rate** (float)：学习率的初始值。
- **end_learning_rate** (float)：学习率的最终值。
- **decay_steps** (int)：用于计算衰减学习率的值。
- **power** (float)：用于计算衰减学习率的值。该参数必须大于0。
- **update_decay_steps** (bool)：如果为True，则学习率每 `decay_steps` 次衰减一次。默认值：False。
输出：
Tensor。当前step的学习率值, shape为 :math:`()`。
**输入：**
异常：
TypeError：`learning_rate`,`end_learning_rate`或`power`不是float。
TypeError：`decay_steps`不是int或`update_decay_steps`不是bool。
ValueError：`end_learning_rate`小于0或`decay_steps`小于1。
ValueError：`learning_rate`或`power`小于或等于0。
**global_step** （Tensor）：当前step数。
支持平台：
``Ascend`` ``GPU``
**输出：**
示例：
>>> learning_rate = 0.1
>>> end_learning_rate = 0.01
>>> decay_steps = 4
>>> power = 0.5
>>> global_step = Tensor(2, mstype.int32)
>>> polynomial_decay_lr = nn.PolynomialDecayLR(learning_rate, end_learning_rate, decay_steps, power)
>>> result = polynomial_decay_lr(global_step)
>>> print(result)
0.07363961
Tensor。当前step的学习率值, shape为 :math:`()`。
**异常：**
- **TypeError**：`learning_rate`,`end_learning_rate` 或 `power` 不是float。
- **TypeError**：`decay_steps` 不是int或 `update_decay_steps` 不是bool。
- **ValueError**：`end_learning_rate` 小于0或 `decay_steps` 小于1。
- **ValueError**：`learning_rate` 或 `power` 小于或等于0。
**支持平台：**
``Ascend`` ``GPU``
**样例：**
>>> learning_rate = 0.1
>>> end_learning_rate = 0.01
>>> decay_steps = 4
>>> power = 0.5
>>> global_step = Tensor(2, mstype.int32)
>>> polynomial_decay_lr = nn.PolynomialDecayLR(learning_rate, end_learning_rate, decay_steps, power)
>>> result = polynomial_decay_lr(global_step)
>>> print(result)
0.07363961

112
docs/api/api_python/nn/mindspore.nn.ProximalAdagrad.txt
View File

@ -1,9 +1,12 @@
Class mindspore.nn.ProximalAdagrad(*args, **kwargs)
mindspore.nn.ProximalAdagrad
==============================
.. py:class:: mindspore.nn.ProximalAdagrad(*args, **kwargs)
使用ApplyProximalAdagrad算子实现ProximalAdagrad算法。
ProximalAdagrad用于在线学习和随机优化。
请参阅论文`Efficient Learning using Forward-Backward Splitting <http://papers.nips.cc//paper/3793-efficient-learning-using-forward-backward-splitting.pdf>`_。
请参阅论文 `Efficient Learning using Forward-Backward Splitting <http://papers.nips.cc//paper/3793-efficient-learning-using-forward-backward-splitting.pdf>`_。
.. math::
accum_{t+1} = accum_{t} + grad * grad
@ -14,69 +17,78 @@ Class mindspore.nn.ProximalAdagrad(*args, **kwargs)
.. math::
var_{t+1} = \frac{sign(\text{prox_v})}{1 + lr * l2} * \max(\left| \text{prox_v} \right| - lr * l1, 0)
其中，grad、lr、var、accum和t分别表示`grads`, `learning_rate`, `params`、累加器和当前step。
其中，grad、lr、var、accum和t分别表示 `grads`, `learning_rate`, `params` 、累加器和当前step。
.. note::
.. include:: mindspore.nn.optim_note_sparse.rst
.. include:: mindspore.nn.optim_note_weight_decay.rst
参数：
param (Union[list[Parameter], list[dict]]) - 必须是 `Parameter` 组成的列表或字典组成的列表。当列表元素是字典时，字典的键可以是"params"、"lr"、"weight_decay"、"grad_centralization"和"order_params"：
**参数：**
.. include:: mindspore.nn.optim_group_param.rst
.. include:: mindspore.nn.optim_group_lr.rst
.. include:: mindspore.nn.optim_group_weight_decay.rst
.. include:: mindspore.nn.optim_group_gc.rst
.. include:: mindspore.nn.optim_group_order.rst
- **param** (Union[list[Parameter], list[dict]]) - 必须是 `Parameter` 组成的列表或字典组成的列表。当列表元素是字典时，字典的键可以是"params"、"lr"、"weight_decay"、"grad_centralization"和"order_params"：
accum (float)：累加器`accum`的初始值，起始值必须为零或正值。默认值：0.1。
.. include:: mindspore.nn.optim_group_param.rst
.. include:: mindspore.nn.optim_group_lr.rst
.. include:: mindspore.nn.optim_group_weight_decay.rst
.. include:: mindspore.nn.optim_group_gc.rst
.. include:: mindspore.nn.optim_group_order.rst
learning_rate (Union[float, Tensor, Iterable, LearningRateSchedule]): 默认值：1e-3。
.. include:: mindspore.nn.optim_arg_dynamic_lr.rst
- **accum** (float)：累加器`accum`的初始值，起始值必须为零或正值。默认值：0.1。
l1 (float):l1正则化强度，必须大于或等于零。默认值：0.0。
l2 (float):l2正则化强度，必须大于或等于零。默认值：0.0。
use_locking (bool)：如果为True，则更新操作使用锁保护。默认值：False。
.. include:: mindspore.nn.optim_arg_loss_scale.rst
weight_decay (Union[float, int])：要乘以权重的权重衰减值，必须为零或正值。默认值：0.0。
- **learning_rate** (Union[float, Tensor, Iterable, LearningRateSchedule]): 默认值：1e-3。
输入：
- **grads** (tuple[Tensor]) - 优化器中`params`的梯度，shape与优化器中的`params`相同。
.. include:: mindspore.nn.optim_arg_dynamic_lr.rst
输出：
Tensor[bool]，值为True。
- **l1** (float):l1正则化强度，必须大于或等于零。默认值：0.0。
- **l2** (float):l2正则化强度，必须大于或等于零。默认值：0.0。
- **use_locking** (bool)：如果为True，则更新操作使用锁保护。默认值：False。
异常：
TypeError：`learning_rate`不是int、float、Tensor、Iterable或LearningRateSchedule。
TypeError：`parameters`的元素不是Parameter或字典。
TypeError：`accum`、`l1`、`l2`或`loss_scale`不是float。
TypeError：`weight_decay`不是float或int。
ValueError：`loss_scale`小于或等于0。
ValueError：`accum`、`l1`、`l2`或`weight_decay`小于0。
.. include:: mindspore.nn.optim_arg_loss_scale.rst
支持平台：
``Ascend``
- **weight_decay** (Union[float, int])：要乘以权重的权重衰减值，必须为零或正值。默认值：0.0。
**输入：**
**grads** (tuple[Tensor]) - 优化器中 `params` 的梯度，shape与优化器中的 `params` 相同。
**输出：**
Tensor[bool]，值为True。
**异常：**
- **TypeError**：`learning_rate` 不是int、float、Tensor、Iterable或LearningRateSchedule。
- **TypeError**：`parameters` 的元素不是Parameter或字典。
- **TypeError**：`accum`、`l1`、`l2` 或 `loss_scale`不是float。
- **TypeError**：`weight_decay` 不是float或int。
- **ValueError**：`loss_scale` 小于或等于0。
- **ValueError**：`accum`、`l1`、`l2` 或 `weight_decay` 小于0。
**支持平台：**
``Ascend``
**样例：**
>>> net = Net()
>>> #1) 所有参数使用相同的学习率和权重衰减
>>> optim = nn.ProximalAdagrad(params=net.trainable_params())
>>>
>>> #2) 使用参数组并设置不同的值
>>> conv_params = list(filter(lambda x: 'conv' in x.name, net.trainable_params()))
>>> no_conv_params = list(filter(lambda x: 'conv' not in x.name, net.trainable_params()))
>>> group_params = [{'params': conv_params, 'weight_decay': 0.01, 'grad_centralization':True},
... {'params': no_conv_params, 'lr': 0.01},
... {'order_params': net.trainable_params()}]
>>> optim = nn.ProximalAdagrad(group_params, learning_rate=0.1, weight_decay=0.0)
>>> # conv_params参数组将使用优化器中的学习率0.1、该组的权重衰减0.01、该组的梯度中心化配置True。
>>> # no_conv_params参数组将使用该组的学习率0.01、优化器中的权重衰减0.0、梯度中心化使用默认值False。
>>> # 优化器按照"order_params"配置的参数顺序更新参数。
>>>
>>> loss = nn.SoftmaxCrossEntropyWithLogits()
>>> model = Model(net, loss_fn=loss, optimizer=optim)
示例：
>>> net = Net()
>>> #1) 所有参数使用相同的学习率和权重衰减
>>> optim = nn.ProximalAdagrad(params=net.trainable_params())
>>>
>>> #2) 使用参数组并设置不同的值
>>> conv_params = list(filter(lambda x: 'conv' in x.name, net.trainable_params()))
>>> no_conv_params = list(filter(lambda x: 'conv' not in x.name, net.trainable_params()))
>>> group_params = [{'params': conv_params, 'weight_decay': 0.01, 'grad_centralization':True},
... {'params': no_conv_params, 'lr': 0.01},
... {'order_params': net.trainable_params()}]
>>> optim = nn.ProximalAdagrad(group_params, learning_rate=0.1, weight_decay=0.0)
>>> # conv_params参数组将使用优化器中的学习率0.1、该组的权重衰减0.01、该组的梯度中心化配置True。
>>> # no_conv_params参数组将使用该组的学习率0.01、优化器中的权重衰减0.0、梯度中心化使用默认值False。
>>> # 优化器按照"order_params"配置的参数顺序更新参数。
>>>
>>> loss = nn.SoftmaxCrossEntropyWithLogits()
>>> model = Model(net, loss_fn=loss, optimizer=optim)
.. include:: mindspore.nn.optim_target_unique_for_sparse.rst

131
docs/api/api_python/nn/mindspore.nn.RMSProp.txt
View File

@ -1,8 +1,11 @@
Class mindspore.nn.RMSProp(*args, **kwargs)
mindspore.nn.RMSProp
======================
.. py:class:: mindspore.nn.RMSProp(*args, **kwargs)
实现均方根传播（RMSProp）算法。
根据RMSProp算法更新`params`，算法详见[http://www.cs.toronto.edu/~tijmen/csc321/slides/lecture_slides_lec6.pdf]第29页。
根据RMSProp算法更新 `params`，算法详见 [http://www.cs.toronto.edu/~tijmen/csc321/slides/lecture_slides_lec6.pdf] 第29页。
公式如下：
@ -15,7 +18,7 @@ Class mindspore.nn.RMSProp(*args, **kwargs)
.. math::
w = w - m_{t+1}
第一个方程计算每个权重的平方梯度的移动平均。然后将梯度除以:math:`\sqrt{ms_{t+1} + \epsilon}`。
第一个方程计算每个权重的平方梯度的移动平均。然后将梯度除以 :math:`\sqrt{ms_{t+1} + \epsilon}`。
如果centered为True：
@ -31,71 +34,81 @@ Class mindspore.nn.RMSProp(*args, **kwargs)
.. math::
w = w - m_{t+1}
其中:math:`w`代表待更新的网络参数`params`。
:math:`g_{t+1}`是平均梯度。
:math:`s_{t+1}`是均方梯度。
:math:`m_{t+1}`是moment，`w`的delta。
:math:`\rho`代表`decay`。:math:`\beta`是动量项，表示`momentum`。
:math:`\epsilon`是平滑项，可以避免除以零，表示`epsilon`。
:math:`\eta`是学习率，表示`learning_rate`。:math:`\nabla Q_{i}(w)`是梯度，表示`gradients`。
:math:`t`表示当前step。
其中 :math:`w` 代表待更新的网络参数 `params`。
:math:`g_{t+1}` 是平均梯度。
:math:`s_{t+1}` 是均方梯度。
:math:`m_{t+1}` 是moment，`w` 的delta。
:math:`\rho` 代表 `decay`。:math:`\beta` 是动量项，表示 `momentum`。
:math:`\epsilon` 是平滑项，可以避免除以零，表示 `epsilon`。
:math:`\eta` 是学习率，表示 `learning_rate`。 :math:`\nabla Q_{i}(w)` 是梯度，表示 `gradients`。
:math:`t` 表示当前step。
.. note::
.. include:: mindspore.nn.optim_note_weight_decay.rst
参数：
params (Union[list[Parameter], list[dict]])：必须是 `Parameter` 组成的列表或字典组成的列表。当列表元素是字典时，字典的键可以是"params"、"lr"、"weight_decay"、"grad_centralization"和"order_params"：
**参数：**
.. include:: mindspore.nn.optim_group_param.rst
.. include:: mindspore.nn.optim_group_lr.rst
.. include:: mindspore.nn.optim_group_weight_decay.rst
.. include:: mindspore.nn.optim_group_gc.rst
.. include:: mindspore.nn.optim_group_order.rst
- **params** (Union[list[Parameter], list[dict]])：必须是 `Parameter` 组成的列表或字典组成的列表。当列表元素是字典时，字典的键可以是"params"、"lr"、"weight_decay"、"grad_centralization"和"order_params"：
learning_rate (Union[float, Tensor, Iterable, LearningRateSchedule])：默认值：0.1。
.. include:: mindspore.nn.optim_arg_dynamic_lr.rst
decay (float)：衰减率。必须大于等于0。默认值：0.9。
momentum (float)：Float类型的超参数，表示移动平均的动量（momentum）。必须大于等于0。默认值：0.0。
epsilon (float)：将添加到分母中，以提高数值稳定性。取值大于0。默认值：1e-10。
use_locking (bool)：是否对参数更新加锁保护。默认值：False。
centered (bool)：如果为True，则梯度将通过梯度的估计方差进行归一。默认值：False。
.. include:: mindspore.nn.optim_arg_loss_scale.rst
weight_decay (Union[float, int])：权重衰减（L2 penalty）。必须大于等于0。默认值：0.0。
.. include:: mindspore.nn.optim_group_param.rst
.. include:: mindspore.nn.optim_group_lr.rst
.. include:: mindspore.nn.optim_group_weight_decay.rst
.. include:: mindspore.nn.optim_group_gc.rst
.. include:: mindspore.nn.optim_group_order.rst
输入：
- **gradients** （tuple[Tensor]） - `params`的梯度，shape与`params`相同。
- **learning_rate (Union[float, Tensor, Iterable, LearningRateSchedule])：默认值：0.1。
输出：
Tensor[bool]，值为True。
.. include:: mindspore.nn.optim_arg_dynamic_lr.rst
异常：
TypeError：`learning_rate`不是int、float、Tensor、Iterable或LearningRateSchedule。
TypeError：`decay`、`momentum`、`epsilon`或`loss_scale`不是float。
TypeError：`parameters`的元素不是Parameter或字典。
TypeError：`weight_decay`不是float或int。
TypeError：`use_locking`或`centered`不是bool。
ValueError：`epsilon`小于或等于0。
ValueError：`decay`或`momentum`小于0。
- **decay** (float)：衰减率。必须大于等于0。默认值：0.9。
- **momentum** (float)：Float类型的超参数，表示移动平均的动量（momentum）。必须大于等于0。默认值：0.0。
- **epsilon** (float)：将添加到分母中，以提高数值稳定性。取值大于0。默认值：1e-10。
- **use_locking** (bool)：是否对参数更新加锁保护。默认值：False。
- **centered** (bool)：如果为True，则梯度将通过梯度的估计方差进行归一。默认值：False。
.. include:: mindspore.nn.optim_arg_loss_scale.rst
支持平台：
``Ascend`` ``GPU`` ``CPU``
- **weight_decay** (Union[float, int])：权重衰减（L2 penalty）。必须大于等于0。默认值：0.0。
示例：
>>> net = Net()
>>> #1) 所有参数使用相同的学习率和权重衰减
>>> optim = nn.RMSProp(params=net.trainable_params(), learning_rate=0.1)
>>>
>>> #2) 使用参数分组并设置不同的值
>>> conv_params = list(filter(lambda x: 'conv' in x.name, net.trainable_params()))
>>> no_conv_params = list(filter(lambda x: 'conv' not in x.name, net.trainable_params()))
>>> group_params = [{'params': conv_params, 'weight_decay': 0.01, 'grad_centralization':True},
... {'params': no_conv_params, 'lr': 0.01},
... {'order_params': net.trainable_params()}]
>>> optim = nn.RMSProp(group_params, learning_rate=0.1, weight_decay=0.0)
>>> # conv_params参数组将使用优化器中的学习率0.1、该组的权重衰减0.01、该组的梯度中心化配置True。
>>> # no_conv_params参数组将使用该组的学习率0.01、优化器中的权重衰减0.0、梯度中心化使用默认值False。
>>> # 优化器按照"order_params"配置的参数顺序更新参数。
>>>
>>> loss = nn.SoftmaxCrossEntropyWithLogits()
>>> model = Model(net, loss_fn=loss, optimizer=optim)
**输入：**
**gradients** （tuple[Tensor]） - `params` 的梯度，shape与 `params` 相同。
**输出：**
Tensor[bool]，值为True。
**异常：**
- **TypeError**：`learning_rate` 不是int、float、Tensor、Iterable或LearningRateSchedule。
- **TypeError**：`decay` 、 `momentum` 、 `epsilon` 或 `loss_scale` 不是float。
- **TypeError**：`parameters` 的元素不是Parameter或字典。
- **TypeError**：`weight_decay` 不是float或int。
- **TypeError**：`use_locking` 或 `centered` 不是bool。
- **ValueError**：`epsilon` 小于或等于0。
- **ValueError**：`decay` 或 `momentum` 小于0。
**支持平台：**
``Ascend`` ``GPU`` ``CPU``
**样例：**
>>> net = Net()
>>> #1) 所有参数使用相同的学习率和权重衰减
>>> optim = nn.RMSProp(params=net.trainable_params(), learning_rate=0.1)
>>>
>>> #2) 使用参数分组并设置不同的值
>>> conv_params = list(filter(lambda x: 'conv' in x.name, net.trainable_params()))
>>> no_conv_params = list(filter(lambda x: 'conv' not in x.name, net.trainable_params()))
>>> group_params = [{'params': conv_params, 'weight_decay': 0.01, 'grad_centralization':True},
... {'params': no_conv_params, 'lr': 0.01},
... {'order_params': net.trainable_params()}]
>>> optim = nn.RMSProp(group_params, learning_rate=0.1, weight_decay=0.0)
>>> # conv_params参数组将使用优化器中的学习率0.1、该组的权重衰减0.01、该组的梯度中心化配置True。
>>> # no_conv_params参数组将使用该组的学习率0.01、优化器中的权重衰减0.0、梯度中心化使用默认值False。
>>> # 优化器按照"order_params"配置的参数顺序更新参数。
>>>
>>> loss = nn.SoftmaxCrossEntropyWithLogits()
>>> model = Model(net, loss_fn=loss, optimizer=optim)

89
docs/api/api_python/nn/mindspore.nn.TrainOneStepCell.txt
View File

@ -1,50 +1,59 @@
Class mindspore.nn.TrainOneStepCell(network, optimizer, sens=1.0)
mindspore.nn.TrainOneStepCell
=============================
.. py:class:: mindspore.nn.TrainOneStepCell(network, optimizer, sens=1.0)
训练网络封装类。
封装`network`和`optimizer`，构建一个输入'\*inputs'的用于训练的Cell。
执行函数`construct`中会构建反向图以更新网络参数。支持不同的并行训练模式。
封装 `network` 和 `optimizer` ，构建一个输入'\*inputs'的用于训练的Cell。
执行函数 `construct` 中会构建反向图以更新网络参数。支持不同的并行训练模式。
参数：
network (Cell)：训练网络。只支持单输出网络。
optimizer (Union[Cell])：用于更新网络参数的优化器。
sens (numbers.Number)：反向传播的输入，缩放系数。默认值为1.0。
**参数：**
输入：
- **(\*inputs)** (Tuple(Tensor)) - shape为:math:`(N, \ldots)`的Tensor组成的元组。
- **network** (Cell)：训练网络。只支持单输出网络。
- **optimizer** (Union[Cell])：用于更新网络参数的优化器。
- **sens** (numbers.Number)：反向传播的输入，缩放系数。默认值为1.0。
输出：
Tensor，损失函数值，其shape通常为:math:`()`。
**输入：**
异常：
TypeError：`sens`不是numbers.Number。
**(\*inputs)** (Tuple(Tensor)) - shape为 :math:`(N, \ldots)` 的Tensor组成的元组。
支持平台：
``Ascend`` ``GPU`` ``CPU``
**输出：**
示例：
>>> net = Net()
>>> loss_fn = nn.SoftmaxCrossEntropyWithLogits()
>>> optim = nn.Momentum(net.trainable_params(), learning_rate=0.1, momentum=0.9)
>>> # 1）使用MindSpore提供的WithLossCell
>>> loss_net = nn.WithLossCell(net, loss_fn)
>>> train_net = nn.TrainOneStepCell(loss_net, optim)
>>>
>>> # 2）用户自定义的WithLossCell
>>> class MyWithLossCell(Cell):
... def __init__(self, backbone, loss_fn):
... super(MyWithLossCell, self).__init__(auto_prefix=False)
... self._backbone = backbone
... self._loss_fn = loss_fn
...
... def construct(self, x, y, label):
... out = self._backbone(x, y)
... return self._loss_fn(out, label)
...
... @property
... def backbone_network(self):
... return self._backbone
...
>>> loss_net = MyWithLossCell(net, loss_fn)
>>> train_net = nn.TrainOneStepCell(loss_net, optim)
Tensor，损失函数值，其shape通常为 :math:`()` 。
**异常：**
**TypeError**：`sens` 不是numbers.Number。
**支持平台：**
``Ascend`` ``GPU`` ``CPU``
**样例：**
>>> net = Net()
>>> loss_fn = nn.SoftmaxCrossEntropyWithLogits()
>>> optim = nn.Momentum(net.trainable_params(), learning_rate=0.1, momentum=0.9)
>>> # 1）使用MindSpore提供的WithLossCell
>>> loss_net = nn.WithLossCell(net, loss_fn)
>>> train_net = nn.TrainOneStepCell(loss_net, optim)
>>>
>>> # 2）用户自定义的WithLossCell
>>> class MyWithLossCell(Cell):
... def __init__(self, backbone, loss_fn):
... super(MyWithLossCell, self).__init__(auto_prefix=False)
... self._backbone = backbone
... self._loss_fn = loss_fn
...
... def construct(self, x, y, label):
... out = self._backbone(x, y)
... return self._loss_fn(out, label)
...
... @property
... def backbone_network(self):
... return self._backbone
...
>>> loss_net = MyWithLossCell(net, loss_fn)
>>> train_net = nn.TrainOneStepCell(loss_net, optim)

175
docs/api/api_python/nn/mindspore.nn.TrainOneStepWithLossScaleCell.txt
View File

@ -1,116 +1,129 @@
Class mindspore.nn.TrainOneStepWithLossScaleCell(network, optimizer, scale_sense)
mindspore.nn.TrainOneStepWithLossScaleCell
==========================================
.. py:class:: mindspore.nn.TrainOneStepWithLossScaleCell(network, optimizer, scale_sense)
使用梯度放大功能（loss scale）的训练网络。
实现了包含梯度放大功能的单次训练。它使用网络、优化器和用于更新梯度放大系数的Cell(或一个Tensor)作为参数。可在host侧或device侧更新梯度放大系数。
如果需要在host侧更新，使用Tensor作为`scale_sense`，否则，使用可更新梯度放大系数的Cell实例作为`scale_sense`。
如果需要在host侧更新，使用Tensor作为 `scale_sense` ，否则，使用可更新梯度放大系数的Cell实例作为 `scale_sense` 。
参数：
network (Cell)：训练网络。仅支持单输出网络。
optimizer (Cell)：用于更新网络参数的优化器。
scale_sense (Union[Tensor, Cell])：如果此值为Cell类型，`TrainOneStepWithLossScaleCell`会调用它来更新梯度放大系数。如果此值为Tensor类型，可调用`set_sense_scale`来更新梯度放大系数，shape为:math:`()`或:math:`(1,)`。
**参数：**
输入：
- **(*inputs)** (Tuple(Tensor))- shape为:math:`(N, \ldots)`的Tensor组成的元组。
- **network** (Cell)：训练网络。仅支持单输出网络。
- **optimizer** (Cell)：用于更新网络参数的优化器。
- **scale_sense** (Union[Tensor, Cell])：如果此值为Cell类型，`TrainOneStepWithLossScaleCell` 会调用它来更新梯度放大系数。如果此值为Tensor类型，可调用 `set_sense_scale` 来更新梯度放大系数，shape为 :math:`()` 或 :math:`(1,)` 。
输出：
Tuple，包含三个Tensor，分别为损失函数值、溢出状态和当前梯度放大系数。
**输入：**
- **loss** （Tensor） - shape为:math:`()`的Tensor。
- **overflow** （Tensor）- shape为:math:`()`的Tensor，类型为bool。
- **loss scale** （Tensor）- shape为:math:`()`的Tensor。
**(*inputs)** (Tuple(Tensor))- shape为 :math:`(N, \ldots)` 的Tensor组成的元组。
异常：
TypeError：`scale_sense`既不是Cell，也不是Tensor。
ValueError：`scale_sense`的shape既不是(1,)也不是()。
**输出：**
支持平台：
``Ascend`` ``GPU``
Tuple，包含三个Tensor，分别为损失函数值、溢出状态和当前梯度放大系数。
示例：
>>> import numpy as np
>>> from mindspore import Tensor, Parameter, nn, ops
>>> from mindspore import dtype as mstype
>>>
>>> class Net(nn.Cell):
... def __init__(self, in_features, out_features):
... super(Net, self).__init__()
... self.weight = Parameter(Tensor(np.ones([in_features, out_features]).astype(np.float32)),
... name='weight')
... self.matmul = ops.MatMul()
...
... def construct(self, x):
... output = self.matmul(x, self.weight)
... return output
...
>>> size, in_features, out_features = 16, 16, 10
>>> #1）scale_sense类型为Cell时：
>>> net = Net(in_features, out_features)
>>> loss = nn.MSELoss()
>>> optimizer = nn.Momentum(net.trainable_params(), learning_rate=0.1, momentum=0.9)
>>> net_with_loss = nn.WithLossCell(net, loss)
>>> manager = nn.DynamicLossScaleUpdateCell(loss_scale_value=2**12, scale_factor=2, scale_window=1000)
>>> train_network = nn.TrainOneStepWithLossScaleCell(net_with_loss, optimizer, scale_sense=manager)
>>> input = Tensor(np.ones([out_features, in_features]), mindspore.float32)
>>> labels = Tensor(np.ones([out_features,]), mindspore.float32)
>>> output = train_network(input, labels)
>>>
>>>> #2）当scale_sense类型为Tensor时：
>>> net = Net(in_features, out_features)
>>> loss = nn.MSELoss()
>>> optimizer = nn.Momentum(net.trainable_params(), learning_rate=0.1, momentum=0.9)
>>> net_with_loss = nn.WithLossCell(net, loss)
>>> inputs = Tensor(np.ones([size, in_features]).astype(np.float32))
>>> label = Tensor(np.zeros([size, out_features]).astype(np.float32))
>>> scaling_sens = Tensor(np.full((1), np.finfo(np.float32).max), dtype=mstype.float32)
>>> train_network = nn.TrainOneStepWithLossScaleCell(net_with_loss, optimizer, scale_sense=scaling_sens)
>>> output = train_network(inputs, label)
- **loss** （Tensor） - shape为 :math:`()` 的Tensor。
- **overflow** （Tensor）- shape为 :math:`()` 的Tensor，类型为bool。
- **loss scale** （Tensor）- shape为 :math:`()` 的Tensor。
get_overflow_status(status, compute_output)
**异常：**
- **TypeError**：`scale_sense` 既不是Cell，也不是Tensor。
- **ValueError**：`scale_sense` 的shape既不是(1,)也不是()。
**支持平台：**
``Ascend`` ``GPU``
**样例：**
>>> import numpy as np
>>> from mindspore import Tensor, Parameter, nn, ops
>>> from mindspore import dtype as mstype
>>>
>>> class Net(nn.Cell):
... def __init__(self, in_features, out_features):
... super(Net, self).__init__()
... self.weight = Parameter(Tensor(np.ones([in_features, out_features]).astype(np.float32)),
... name='weight')
... self.matmul = ops.MatMul()
...
... def construct(self, x):
... output = self.matmul(x, self.weight)
... return output
...
>>> size, in_features, out_features = 16, 16, 10
>>> #1）scale_sense类型为Cell时：
>>> net = Net(in_features, out_features)
>>> loss = nn.MSELoss()
>>> optimizer = nn.Momentum(net.trainable_params(), learning_rate=0.1, momentum=0.9)
>>> net_with_loss = nn.WithLossCell(net, loss)
>>> manager = nn.DynamicLossScaleUpdateCell(loss_scale_value=2**12, scale_factor=2, scale_window=1000)
>>> train_network = nn.TrainOneStepWithLossScaleCell(net_with_loss, optimizer, scale_sense=manager)
>>> input = Tensor(np.ones([out_features, in_features]), mindspore.float32)
>>> labels = Tensor(np.ones([out_features,]), mindspore.float32)
>>> output = train_network(input, labels)
>>>
>>>> #2）当scale_sense类型为Tensor时：
>>> net = Net(in_features, out_features)
>>> loss = nn.MSELoss()
>>> optimizer = nn.Momentum(net.trainable_params(), learning_rate=0.1, momentum=0.9)
>>> net_with_loss = nn.WithLossCell(net, loss)
>>> inputs = Tensor(np.ones([size, in_features]).astype(np.float32))
>>> label = Tensor(np.zeros([size, out_features]).astype(np.float32))
>>> scaling_sens = Tensor(np.full((1), np.finfo(np.float32).max), dtype=mstype.float32)
>>> train_network = nn.TrainOneStepWithLossScaleCell(net_with_loss, optimizer, scale_sense=scaling_sens)
>>> output = train_network(inputs, label)
.. py:method:: get_overflow_status(status, compute_output)
获取浮点溢出状态。
溢出检测的目标过程执行完成后，获取溢出结果。继承该类自定义训练网络时，可复用该接口。
输入：
- **status** (object) - 用于检测溢出的状态实例。
- **compute_output** - 对特定计算过程进行溢出检测时，将`compute_output`设置为该计算过程的输出，以确保在执行计算之前获取了`status`。
**输入：**
输出：
bool，是否发生溢出。
- **status** (object) - 用于检测溢出的状态实例。
- **compute_output** - 对特定计算过程进行溢出检测时，将 `compute_output` 设置为该计算过程的输出，以确保在执行计算之前获取了 `status`。
**输出：**
bool，是否发生溢出。
process_loss_scale(overflow)
.. py:method:: process_loss_scale(overflow)
根据溢出状态计算梯度放大系数。继承该类自定义训练网络时，可复用该接口。
输入：
- **overflow** (bool) - 是否发生溢出。
**输入：**
输出：
bool，溢出状态，即输入。
**overflow** (bool) - 是否发生溢出。
**输出：**
bool，溢出状态，即输入。
set_sense_scale(sens)
.. py:method:: set_sense_scale(sens)
如果使用了Tensor类型的`scale_sense`，可调用此函数修改它的值。
输入：
- **sens** （Tensor）- 新的梯度放大系数，其shape和类型需要与原始`scale_sense`相同。
**输入：**
start_overflow_check(pre_cond, compute_input)
**sens** （Tensor）- 新的梯度放大系数，其shape和类型需要与原始 `scale_sense` 相同。
.. py:method:: start_overflow_check(pre_cond, compute_input)
启动浮点溢出检测。创建并清除溢出检测状态。
指定参数'pre_cond'和'compute_input'，以确保在正确的时间清除溢出状态。
以当前接口为例，我们需要在损失函数计算后进行清除状态，在梯度计算过程中检测溢出。在这种情况下，pre_cond应为损失函数的输出，而compute_input应为梯度计算函数的输入。继承该类自定义训练网络时，可复用该接口。
输入：
- **pre_cond** (Tensor) -启动溢出检测的先决条件。它决定溢出状态清除和先前处理的执行顺序。它确保函数'start_overflow'在执行完先决条件后清除状态。
- **compute_input** (object) - 后续运算的输入。需要对特定的计算过程进行溢出检测。将`compute_input`设置这一计算过程的输入，以确保在执行该计算之前清除了溢出状态。
指定参数 `pre_cond` 和 `compute_input` ，以确保在正确的时间清除溢出状态。以当前接口为例，我们需要在损失函数计算后进行清除状态，在梯度计算过程中检测溢出。在这种情况下，`pre_cond` 应为损失函数的输出，而 `compute_input` 应为梯度计算函数的输入。继承该类自定义训练网络时，可复用该接口。
**输入：**
输出：
Tuple[object, object]，GPU后端的第一个值为False，而其他后端的第一个值是NPUAllocFloatStatus的实例。该值用于在`get_overflow_status`期间检测溢出。
第二个值与`compute_input`的输入相同，用于控制执行序。
- **pre_cond** (Tensor) -启动溢出检测的先决条件。它决定溢出状态清除和先前处理的执行顺序。它确保函数 `start_overflow` 在执行完先决条件后清除状态。
- **compute_input** (object) - 后续运算的输入。需要对特定的计算过程进行溢出检测。将 `compute_input` 设置这一计算过程的输入，以确保在执行该计算之前清除了溢出状态。
**输出：**
**Tuple** [object, object]，GPU后端的第一个值为False，而其他后端的第一个值是NPUAllocFloatStatus的实例。该值用于在 `get_overflow_status` 期间检测溢出。第二个值与 `compute_input` 的输入相同，用于控制执行序。

4
docs/api/api_python/nn/mindspore.nn.WarmUpLR.rst
View File

@ -30,8 +30,8 @@ mindspore.nn.WarmUpLR
**异常：**
- **TypeError：** `learning_rate` 不是float。
- **TypeError：** `warmup_steps` 不是int。
- **- **TypeError**：** `learning_rate` 不是float。
- **- **TypeError**：** `warmup_steps` 不是int。
- **ValueError：** `warmup_steps` 小于1。
- **ValueError：** `learning_rate` 小于或等于0。

47
docs/api/api_python/nn/mindspore.nn.WithEvalCell.txt
View File

@ -1,29 +1,36 @@
Class mindspore.nn.WithEvalCell(network, loss_fn, add_cast_fp32=False)
mindspore.nn.WithEvalCell
=========================
.. py:class:: mindspore.nn.WithEvalCell(network, loss_fn, add_cast_fp32=False)
封装前向网络和损失函数，返回用于计算评估指标的损失函数值、前向输出和标签。
**参数：**
参数：
network (Cell)：前向网络。
loss_fn (Cell)：损失函数。
add_cast_fp32 (bool)：是否将数据类型调整为float32。默认值：False。
- **network** (Cell)：前向网络。
- **loss_fn** (Cell)：损失函数。
- **add_cast_fp32** (bool)：是否将数据类型调整为float32。默认值：False。
输入：
- **data** （Tensor） - shape为:math:`(N, \ldots)`的Tensor。
- **label** （Tensor） - shape为:math:`(N, \ldots)`的Tensor。
**输入：**
输出：
Tuple(Tensor)，包括标量损失函数、shape为:math:`(N, \ldots)`的网络输出和shape为:math:`(N, \ldots)`的标签。
- **data** （Tensor） - shape为 :math:`(N, \ldots)` 的Tensor。
- **label** （Tensor） - shape为 :math:`(N, \ldots)` 的Tensor。
异常：
TypeError：`add_cast_fp32`不是bool。
**输出：**
支持平台：
``Ascend`` ``GPU`` ``CPU``
Tuple(Tensor)，包括标量损失函数、shape为 :math:`(N, \ldots)` 的网络输出和shape为 :math:`(N, \ldots)` 的标签。
示例：
>>> # 未包含损失函数的前向网络
>>> net = Net()
>>> loss_fn = nn.SoftmaxCrossEntropyWithLogits()
>>> eval_net = nn.WithEvalCell(net, loss_fn)
**异常：**
**TypeError**： `add_cast_fp32` 不是bool。
**支持平台：**
``Ascend`` ``GPU`` ``CPU``
**样例：**
>>> # 未包含损失函数的前向网络
>>> net = Net()
>>> loss_fn = nn.SoftmaxCrossEntropyWithLogits()
>>> eval_net = nn.WithEvalCell(net, loss_fn)

67
docs/api/api_python/nn/mindspore.nn.WithLossCell.txt
View File

@ -1,42 +1,53 @@
Class mindspore.nn.WithLossCell(backbone, loss_fn)
mindspore.nn.WithLossCell
=========================
.. py:class:: mindspore.nn.WithLossCell(backbone, loss_fn)
包含损失函数的Cell。
封装`backbone`和`loss_fn`。此Cell接受数据和标签作为输入，并将返回损失函数作为计算结果。
封装 `backbone` 和 `loss_fn` 。此Cell接受数据和标签作为输入，并将返回损失函数作为计算结果。
参数：
backbone (Cell)：要封装的目标网络。
loss_fn (Cell)：用于计算损失函数。
**参数：**
输入：
- **data** （Tensor） - shape为:math:`(N, \ldots)`的Tensor。
- **label** （Tensor） - shape为:math:`(N, \ldots)`的Tensor。
- **backbone** (Cell)：要封装的目标网络。
- **loss_fn** (Cell)：用于计算损失函数。
输出：
Tensor，loss值，其shape通常为:math:`()`。
**输入：**
异常：
TypeError：`data`或`label`的数据类型既不是float16也不是float32。
- **data** （Tensor） - shape为 :math:`(N, \ldots)` 的Tensor。
- **label** （Tensor） - shape为 :math:`(N, \ldots)` 的Tensor。
支持平台：
``Ascend`` ``GPU`` ``CPU``
**输出：**
示例：
>>> net = Net()
>>> loss_fn = nn.SoftmaxCrossEntropyWithLogits(sparse=False)
>>> net_with_criterion = nn.WithLossCell(net, loss_fn)
>>>
>>> batch_size = 2
>>> data = Tensor(np.ones([batch_size, 1, 32, 32]).astype(np.float32) * 0.01)
>>> label = Tensor(np.ones([batch_size, 10]).astype(np.float32))
>>>
>>> output_data = net_with_criterion(data, label)
Tensor，loss值，其shape通常为 :math:`()` 。
**异常：**
**TypeError**：`data` 或 `label` 的数据类型既不是float16也不是float32。
**支持平台：**
``Ascend`` ``GPU`` ``CPU``
**样例：**
>>> net = Net()
>>> loss_fn = nn.SoftmaxCrossEntropyWithLogits(sparse=False)
>>> net_with_criterion = nn.WithLossCell(net, loss_fn)
>>>
>>> batch_size = 2
>>> data = Tensor(np.ones([batch_size, 1, 32, 32]).astype(np.float32) * 0.01)
>>> label = Tensor(np.ones([batch_size, 10]).astype(np.float32))
>>>
>>> output_data = net_with_criterion(data, label)
backbone_network
.. py:method:: backbone_network
:property:
获取骨干网络。
获取骨干网络。
返回：
Cell，骨干网络。
**返回：**
Cell，骨干网络。

44
docs/api/api_python/nn/mindspore.nn.cosine_decay_lr.txt
View File

@ -1,4 +1,7 @@
mindspore.nn.cosine_decay_lr(min_lr, max_lr, total_step, step_per_epoch, decay_epoch)
mindspore.nn.cosine_decay_lr
==============================
.. py:class:: mindspore.nn.cosine_decay_lr(min_lr, max_lr, total_step, step_per_epoch, decay_epoch)
基于余弦衰减函数计算学习率。
@ -8,25 +11,28 @@ mindspore.nn.cosine_decay_lr(min_lr, max_lr, total_step, step_per_epoch, decay_e
decayed\_learning\_rate[i] = min\_lr + 0.5 * (max\_lr - min\_lr) *
(1 + cos(\frac{current\_epoch}{decay\_epoch}\pi))
其中:math:`current\_epoch=floor(\frac{i}{step\_per\_epoch})`。
其中 :math:`current\_epoch=floor(\frac{i}{step\_per\_epoch})`。
参数：
min_lr (float)：学习率的最小值。
max_lr (float)：学习率的最大值。
total_step (int)：step总数。
step_per_epoch (int)：每个epoch的step数。
decay_epoch (int)：用于计算衰减学习率的值。
**参数：**
返回：
list[float]。列表大小为`total_step`。
- **min_lr** (float)：学习率的最小值。
- **max_lr** (float)：学习率的最大值。
- **total_step** (int)：step总数。
- **step_per_epoch** (int)：每个epoch的step数。
- **decay_epoch** (int)：用于计算衰减学习率的值。
示例：
>>> min_lr = 0.01
>>> max_lr = 0.1
>>> total_step = 6
>>> step_per_epoch = 2
>>> decay_epoch = 2
>>> output = cosine_decay_lr(min_lr, max_lr, total_step, step_per_epoch, decay_epoch)
>>> print(output)
[0.1, 0.1, 0.05500000000000001, 0.05500000000000001, 0.01, 0.01]
**返回：**
list[float]。列表大小为`total_step`。
**样例：**
>>> min_lr = 0.01
>>> max_lr = 0.1
>>> total_step = 6
>>> step_per_epoch = 2
>>> decay_epoch = 2
>>> output = cosine_decay_lr(min_lr, max_lr, total_step, step_per_epoch, decay_epoch)
>>> print(output)
[0.1, 0.1, 0.05500000000000001, 0.05500000000000001, 0.01, 0.01]

46
docs/api/api_python/nn/mindspore.nn.exponential_decay_lr.txt
View File

@ -1,4 +1,7 @@
mindspore.nn.exponential_decay_lr(learning_rate, decay_rate, total_step, step_per_epoch, decay_epoch, is_stair=False)
mindspore.nn.exponential_decay_lr
=======================================
.. py:class:: mindspore.nn.exponential_decay_lr(learning_rate, decay_rate, total_step, step_per_epoch, decay_epoch, is_stair=False)
基于指数衰减函数计算学习率。
@ -7,26 +10,29 @@ mindspore.nn.exponential_decay_lr(learning_rate, decay_rate, total_step, step_pe
.. math::
decayed\_learning\_rate[i] = learning\_rate * decay\_rate^{\frac{current\_epoch}{decay\_epoch}}
其中:math:`current\_epoch=floor(\frac{i}{step\_per\_epoch})`。
其中 :math:`current\_epoch=floor(\frac{i}{step\_per\_epoch})`。
参数：
learning_rate (float)：学习率的初始值。
decay_rate (float)：衰减率。
total_step (int)：step总数。
step_per_epoch (int)：每个 epoch的step数。
decay_epoch (int)：用于计算衰减学习率的值。
is_stair (bool)：如果为True，则学习率每`decay_epoch`次衰减一次。默认值：False。
**参数：**
返回：
list[float]。列表的大小为`total_step`。
- **learning_rate (float)：学习率的初始值。
- **decay_rate (float)：衰减率。
- **total_step (int)：step总数。
- **step_per_epoch (int)：每个 epoch的step数。
- **decay_epoch (int)：用于计算衰减学习率的值。
- **is_stair (bool)：如果为True，则学习率每 `decay_epoch` 次衰减一次。默认值：False。
示例：
>>> learning_rate = 0.1
>>> decay_rate = 0.9
>>> total_step = 6
>>> step_per_epoch = 2
>>> decay_epoch = 1
>>> output = exponential_decay_lr(learning_rate, decay_rate, total_step, step_per_epoch, decay_epoch)
>>> print(output)
[0.1, 0.1, 0.09000000000000001, 0.09000000000000001, 0.08100000000000002, 0.08100000000000002]
**返回：**
list[float]。列表的大小为`total_step`。
**样例：**
>>> learning_rate = 0.1
>>> decay_rate = 0.9
>>> total_step = 6
>>> step_per_epoch = 2
>>> decay_epoch = 1
>>> output = exponential_decay_lr(learning_rate, decay_rate, total_step, step_per_epoch, decay_epoch)
>>> print(output)
[0.1, 0.1, 0.09000000000000001, 0.09000000000000001, 0.08100000000000002, 0.08100000000000002]

44
docs/api/api_python/nn/mindspore.nn.inverse_decay_lr.txt
View File

@ -1,4 +1,7 @@
mindspore.nn.inverse_decay_lr(learning_rate, decay_rate, total_step, step_per_epoch, decay_epoch, is_stair=False)
mindspore.nn.inverse_decay_l
=============================
.. py:class:: mindspore.nn.inverse_decay_lr(learning_rate, decay_rate, total_step, step_per_epoch, decay_epoch, is_stair=False)
基于逆时间衰减函数计算学习率。
@ -9,24 +12,27 @@ mindspore.nn.inverse_decay_lr(learning_rate, decay_rate, total_step, step_per_ep
其中，:math:`current\_epoch=floor(\frac{i}{step\_per\_epoch})`。
参数：
learning_rate (float)：学习率的初始值。
decay_rate (float)：衰减率。
total_step (int)：step总数。
step_per_epoch (int)：每个epoch的step数。
decay_epoch (int)：用于计算衰减学习率的值。
is_stair (bool)：如果为True，则学习率每`decay_epoch`次衰减一次。默认值：False。
**参数：**
返回：
list[float]。列表大小为`total_step`。
- **learning_rate** (float)：学习率的初始值。
- **decay_rate** (float)：衰减率。
- **total_step** (int)：step总数。
- **step_per_epoch** (int)：每个epoch的step数。
- **decay_epoch** (int)：用于计算衰减学习率的值。
- **is_stair** (bool)：如果为True，则学习率每 `decay_epoch` 次衰减一次。默认值：False。
示例：
>>> learning_rate = 0.1
>>> decay_rate = 0.5
>>> total_step = 6
>>> step_per_epoch = 1
>>> decay_epoch = 1
>>> output = inverse_decay_lr(learning_rate, decay_rate, total_step, step_per_epoch, decay_epoch, True)
>>> print(output)
[0.1, 0.06666666666666667, 0.05, 0.04, 0.03333333333333333, 0.028571428571428574]
**返回：**
list[float]。列表大小为 `total_step` 。
**样例：**
>>> learning_rate = 0.1
>>> decay_rate = 0.5
>>> total_step = 6
>>> step_per_epoch = 1
>>> decay_epoch = 1
>>> output = inverse_decay_lr(learning_rate, decay_rate, total_step, step_per_epoch, decay_epoch, True)
>>> print(output)
[0.1, 0.06666666666666667, 0.05, 0.04, 0.03333333333333333, 0.028571428571428574]

46
docs/api/api_python/nn/mindspore.nn.natural_exp_decay_lr.txt
View File

@ -1,4 +1,7 @@
mindspore.nn.natural_exp_decay_lr(learning_rate, decay_rate, total_step, step_per_epoch, decay_epoch, is_stair=False)
mindspore.nn.natural_exp_decay_lr
=================================
.. py:class:: mindspore.nn.natural_exp_decay_lr(learning_rate, decay_rate, total_step, step_per_epoch, decay_epoch, is_stair=False)
基于自然指数衰减函数计算学习率。
@ -7,26 +10,29 @@ mindspore.nn.natural_exp_decay_lr(learning_rate, decay_rate, total_step, step_pe
.. math::
decayed\_learning\_rate[i] = learning\_rate * e^{-decay\_rate * current\_epoch}
其中:math:`current\_epoch=floor(\frac{i}{step\_per\_epoch})`。
其中 :math:`current\_epoch=floor(\frac{i}{step\_per\_epoch})` 。
参数：
learning_rate (float)：学习率的初始值。
decay_rate (float)：衰减率。
total_step (int)：step总数。
step_per_epoch (int)：每个epoch的step数。
decay_epoch (int)：用于计算衰减学习率的值。
is_stair (bool)：如果为True，则学习率每`decay_epoch`次衰减一次。默认值：False。
**参数：**
返回：
list[float]. `total_step`表示列表的大小。
- **learning_rate** (float)：学习率的初始值。
- **decay_rate** (float)：衰减率。
- **total_step** (int)：step总数。
- **step_per_epoch** (int)：每个epoch的step数。
- **decay_epoch** (int)：用于计算衰减学习率的值。
- **is_stair** (bool)：如果为True，则学习率每 `decay_epoch` 次衰减一次。默认值：False。
示例：
>>> learning_rate = 0.1
>>> decay_rate = 0.9
>>> total_step = 6
>>> step_per_epoch = 2
>>> decay_epoch = 2
>>> output = natural_exp_decay_lr(learning_rate, decay_rate, total_step, step_per_epoch, decay_epoch, True)
>>> print(output)
[0.1, 0.1, 0.1, 0.1, 0.016529888822158657, 0.016529888822158657]
**返回：**
list[float]. `total_step`表示列表的大小。
**样例：**
>>> learning_rate = 0.1
>>> decay_rate = 0.9
>>> total_step = 6
>>> step_per_epoch = 2
>>> decay_epoch = 2
>>> output = natural_exp_decay_lr(learning_rate, decay_rate, total_step, step_per_epoch, decay_epoch, True)
>>> print(output)
[0.1, 0.1, 0.1, 0.1, 0.016529888822158657, 0.016529888822158657]

34
docs/api/api_python/nn/mindspore.nn.piecewise_constant_lr.txt
View File

@ -1,23 +1,29 @@
mindspore.nn.piecewise_constant_lr(milestone, learning_rates)
mindspore.nn.piecewise_constant_lr
====================================
.. py:class:: mindspore.nn.piecewise_constant_lr(milestone, learning_rates)
获取分段常量学习率。
通过给定的`milestone`和`learning_rates`计算学习率。设`milestone`的值为:math:`(M_1, M_2, ..., M_t, ..., M_N)`，`learning_rates`的值为:math:`(x_1, x_2, ..., x_t, ..., x_N)`。N是`milestone`的长度。
设`y`为输出学习率， 那么对于第i步，计算y[i]的公式为：
通过给定的 `milestone` 和 `learning_rates` 计算学习率。设 `milestone` 的值为 :math:`(M_1, M_2, ..., M_t, ..., M_N)` ， `learning_rates` 的值为 :math:`(x_1, x_2, ..., x_t, ..., x_N)` 。N是 `milestone` 的长度。
设 `y` 为输出学习率， 那么对于第i步，计算y[i]的公式为：
.. math::
y[i] = x_t,\ for\ i \in [M_{t-1}, M_t)
参数：
milestone (Union[list[int], tuple[int]])：milestone列表。此列表是一个单调递增的列表。类表中的元素必须大于0。
learning_rates (Union[list[float], tuple[float]])：学习率列表。
**参数：**
返回：
list[float]。列表的大小为:math:`M_N`。
- **milestone** (Union[list[int], tuple[int]])：milestone列表。此列表是一个单调递增的列表。类表中的元素必须大于0。
- **learning_rates** (Union[list[float], tuple[float]])：学习率列表。
示例：
>>> milestone = [2, 5, 10]
>>> learning_rates = [0.1, 0.05, 0.01]
>>> output = piecewise_constant_lr(milestone, learning_rates)
>>> print(output)
[0.1, 0.1, 0.05, 0.05, 0.05, 0.01, 0.01, 0.01, 0.01, 0.01]
**返回：**
list[float]。列表的大小为 :math:`M_N`。
**样例：**
>>> milestone = [2, 5, 10]
>>> learning_rates = [0.1, 0.05, 0.01]
>>> output = piecewise_constant_lr(milestone, learning_rates)
>>> print(output)
[0.1, 0.1, 0.05, 0.05, 0.05, 0.01, 0.01, 0.01, 0.01, 0.01]

50
docs/api/api_python/nn/mindspore.nn.polynomial_decay_lr.txt
View File

@ -1,4 +1,7 @@
mindspore.nn.polynomial_decay_lr(learning_rate, end_learning_rate, total_step, step_per_epoch, decay_epoch, power, update_decay_epoch=False)
mindspore.nn.polynomial_decay_lr
====================================
.. py:class:: mindspore.nn.polynomial_decay_lr(learning_rate, end_learning_rate, total_step, step_per_epoch, decay_epoch, power, update_decay_epoch=False)
基于多项式衰减函数计算学习率。
@ -19,31 +22,34 @@ mindspore.nn.polynomial_decay_lr(learning_rate, end_learning_rate, total_step, s
.. math::
tmp\_decay\_epoch = decay\_epoch
如果`update_decay_epoch`为True，则每个epoch更新`tmp_decay_epoch`的值。公式为：
如果 `update_decay_epoch` 为True，则每个epoch更新 `tmp_decay_epoch` 的值。公式为：
.. math::
tmp\_decay\_epoch = decay\_epoch * ceil(current\_epoch / decay\_epoch)
参数：
learning_rate (float)：学习率的初始值。
end_learning_rate (float)：学习率的最终值。
total_step (int)：step总数。
step_per_epoch (int)：每个epoch的step数。
decay_epoch (int)：用于计算衰减学习率的值。
power (float)：用于计算衰减学习率的值。该参数必须大于0。
update_decay_epoch (bool)：如果为True，则更新`decay_epoch`。默认值：False。
**参数：**
返回：
list[float]。列表的大小为`total_step`。
- **learning_rate** (float)：学习率的初始值。
- **end_learning_rate** (float)：学习率的最终值。
- **total_step** (int)：step总数。
- **step_per_epoch** (int)：每个epoch的step数。
- **decay_epoch** (int)：用于计算衰减学习率的值。
- **power** (float)：用于计算衰减学习率的值。该参数必须大于0。
- **update_decay_epoch** (bool)：如果为True，则更新 `decay_epoch` 。默认值：False。
示例：
>>> learning_rate = 0.1
>>> end_learning_rate = 0.01
>>> total_step = 6
>>> step_per_epoch = 2
>>> decay_epoch = 2
>>> power = 0.5
>>> r = polynomial_decay_lr(learning_rate, end_learning_rate, total_step, step_per_epoch, decay_epoch, power)
>>> print(r)
[0.1, 0.1, 0.07363961030678928, 0.07363961030678928, 0.01, 0.01]
**返回：**
list[float]。列表的大小为 `total_step`。
**样例：**
>>> learning_rate = 0.1
>>> end_learning_rate = 0.01
>>> total_step = 6
>>> step_per_epoch = 2
>>> decay_epoch = 2
>>> power = 0.5
>>> r = polynomial_decay_lr(learning_rate, end_learning_rate, total_step, step_per_epoch, decay_epoch, power)
>>> print(r)
[0.1, 0.1, 0.07363961030678928, 0.07363961030678928, 0.01, 0.01]

40
docs/api/api_python/nn/mindspore.nn.warmup_lr.txt
View File

@ -1,4 +1,7 @@
mindspore.nn.warmup_lr(learning_rate, total_step, step_per_epoch, warmup_epoch)
mindspore.nn.warmup_lr
=======================
.. py:function:: mindspore.nn.warmup_lr(learning_rate, total_step, step_per_epoch, warmup_epoch)
预热学习率。
@ -7,23 +10,26 @@ mindspore.nn.warmup_lr(learning_rate, total_step, step_per_epoch, warmup_epoch)
.. math::
warmup\_learning\_rate[i] = learning\_rate * tmp\_epoch / warmup\_epoch
其中:math:`tmp\_epoch=min(current\_epoch, warmup\_epoch),\ current\_epoch=floor(\frac{i}{step\_per\_epoch})`
其中 :math:`tmp\_epoch=min(current\_epoch, warmup\_epoch),\ current\_epoch=floor(\frac{i}{step\_per\_epoch})`
参数：
learning_rate (float)：学习率的初始值。
total_step (int)：step总数。
step_per_epoch (int)：每个epoch的step数。
warmup_epoch (int)：预热学习率的epoch数。
**参数：**
返回：
list[float].`total_step`表示列表的大小。
- **learning_rate** (float)：学习率的初始值。
- **total_step** (int)：step总数。
- **step_per_epoch** (int)：每个epoch的step数。
- **warmup_epoch** (int)：预热学习率的epoch数。
示例：
>>> learning_rate = 0.1
>>> total_step = 6
>>> step_per_epoch = 2
>>> warmup_epoch = 2
>>> output = warmup_lr(learning_rate, total_step, step_per_epoch, warmup_epoch)
>>> print(output)
[0.0, 0.0, 0.05, 0.05, 0.1, 0.1]
**返回：**
list[float] - `total_step` 表示列表的大小。
**样例：**
>>> learning_rate = 0.1
>>> total_step = 6
>>> step_per_epoch = 2
>>> warmup_epoch = 2
>>> output = warmup_lr(learning_rate, total_step, step_per_epoch, warmup_epoch)
>>> print(output)
[0.0, 0.0, 0.05, 0.05, 0.1, 0.1]

240
docs/api/api_python/parallel/mindspore.communication.rst
View File

@ -5,289 +5,241 @@ mindspore.communication
.. py:class:: mindspore.communication.GlobalComm
全局通信信息。GlobalComm 是一个全局类。 成员包含：BACKEND、WORLD_COMM_GROUP。
- BACKEND：使用的通信库，HCCL或者NCCL。
- GlobalComm：全局通信域。
.. py:method:: mindspore.communication.init(backend_name=None)
初始化通信服务需要的分布式后端，例如HCCL或NCCL服务。
.. note::
HCCL的全称是华为集合通信库（Huawei Collective Communication Library），NCCL的全称是英伟达集合通信库（NVIDIA Collective Communication Library）。`init` 方法应该在 `set_context` 方法之后使用。
.. note::HCCL的全称是华为集合通信库（Huawei Collective Communication Library），NCCL的全称是英伟达集合通信库（NVIDIA Collective Communication Library）。`init` 方法应该在 `set_context` 方法之后使用。
**参数：**
- **backend_name** (`str`) – 后台服务的名称，可选HCCL或NCCL。如果未设置则根据硬件平台类型（device_target）进行推断，默认值为None。
**backend_name** (str) – 后台服务的名称，可选HCCL或NCCL。如果未设置则根据硬件平台类型（device_target）进行推断，默认值为None。
**异常：**
- **TypeError** – 在参数 `backend_name` 不是字符串时抛出。
- **TypeError** – 在参数 `backend_name` 不是字符串时抛出。
- **RuntimeError** – 在以下情况将抛出：1）硬件设备类型无效；2）后台服务无效；3）分布式计算初始化失败；4）未设置环境变量 `RANK_ID` 或 `MINDSPORE_HCCL_CONFIG_PATH` 的情况下初始化HCCL服务。
- **ValueError** – 在环境变量 `RANK_ID` 设置成非数字时抛出。
- **RuntimeError** – 在以下情况将抛出：1）硬件设备类型无效；2）后台服务无效；3）分布式计算初始化失败；4）未设置环境变量 `RANK_ID` 或 `MINDSPORE_HCCL_CONFIG_PATH` 的情况下初始化HCCL服务。
- **ValueError** – 在环境变量 `RANK_ID` 设置成非数字时抛出。
**样例：**
.. code-block::
**样例：**
>>> from mindspore.context import set_context
>>> set_context(device_target="Ascend")
>>> init()
>>> from mindspore.context import set_context
>>> set_context(device_target="Ascend")
>>> init()
.. py:class:: mindspore.communication.release()
释放分布式资源,例如‘HCCL’或‘NCCL’服务。
.. note::
`release` 方法应该在 `init` 方法之后使用。
.. note::`release` 方法应该在 `init` 方法之后使用。
**异常：**
- **RuntimeError** - 在释放分布式资源失败时抛出。
**RuntimeError** - 在释放分布式资源失败时抛出。
.. py:class:: mindspore.communication.get_rank(group=GlobalComm.WORLD_COMM_GROUP)
在指定通信组中获取当前的设备序号。
.. note::
`get_rank` 方法应该在 `init` 方法之后使用。
.. note::`get_rank` 方法应该在 `init` 方法之后使用。
**参数：**
- **group** (`str`) - 通信组名称，通常由 `create_group` 方法创建，否则将使用默认组。
- **默认值** - ‘WORLD_COMM_GROUP’。
**group** (str) - 通信组名称，通常由 `create_group` 方法创建，否则将使用默认组。默认值：‘WORLD_COMM_GROUP’。
**返回：**
int, 调用该方法的进程对应的组内序号。
int, 调用该方法的进程对应的组内序号。
**异常：**
- **TypeError** – 在参数 `group` 不是字符串时抛出。
- **ValueError** – 在后台不可用时抛出。
- **RuntimeError** – 在‘HCCL’或‘NCCL’服务不可用时抛出。
**TypeError** – 在参数 `group` 不是字符串时抛出。
**ValueError** – 在后台不可用时抛出。
**RuntimeError** – 在‘HCCL’或‘NCCL’服务不可用时抛出。
.. py:class:: mindspore.communication.get_group_size(group=GlobalComm.WORLD_COMM_GROUP)
获取指定通信组的设备总数。
.. note::
`get_group_size` 方法应该在 `init` 方法之后使用。
.. note:: `get_group_size` 方法应该在 `init` 方法之后使用。
**参数：**
- **group** (`str`) - 通信组名称，通常由 `create_group` 方法创建，否则将使用默认组。
- **默认值** - ‘WORLD_COMM_GROUP’。
**group** (str) - 通信组名称，通常由 `create_group` 方法创建，否则将使用默认组。默认值：‘WORLD_COMM_GROUP’。
**返回：**
int, 指定通信组的设备总数。
int, 指定通信组的设备总数。
**异常：**
- **TypeError** – 在参数 `group` 不是字符串时抛出。
- **ValueError** – 在后台不可用时抛出。
- **RuntimeError** – 在‘HCCL’或‘NCCL’服务不可用时抛出。
- **TypeError** – 在参数 `group` 不是字符串时抛出。
- **ValueError** – 在后台不可用时抛出。
- **RuntimeError** – 在‘HCCL’或‘NCCL’服务不可用时抛出。
.. py:class:: mindspore.communication.get_world_rank_from_group_rank(group, group_rank_id)
由指定通信组中的设备序号获取通信集群中的全局设备序号。
.. note::
1. GPU 版本的MindSpore不支持此方法；
2. 参数 `group` 不能是 `hccl_world_group`；
3. `get_world_rank_from_group_rank` 方法应该在 `init` 方法之后使用。
- GPU 版本的MindSpore不支持此方法；
- 参数 `group` 不能是 `hccl_world_group`；
- `get_world_rank_from_group_rank` 方法应该在 `init` 方法之后使用。
**参数：**
- **group** (`str`) - 传入的通信组名称，通常由 `create_group` 方法创建。
- **group_rank_id** (`int`) - 通信组内的设备序号
- **group** (str) - 传入的通信组名称，通常由 `create_group` 方法创建。
- **group_rank_id** (int) - 通信组内的设备序号。
**返回：**
int, 通信集群中的全局设备序号。
int, 通信集群中的全局设备序号。
**异常：**
- **TypeError** – 在参数 `group_rank_id` 不是数字或参数 `group` 不是字符串时抛出。
- **ValueError** – 在参数 `group` 是 `hccl_world_group` 或后台不可用时抛出。
- **RuntimeError** – 在‘HCCL’或‘NCCL’服务不可用，以及使用GPU版本的MindSpore时抛出。
- **TypeError** – 在参数 `group_rank_id` 不是数字或参数 `group` 不是字符串时抛出。
- **ValueError** – 在参数 `group` 是 `hccl_world_group` 或后台不可用时抛出。
- **RuntimeError** – 在‘HCCL’或‘NCCL’服务不可用，以及使用GPU版本的MindSpore时抛出。
**样例：**
.. code-block::
>>> from mindspore.context import set_context
>>> set_context(device_target="Ascend")
>>> init()
>>> group = "0-4"
>>> rank_ids = [0,4]
>>> create_group(group, rank_ids)
>>> world_rank_id = get_world_rank_from_group_rank(group, 1)
>>> print("world_rank_id is: ", world_rank_id) # 全局设备序号为4
>>> from mindspore.context import set_context
>>> set_context(device_target="Ascend")
>>> init()
>>> group = "0-4"
>>> rank_ids = [0,4]
>>> create_group(group, rank_ids)
>>> world_rank_id = get_world_rank_from_group_rank(group, 1)
>>> print("world_rank_id is: ", world_rank_id) # 全局设备序号为4
.. py:class:: mindspore.communication.get_group_rank_from_world_rank(world_rank_id, group)
由通信集群中的全局设备序号获取指定用户通信组中的设备序号。
.. note::
1. GPU 版本的MindSpore不支持此方法；
2. 参数 `group` 不能是 `hccl_world_group`；
3. `get_group_rank_from_world_rank` 方法应该在 `init` 方法之后使用。
- GPU 版本的MindSpore不支持此方法；
- 参数 `group` 不能是 `hccl_world_group`；
- `get_group_rank_from_world_rank` 方法应该在 `init` 方法之后使用。
**参数：**
- **world_rank_id** (`int`) - 通信集群内的全局设备序号。
- **group** (`str`) - 传入的通信组名称，通常由 `create_group` 方法创建。
- **world_rank_id** (`int`) - 通信集群内的全局设备序号。
- **group** (`str`) - 传入的通信组名称，通常由 `create_group` 方法创建。
**返回：**
int, 当前用户通信组中的设备序号。
int, 当前用户通信组中的设备序号。
**异常：**
- **TypeError** – 在参数 `group_rank_id` 不是数字或参数 `group` 不是字符串时抛出。
- **ValueError** – 在参数 `group` 是 `hccl_world_group` 或后台不可用时抛出。
- **RuntimeError** – 在‘HCCL’或‘NCCL’服务不可用，以及使用GPU版本的MindSpore时抛出。
- **TypeError** – 在参数 `group_rank_id` 不是数字或参数 `group` 不是字符串时抛出。
- **ValueError** – 在参数 `group` 是 `hccl_world_group` 或后台不可用时抛出。
- **RuntimeError** – 在‘HCCL’或‘NCCL’服务不可用，以及使用GPU版本的MindSpore时抛出。
**样例：**
.. code-block::
>>> from mindspore.context import set_context
>>> set_context(device_target="Ascend")
>>> init()
>>> group = "0-4"
>>> rank_ids = [0,4]
>>> create_group(group, rank_ids)
>>> group_rank_id = get_group_rank_from_world_rank(4, group)
>>> print("group_rank_id is: ", group_rank_id) # 组内设备序号是1
>>> from mindspore.context import set_context
>>> set_context(device_target="Ascend")
>>> init()
>>> group = "0-4"
>>> rank_ids = [0,4]
>>> create_group(group, rank_ids)
>>> group_rank_id = get_group_rank_from_world_rank(4, group)
>>> print("group_rank_id is: ", group_rank_id) # 组内设备序号是1
.. py:class:: mindspore.communication.create_group(group, rank_ids)
创建用户通信组。
.. note::
1. GPU 版本的MindSpore不支持此方法；
2. 列表rank_ids的长度应大于1；
3. 列表rank_ids内不能有重复数据；
4. `create_group` 方法应该在 `init` 方法之后使用。
- GPU 版本的MindSpore不支持此方法；
- 列表rank_ids的长度应大于1；
- 列表rank_ids内不能有重复数据；
- `create_group` 方法应该在 `init` 方法之后使用。
**参数：**
- **group** (`str`) - 将被创建的通信组名称。
- **rank_ids** (`list`) - 设备编号列表。
- **group** (str) - 将被创建的通信组名称。
- **rank_ids** (list) - 设备编号列表。
**异常：**
- **TypeError** – 在参数 `group_rank_id` 不是数字或参数 `group` 不是字符串时抛出。
- **ValueError** – 在列表rank_ids的长度小于1，或列表rank_ids内有重复数据，以及后台无效时抛出。
- **RuntimeError** – 在‘HCCL’或‘NCCL’ 服务不可用，以及使用GPU版本的MindSpore时抛出。
- **TypeError** – 在参数 `group_rank_id` 不是数字或参数 `group` 不是字符串时抛出。
- **ValueError** – 在列表rank_ids的长度小于1，或列表rank_ids内有重复数据，以及后台无效时抛出。
- **RuntimeError** – 在‘HCCL’或‘NCCL’ 服务不可用，以及使用GPU版本的MindSpore时抛出。
**样例：**
.. code-block::
>>> from mindspore.context import set_context
>>> set_context(device_target="Ascend")
>>> init()
>>> group = "0-8"
>>> rank_ids = [0,8]
>>> create_group(group, rank_ids)
>>> from mindspore.context import set_context
>>> set_context(device_target="Ascend")
>>> init()
>>> group = "0-8"
>>> rank_ids = [0,8]
>>> create_group(group, rank_ids)
.. py:class:: mindspore.communication.get_local_rank(group=GlobalComm.WORLD_COMM_GROUP)
获取指定通信组中当前设备的本地设备序号。
.. note::
1. GPU 版本的MindSpore不支持此方法；
2. `get_local_rank` 方法应该在 `init` 方法之后使用。
- GPU 版本的MindSpore不支持此方法；
- `get_local_rank` 方法应该在 `init` 方法之后使用。
**参数：**
- **group** (`str`) - 通信组名称，通常由 `create_group` 方法创建，否则将使用默认组名称。
- **默认值** - ‘WORLD_COMM_GROUP’。
**group** (`str`) - 通信组名称，通常由 `create_group` 方法创建，否则将使用默认组名称。默认值：‘WORLD_COMM_GROUP’。
**返回：**
int, 调用该方法的进程对应的通信组内本地设备序号。
int, 调用该方法的进程对应的通信组内本地设备序号。
**异常：**
- **TypeError** – 在参数 `group` 不是字符串时抛出。
- **ValueError** – 在后台不可用时抛出。
- **RuntimeError** – 在‘HCCL’或‘NCCL’服务不可用时抛出。
- **TypeError** – 在参数 `group` 不是字符串时抛出。
- **ValueError** – 在后台不可用时抛出。
- **RuntimeError** – 在‘HCCL’或‘NCCL’服务不可用时抛出。
.. py:class:: mindspore.communication.get_local_rank_size(group=GlobalComm.WORLD_COMM_GROUP)
获取指定通信组的本地设备总数。
.. note::
1. GPU 版本的MindSpore不支持此方法；
2. `get_local_rank_size` 方法应该在 `init` 方法之后使用。
- GPU 版本的MindSpore不支持此方法；
- `get_local_rank_size` 方法应该在 `init` 方法之后使用。
**参数：**
- **group** (`str`) - 传入的通信组名称，通常由 `create_group` 方法创建，或默认使用‘WORLD_COMM_GROUP’。
**group** (str) - 传入的通信组名称，通常由 `create_group` 方法创建，或默认使用‘WORLD_COMM_GROUP’。
**返回：**
int, 调用该方法的进程对应的通信组设备总数。
int, 调用该方法的进程对应的通信组设备总数。
**异常：**
- **TypeError** – 在参数 `group` 不是字符串时抛出。
- **ValueError** – 在后台不可用时抛出。
- **RuntimeError** – 在‘HCCL’或‘NCCL’服务不可用时抛出。
- **TypeError** – 在参数 `group` 不是字符串时抛出。
- **ValueError** – 在后台不可用时抛出。
- **RuntimeError** – 在‘HCCL’或‘NCCL’服务不可用时抛出。
.. py:class:: mindspore.communication.destroy_group(group)
销毁用户通信组。
.. note::
1. GPU 版本的MindSpore不支持此方法；
2. 参数 `group` 不能是 `hccl_world_group`；
3. `destroy_group` 方法应该在 `init` 方法之后使用。
- GPU 版本的MindSpore不支持此方法；
- 参数 `group` 不能是 `hccl_world_group`；
- `destroy_group` 方法应该在 `init` 方法之后使用。
**参数：**
- **group** (`str`) - 将被销毁的通信组，通常由 `create_group` 方法创建。
**group** (str) - 将被销毁的通信组，通常由 `create_group` 方法创建。
**异常：**
- **TypeError** – 在参数 `group` 不是字符串时抛出。
- **ValueError** – 在参数 `group` 是 `hccl_world_group` 或后台不可用时抛出。
- **RuntimeError** – 在‘HCCL’或‘NCCL’服务不可用时抛出。
- **TypeError** – 在参数 `group` 不是字符串时抛出。
- **ValueError** – 在参数 `group` 是 `hccl_world_group` 或后台不可用时抛出。
- **RuntimeError** – 在‘HCCL’或‘NCCL’服务不可用时抛出。

125
docs/api/api_python/parallel/mindspore.context.txt
View File

@ -1,125 +0,0 @@
get_auto_parallel_context(attr_key)
根据key获取自动并行的配置。
参数：
attr_key (str)：配置的key。
返回：
根据key返回配置的值。
异常：
ValueError：输入key不在自动并行的配置列表中。
Class mindspore.context.ParallelMode
并行模式。
有五种并行模式，分别是STAND_ALONE、DATA_PARALLEL、HYBRID_PARALLEL、SEMI_AUTO_PARALLEL和AUTO_PARALLEL。
默认值：STAND_ALONE。
- STAND_ALONE：单卡模式。
- DATA_PARALLEL：数据并行模式。
- HYBRID_PARALLEL：手动实现数据并行和模型并行。
- SEMI_AUTO_PARALLEL：半自动并行模式。
- AUTO_PARALLEL：自动并行模式。
MODE_LIST：表示所有支持的并行模式的列表。
reset_auto_parallel_context()
重置自动并行的配置为默认值。
- device_num：1。
- global_rank：0。
- gradients_mean：False。
- gradient_fp32_sync：True。
- parallel_mode：'stand_alone'。
- auto_parallel_search_mode：'dynamic_programming'。
- parameter_broadcast：False。
- strategy_ckpt_load_file：''。
- strategy_ckpt_save_file：''。
- full_batch：False。
- enable_parallel_optimizer：False。
- pipeline_stages：1。
set_auto_parallel_context(**kwargs)
配置自动并行，仅在Ascend和GPU上有效。
应在init之前配置自动并行。
注：
配置时，必须输入配置的名称。
如果某个程序具有不同并行模式下的任务，则需要再为下一个任务设置新的并行模式之前，调用reset_auto_parallel_context()接口来重置配置。
若要设置或更改并行模式，必须在创建任何Initializer之前调用接口，否则，在编译网络时，可能会出现RuntimeError。
某些配置适用于特定的并行模式，有关详细信息，请参见下表：
=========================== ===========================
Common AUTO_PARALLEL
=========================== ===========================
device_num gradient_fp32_sync
global_rank loss_repeated_mean
gradients_mean auto_parallel_search_mode
parallel_mode strategy_ckpt_load_file
all_reduce_fusion_config strategy_ckpt_save_file
enable_parallel_optimizer dataset_strategy
\ pipeline_stages
\ grad_accumulation_step
=========================== ===========================
参数：
device_num (int)：表示可用设备的编号，必须在【1,4096】范围中。默认值：1。
global_rank (int)：表示全局秩的ID，必须在【0,4095】范围中。默认值：0。
gradients_mean (bool)：表示是否在梯度的allreduce后执行平均算子。
stand_alone不支持gradients_mean。默认值：False。
gradient_fp32_sync (bool)：在FP32中运行gradients的allreduce。stand_alone、data_parallel和hybrid_parallel不支持gradient_fp32_sync。默认值：True。
parallel_mode (str)：有五种并行模式，分别是stand_alone、data_parallel、hybrid_parallel、semi_auto_parallel和auto_parallel。默认值：stand_alone。
- stand_alone：单卡模式。
- data_parallel：数据并行模式。
- hybrid_parallel：手动实现数据并行和模型并行。
- semi_auto_parallel：半自动并行模式。
- auto_parallel：自动并行模式。
auto_parallel_search_mode (str)：表示有两种策略搜索模式，分别是recursive_programming和dynamic_programming。默认值：dynamic_programming。
- recursive_programming：表示双递归搜索模式。
- dynamic_programming：表示动态规划搜索模式。
parameter_broadcast (bool)：表示在训练前是否广播参数。在训练之前，为了使所有设备的网络初始化参数值相同，请将设备0上的参数广播到其他设备。不同并行模式下的参数广播不同。
在data_parallel模式下，除layerwise_parallel属性为True的参数外，所有参数都会被广播。在Hybrid_parallel、semi_auto_parallel和auto_parallel模式下，分段参数不参与广播。默认值：False。
strategy_ckpt_load_file (str)：表示用于加载并行策略checkpoint的路径。默认值：''。
strategy_ckpt_save_file (str)：表示用于保存并行策略checkpoint的路径。默认值：''。
full_batch (bool)：如果在auto_parallel模式下加载整个batch数据集，则此参数应设置为True。默认值：False。目前不建议使用该接口，建议使用dataset_strategy来替换它。
dataset_strategy (Union[str, tuple])：表示数据集分片策略。默认值：data_parallel。
dataset_strategy="data_parallel"等于full_batch=False，dataset_strategy="full_batch"等于full_batch=True。对于通过模型并列策略加载到网络的数据集，如ds_stra ((1, 8)、(1, 8))，需要使用set_auto_parallel_context(dataset_strategy=ds_stra)。
enable_parallel_optimizer (bool)：这是一个开发中的特性，它可以为数据并行训练对权重更新计算进行分片，以节省时间和内存。目前，自动和半自动并行模式支持Ascend和GPU中的所有优化器。数据并行模式仅支持Ascend中的`Lamb`和`AdamWeightDecay`。默认值：False。
all_reduce_fusion_config (list)：通过参数索引设置allreduce 融合策略。仅支持ReduceOp.SUM和HCCL_WORLD_GROUP/NCCL_WORLD_GROUP。没有默认值。如果不设置，则关闭算子融合。
pipeline_stages (int)：设置pipeline并行的阶段信息。这表明了设备如何单独分布在pipeline上。所有的设备将被划分为pipeline_stags个阶段。
目前，这只能在启动semi_auto_parallel模式的情况下使用。默认值：1。
grad_accumulation_step (int)：在自动和半自动并行模式下设置梯度的累积step。
其值应为正整数。默认值：1。
异常：
ValueError：输入key不是自动并行上下文中的属性。
样例：
>>> context.set_auto_parallel_context(device_num=8)
>>> context.set_auto_parallel_context(global_rank=0)
>>> context.set_auto_parallel_context(gradients_mean=True)
>>> context.set_auto_parallel_context(gradient_fp32_sync=False)
>>> context.set_auto_parallel_context(parallel_mode="auto_parallel")
>>> context.set_auto_parallel_context(auto_parallel_search_mode="dynamic_programming")
>>> context.set_auto_parallel_context(parameter_broadcast=False)
>>> context.set_auto_parallel_context(strategy_ckpt_load_file="./strategy_stage1.ckpt")
>>> context.set_auto_parallel_context(strategy_ckpt_save_file="./strategy_stage1.ckpt")
>>> context.set_auto_parallel_context(dataset_strategy=((1, 8), (1, 8)))
>>> context.set_auto_parallel_context(enable_parallel_optimizer=False)
>>> context.set_auto_parallel_context(all_reduce_fusion_config=[8, 160])
>>> context.set_auto_parallel_context(pipeline_stages=2)

18
docs/api/api_python/parallel/mindspore.load_distributed_checkpoint.txt
View File

@ -7,16 +7,16 @@ mindspore.load_distributed_checkpoint
**参数：**
- **network** (Cell)：分布式预测网络。
- **checkpoint_filenames** (list[str])：checkpoint文件的名称，按rank id 顺序排列。
- **predict_strategy** (dict)：predict时参数的切分策略。
- **train_strategy_filename** (str)：训练策略proto文件名。默认值：None。
- **strict_load** (bool)：表示是否严格加载参数到网络。如果值为False，则当checkpoint文件中参数名称的后缀与网络中的参数相同时，加载参数到网络。当类型不一致时，对相同类型的参数进行类型转换，如从float32到float16。默认值：False。
- **dec_key** (Union[None, bytes])：用于解密的字节类型key。如果value为None，则不需要解密。默认值：None。
- **dec_mode** (str)：仅当dec_key不设为None时，该参数有效。指定了解密模式，目前支持AES-GCM和AES-CBC。默认值：AES-GCM。
- **network** (Cell)：分布式预测网络。
- **checkpoint_filenames** (list[str])：checkpoint文件的名称，按rank id 顺序排列。
- **predict_strategy** (dict)：预测时参数的切分策略。
- **train_strategy_filename** (str)：训练策略proto文件名。默认值：None。
- **strict_load** (bool)：表示是否严格加载参数到网络。如果值为False，则当checkpoint文件中参数名称的后缀与网络中的参数相同时，加载参数到网络。当类型不一致时，对相同类型的参数进行类型转换，如从float32到float16。默认值：False。
- **dec_key** (Union[None, bytes])：用于解密的字节类型key。如果value为None，则不需要解密。默认值：None。
- **dec_mode** (str)：仅当dec_key不设为None时，该参数有效。指定了解密模式，目前支持AES-GCM和AES-CBC。默认值：AES-GCM。
**异常：**
- **TypeError：** 输入类型不符合要求。
- **ValueError：** 无法加载checkpoint文件到网络。
- **TypeError：** 输入类型不符合要求。
- **ValueError：** 无法加载checkpoint文件到网络。

178
docs/api/api_python/parallel/mindspore.nn.DistributedGradReducer.txt
View File

@ -1,99 +1,105 @@
Class mindspore.nn.DistributedGradReducer(parameters, mean=True, degree=None, fusion_type=1, group='hccl_world_group')
mindspore.nn.DistributedGradReducer
===================================
.. py:class:: mindspore.nn.DistributedGradReducer(parameters, mean=True, degree=None, fusion_type=1, group='hccl_world_group')
分布式优化器。
对反向梯度进行AllReduce运算。
参数：
parameters (list)：需要更新的参数。
mean (bool)：当mean为True时，对AllReduce之后的梯度求均值。默认值：False。
degree (int)：平均系数，通常等于设备编号。默认值：None。
fusion_type (int)：AllReduce算子的融合类型。默认值：1。
**参数：**
异常：
ValueError：如果degree不是int或小于0。
- **parameters** (list)：需要更新的参数。
- **mean** (bool)：当mean为True时，对AllReduce之后的梯度求均值。默认值：False。
- **degree** (int)：平均系数，通常等于设备编号。默认值：None。
- **fusion_type** (int)：AllReduce算子的融合类型。默认值：1。
支持平台：
``Ascend`` ``GPU``
**异常：**
示例：
>>> #此示例应与多个进程一起运行。
>>> #请参考Mindpore.cn上的“教程>分布式训练”。
>>> import numpy as np
>>> from mindspore.communication import init
>>> from mindspore import ops
>>> from mindspore import context
>>> from mindspore.context import ParallelMode
>>> from mindspore import Parameter, Tensor
>>> from mindspore import nn
>>>
>>> context.set_context(mode=context.GRAPH_MODE)
>>> init()
>>> context.reset_auto_parallel_context()
>>> context.set_auto_parallel_context(parallel_mode=ParallelMode.DATA_PARALLEL)
>>>
>>> class TrainingWrapper(nn.Cell):
... def __init__(self, network, optimizer, sens=1.0):
... super(TrainingWrapper, self).__init__(auto_prefix=False)
... self.network = network
... self.network.add_flags(defer_inline=True)
... self.weights = optimizer.parameters
... self.optimizer = optimizer
... self.grad = ops.GradOperation(get_by_list=True, sens_param=True)
... self.sens = sens
... self.reducer_flag = False
... self.grad_reducer = None
... self.parallel_mode = context.get_auto_parallel_context("parallel_mode")
... if self.parallel_mode in [ParallelMode.DATA_PARALLEL, ParallelMode.HYBRID_PARALLEL]:
... self.reducer_flag = True
... if self.reducer_flag:
... mean = context.get_auto_parallel_context("gradients_mean")
... degree = context.get_auto_parallel_context("device_num")
... self.grad_reducer = nn.DistributedGradReducer(optimizer.parameters, mean, degree)
...
... def construct(self, *args):
... weights = self.weights
... loss = self.network(*args)
... sens = ops.Fill()(ops.DType()(loss), ops.Shape()(loss), self.sens)
... grads = self.grad(self.network, weights)(*args, sens)
... if self.reducer_flag:
... # apply grad reducer on grads
... grads = self.grad_reducer(grads)
... return ops.Depend(loss, self.optimizer(grads))
>>>
>>> class Net(nn.Cell):
... def __init__(self, in_features, out_features)：
... super(Net, self).__init__()
... self.weight = Parameter(Tensor(np.ones([in_features, out_features]).astype(np.float32)),
... name='weight')
... self.matmul = ops.MatMul()
...
... def construct(self, x)：
... output = self.matmul(x, self.weight)
... return output
>>>
>>> size, in_features, out_features = 16, 16, 10
>>> network = Net(in_features, out_features)
>>> loss = nn.MSELoss()
>>> net_with_loss = nn.WithLossCell(network, loss)
>>> optimizer = nn.Momentum(net_with_loss.trainable_params(), learning_rate=0.1, momentum=0.9)
>>> train_cell = TrainingWrapper(net_with_loss, optimizer)
>>> inputs = Tensor(np.ones([size, in_features]).astype(np.float32))
>>> label = Tensor(np.zeros([size, out_features]).astype(np.float32))
>>> grads = train_cell(inputs, label)
>>> print(grads)
256.0
**ValueError**：如果degree不是int或小于0。
construct(grads)
**支持平台：**
某些情况下，梯度的数据精度可以与float16和float32混合。因此，AllReduce的结果不可靠。
要解决这个问题，必须在AllReduce之前强制转换为float32，并在操作之后再强制转换为float32。
``Ascend`` ``GPU``
参数：
grads (Union[Tensor, tuple[Tensor]])：操作前的梯度tensor或tuple。
**样例：**
返回：
new_grads (Union[Tensor, tuple[Tensor]])，操作后的梯度tensor或tuple。
>>> #此示例应与多个进程一起运行。
>>> #请参考Mindpore.cn上的“教程>分布式训练”。
>>> import numpy as np
>>> from mindspore.communication import init
>>> from mindspore import ops
>>> from mindspore import context
>>> from mindspore.context import ParallelMode
>>> from mindspore import Parameter, Tensor
>>> from mindspore import nn
>>>
>>> context.set_context(mode=context.GRAPH_MODE)
>>> init()
>>> context.reset_auto_parallel_context()
>>> context.set_auto_parallel_context(parallel_mode=ParallelMode.DATA_PARALLEL)
>>>
>>> class TrainingWrapper(nn.Cell):
... def __init__(self, network, optimizer, sens=1.0):
... super(TrainingWrapper, self).__init__(auto_prefix=False)
... self.network = network
... self.network.add_flags(defer_inline=True)
... self.weights = optimizer.parameters
... self.optimizer = optimizer
... self.grad = ops.GradOperation(get_by_list=True, sens_param=True)
... self.sens = sens
... self.reducer_flag = False
... self.grad_reducer = None
... self.parallel_mode = context.get_auto_parallel_context("parallel_mode")
... if self.parallel_mode in [ParallelMode.DATA_PARALLEL, ParallelMode.HYBRID_PARALLEL]:
... self.reducer_flag = True
... if self.reducer_flag:
... mean = context.get_auto_parallel_context("gradients_mean")
... degree = context.get_auto_parallel_context("device_num")
... self.grad_reducer = nn.DistributedGradReducer(optimizer.parameters, mean, degree)
...
... def construct(self, *args):
... weights = self.weights
... loss = self.network(*args)
... sens = ops.Fill()(ops.DType()(loss), ops.Shape()(loss), self.sens)
... grads = self.grad(self.network, weights)(*args, sens)
... if self.reducer_flag:
... # apply grad reducer on grads
... grads = self.grad_reducer(grads)
... return ops.Depend(loss, self.optimizer(grads))
>>>
>>> class Net(nn.Cell):
... def __init__(self, in_features, out_features)：
... super(Net, self).__init__()
... self.weight = Parameter(Tensor(np.ones([in_features, out_features]).astype(np.float32)),
... name='weight')
... self.matmul = ops.MatMul()
...
... def construct(self, x)：
... output = self.matmul(x, self.weight)
... return output
>>>
>>> size, in_features, out_features = 16, 16, 10
>>> network = Net(in_features, out_features)
>>> loss = nn.MSELoss()
>>> net_with_loss = nn.WithLossCell(network, loss)
>>> optimizer = nn.Momentum(net_with_loss.trainable_params(), learning_rate=0.1, momentum=0.9)
>>> train_cell = TrainingWrapper(net_with_loss, optimizer)
>>> inputs = Tensor(np.ones([size, in_features]).astype(np.float32))
>>> label = Tensor(np.zeros([size, out_features]).astype(np.float32))
>>> grads = train_cell(inputs, label)
>>> print(grads)
256.0
.. py:method:: construct(grads)
某些情况下，梯度的数据精度可以与float16和float32混合。因此，AllReduce的结果不可靠。要解决这个问题，必须在AllReduce之前强制转换为float32，并在操作之后再强制转换为float32。
**参数：**
**grads** (Union[Tensor, tuple[Tensor]])：操作前的梯度Tensor或tuple。
**返回：**
**new_grads** (Union[Tensor, tuple[Tensor]])，操作后的梯度Tensor或tuple。

18
docs/api/api_python/parallel/mindspore.nn.PipelineCell.txt
View File

@ -1,15 +1,17 @@
Class mindspore.nn.PipelineCell(network, micro_size)
.. py:class:: mindspore.nn.PipelineCell(network, micro_size)
将MiniBatch切分成更细粒度的MicroBatch，用于流水线并行的训练中。
注：
.. note::
micro_size必须大于或等于流水线stage的个数。
参数：
network (Cell)：要包裹的目标网络。
micro_size (int)：MicroBatch大小。
** 参数：**
示例：
>>> net = Net()
>>> net = PipelineCell(net, 4)
- **network** (Cell)：要修饰的目标网络。
- **micro_size** (int)：MicroBatch大小。
**示例：**
>>> net = Net()
>>> net = PipelineCell(net, 4)