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

!26943 modify comments for Model api 

Merge pull request !26943 from wangnan39/code_docs_model
This commit is contained in:
i-robot 2021-12-01 10:46:19 +00:00 committed by Gitee
parent 295f4f411d b1e02acb51
commit 3be3c7cdfd
2 changed files with 266 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

191
docs/api/api_python/mindspore.model.rst.txt Normal file
View File

@ -0,0 +1,191 @@
Class mindspore.Model(network, loss_fn=None, optimizer=None, metrics=None, eval_network=None, eval_indexes=None, amp_level="O0", acc_level="O0", **kwargs)
模型训练或推理的高阶接口。
`Model`会根据用户传入的参数封装可训练或推理的实例。
参数：
network (Cell) – 用于训练或推理的神经网络。
loss_fn (Cell) - 损失函数。如果`loss_fn`为None，`network`中需要进行损失函数计算，必要时也需要进行并行计算。默认值：None。
optimizer(Cell) - 用于更新网络权重的优化器。如果`optimizer`为None，`network`中需要进行反向传播和网络权重更新。默认值：None。
metrics (Union[dict, set]) - 用于模型评估的一组评价函数。例如：{'accuracy', 'recall'}。默认值：None。
eval_network (Cell) - 用于评估的神经网络。未定义情况下，`Model`会使用`network`和`loss_fn`封装一个`eval_network`。默认值：None。
eval_indexes (list) - 在定义`eval_network`的情况下使用。如果`eval_indexes`为默认值None，`Model`会将`eval_network`的所有输出传给`metrics`。如果配置`eval_indexes`，必须包含三个元素，分别为损失值、预测值和标签在`eval_network`输出中的位置，此时，损失值将传给损失评价函数，预测值和标签将传给其他评价函数。推荐使用评价函数的:func:`mindspore.nn.Metric.set_indexes`代替`eval_indexes`。默认值：None。
amp_level (str) - :func:`mindspore.build_train_network`的可选参数 `level`，`level` 为混合精度等级，该参数支持["O0", "O2", "O3", "auto"]。默认值："O0"。
- O0: 无变化。
- O2: 将网络精度转为float16，batchnorm保持float32精度，使用动态调整梯度放大系数（loss scale）的策略。
- O3: 将网络精度转为float16，并为:func:`mindspore.build_train_network`接口配置属性`keep_batchnorm_fp32=False`。
- auto: 为不同处理器设置专家推荐的混合精度等级，如在GPU上设为O2，在Ascend上设为O3。该设置方式不适用于所有场景，建议用户根据具体的网络模型自定义设置`amp_level`。
在GPU上建议使用O2，在Ascend上建议使用O3。关于`amp_level`详见:func:`mindpore.build_train_network`。
样例:
>>> from mindspore import Model, nn
>>>
>>> class Net(nn.Cell):
... def __init__(self, num_class=10, num_channel=1):
... super(Net, self).__init__()
... self.conv1 = nn.Conv2d(num_channel, 6, 5, pad_mode='valid')
... self.conv2 = nn.Conv2d(6, 16, 5, pad_mode='valid')
... self.fc1 = nn.Dense(16*5*5, 120, weight_init='ones')
... self.fc2 = nn.Dense(120, 84, weight_init='ones')
... self.fc3 = nn.Dense(84, num_class, weight_init='ones')
... self.relu = nn.ReLU()
... self.max_pool2d = nn.MaxPool2d(kernel_size=2, stride=2)
... self.flatten = nn.Flatten()
...
... def construct(self, x):
... x = self.max_pool2d(self.relu(self.conv1(x)))
... x = self.max_pool2d(self.relu(self.conv2(x)))
... x = self.flatten(x)
... x = self.relu(self.fc1(x))
... x = self.relu(self.fc2(x))
... x = self.fc3(x)
... return x
>>>
>>> net = Net()
>>> loss = nn.SoftmaxCrossEntropyWithLogits()
>>> optim = nn.Momentum(params=net.trainable_params(), learning_rate=0.1, momentum=0.9)
>>> model = Model(net, loss_fn=loss, optimizer=optim, metrics=None)
>>> # 如何构建数据集，请参考官方网站的数据集相关章节
>>> dataset = create_custom_dataset()
>>> model.train(2, dataset)
build(train_dataset=None, valid_dataset=None, sink_size=-1)
数据下沉模式下构建计算图和数据图。
告警：
这是一个实验性接口，后续可能删除或修改。
注：
如果预先调用该接口构建计算图，那么`Model.train`会直接执行计算图。预构建计算图目前仅支持`GRAPH_MODE`模式和`Ascend`处理器，仅支持数据下沉模式。
参数：
train_dataset (Dataset) – 一个训练集迭代器。如果定义了`train_dataset`，将会构建训练计算图。默认值：None。
valid_dataset (Dataset) - 一个验证集迭代器。如果定义了`valid_dataset`，将会构建验证计算图，此时`Model`中的`metrics`不能为None。默认值：None。
sink_size (int) - 控制每次数据下沉的数据量。默认值：-1。
epoch (int) - 控制训练轮次。默认值：1。
样例：
>>> from mindspore import Model, nn, FixedLossScaleManager
>>>
>>> # 如何构建数据集，请参考官方网站的数据集相关章节
>>> dataset = create_custom_dataset()
>>> net = Net()
>>> loss = nn.SoftmaxCrossEntropyWithLogits()
>>> loss_scale_manager = FixedLossScaleManager()
>>> optim = nn.Momentum(params=net.trainable_params(), learning_rate=0.1, momentum=0.9)
>>> model = Model(net, loss_fn=loss, optimizer=optim, metrics=None, loss_scale_manager=loss_scale_manager)
>>> model.build(dataset, epoch=2)
>>> model.train(2, dataset)
>>> model.train(2, dataset)
eval(valid_dataset, callbacks=None, dataset_sink_mode=True)
模型评估接口。
使用`PYNATIVE_MODE`模式或`CPU`处理器时，模型评估流程将以非下沉模式执行。
注：
如果`dataset_sink_mode`配置为True，数据将被送到处理器中。如果处理器是Ascend，数据特征将被逐一传输，每次数据传输的限制是256M。
如果`dataset_sink_mode`配置为True，数据集仅能在当前模型中使用，而不能被其他模型使用。
该接口会构建并执行计算图，如果使用前先执行了`Model.build`，那么它会直接执行计算图而不构建。
参数：
valid_dataset (Dataset) – 评估模型的数据集。
callbacks (Optional[list(Callback), Callback]) - 评估过程中需要执行的回调对象或回调对象列表。默认值：None。
dataset_sink_mode (bool) - 是否通过数据通道获取数据。默认值：True。
返回：
Dict，键是用户定义的评价指标名称，值是以推理模式运行的评估结果。
样例：
>>> from mindspore import Model, nn
>>>
>>> # 如何构建数据集，请参考官方网站的数据集相关章节
>>> dataset = create_custom_dataset()
>>> net = Net()
>>> loss = nn.SoftmaxCrossEntropyWithLogits()
>>> model = Model(net, loss_fn=loss, optimizer=None, metrics={'acc'})
>>> acc = model.eval(dataset, dataset_sink_mode=False)
eval_network
获取该模型的评价网络。
返回：
评估网络实例。
predict(*predict_data)
输入样本得到预测结果。
参数：
predict_data (Tensor) – 预测样本，数据可以是单个张量、张量列表或张量元组。
返回：
返回预测结果，类型是张量或数组。
样例:
>>> import mindspore as ms
>>> from mindspore import Model, Tensor
>>>
>>> input_data = Tensor(np.random.randint(0, 255, [1, 1, 32, 32]), ms.float32)
>>> model = Model(Net())
>>> result = model.predict(input_data)
predict_network
获得该模型的预测网络。
返回：
预测网络实例。
train(epoch, train_dataset, callbacks=None, dataset_sink_mode=True, sink_size=-1)
模型训练接口。
使用`PYNATIVE_MODE`模式或`CPU`处理器时，模型训练流程将以非下沉模式执行。
注：
如果`dataset_sink_mode`配置为True，数据将被送到处理器中。如果处理器是Ascend，数据特征将被逐一传输，每次数据传输的限制是256M。
如果`dataset_sink_mode`配置为True，仅在每个epoch结束时调用Callback实例的step_end方法。
如果`dataset_sink_mode`配置为True，数据集仅能在当前模型中使用，而不能被其他模型使用。
如果`sink_size`大于零，每次epoch可以无限次遍历数据集，直到遍历数据量等于`sink_size`为止。然后下次epoch是从上一次遍历的最后位置继续开始遍历。
该接口会构建并执行计算图，如果使用前先执行了`Model.build`，那么它会直接执行计算图而不构建。
参数：
epoch (int) – 训练执行轮次。通常每个epoch都会使用全量数据集进行训练。当`dataset_sink_mode`设置为True且`sink_size`大于零时，则每个epoch训练次数为`sink_size`而不是数据集的总步数。
train_dataset (Dataset) – 一个训练数据集迭代器。如果定义了`loss_fn`，则数据和标签会被分别传给`network`和`loss_fn`，此时数据集需要返回一个元组（data, label）。如果数据集中有多个数据或者标签，可以设置`loss_fn`为None，并在`network`中实现损失函数计算，此时数据集返回的所有数据组成的元组（data1, data2, data3, ...）会传给`network`。
callback (Optional[list[Callback], Callback]) – 训练过程中需要执行的回调对象或者回调对象列表。默认值：None。
dataset_sink_mode (bool) – 是否通过数据通道获取数据。使用`PYNATIVE_MODE`模式或`CPU`处理器时，模型训练流程将以非下沉模式执行。默认值：True。
sink_size (int) – 控制每次数据下沉的数据量。`dataset_sink_mode`为False时`sink_size`无效。如果sink_size=-1，则每一次epoch下沉完整数据集。如果sink_size>0，则每一次epoch下沉数据量为sink_size的数据集。默认值：-1。
样例:
>>> from mindspore import Model, nn, FixedLossScaleManager
>>>
>>> # 如何构建数据集，请参考官方网站的数据集相关章节
>>> dataset = create_custom_dataset()
>>> net = Net()
>>> loss = nn.SoftmaxCrossEntropyWithLogits()
>>> loss_scale_manager = FixedLossScaleManager()
>>> optim = nn.Momentum(params=net.trainable_params(), learning_rate=0.1, momentum=0.9)
>>> model = Model(net, loss_fn=loss, optimizer=optim, metrics=None, loss_scale_manager=loss_scale_manager)
>>> model.train(2, dataset)
train_network
获得该模型的训练网络。
返回：
预测网络实例。

129
mindspore/train/model.py
View File

@ -116,36 +116,39 @@ class Model:
"""
High-Level API for training or inference.
`Model` groups layers into an object with training and inference features.
`Model` groups layers into an object with training and inference features based on the arguments.
Args:
network (Cell): A training or testing network.
loss_fn (Cell): Objective function, if loss_fn is None, the
network should contain the logic of loss and grads calculation,
and parallel if needed. Default: None.
optimizer (Cell): Optimizer for updating the weights. Default: None.
metrics (Union[dict, set]): A Dictionary or a set of metrics to be evaluated by the model during
training and inference. eg: {'accuracy', 'recall'}. Default: None.
loss_fn (Cell): Objective function. If `loss_fn` is None, the `network` should contain the calculation of loss
and parallel if needed. Default: None.
optimizer (Cell): Optimizer for updating the weights. If `optimizer` is None, the `network` needs to
do backpropagation and update weights. Default value: None.
metrics (Union[dict, set]): A Dictionary or a set of metrics for model evaluation.
eg: {'accuracy', 'recall'}. Default: None.
eval_network (Cell): Network for evaluation. If not defined, `network` and `loss_fn` would be wrapped as
`eval_network` . Default: None.
eval_indexes (list): When defining the `eval_network`, if `eval_indexes` is None, all outputs of the
`eval_network` would be passed to metrics, otherwise `eval_indexes` must contain three
elements, including the positions of loss value, predicted value and label. The loss
value would be passed to the `Loss` metric, the predicted value and label would be passed
to other metric. Default: None.
amp_level (str): Option for argument `level` in `mindspore.amp.build_train_network` , level for mixed
eval_indexes (list): It is used when eval_network is defined. If `eval_indexes` is None by default, all outputs
of the `eval_network` would be passed to metrics. If `eval_indexes` is set, it must contain
three elements: the positions of loss value, predicted value and label in outputs of the
`eval_network`. In this case, the loss value will be passed to the `Loss` metric, the
predicted value and label will be passed to other metrics.
:func: `mindindex.nn.metric.set_indexes` is recommended instead of `eval_indexes`.
Default: None.
amp_level (str): Option for argument `level` in :func:`mindspore.build_train_network`, level for mixed
precision training. Supports ["O0", "O2", "O3", "auto"]. Default: "O0".
- O0: Do not change.
- O2: Cast network to float16, keep batchnorm run in float32, using dynamic loss scale.
- O3: Cast network to float16, with additional property `keep_batchnorm_fp32=False` .
- auto: Set to level to recommended level in different devices. Set level to O2 on GPU, Set
level to O3 Ascend. The recommended level is chosen by the export experience, cannot
always general. User should specify the level for special network.
- O3: Cast network to float16 and add property `keep_batchnorm_fp32=False` to
:func:`mindspore.build_train_network`.
- auto: Set level to recommended level in different devices. Set level to O2 on GPU, set
level to O3 on Ascend. The recommended level is chosen by the export experience, not applicable to all
scenarios. User should specify the level for special network.
O2 is recommended on GPU, O3 is recommended on Ascend.The more detailed explanation of `amp_level` setting
can be found at `mindspore.amp.build_train_network` .
boost_level (str): Option for argument `level` in `mindspore.boost` , level for boost mode
O2 is recommended on GPU, O3 is recommended on Ascend. The more detailed explanation of `amp_level` setting
can be found at `mindspore.build_train_network`.
boost_level (str): Option for argument `level` in `mindspore.boost`, level for boost mode
training. Supports ["O0", "O1", "O2"]. Default: "O0".
- O0: Do not change.
@ -722,40 +725,46 @@ class Model:
def train(self, epoch, train_dataset, callbacks=None, dataset_sink_mode=True, sink_size=-1):
"""
Training API where the iteration is controlled by python front-end.
Training API.
When setting pynative mode or CPU, the training process will be performed with dataset not sink.
Note:
If dataset_sink_mode is True, data will be sent to device. If the device is Ascend, features
of data will be transferred one by one. The limitation of data transmission per time is 256M.
When dataset_sink_mode is True, the step_end method of the Callback class will be executed when
the epoch_end method is called.
When dataset_sink_mode is True, the `step_end` method of the instance of Callback will be called at the end
of epoch.
If dataset_sink_mode is True, dataset will be bound to this model and cannot be used by other models.
If sink_size > 0, each epoch of the dataset can be traversed unlimited times until you get sink_size
elements of the dataset. The next epoch continues to traverse from the end position of the previous
traversal. The interface builds the computational graphs and then executes the computational graphs.
However, when the 'model.build' is executed first, it only performs the graphs execution.
traversal.
The interface builds the computational graphs and then executes the computational graphs. However, when
the `Model.build` is executed first, it only performs the graphs execution.
Args:
epoch (int): Generally, total number of iterations on the data per epoch.
When dataset_sink_mode is set to true and sink_size>0, each epoch sink sink_size
steps on the data instead of total number of iterations.
train_dataset (Dataset): A training dataset iterator. If there is no
loss_fn, a tuple with multiple data (data1, data2, data3, ...) should be
returned and passed to the network. Otherwise, a tuple (data, label) should
be returned. The data and label would be passed to the network and loss
function respectively.
epoch (int): Total training epochs. Generally, train network will be trained on complete dataset per epoch.
If `dataset_sink_mode` is set to True and `sink_size` is greater than 0, each epoch will
train `sink_size` steps instead of total steps of dataset.
train_dataset (Dataset): A training dataset iterator. If `loss_fn` is defined, the data and label will be
passed to the `network` and the `loss_fn` respectively, so a tuple (data, label)
should be returned from dataset. If there is multiple data or labels, set `loss_fn`
to None and implement calculation of loss in `network`,
then a tuple (data1, data2, data3, ...) with all data returned from dataset will be
passed to the `network`.
callbacks (Optional[list[Callback], Callback]): List of callback objects or callback object,
which should be executed while training.
Default: None.
dataset_sink_mode (bool): Determines whether to pass the data through dataset channel.
Configure pynative mode or CPU, the training process will be performed with
dataset not sink. Default: True.
sink_size (int): Control the amount of data in each sink.
sink_size (int): Control the amount of data in each sink. `sink_size` is invalid if `dataset_sink_mode`
is False.
If sink_size = -1, sink the complete dataset for each epoch.
If sink_size > 0, sink sink_size data for each epoch.
If dataset_sink_mode is False, set sink_size as invalid.
Default: -1.
Examples:
@ -802,19 +811,18 @@ class Model:
Build computational graphs and data graphs with the sink mode.
.. warning::
This is an experimental prototype that is subject to change and/or deletion.
This is an experimental prototype that is subject to change or deletion.
Note:
Pre-build process only supports `GRAPH_MODE` and `Ascend` target currently.
The interface builds the computational graphs, when the interface is executed first,
'model.train' only performs the graphs execution.
The interface builds the computational graphs, when the interface is executed first, 'Model.train' only
performs the graphs execution. Pre-build process only supports `GRAPH_MODE` and `Ascend` target currently.
It only supports dataset sink mode.
Args:
train_dataset (Dataset): A training dataset iterator. If `train_dataset` is defined, training graphs will be
initialized. Default: None.
built. Default: None.
valid_dataset (Dataset): An evaluating dataset iterator. If `valid_dataset` is defined, evaluation graphs
will be initialized, and `metrics` in `Model` can not be None. Default: None.
will be built, and `metrics` in `Model` can not be None. Default: None.
sink_size (int): Control the amount of data in each sink. Default: -1.
epoch (int): Control the training epochs. Default: 1.
jit_config (Union[str, str]): Control the jit config.
@ -919,21 +927,24 @@ class Model:
def eval(self, valid_dataset, callbacks=None, dataset_sink_mode=True):
"""
Evaluation API where the iteration is controlled by python front-end.
Evaluation API.
Configure to pynative mode or CPU, the evaluating process will be performed with dataset non-sink mode.
Note:
If dataset_sink_mode is True, data will be sent to device. If the device is Ascend, features
of data will be transferred one by one. The limitation of data transmission per time is 256M.
When dataset_sink_mode is True, the step_end method of the Callback class will be executed when
the epoch_end method is called.
If dataset_sink_mode is True, dataset will be bound to this model and cannot be used by other models.
The interface builds the computational graphs and then executes the computational graphs. However, when
the `Model.build` is executed first, it only performs the graphs execution.
Args:
valid_dataset (Dataset): Dataset to evaluate the model.
callbacks (Optional[list(Callback)]): List of callback objects which should be executed
while training. Default: None.
callbacks (Optional[list(Callback), Callback]): List of callback objects or callback object,
which should be executed while evaluation.
Default: None.
dataset_sink_mode (bool): Determines whether to pass the data through dataset channel.
Default: True.
@ -993,11 +1004,6 @@ class Model:
"""
Generate output predictions for the input samples.
Data could be a single tensor, a list of tensor, or a tuple of tensor.
Note:
This is a pre-compile function. The arguments should be the same as model.predict() function.
Args:
predict_data (Optional[Tensor, list[Tensor], tuple[Tensor]]): The predict data, can be a single tensor,
a list of tensor, or a tuple of tensor.
@ -1175,17 +1181,32 @@ class Model:
@property
def train_network(self):
"""Get the model's train_network."""
"""
Get the model's train network.
Returns:
Object, the instance of train network.
"""
return self._train_network
@property
def predict_network(self):
"""Get the model's predict_network."""
"""
Get the model's predict network.
Returns:
Object, the instance of predict network.
"""
return self._predict_network
@property
def eval_network(self):
"""Get the model's eval_network."""
"""
Get the model's eval network.
Returns:
Object, the instance of evaluate network.
"""
return self._eval_network