mindspore.nn.Cell

class mindspore.nn.Cell(auto_prefix=True, flags=None)[源代码]

MindSpore中神经网络的基本构成单元。模型或神经网络层应当继承该基类。

mindspore.nn 中神经网络层也是Cell的子类,如 mindspore.nn.Conv2dmindspore.nn.ReLU 等。Cell在GRAPH_MODE(静态图模式)下将编译为一张计算图,在PYNATIVE_MODE(动态图模式)下作为神经网络的基础模块。

说明

Cell默认情况下是推理模式。对于继承Cell的类,如果训练和推理具有不同结构,子类会默认执行推理分支。设置训练模式,请参考 mindspore.nn.Cell.set_train

警告

在Cell的子类中不能定义名为'cast'的方法,不能定义名为'phase'和'cells'的属性, 否则会报错。

参数:
  • auto_prefix (bool,可选) - 是否自动为Cell及其子Cell生成NameSpace。该参数同时会影响 Cell 中权重参数的名称。如果设置为 True ,则自动给权重参数的名称添加前缀,否则不添加前缀。通常情况下,骨干网络应设置为 True ,否则会产生重名问题。用于训练骨干网络的优化器、 mindspore.nn.TrainOneStepCell 等,应设置为 False ,否则骨干网络的权重参数名会被误改。默认值: True

  • flags (dict,可选) - Cell的配置信息,目前用于绑定Cell和数据集。用户也通过该参数自定义Cell属性。默认值: None

支持平台:

Ascend GPU CPU

样例:

>>> import mindspore.nn as nn
>>> from mindspore import ops
>>> class MyCell(nn.Cell):
...     def __init__(self, forward_net):
...         super(MyCell, self).__init__(auto_prefix=False)
...         self.net = forward_net
...         self.relu = ops.ReLU()
...
...     def construct(self, x):
...         y = self.net(x)
...         return self.relu(y)
>>>
>>> inner_net = nn.Conv2d(120, 240, 4, has_bias=False, weight_init='normal')
>>> my_net = MyCell(inner_net)
>>> print(my_net.trainable_params())
... # If the 'auto_prefix' set to True or not set when call the '__init__' method of the parent class,
... # the parameter's name will be 'net.weight'.
[Parameter (name=weight, shape=(240, 120, 4, 4), dtype=Float32, requires_grad=True)]
add_flags(**flags)[源代码]

为Cell添加自定义属性。

在实例化Cell类时,如果入参flags不为空,会调用此方法。

参数:
  • flags (dict) - Cell的配置信息,目前用于绑定Cell和数据集。用户也通过该参数自定义Cell属性。

样例:

>>> import mindspore as ms
>>> from mindspore import Tensor, nn
...
>>> class Net(nn.Cell):
...     def __init__(self):
...         super(Net, self).__init__()
...         self.relu = nn.ReLU()
...
...     def construct(self, x):
...         x = self.relu(x)
...         return x
>>> net = Net()
>>> net.add_flags(sink_mode=True)
>>> print(net.sink_mode)
True
add_flags_recursive(**flags)[源代码]

如果Cell含有多个子Cell,此方法会递归得给所有子Cell添加自定义属性。

参数:
  • flags (dict) - Cell的配置信息,目前用于绑定Cell和数据集。用户也通过该参数自定义Cell属性。

样例:

>>> import mindspore as ms
>>> from mindspore import Tensor, nn
...
>>> class Net(nn.Cell):
...     def __init__(self):
...         super(Net, self).__init__()
...         self.relu = nn.ReLU()
...
...     def construct(self, x):
...         x = self.relu(x)
...         return x
>>> net = Net()
>>> net.add_flags_recursive(sink_mode=True)
>>> print(net.sink_mode)
True
apply(fn)[源代码]

递归地将 fn 应用于每个子Cell(由 .cells() 返回)以及自身。通常用于初始化模型的参数。

参数:
  • fn (function) - 被执行于每个Cell的function。

返回:

Cell类型,Cell本身。

样例:

>>> import mindspore.nn as nn
>>> from mindspore.common.initializer import initializer, One
>>> net = nn.SequentialCell(nn.Dense(2, 2), nn.Dense(2, 2))
>>> def func(cell):
...     if isinstance(cell, nn.Dense):
...         cell.weight.set_data(initializer(One(), cell.weight.shape, cell.weight.dtype))
>>> net.apply(func)
SequentialCell<
  (0): Dense<input_channels=2, output_channels=2, has_bias=True>
  (1): Dense<input_channels=2, output_channels=2, has_bias=True>
  >
>>> print(net[0].weight.asnumpy())
[[1. 1.]
 [1. 1.]]
auto_cast_inputs(inputs)[源代码]

在混合精度下,自动对输入进行类型转换。

参数:
  • inputs (tuple) - construct方法的输入。

返回:

Tuple类型,经过类型转换后的输入。

property bprop_debug

在图模式下使用,用于标识是否使用自定义的反向传播函数。

教程样例:
cast_inputs(inputs, dst_type)[源代码]

将输入转换为指定类型。

参数:
  • inputs (tuple[Tensor]) - 输入。

  • dst_type (mindspore.dtype) - 指定的数据类型。

返回:

tuple[Tensor]类型,转换类型后的结果。

cast_param(param)[源代码]

在PyNative模式下,根据自动混合精度的精度设置转换Cell中参数的类型。

该接口目前在自动混合精度场景下使用。

参数:
  • param (Parameter) - 需要被转换类型的输入参数。

返回:

Parameter类型,转换类型后的参数。

cells()[源代码]

返回当前Cell的子Cell的迭代器。

返回:

Iteration类型,Cell的子Cell。

样例:

>>> import mindspore as ms
>>> from mindspore import Tensor, nn
...
>>> class Net(nn.Cell):
...     def __init__(self):
...         super(Net, self).__init__()
...         self.dense = nn.Dense(2, 2)
...
...     def construct(self, x):
...         x = self.dense(x)
...         return x
>>> net = Net()
>>> print(net.cells())
odict_values([Dense<input_channels=2, output_channels=2, has_bias=True>])
cells_and_names(cells=None, name_prefix='')[源代码]

递归地获取当前Cell及输入 cells 的所有子Cell的迭代器,包括Cell的名称及其本身。

参数:
  • cells (str) - 需要进行迭代的Cell。默认值: None

  • name_prefix (str) - 作用域。默认值: ''

返回:

Iteration类型,当前Cell及输入 cells 的所有子Cell和相对应的名称。

样例:

>>> from mindspore import nn
>>> class Net(nn.Cell):
...     def __init__(self):
...         super(Net, self).__init__()
...         self.conv = nn.Conv2d(3, 64, 3)
...     def construct(self, x):
...         out = self.conv(x)
...         return out
>>> names = []
>>> n = Net()
>>> for m in n.cells_and_names():
...     if m[0]:
...         names.append(m[0])
check_names()[源代码]

检查Cell中的网络参数名称是否重复。

compile(*args, **kwargs)[源代码]

编译Cell为计算图,输入需与construct中定义的输入一致。

参数:
  • args (tuple) - Cell的输入。

  • kwargs (dict) - Cell的输入。

compile_and_run(*args, **kwargs)[源代码]

编译并运行Cell,输入需与construct中定义的输入一致。

说明

不推荐使用该函数,建议直接调用Cell实例。

参数:
  • args (tuple) - Cell的输入。

  • kwargs (dict) - Cell的输入。

返回:

Object类型,执行的结果。

construct(*args, **kwargs)[源代码]

定义要执行的计算逻辑。所有子类都必须重写此方法。

说明

当前不支持inputs同时输入tuple类型和非tuple类型。

参数:
  • args (tuple) - 可变参数列表,默认值: ()

  • kwargs (dict) - 可变的关键字参数的字典,默认值: {}

返回:

Tensor类型,返回计算结果。

extend_repr()[源代码]

在原有描述基础上扩展Cell的描述。

若需要在print时输出个性化的扩展信息,请在您的网络中重新实现此方法。

flatten_weights(fusion_size=0)[源代码]

重置权重参数(即可训练参数)使用的数据内存,让这些参数按数据类型分组使用连续内存块。

说明

默认情况下,具有相同数据类型的参数会使用同一个连续内存块。但对于某些具有大量参数的模型, 将一个大的连续内存块分为多个小一点的内存块有可能提升性能,对于这种情况, 可以通过 fusion_size 参数来限制最大连续内存块的的大小。

参数:
  • fusion_size (int) - 最大连续内存块的大小(以字节为单位), 0 表示不限制大小。默认值: 0

generate_scope()[源代码]

为网络中的每个Cell对象生成NameSpace。

get_flags()[源代码]

获取该Cell的自定义属性,自定义属性通过 add_flags 方法添加。

样例:

>>> import mindspore as ms
>>> from mindspore import Tensor, nn
...
>>> class Net(nn.Cell):
...     def __init__(self):
...         super(Net, self).__init__()
...         self.relu = nn.ReLU()
...
...     def construct(self, x):
...         x = self.relu(x)
...         return x
>>> net = Net()
>>> net.add_flags(sink_mode=True)
>>> print(net.get_flags())
{'sink_mode':True}
get_func_graph_proto()[源代码]

返回图的二进制原型。

get_inputs()[源代码]

返回编译计算图所设置的输入。

返回:

Tuple类型,编译计算图所设置的输入。

警告

这是一个实验性API,后续可能修改或删除。

样例:

>>> import numpy as np
>>> import mindspore as ms
>>> from mindspore import nn, Tensor
>>>
>>> class ReluNet(nn.Cell):
...     def __init__(self):
...         super(ReluNet, self).__init__()
...         self.relu = nn.ReLU()
...     def construct(self, x):
...         return self.relu(x)
>>>
>>> net = ReluNet()
>>> input_dyn = Tensor(shape=[3, None], dtype=ms.float32)
>>> net.set_inputs(input_dyn)
>>> get_inputs = net.get_inputs()
>>> print(get_inputs)
(Tensor(shape=[3, -1], dtype=Float32, value= ),)
get_parameters(expand=True)[源代码]

返回Cell中parameter的迭代器。

获取Cell的参数。如果 expandtrue ,获取此cell和所有subcells的参数。关于subcell,请看下面的示例。

参数:
  • expand (bool) - 如果为 True ,则递归地获取当前Cell和所有子Cell的parameter。否则,只生成当前Cell的subcell的parameter。默认值: True

返回:

Iteration类型,Cell的parameter。

样例:

>>> import mindspore as ms
>>> from mindspore import nn, ops, Tensor
>>> import numpy as np
>>> class TestNet(nn.Cell):
...     def __init__(self):
...         super().__init__()
...         self.my_w1 = ms.Parameter(Tensor(np.ones([4, 4]), ms.float32))
...         self.my_w2 = ms.Parameter(Tensor(np.ones([16]), ms.float32))
...     def construct(self, x):
...         x += self.my_w1
...         x = ops.reshape(x, (16,)) - self.my_w2
...         return x
>>> class TestNet2(nn.Cell):
...     def __init__(self):
...         super().__init__()
...         self.my_t1 = ms.Parameter(Tensor(np.ones([4, 4]), ms.float32))
...         # self.subcell is a subcell of TestNet2, when using expand=True, the parameters of TestNet will
...         # also be gathered.
...         self.subcell = TestNet()
...     def construct(self, x):
...         x += self.my_w1
...         x = ops.reshape(x, (16,)) - self.my_w2
...         return x
>>> net = TestNet2()
>>> print([p for p in net.get_parameters(expand=True)])
[Parameter (name=my_t1, shape=(4, 4), dtype=Float32, requires_grad=True), Parameter (name=subcell.my_w1,
shape=(4, 4), dtype=Float32, requires_grad=True), Parameter (name=subcell.my_w2, shape=(16,), dtype=Float32,
requires_grad=True)]
get_scope()[源代码]

返回Cell的作用域。

返回:

String类型,网络的作用域。

infer_param_pipeline_stage()[源代码]

推导Cell中当前 pipeline_stage 的参数。

说明

  • 这个接口在2.3版本废弃,并且会在未来版本移除。

返回:

属于当前 pipeline_stage 的参数。

异常:
  • RuntimeError - 如果参数不属于任何stage。

init_parameters_data(auto_parallel_mode=False)[源代码]

初始化并替换Cell中所有的parameter的值。

说明

在调用 init_parameters_data 后,trainable_params() 或其他相似的接口可能返回不同的参数对象,不要保存这些结果。

参数:
  • auto_parallel_mode (bool) - 是否在自动并行模式下执行。默认值: False

返回:

Dict[Parameter, Parameter],返回一个原始参数和替换参数的字典。

样例:

>>> import mindspore as ms
>>> from mindspore import Tensor, nn
...
>>> class Net(nn.Cell):
...     def __init__(self):
...         super(Net, self).__init__()
...         self.dense = nn.Dense(2, 2)
...
...     def construct(self, x):
...         x = self.dense(x)
...         return x
>>> net = Net()
>>> print(net.init_parameters_data())
{Parameter (name=dense.weight, shape=(2,2), dtype=Float32, requires_grad=True):
 Parameter (name=dense.weight, shape=(2,2), dtype=Float32, requires_grad=True),
 Parameter (name=dense.bias, shape=(2,), dtype=Float32, requires_grad=True):
 Parameter (name=dense.bias, shape=(2,), dtype=Float32, requires_grad=True)}
insert_child_to_cell(child_name, child_cell)[源代码]

将一个给定名称的子Cell添加到当前Cell。

参数:
  • child_name (str) - 子Cell名称。

  • child_cell (Cell) - 要插入的子Cell。

异常:
  • KeyError - 如果子Cell的名称不正确或与其他子Cell名称重复。

  • TypeError - 如果 child_name 的类型不为str类型。

  • TypeError - 如果子Cell的类型不正确。

样例:

>>> import mindspore as ms
>>> from mindspore import Tensor, nn
...
>>> net1 = nn.ReLU()
>>> net2 = nn.Dense(2, 2)
>>> net1.insert_child_to_cell("child", net2)
>>> print(net1)
ReLU<
  (child): Dense<input_channels=2, output_channels=2, has_bias=True>
  >
insert_param_to_cell(param_name, param, check_name_contain_dot=True)[源代码]

向当前Cell添加参数。

将指定名称的参数添加到Cell中。目前在 mindspore.nn.Cell.__setattr__ 中使用。

参数:
  • param_name (str) - 参数名称。

  • param (Parameter) - 要插入到Cell的参数。

  • check_name_contain_dot (bool) - 是否对 param_name 中的"."进行检查。默认值: True

异常:
  • KeyError - 如果参数名称为空或包含"."。

  • TypeError - 如果参数的类型不是Parameter。

样例:

>>> import mindspore as ms
>>> from mindspore import Tensor, nn, Parameter
...
>>> class Net(nn.Cell):
...     def __init__(self):
...         super(Net, self).__init__()
...         self.relu = nn.ReLU()
...
...     def construct(self, x):
...         x = self.relu(x)
...         return x
>>> net = Net()
>>> net.insert_param_to_cell("bias", Parameter(Tensor([1, 2, 3])))
>>> print(net.bias)
Parameter(name=bias, shape=(3,), dtype=Int64, requires_grad=True)
name_cells()[源代码]

递归地获取一个Cell中所有子Cell的迭代器。

包括Cell名称和Cell本身。

返回:

Dict[String, Cell],Cell中的所有子Cell及其名称。

样例:

>>> import mindspore as ms
>>> from mindspore import Tensor, nn
...
>>> class Net(nn.Cell):
...     def __init__(self):
...         super(Net, self).__init__()
...         self.dense = nn.Dense(2, 2)
...
...     def construct(self, x):
...         x = self.dense(x)
...         return x
>>> net = Net()
>>> print(net.name_cells())
OrderedDict([('dense', Dense<input_channels=2, output_channels=2, has_bias=True>)])
property param_prefix

当前Cell的子Cell的参数名前缀。

样例:

>>> import mindspore as ms
>>> from mindspore import Tensor, nn
...
>>> class Net(nn.Cell):
...     def __init__(self):
...         super(Net, self).__init__()
...         self.dense = nn.Dense(2, 2)
...
...     def construct(self, x):
...         x = self.dense(x)
...         return x
>>> net = Net()
>>> net.update_cell_prefix()
>>> print(net.dense.param_prefix)
dense
property parameter_layout_dict

parameter_layout_dict 表示一个参数的张量layout,这种张量layout是由分片策略和分布式算子信息推断出来的。

parameters_and_names(name_prefix='', expand=True)[源代码]

返回Cell中parameter的迭代器。

包含参数名称和参数本身。

参数:
  • name_prefix (str) - 作用域。默认值: ''

  • expand (bool) - 如果为True,则递归地获取当前Cell和所有子Cell的参数及名称;如果为 False ,只生成当前Cell的子Cell的参数及名称。默认值: True

返回:

迭代器,Cell的名称和Cell本身。

样例:

>>> from mindspore import nn
>>> n = nn.Dense(3, 4)
>>> names = []
>>> for m in n.parameters_and_names():
...     if m[0]:
...         names.append(m[0])
教程样例:
parameters_broadcast_dict(recurse=True)[源代码]

获取这个Cell的参数广播字典。

参数:
  • recurse (bool) - 是否包含子Cell的参数。默认值: True

返回:

OrderedDict,返回参数广播字典。

parameters_dict(recurse=True)[源代码]

获取此Cell的parameter字典。

参数:
  • recurse (bool) - 是否递归得包含所有子Cell的parameter。默认值: True

返回:

OrderedDict类型,返回参数字典。

样例:

>>> import mindspore as ms
>>> from mindspore import Tensor, nn, Parameter
...
>>> class Net(nn.Cell):
...     def __init__(self):
...         super(Net, self).__init__()
...         self.dense = nn.Dense(2, 2)
...
...     def construct(self, x):
...         x = self.dense(x)
...         return x
>>> net = Net()
>>> print(net.parameters_dict())
OrderedDict([('dense.weight', Parameter(name=dense.weight, shape=(2, 2), dtype=Float32,
requires_grad=True)), ('dense.bias', Parameter(name=dense.bias, shape=(2,), dtype=Float32,
requires_grad=True))])
property pipeline_stage

pipeline_stage 表示当前Cell所在的stage。

place(role, rank_id)[源代码]

为该Cell中所有算子设置标签。此标签告诉MindSpore编译器此Cell在哪个进程上启动。 每个标签都由进程角色 rolerank_id 组成,因此,通过对不同Cell设置不同标签,这些Cell将在不同进程启动,使用户可以进行分布式训练/推理等任务。

说明

  • 此接口只在成功调用 mindspore.communication.init() 完成动态组网后才能生效。

参数:
  • role (str) - 算子执行所在进程的角色。只支持'MS_WORKER'。

  • rank_id (int) - 算子执行所在进程的id。在相同进程角色间, rank_id 是唯一的。

样例:

>>> from mindspore import context
>>> import mindspore.nn as nn
>>> context.set_context(mode=context.GRAPH_MODE)
>>> fc = nn.Dense(2, 3)
>>> fc.place('MS_WORKER', 0)
recompute(**kwargs)[源代码]

设置Cell重计算。Cell中输出算子以外的所有算子将被设置为重计算。如果一个算子的计算结果被输出到一些反向节点来进行梯度计算,且被设置成重计算,那么我们会在反向传播中重新计算它,而不去存储在前向传播中的中间激活层的计算结果。

说明

  • 如果计算涉及到诸如随机化或全局变量之类的操作,那么目前还不能保证等价。

  • 如果该Cell中算子的重计算API也被调用,则该算子的重计算模式以算子的重计算API的设置为准。

  • 该接口仅配置一次,即当父Cell配置了,子Cell不需再配置。

  • Cell的输出算子默认不做重计算,这一点是基于我们减少内存占用的配置经验。如果一个Cell里面只有一个算子而且想要把这个算子设置为重计算的,那么请使用算子的重计算API。

  • 当应用了重计算且内存充足时,可以配置'mp_comm_recompute=False'来提升性能。

  • 当应用了重计算但内存不足时,可以配置'parallel_optimizer_comm_recompute=True'来节省内存。有相同融合group的Cell应该配置相同的parallel_optimizer_comm_recompute。

参数:
  • mp_comm_recompute (bool) - 表示在自动并行或半自动并行模式下,指定Cell内部由模型并行引入的通信操作是否重计算。默认值: True

  • parallel_optimizer_comm_recompute (bool) - 表示在自动并行或半自动并行模式下,指定Cell内部由优化器并行引入的AllGather通信是否重计算。默认值: False

register_backward_hook(hook_fn)[源代码]

设置Cell对象的反向hook函数。

说明

  • register_backward_hook(hook_fn) 在图模式下,或者在PyNative模式下使用 jit 装饰器功能时不起作用。

  • hook_fn必须有如下代码定义。 cell_id 是已注册Cell对象的信息,包括名称和ID。 grad_input 是反向传递给Cell对象的梯度。 grad_output 是Cell对象的反向输出梯度。用户可以在hook_fn中打印梯度数据或者返回新的输出梯度。

  • hook_fn返回新的输出梯度或者None:hook_fn(cell_id, grad_input, grad_output) -> New grad_output or None。

  • 为了避免脚本在切换到图模式时运行失败,不建议在Cell对象的 construct 函数中调用 register_backward_hook(hook_fn)

  • PyNative模式下,如果在Cell对象的 construct 函数中调用 register_backward_hook(hook_fn) ,那么Cell对象每次运行都将增加一个 hook_fn

参数:
  • hook_fn (function) - 捕获Cell对象信息和反向输入,输出梯度的 hook_fn 函数。

返回:

返回与 hook_fn 函数对应的 handle 对象。可通过调用 handle.remove() 来删除添加的 hook_fn 函数。

异常:
  • TypeError - 如果 hook_fn 不是Python函数。

样例:

>>> import numpy as np
>>> import mindspore as ms
>>> from mindspore import Tensor, nn, ops
>>> ms.set_context(mode=ms.PYNATIVE_MODE)
>>> def backward_hook_fn(cell_id, grad_input, grad_output):
...     print("backward input: ", grad_input)
...     print("backward output: ", grad_output)
...
>>> class Net(nn.Cell):
...     def __init__(self):
...         super(Net, self).__init__()
...         self.relu = nn.ReLU()
...         self.handle = self.relu.register_backward_hook(backward_hook_fn)
...
...     def construct(self, x):
...         x = x + x
...         x = self.relu(x)
...         return x
>>> grad = ops.GradOperation(get_all=True)
>>> net = Net()
>>> output = grad(net)(Tensor(np.ones([1]).astype(np.float32)))
backward input: (Tensor(shape=[1], dtype=Float32, value= [ 1.00000000e+00]),)
backward output: (Tensor(shape=[1], dtype=Float32, value= [ 1.00000000e+00]),)
>>> print(output)
(Tensor(shape=[1], dtype=Float32, value= [ 2.00000000e+00]),)
register_forward_hook(hook_fn)[源代码]

设置Cell对象的正向hook函数。

说明

  • register_forward_hook(hook_fn) 在图模式下,或者在PyNative模式下使用 jit 装饰器功能时不起作用。

  • hook_fn必须有如下代码定义。 cell 是已注册Cell对象。 inputs 是网络正向传播时Cell对象的输入数据。 outputs 是网络正向传播时Cell对象的输出数据。用户可以在hook_fn中打印数据或者返回新的输出数据。

  • hook_fn返回新的输出数据或者None:hook_fn(cell, inputs, outputs) -> New outputs or None。

  • 为了避免脚本在切换到图模式时运行失败,不建议在Cell对象的 construct 函数中调用 register_forward_hook(hook_fn)

  • PyNative模式下,如果在Cell对象的 construct 函数中调用 register_forward_hook(hook_fn) ,那么Cell对象每次运行都将增加一个 hook_fn

参数:
  • hook_fn (function) - 捕获Cell对象信息和正向输入,输出数据的 hook_fn 函数。

返回:

返回与 hook_fn 函数对应的 handle 对象。可通过调用 handle.remove() 来删除添加的 hook_fn 函数。

异常:
  • TypeError - 如果 hook_fn 不是Python函数。

样例:

>>> import numpy as np
>>> import mindspore as ms
>>> from mindspore import Tensor, nn, ops
>>> ms.set_context(mode=ms.PYNATIVE_MODE)
>>> def forward_hook_fn(cell, inputs, output):
...     print("forward inputs: ", inputs)
...     print("forward output: ", output)
...
>>> class Net(nn.Cell):
...     def __init__(self):
...         super(Net, self).__init__()
...         self.mul = nn.MatMul()
...         self.handle = self.mul.register_forward_hook(forward_hook_fn)
...
...     def construct(self, x, y):
...         x = x + x
...         x = self.mul(x, y)
...         return x
>>> grad = ops.GradOperation(get_all=True)
>>> net = Net()
>>> output = grad(net)(Tensor(np.ones([1]).astype(np.float32)), Tensor(np.ones([1]).astype(np.float32)))
forward inputs: (Tensor(shape=[1], dtype=Float32, value= [ 2.00000000e+00]), Tensor(shape=[1],
                dtype=Float32, value= [ 1.00000000e+00]))
forward output: 2.0
>>> print(output)
(Tensor(shape=[1], dtype=Float32, value= [ 2.00000000e+00]), Tensor(shape=[1], dtype=Float32,
value= [ 2.00000000e+00]))
register_forward_pre_hook(hook_fn)[源代码]

设置Cell对象的正向pre_hook函数。

说明

  • register_forward_pre_hook(hook_fn) 在图模式下,或者在PyNative模式下使用 jit 装饰器功能时不起作用。

  • hook_fn必须有如下代码定义。 cell 是已注册Cell对象。 inputs 是网络正向传播时Cell对象的输入数据。用户可以在hook_fn中打印输入数据或者返回新的输入数据。

  • hook_fn返回新的输入数据或者None:hook_fn(cell, inputs) -> New inputs or None。

  • 为了避免脚本在切换到图模式时运行失败,不建议在Cell对象的 construct 函数中调用 register_forward_pre_hook(hook_fn)

  • PyNative模式下,如果在Cell对象的 construct 函数中调用 register_forward_pre_hook(hook_fn) ,那么Cell对象每次运行都将增加一个 hook_fn

参数:
  • hook_fn (function) - 捕获Cell对象信息和正向输入数据的hook_fn函数。

返回:

返回与 hook_fn 函数对应的 handle 对象。可通过调用 handle.remove() 来删除添加的 hook_fn 函数。

异常:
  • TypeError - 如果 hook_fn 不是Python函数。

样例:

>>> import numpy as np
>>> import mindspore as ms
>>> from mindspore import Tensor, nn, ops
>>> ms.set_context(mode=ms.PYNATIVE_MODE)
>>> def forward_pre_hook_fn(cell, inputs):
...     print("forward inputs: ", inputs)
...
>>> class Net(nn.Cell):
...     def __init__(self):
...         super(Net, self).__init__()
...         self.mul = nn.MatMul()
...         self.handle = self.mul.register_forward_pre_hook(forward_pre_hook_fn)
...
...     def construct(self, x, y):
...         x = x + x
...         x = self.mul(x, y)
...         return x
>>> grad = ops.GradOperation(get_all=True)
>>> net = Net()
>>> output = grad(net)(Tensor(np.ones([1]).astype(np.float32)), Tensor(np.ones([1]).astype(np.float32)))
forward inputs: (Tensor(shape=[1], dtype=Float32, value= [ 2.00000000e+00]), Tensor(shape=[1],
                dtype=Float32, value= [ 1.00000000e+00]))
>>> print(output)
(Tensor(shape=[1], dtype=Float32, value= [ 2.00000000e+00]), Tensor(shape=[1], dtype=Float32,
value= [ 2.00000000e+00]))
remove_redundant_parameters()[源代码]

删除冗余参数。

这个接口通常不需要显式调用。

run_construct(cast_inputs, kwargs)[源代码]

运行construct方法。

说明

该函数已经弃用,将会在未来版本中删除。不推荐使用此函数。

参数:
  • cast_inputs (tuple) - Cell的输入。

  • kwargs (dict) - 关键字参数。

返回:

Cell的输出。

set_boost(boost_type)[源代码]

为了提升网络性能,可以配置boost内的算法让框架自动使能该算法来加速网络训练。

请确保 boost_type 所选择的算法在 algorithm library 算法库中。

说明

部分加速算法可能影响网络精度,请谨慎选择。

参数:
  • boost_type (str) - 加速算法。

返回:

Cell类型,Cell本身。

异常:
  • ValueError - 如果 boost_type 不在boost算法库内。

set_broadcast_flag(mode=True)[源代码]

设置该Cell的参数广播模式。

参数:
  • mode (bool) - 指定当前模式是否进行参数广播。默认值: True

set_comm_fusion(fusion_type, recurse=True)[源代码]

为Cell中的参数设置融合类型。请参考 mindspore.Parameter.comm_fusion 的描述。

说明

当函数被多次调用时,此属性值将被重写。

参数:
  • fusion_type (int) - Parameter的 comm_fusion 属性的设置值。

  • recurse (bool) - 是否递归地设置子Cell的可训练参数。默认值: True

set_data_parallel()[源代码]

在非自动策略搜索的情况下,如果此Cell的所有算子(包括此Cell内含嵌套的cell)未指定并行策略,则将为这些基本算子设置为数据并行策略。

说明

仅在图模式,使用auto_parallel_context = ParallelMode.AUTO_PARALLEL生效。

样例:

>>> import mindspore.nn as nn
>>> net = nn.Dense(3, 4)
>>> net.set_data_parallel()
set_grad(requires_grad=True)[源代码]

Cell的梯度设置。在PyNative模式下,该参数指定Cell是否需要梯度。如果为 True ,则在执行正向网络时,将生成需要计算梯度的反向网络。

参数:
  • requires_grad (bool) - 指定网络是否需要梯度,如果为 True ,PyNative模式下Cell将构建反向网络。默认值: True

返回:

Cell类型,Cell本身。

set_inputs(*inputs, **kwargs)[源代码]

设置编译计算图所需的输入。输入数量需与数据集数量一致。若使用Model接口,请确保所有传入Model的网络和损失函数都配置了set_inputs。 输入Tensor的shape可以为动态或静态。

说明

有两种配置模式:

  • 全量配置模式:输入将被用作图编译时的完整编译参数。

  • 增量配置模式:输入被配置到Cell的部分输入上,这些输入将替换图编译对应位置上的参数。

只能传入inputs和kwargs的其中一个。inputs用于全量配置模式,kwargs用于增量配置模式。

参数:
  • inputs (tuple) - 全量配置模式的参数。

  • kwargs (dict) - 增量配置模式的参数。可设置的key值为 self.construct 中定义的参数名。

警告

这是一个实验性API,后续可能修改或删除。

样例:

>>> import numpy as np
>>> import mindspore as ms
>>> from mindspore import nn, Tensor
>>>
>>> class ReluNet(nn.Cell):
...     def __init__(self):
...         super(ReluNet, self).__init__()
...         self.relu = nn.ReLU()
...     def construct(self, x):
...         return self.relu(x)
>>>
>>> net = ReluNet()
>>> input_dyn = Tensor(shape=[3, None], dtype=ms.float32)
>>> net.set_inputs(input_dyn)
>>> input = Tensor(np.random.random([3, 10]), dtype=ms.float32)
>>> output = net(input)
>>>
>>> net2 = ReluNet()
>>> net2.set_inputs(x=input_dyn)
>>> output = net2(input)
set_jit_config(jit_config)[源代码]

为Cell设置编译时所使用的JitConfig配置项。

参数:

样例:

>>> import mindspore as ms
>>> from mindspore import Tensor, nn
...
>>> class Net(nn.Cell):
...     def __init__(self):
...         super(Net, self).__init__()
...         self.relu = nn.ReLU()
...
...     def construct(self, x):
...         x = self.relu(x)
...         return x
>>> net = Net()
>>> jitconfig = ms.JitConfig()
>>> net.set_jit_config(jitconfig)
set_param_ps(recurse=True, init_in_server=False)[源代码]

设置可训练参数是否由参数服务器更新,以及是否在服务器上初始化可训练参数。

说明

只在运行的任务处于参数服务器模式时有效。 只支持在图模式下调用。

参数:
  • recurse (bool) - 是否设置子网络的可训练参数。默认值: True

  • init_in_server (bool) - 是否在服务器上初始化由参数服务器更新的可训练参数。默认值: False

set_train(mode=True)[源代码]

将Cell设置为训练模式。

设置当前Cell和所有子Cell的训练模式。对于训练和预测具有不同结构的网络层(如 BatchNorm),将通过这个属性区分分支。如果设置为True,则执行训练分支,否则执行另一个分支。

说明

当执行 mindspore.train.Model.train() 的时候,框架会默认调用Cell.set_train(True)。 当执行 mindspore.train.Model.eval() 的时候,框架会默认调用Cell.set_train(False)。

参数:
  • mode (bool) - 指定模型是否为训练模式。默认值: True

返回:

Cell类型,Cell本身。

教程样例:
shard(in_strategy, out_strategy=None, parameter_plan=None, device='Ascend', level=0)[源代码]

指定输入/输出Tensor的分布策略,通过其余算子的策略推导得到。在PyNative模式下,可以利用此方法指定某个Cell以图模式进行分布式执行。 在图模式下, 可以利用此方法设置某个模块的分布式切分策略,未设置的会自动通过策略传播方式配置。 in_strategy/out_strategy需要为元组类型, 其中的每一个元素指定对应的输入/输出的Tensor分布策略,可参考: mindspore.ops.Primitive.shard() 的描述。也可以设置为None,会默认以数据并行执行。 其余算子的并行策略由输入输出指定的策略推导得到。

说明

调用该方法后,并行模式(parallel_mode)会自动设置为"auto_parallel"且搜索模式(search_mode)自动设置为"sharding_propagation"。 如果输入含有Parameter,其对应的策略应该在 in_strategy 里设置。

参数:
  • in_strategy (tuple) - 指定各输入的切分策略,输入元组的每个元素可以为元组或None,元组即具体指定输入每一维的切分策略,None则会默认以数据并行执行。

  • out_strategy (Union[None, tuple]) - 指定各输出的切分策略,用法同in_strategy,目前未使能。默认值: None

  • parameter_plan (Union[dict, None]) - 指定各参数的切分策略,传入字典时,键是str类型的参数名,值是一维整数tuple表示相应的切分策略, 如果参数名错误或对应参数已经设置了切分策略,该参数的设置会被跳过。默认值: None

  • device (string) - 指定执行设备,可以为[ "CPU" , "GPU" , "Ascend" ]中任意一个,目前未使能。默认值: "Ascend"

  • level (int) - 指定搜索切分策略的目标函数,即是最大化计算通信比、最小化内存消耗、最大化执行速度等。可以为[ 0 , 1 , 2 ]中任意一个,默认值: 0 。目前仅支持最大化计算通信比,其余模式未使能。

返回:

Function,返回一个在自动并行流程下执行的函数。

样例:

>>> import mindspore.nn as nn
>>>
>>> class Block(nn.Cell):
...   def __init__(self):
...     self.dense1 = nn.Dense(10, 10)
...     self.relu = nn.ReLU()
...     self.dense2 = nn.Dense2(10, 10)
...   def construct(self, x):
...     x = self.relu(self.dense2(self.relu(self.dense1(x))))
...     return x
>>>
>>> class example(nn.Cell):
...   def __init__(self):
...     self.block1 = Block()
...     self.block2 = Block()
...     self.block2_shard = self.block2.shard(in_strategy=((2, 1),), out_strategy=(None,),
...                                           parameter_plan={'self.block2.shard.dense1.weight': (4, 1)})
...   def construct(self, x):
...     x = self.block1(x)
...     x = self.block2_shard(x)
...     return x
to_float(dst_type)[源代码]

在Cell和所有子Cell的输入上添加类型转换,以使用特定的浮点类型运行。

如果 dst_typemindspore.dtype.float16 ,Cell的所有输入(包括作为常量的input, Parameter, Tensor)都会被转换为float16。请参考 mindspore.amp.build_train_network() 的源代码中的用法。

说明

多次调用将产生覆盖。

参数:
  • dst_type (mindspore.dtype) - Cell转换为 dst_type 类型运行。 dst_type 可以是 mindspore.dtype.float16mindspore.dtype.float32 或者 mindspore.dtype.bfloat16

返回:

Cell类型,Cell本身。

异常:
  • ValueError - 如果 dst_type 不是 mindspore.dtype.float32 ,不是 mindspore.dtype.float16 , 也不是 mindspore.dtype.bfloat16

支持平台:

Ascend GPU CPU

样例:

>>> import mindspore.nn as nn
>>> from mindspore import dtype as mstype
>>>
>>> net = nn.Conv2d(120, 240, 4, has_bias=False, weight_init='normal')
>>> net.to_float(mstype.float16)
Conv2d<input_channels=120, output_channels=240, kernel_size=(4, 4), stride=(1, 1), pad_mode=same,
padding=0, dilation=(1, 1), group=1, has_bias=False, weight_init=normal, bias_init=None, format=NCHW>
trainable_params(recurse=True)[源代码]

返回Cell的一个可训练参数的列表。

参数:
  • recurse (bool) - 是否递归地包含当前Cell的所有子Cell的可训练参数。默认值: True

返回:

List类型,可训练参数列表。

教程样例:
untrainable_params(recurse=True)[源代码]

返回Cell的一个不可训练参数的列表。

参数:
  • recurse (bool) - 是否递归地包含当前Cell的所有子Cell的不可训练参数。默认值: True

返回:

List类型,不可训练参数列表。

update_cell_prefix()[源代码]

递归地更新所有子Cell的 param_prefix

在调用此方法后,可以通过Cell的 param_prefix 属性获取该Cell的所有子Cell的名称前缀。

update_cell_type(cell_type)[源代码]

量化感知训练网络场景下,更新当前Cell的类型。

此方法将Cell类型设置为 cell_type

参数:
  • cell_type (str) - 被更新的类型,cell_type 可以是"quant"或"second-order"。

update_parameters_name(prefix='', recurse=True)[源代码]

给网络参数名称添加 prefix 前缀字符串。

参数:
  • prefix (str) - 前缀字符串。默认值: ''

  • recurse (bool) - 是否递归地包含所有子Cell的参数。默认值: True