Apache Mxnet 简明教程

Apache MXNet - Python API Module

Apache MXNet 的模块 API 类似于前馈模型，而且可以很容易地组合类似于 Torch 模块。它由以下的类组成：

Apache MXNet’s module API is like a FeedForward model and it is easier to compose similar to Torch module. It consists of following classes −

BaseModule([logger])

它表示模块的基础类。可以将模块视为计算组件或计算机器。模块的任务是执行前向传播和反向传播。它还更新模型中的参数。

It represents the base class of a module. A module can be thought of as computation component or computation machine. The job of a module is to execute forward and backward passes. It also updates parameters in a model.

Methods

下表显示 BaseModule class 中包含的方法：

Following table shows the methods consisted in BaseModule class−

Methods

Definition

backward([out_grads])

As name implies this method implements the backward computation.

bind(data_shapes[, label_shapes, …])

It binds the symbols to construct executors and it is necessary before one can perform computation with the module.

fit(train_data[, eval_data, eval_metric, …])

This method trains the module parameters.

forward(data_batch[, is_train])

As name implies this method implements the Forward computation. This method supports data batches with various shapes like different batch sizes or different image sizes.

forward_backward(data_batch)

It is a convenient function, as name implies, that calls both forward and backward.

get_input_grads([merge_multi_context])

This method will gets the gradients to the inputs which is computed in the previous backward computation.

get_outputs([merge_multi_context])

As name implies, this method will gets outputs of the previous forward computation.

get_params()

It gets the parameters especially those which are potentially copies of the actual parameters used to do computation on the device.

get_states([merge_multi_context])

init_optimizer([kvstore, optimizer, …])

This method installs and initialize the optimizers. It also initializes kvstore for distribute training.

init_params([initializer, arg_params, …])

As name implies, this method will initialize the parameters and auxiliary states.

install_monitor(mon)

This method will install monitor on all executors.

iter_predict(eval_data[, num_batch, reset, …])

This method will iterate over predictions.

load_params(fname)

It will, as name specifies, load model parameters from file.

predict(eval_data[, num_batch, …])

It will run the prediction and collects the outputs as well.

prepare(data_batch[, sparse_row_id_fn])

The operator prepares the module for processing a given data batch.

save_params(fname)

As name specifies, this function will save the model parameters to file.

score(eval_data, eval_metric[, num_batch, …])

It runs the prediction on eval_data and also evaluates the performance according to the given eval_metric.

set_params(arg_params, aux_params[, …])

This method will assign the parameter and aux state values.

set_states([states, value])

This method, as name implies, sets value for states.

update()

This method updates the given parameters according to the installed optimizer. It also updates the gradients computed in the previous forward-backward batch.

update_metric(eval_metric, labels[, pre_sliced])

This method, as name implies, evaluates and accumulates the evaluation metric on outputs of the last forward computation.

backward([out_grads])

As name implies this method implements the backward computation.

bind(data_shapes[, label_shapes, …])

It set up the buckets and binds the executor for the default bucket key. This method represents the binding for a BucketingModule.

forward(data_batch[, is_train])

As name implies this method implements the Forward computation. This method supports data batches with various shapes like different batch sizes or different image sizes.

get_input_grads([merge_multi_context])

This method will get the gradients to the inputs which is computed in the previous backward computation.

get_outputs([merge_multi_context])

As name implies, this method will get outputs from the previous forward computation.

get_params()

It gets the current parameters especially those which are potentially copies of the actual parameters used to do computation on the device.

get_states([merge_multi_context])

This method will get states from all devices.

init_optimizer([kvstore, optimizer, …])

This method installs and initialize the optimizers. It also initializes kvstore for distribute training.

init_params([initializer, arg_params, …])

As name implies, this method will initialize the parameters and auxiliary states.

install_monitor(mon)

This method will install monitor on all executors.

load(prefix, epoch[, sym_gen, …])

This method will create a model from the previously saved checkpoint.

load_dict([sym_dict, sym_gen, …])

This method will create a model from a dictionary (dict) mapping bucket_key to symbols. It also shares arg_params and aux_params.

prepare(data_batch[, sparse_row_id_fn])

The operator prepares the module for processing a given data batch.

save_checkpoint(prefix, epoch[, remove_amp_cast])

This method, as name implies, saves the current progress to the checkpoint for all buckets in BucketingModule. It is recommended to use mx.callback.module_checkpoint as epoch_end_callback to save during training.

set_params(arg_params, aux_params[,…])

As name specifies, this function will assign parameters and aux state values.

set_states([states, value])

This method, as name implies, sets value for states.

switch_bucket(bucket_key, data_shapes[, …])

It will switche to a different bucket.

update()

This method updates the given parameters according to the installed optimizer. It also updates the gradients computed in the previous forward-backward batch.

update_metric(eval_metric, labels[, pre_sliced])

This method, as name implies, evaluates and accumulates the evaluation metric on outputs of the last forward computation.

Attributes

以下表列出 BaseModule 类的各个方法包含的属性 −

Following table shows the attributes consisted in the methods of BaseModule class −

Attributes

Definition

data_names

It consists of the list of names for data required by this module.

data_shapes

It consists of the list of (name, shape) pairs specifying the data inputs to this module.

label_shapes

It shows the list of (name, shape) pairs specifying the label inputs to this module.

output_names

It consists of the list of names for the outputs of this module.

output_shapes

It consists of the list of (name, shape) pairs specifying the outputs of this module.

symbol

As name specified, this attribute gets the symbol associated with this module.

data_shapes：你可以参考 https://mxnet.apache.org 处提供的链接以了解更多详细信息。output_shapes：详细信息

data_shapes: You can refer the link available at https://mxnet.apache.org for details. output_shapes: More

output_shapes：更多信息可在 https://mxnet.apache.org/api/python 找到

output_shapes: More information is available at https://mxnet.apache.org/api/python

BucketingModule(sym_gen[…])

它表示一个模块的 Bucketingmodule 类，它有助于有效地处理长度不一的输入。

It represents the Bucketingmodule class of a Module which helps to deal efficiently with varying length inputs.

Methods

以下表列出 BucketingModule class 中包含的方法 −

Following table shows the methods consisted in BucketingModule class −

Attributes

以下表列出 BaseModule class 的各个方法包含的属性 −

Following table shows the attributes consisted in the methods of BaseModule class −

Attributes

Definition

data_names

It consists of the list of names for data required by this module.

data_shapes

It consists of the list of (name, shape) pairs specifying the data inputs to this module.

label_shapes

It shows the list of (name, shape) pairs specifying the label inputs to this module.

output_names

It consists of the list of names for the outputs of this module.

output_shapes

It consists of the list of (name, shape) pairs specifying the outputs of this module.

Symbol

As name specified, this attribute gets the symbol associated with this module.

data_shapes − 你可以参考 https://mxnet.apache.org/api/python/docs 处的链接了解更多信息。

data_shapes − You can refer the link at https://mxnet.apache.org/api/python/docs for more information.

output_shapes− 你可以参考 https://mxnet.apache.org/api/python/docs 处的链接了解更多信息。

output_shapes− You can refer the link at https://mxnet.apache.org/api/python/docs for more information.

Module(symbol[,data_names, label_names,…])

它表示一个包装 symbol 的基本模块。

It represents a basic module that wrap a symbol.

Methods

以下表列出 Module class 中包含的方法 −

Following table shows the methods consisted in Module class −

Methods

Definition

backward([out_grads])

As name implies this method implements the backward computation.

bind(data_shapes[, label_shapes, …])

It binds the symbols to construct executors and it is necessary before one can perform computation with the module.

borrow_optimizer(shared_module)

As name implies, this method will borrow the optimizer from a shared module.

forward(data_batch[, is_train])

As name implies this method implements the Forward computation. This method supports data batches with various shapes like different batch sizes or different image sizes.

get_input_grads([merge_multi_context])

This method will gets the gradients to the inputs which is computed in the previous backward computation.

get_outputs([merge_multi_context])

As name implies, this method will gets outputs of the previous forward computation.

get_params()

It gets the parameters especially those which are potentially copies of the actual parameters used to do computation on the device.

get_states([merge_multi_context])

This method will get states from all devices

init_optimizer([kvstore, optimizer, …])

This method installs and initialize the optimizers. It also initializes kvstore for distribute training.

init_params([initializer, arg_params, …])

As name implies, this method will initialize the parameters and auxiliary states.

install_monitor(mon)

This method will install monitor on all executors.

load(prefix, epoch[, sym_gen, …])

This method will create a model from the previously saved checkpoint.

load_optimizer_states(fname)

This method will load an optimizer i.e. the updater state from a file.

prepare(data_batch[, sparse_row_id_fn])

The operator prepares the module for processing a given data batch.

reshape(data_shapes[, label_shapes])

This method, as name implies, reshape the module for new input shapes.

save_checkpoint(prefix, epoch[, …])

It saves the current progress to checkpoint.

save_optimizer_states(fname)

This method saves the optimizer or the updater state to a file.

set_params(arg_params, aux_params[,…])

As name specifies, this function will assign parameters and aux state values.

set_states([states, value])

This method, as name implies, sets value for states.

update()

This method updates the given parameters according to the installed optimizer. It also updates the gradients computed in the previous forward-backward batch.

update_metric(eval_metric, labels[, pre_sliced])

This method, as name implies, evaluates and accumulates the evaluation metric on outputs of the last forward computation.

Attributes

下表显示了 Module class 方法包含的属性——

Following table shows the attributes consisted in the methods of Module class −

Attributes

Definition

data_names

It consists of the list of names for data required by this module.

data_shapes

It consists of the list of (name, shape) pairs specifying the data inputs to this module.

label_shapes

It shows the list of (name, shape) pairs specifying the label inputs to this module.

output_names

It consists of the list of names for the outputs of this module.

output_shapes

It consists of the list of (name, shape) pairs specifying the outputs of this module.

label_names

It consists of the list of names for labels required by this module.

data_shapes: 访问链接 https://mxnet.apache.org/api/python/docs/api/module 以获取更多详细信息。

data_shapes: Visit the link https://mxnet.apache.org/api/python/docs/api/module for further details.

output_shapes: 此处给出的链接 https://mxnet.apache.org/api/python/docs/api/module/index.html 将提供其他重要信息。

output_shapes: The link given herewith https://mxnet.apache.org/api/python/docs/api/module/index.html will offer other important information.

PythonLossModule([name,data_names,…])

该类的基础是 mxnet.module.python_module.PythonModule. PythonLossModule 类是一个便捷的模块类，它将所有或许多模块 API 实现为空函数。

The base of this class is mxnet.module.python_module.PythonModule. PythonLossModule class is a convenient module class which implements all or many of the module APIs as empty functions.

Methods

下表显示了 PythonLossModule 类中包含的方法:

Following table shows the methods consisted in PythonLossModule class:

Methods

Definition

backward([out_grads])

As name implies this method implements the backward computation.

forward(data_batch[, is_train])

As name implies this method implements the Forward computation. This method supports data batches with various shapes like different batch sizes or different image sizes.

get_input_grads([merge_multi_context])

This method will gets the gradients to the inputs which is computed in the previous backward computation.

get_outputs([merge_multi_context])

As name implies, this method will gets outputs of the previous forward computation.

install_monitor(mon)

This method will install monitor on all executors.

PythonModule([data_names,label_names…])

该类的基础是 mxnet.module.base_module.BaseModule。PythonModule 类也是一个便捷的模块类，它将所有或许多模块 API 实现为空函数。

The base of this class is mxnet.module.base_module.BaseModule. PythonModule class also is a convenient module class which implements all or many of the module APIs as empty functions.

Methods

下表显示了 PythonModule 类中包含的方法——

Following table shows the methods consisted in PythonModule class −

Methods

Definition

bind(data_shapes[, label_shapes, …])

It binds the symbols to construct executors and it is necessary before one can perform computation with the module.

get_params()

It gets the parameters especially those which are potentially copies of the actual parameters used to do computation on the device.

init_optimizer([kvstore, optimizer, …])

This method installs and initialize the optimizers. It also initializes kvstore for distribute training.

init_params([initializer, arg_params, …])

As name implies, this method will initialize the parameters and auxiliary states.

update()

This method updates the given parameters according to the installed optimizer. It also updates the gradients computed in the previous forward-backward batch.

update_metric(eval_metric, labels[, pre_sliced])

This method, as name implies, evaluates and accumulates the evaluation metric on outputs of the last forward computation.

Attributes

下表显示了 PythonModule 类中的方法包含的属性——

Following table shows the attributes consisted in the methods of PythonModule class −

Attributes

Definition

data_names

It consists of the list of names for data required by this module.

data_shapes

It consists of the list of (name, shape) pairs specifying the data inputs to this module.

label_shapes

It shows the list of (name, shape) pairs specifying the label inputs to this module.

output_names

It consists of the list of names for the outputs of this module.

output_shapes

It consists of the list of (name, shape) pairs specifying the outputs of this module.

data_shapes - 访问链接 https://mxnet.apache.org 查看详细信息。

data_shapes − Follow the link https://mxnet.apache.org for details.

output_shapes - 访问链接 https://mxnet.apache.org 查看更多详细信息

output_shapes − For more details, visit the link available at https://mxnet.apache.org

SequentialModule([logger])

该类的基础是 mxnet.module.base_module.BaseModule。SequentialModule 类也是一个容器模块，它可以链接多个模块。

The base of this class is mxnet.module.base_module.BaseModule. SequentialModule class also is a container module that can chain more than two (multiple) modules together.

Methods

下表显示了 SequentialModule 类中包含的方法

Following table shows the methods consisted in SequentialModule class

Methods

Definition

add(module, **kwargs)

This is most important function of this class. It adds a module to the chain.

backward([out_grads])

As name implies this method implements the backward computation.

bind(data_shapes[, label_shapes, …])

It binds the symbols to construct executors and it is necessary before one can perform computation with the module.

forward(data_batch[, is_train])

As name implies this method implements the Forward computation. This method supports data batches with various shapes like different batch sizes or different image sizes.

get_input_grads([merge_multi_context])

This method will gets the gradients to the inputs which is computed in the previous backward computation.

get_outputs([merge_multi_context])

As name implies, this method will gets outputs of the previous forward computation.

get_params()

It gets the parameters especially those which are potentially copies of the actual parameters used to do computation on the device.

init_optimizer([kvstore, optimizer, …])

This method installs and initialize the optimizers. It also initializes kvstore for distribute training.

init_params([initializer, arg_params, …])

As name implies, this method will initialize the parameters and auxiliary states.

install_monitor(mon)

This method will install monitor on all executors.

update()

This method updates the given parameters according to the installed optimizer. It also updates the gradients computed in the previous forward-backward batch.

update_metric(eval_metric, labels[, pre_sliced])

This method, as name implies, evaluates and accumulates the evaluation metric on outputs of the last forward computation.

Attributes

下表显示了 BaseModule 类的方法中包含的属性 -

Following table shows the attributes consisted in the methods of BaseModule class −

Attributes

Definition

data_names

It consists of the list of names for data required by this module.

data_shapes

It consists of the list of (name, shape) pairs specifying the data inputs to this module.

label_shapes

It shows the list of (name, shape) pairs specifying the label inputs to this module.

output_names

It consists of the list of names for the outputs of this module.

output_shapes

It consists of the list of (name, shape) pairs specifying the outputs of this module.

output_shapes

It consists of the list of (name, shape) pairs specifying the outputs of this module.

data_shapes - 此处给出的链接 https://mxnet.apache.org 将帮助你更详细地理解属性。

data_shapes − The link given herewith https://mxnet.apache.org will help you in understanding the attribute in much detail.

output_shapes - 按照 https://mxnet.apache.org/api 上的链接了解更多详情。

output_shapes − Follow the link available at https://mxnet.apache.org/api for details.

Implementation Examples

在下面的示例中，我们将创建一个 mxnet 模块。

In the example below, we are going create a mxnet module.

import mxnet as mx
input_data = mx.symbol.Variable('input_data')
f_connected1 = mx.symbol.FullyConnected(data, name='f_connected1', num_hidden=128)
activation_1 = mx.symbol.Activation(f_connected1, name='relu1', act_type="relu")
f_connected2 = mx.symbol.FullyConnected(activation_1, name = 'f_connected2', num_hidden = 64)
activation_2 = mx.symbol.Activation(f_connected2, name='relu2',
act_type="relu")
f_connected3 = mx.symbol.FullyConnected(activation_2, name='fc3', num_hidden=10)
out = mx.symbol.SoftmaxOutput(f_connected3, name = 'softmax')
mod = mx.mod.Module(out)
print(out)

Output

输出如下：

The output is mentioned below −

<Symbol softmax>

Example

print(mod)

Output

输出如下所示−

The output is shown below −

<mxnet.module.module.Module object at 0x00000123A9892F28>

在下例中，我们将实现正向计算

In this example below, we will be implementing forward computation

import mxnet as mx
from collections import namedtuple
Batch = namedtuple('Batch', ['data'])
data = mx.sym.Variable('data')
out = data * 2
mod = mx.mod.Module(symbol=out, label_names=None)
mod.bind(data_shapes=[('data', (1, 10))])
mod.init_params()
data1 = [mx.nd.ones((1, 10))]
mod.forward(Batch(data1))
print (mod.get_outputs()[0].asnumpy())

Output

执行以上代码时，应该看到以下输出 −

When you execute the above code, you should see the following output −

[[2. 2. 2. 2. 2. 2. 2. 2. 2. 2.]]

Example

data2 = [mx.nd.ones((3, 5))]

mod.forward(Batch(data2))
print (mod.get_outputs()[0].asnumpy())

Output

以下是代码的输出 −

Given below is the output of the code −

[[2. 2. 2. 2. 2.]
[2. 2. 2. 2. 2.]
[2. 2. 2. 2. 2.]]