.. _sec_rnn_scratch: 循环神经网络的从零开始实现 ========================== 本节将根据 :numref:`sec_rnn`\ 中的描述, 从头开始基于循环神经网络实现字符级语言模型。 这样的模型将在H.G.Wells的时光机器数据集上训练。 和前面 :numref:`sec_language_model`\ 中介绍过的一样, 我们先读取数据集。 .. raw:: html
mxnetpytorchtensorflowpaddle
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python %matplotlib inline import math from mxnet import autograd, gluon, np, npx from d2l import mxnet as d2l npx.set_np() batch_size, num_steps = 32, 35 train_iter, vocab = d2l.load_data_time_machine(batch_size, num_steps) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python %matplotlib inline import math import torch from torch import nn from torch.nn import functional as F from d2l import torch as d2l batch_size, num_steps = 32, 35 train_iter, vocab = d2l.load_data_time_machine(batch_size, num_steps) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python %matplotlib inline import math import tensorflow as tf from d2l import tensorflow as d2l batch_size, num_steps = 32, 35 train_iter, vocab = d2l.load_data_time_machine(batch_size, num_steps) .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output Downloading ../data/timemachine.txt from http://d2l-data.s3-accelerate.amazonaws.com/timemachine.txt... .. raw:: latex \diilbookstyleinputcell .. code:: python train_random_iter, vocab_random_iter = d2l.load_data_time_machine( batch_size, num_steps, use_random_iter=True) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python %matplotlib inline import warnings from d2l import paddle as d2l warnings.filterwarnings("ignore") import math import paddle from paddle import nn from paddle.nn import functional as F batch_size, num_steps = 32, 35 train_iter, vocab = d2l.load_data_time_machine(batch_size, num_steps) .. raw:: html
.. raw:: html
独热编码 -------- 回想一下,在\ ``train_iter``\ 中,每个词元都表示为一个数字索引, 将这些索引直接输入神经网络可能会使学习变得困难。 我们通常将每个词元表示为更具表现力的特征向量。 最简单的表示称为\ *独热编码*\ (one-hot encoding), 它在 :numref:`subsec_classification-problem`\ 中介绍过。 简言之,将每个索引映射为相互不同的单位向量: 假设词表中不同词元的数目为\ :math:`N`\ (即\ ``len(vocab)``\ ), 词元索引的范围为\ :math:`0`\ 到\ :math:`N-1`\ 。 如果词元的索引是整数\ :math:`i`\ , 那么我们将创建一个长度为\ :math:`N`\ 的全\ :math:`0`\ 向量, 并将第\ :math:`i`\ 处的元素设置为\ :math:`1`\ 。 此向量是原始词元的一个独热向量。 索引为\ :math:`0`\ 和\ :math:`2`\ 的独热向量如下所示: .. raw:: html
mxnetpytorchtensorflowpaddle
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python npx.one_hot(np.array([0, 2]), len(vocab)) .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output [07:39:55] ../src/storage/storage.cc:196: Using Pooled (Naive) StorageManager for CPU .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output array([[1., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 1., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python F.one_hot(torch.tensor([0, 2]), len(vocab)) .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output tensor([[1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], [0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]]) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python tf.one_hot(tf.constant([0, 2]), len(vocab)) .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python F.one_hot(paddle.to_tensor([0, 2]), len(vocab)) .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output W0818 09:32:40.444667 12727 gpu_resources.cc:61] Please NOTE: device: 0, GPU Compute Capability: 7.0, Driver API Version: 11.8, Runtime API Version: 11.8 W0818 09:32:40.473868 12727 gpu_resources.cc:91] device: 0, cuDNN Version: 8.7. .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output Tensor(shape=[2, 28], dtype=float32, place=Place(gpu:0), stop_gradient=True, [[1., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], [0., 0., 1., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]]) .. raw:: html
.. raw:: html
我们每次采样的小批量数据形状是二维张量: (批量大小,时间步数)。 ``one_hot``\ 函数将这样一个小批量数据转换成三维张量, 张量的最后一个维度等于词表大小(\ ``len(vocab)``\ )。 我们经常转换输入的维度,以便获得形状为 (时间步数,批量大小,词表大小)的输出。 这将使我们能够更方便地通过最外层的维度, 一步一步地更新小批量数据的隐状态。 .. raw:: html
mxnetpytorchtensorflowpaddle
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python X = np.arange(10).reshape((2, 5)) npx.one_hot(X.T, 28).shape .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output (5, 2, 28) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python X = torch.arange(10).reshape((2, 5)) F.one_hot(X.T, 28).shape .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output torch.Size([5, 2, 28]) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python X = tf.reshape(tf.range(10), (2, 5)) tf.one_hot(tf.transpose(X), 28).shape .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output TensorShape([5, 2, 28]) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python X = paddle.arange(10).reshape((2, 5)) F.one_hot(X.T, 28).shape .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output [5, 2, 28] .. raw:: html
.. raw:: html
初始化模型参数 -------------- 接下来,我们初始化循环神经网络模型的模型参数。 隐藏单元数\ ``num_hiddens``\ 是一个可调的超参数。 当训练语言模型时,输入和输出来自相同的词表。 因此,它们具有相同的维度,即词表的大小。 .. raw:: html
mxnetpytorchtensorflowpaddle
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python def get_params(vocab_size, num_hiddens, device): num_inputs = num_outputs = vocab_size def normal(shape): return np.random.normal(scale=0.01, size=shape, ctx=device) # 隐藏层参数 W_xh = normal((num_inputs, num_hiddens)) W_hh = normal((num_hiddens, num_hiddens)) b_h = np.zeros(num_hiddens, ctx=device) # 输出层参数 W_hq = normal((num_hiddens, num_outputs)) b_q = np.zeros(num_outputs, ctx=device) # 附加梯度 params = [W_xh, W_hh, b_h, W_hq, b_q] for param in params: param.attach_grad() return params .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python def get_params(vocab_size, num_hiddens, device): num_inputs = num_outputs = vocab_size def normal(shape): return torch.randn(size=shape, device=device) * 0.01 # 隐藏层参数 W_xh = normal((num_inputs, num_hiddens)) W_hh = normal((num_hiddens, num_hiddens)) b_h = torch.zeros(num_hiddens, device=device) # 输出层参数 W_hq = normal((num_hiddens, num_outputs)) b_q = torch.zeros(num_outputs, device=device) # 附加梯度 params = [W_xh, W_hh, b_h, W_hq, b_q] for param in params: param.requires_grad_(True) return params .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python def get_params(vocab_size, num_hiddens): num_inputs = num_outputs = vocab_size def normal(shape): return tf.random.normal(shape=shape,stddev=0.01,mean=0,dtype=tf.float32) # 隐藏层参数 W_xh = tf.Variable(normal((num_inputs, num_hiddens)), dtype=tf.float32) W_hh = tf.Variable(normal((num_hiddens, num_hiddens)), dtype=tf.float32) b_h = tf.Variable(tf.zeros(num_hiddens), dtype=tf.float32) # 输出层参数 W_hq = tf.Variable(normal((num_hiddens, num_outputs)), dtype=tf.float32) b_q = tf.Variable(tf.zeros(num_outputs), dtype=tf.float32) params = [W_xh, W_hh, b_h, W_hq, b_q] return params .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python def get_params(vocab_size, num_hiddens): num_inputs = num_outputs = vocab_size def normal(shape): return paddle.randn(shape=shape)* 0.01 # 隐藏层参数 W_xh = normal([num_inputs, num_hiddens]) W_hh = normal([num_hiddens, num_hiddens]) b_h = paddle.zeros(shape=[num_hiddens]) # 输出层参数 W_hq = normal([num_hiddens, num_outputs]) b_q = paddle.zeros(shape=[num_outputs]) # 附加梯度 params = [W_xh, W_hh, b_h, W_hq, b_q] for param in params: param.stop_gradient=False return params .. raw:: html
.. raw:: html
循环神经网络模型 ---------------- 为了定义循环神经网络模型, 我们首先需要一个\ ``init_rnn_state``\ 函数在初始化时返回隐状态。 这个函数的返回是一个张量,张量全用0填充, 形状为(批量大小,隐藏单元数)。 在后面的章节中我们将会遇到隐状态包含多个变量的情况, 而使用元组可以更容易地处理些。 .. raw:: html
mxnetpytorchtensorflowpaddle
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python def init_rnn_state(batch_size, num_hiddens, device): return (np.zeros((batch_size, num_hiddens), ctx=device), ) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python def init_rnn_state(batch_size, num_hiddens, device): return (torch.zeros((batch_size, num_hiddens), device=device), ) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python def init_rnn_state(batch_size, num_hiddens): return (tf.zeros((batch_size, num_hiddens)), ) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python def init_rnn_state(batch_size, num_hiddens): return (paddle.zeros(shape=[batch_size, num_hiddens]), ) .. raw:: html
.. raw:: html
下面的\ ``rnn``\ 函数定义了如何在一个时间步内计算隐状态和输出。 循环神经网络模型通过\ ``inputs``\ 最外层的维度实现循环, 以便逐时间步更新小批量数据的隐状态\ ``H``\ 。 此外,这里使用\ :math:`\tanh`\ 函数作为激活函数。 如 :numref:`sec_mlp`\ 所述, 当元素在实数上满足均匀分布时,\ :math:`\tanh`\ 函数的平均值为0。 .. raw:: html
mxnetpytorchtensorflowpaddle
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python def rnn(inputs, state, params): # inputs的形状:(时间步数量,批量大小,词表大小) W_xh, W_hh, b_h, W_hq, b_q = params H, = state outputs = [] # X的形状:(批量大小,词表大小) for X in inputs: H = np.tanh(np.dot(X, W_xh) + np.dot(H, W_hh) + b_h) Y = np.dot(H, W_hq) + b_q outputs.append(Y) return np.concatenate(outputs, axis=0), (H,) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python def rnn(inputs, state, params): # inputs的形状:(时间步数量,批量大小,词表大小) W_xh, W_hh, b_h, W_hq, b_q = params H, = state outputs = [] # X的形状:(批量大小,词表大小) for X in inputs: H = torch.tanh(torch.mm(X, W_xh) + torch.mm(H, W_hh) + b_h) Y = torch.mm(H, W_hq) + b_q outputs.append(Y) return torch.cat(outputs, dim=0), (H,) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python def rnn(inputs, state, params): # inputs的形状:(时间步数量,批量大小,词表大小) W_xh, W_hh, b_h, W_hq, b_q = params H, = state outputs = [] # X的形状:(批量大小,词表大小) for X in inputs: X = tf.reshape(X,[-1,W_xh.shape[0]]) H = tf.tanh(tf.matmul(X, W_xh) + tf.matmul(H, W_hh) + b_h) Y = tf.matmul(H, W_hq) + b_q outputs.append(Y) return tf.concat(outputs, axis=0), (H,) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python def rnn(inputs, state, params): # inputs的形状:(时间步数量,批量大小,词表大小) W_xh, W_hh, b_h, W_hq, b_q = params H, = state outputs = [] # X的形状:(批量大小,词表大小) for X in inputs: H = paddle.tanh(paddle.mm(X, W_xh) + paddle.mm(H, W_hh) + b_h) Y = paddle.mm(H, W_hq) + b_q outputs.append(Y) return paddle.concat(x=outputs, axis=0), (H,) .. raw:: html
.. raw:: html
定义了所有需要的函数之后,接下来我们创建一个类来包装这些函数, 并存储从零开始实现的循环神经网络模型的参数。 .. raw:: html
mxnetpytorchtensorflowpaddle
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python class RNNModelScratch: #@save """从零开始实现的循环神经网络模型""" def __init__(self, vocab_size, num_hiddens, device, get_params, init_state, forward_fn): self.vocab_size, self.num_hiddens = vocab_size, num_hiddens self.params = get_params(vocab_size, num_hiddens, device) self.init_state, self.forward_fn = init_state, forward_fn def __call__(self, X, state): X = npx.one_hot(X.T, self.vocab_size) return self.forward_fn(X, state, self.params) def begin_state(self, batch_size, ctx): return self.init_state(batch_size, self.num_hiddens, ctx) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python class RNNModelScratch: #@save """从零开始实现的循环神经网络模型""" def __init__(self, vocab_size, num_hiddens, device, get_params, init_state, forward_fn): self.vocab_size, self.num_hiddens = vocab_size, num_hiddens self.params = get_params(vocab_size, num_hiddens, device) self.init_state, self.forward_fn = init_state, forward_fn def __call__(self, X, state): X = F.one_hot(X.T, self.vocab_size).type(torch.float32) return self.forward_fn(X, state, self.params) def begin_state(self, batch_size, device): return self.init_state(batch_size, self.num_hiddens, device) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python class RNNModelScratch: #@save """从零开始实现的循环神经网络模型""" def __init__(self, vocab_size, num_hiddens, init_state, forward_fn, get_params): self.vocab_size, self.num_hiddens = vocab_size, num_hiddens self.init_state, self.forward_fn = init_state, forward_fn self.trainable_variables = get_params(vocab_size, num_hiddens) def __call__(self, X, state): X = tf.one_hot(tf.transpose(X), self.vocab_size) X = tf.cast(X, tf.float32) return self.forward_fn(X, state, self.trainable_variables) def begin_state(self, batch_size, *args, **kwargs): return self.init_state(batch_size, self.num_hiddens) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python class RNNModelScratch: #@save """从零开始实现的循环神经网络模型""" def __init__(self, vocab_size, num_hiddens, get_params, init_state, forward_fn): self.vocab_size, self.num_hiddens = vocab_size, num_hiddens self.params = get_params(vocab_size, num_hiddens) self.init_state, self.forward_fn = init_state, forward_fn def __call__(self, X, state): X = F.one_hot(X.T, self.vocab_size) return self.forward_fn(X, state, self.params) def begin_state(self, batch_size): return self.init_state(batch_size, self.num_hiddens) .. raw:: html
.. raw:: html
让我们检查输出是否具有正确的形状。 例如,隐状态的维数是否保持不变。 .. raw:: html
mxnetpytorchtensorflowpaddle
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python num_hiddens = 512 net = RNNModelScratch(len(vocab), num_hiddens, d2l.try_gpu(), get_params, init_rnn_state, rnn) state = net.begin_state(X.shape[0], d2l.try_gpu()) Y, new_state = net(X.as_in_context(d2l.try_gpu()), state) Y.shape, len(new_state), new_state[0].shape .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output [07:39:56] ../src/storage/storage.cc:196: Using Pooled (Naive) StorageManager for GPU .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output ((10, 28), 1, (2, 512)) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python num_hiddens = 512 net = RNNModelScratch(len(vocab), num_hiddens, d2l.try_gpu(), get_params, init_rnn_state, rnn) state = net.begin_state(X.shape[0], d2l.try_gpu()) Y, new_state = net(X.to(d2l.try_gpu()), state) Y.shape, len(new_state), new_state[0].shape .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output (torch.Size([10, 28]), 1, torch.Size([2, 512])) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python # 定义tensorflow训练策略 device_name = d2l.try_gpu()._device_name strategy = tf.distribute.OneDeviceStrategy(device_name) num_hiddens = 512 with strategy.scope(): net = RNNModelScratch(len(vocab), num_hiddens, init_rnn_state, rnn, get_params) state = net.begin_state(X.shape[0]) Y, new_state = net(X, state) Y.shape, len(new_state), new_state[0].shape .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output (TensorShape([10, 28]), 1, TensorShape([2, 512])) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python num_hiddens = 512 net = RNNModelScratch(len(vocab), num_hiddens, get_params, init_rnn_state, rnn) state = net.begin_state(X.shape[0]) Y, new_state = net(X, state) Y.shape, len(new_state), new_state[0].shape .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output ([10, 28], 1, [2, 512]) .. raw:: html
.. raw:: html
我们可以看到输出形状是(时间步数\ :math:`\times`\ 批量大小,词表大小), 而隐状态形状保持不变,即(批量大小,隐藏单元数)。 预测 ---- 让我们首先定义预测函数来生成\ ``prefix``\ 之后的新字符, 其中的\ ``prefix``\ 是一个用户提供的包含多个字符的字符串。 在循环遍历\ ``prefix``\ 中的开始字符时, 我们不断地将隐状态传递到下一个时间步,但是不生成任何输出。 这被称为\ *预热*\ (warm-up)期, 因为在此期间模型会自我更新(例如,更新隐状态), 但不会进行预测。 预热期结束后,隐状态的值通常比刚开始的初始值更适合预测, 从而预测字符并输出它们。 .. raw:: html
mxnetpytorchtensorflowpaddle
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python def predict_ch8(prefix, num_preds, net, vocab, device): #@save """在prefix后面生成新字符""" state = net.begin_state(batch_size=1, ctx=device) outputs = [vocab[prefix[0]]] get_input = lambda: np.array([outputs[-1]], ctx=device).reshape((1, 1)) for y in prefix[1:]: # 预热期 _, state = net(get_input(), state) outputs.append(vocab[y]) for _ in range(num_preds): # 预测num_preds步 y, state = net(get_input(), state) outputs.append(int(y.argmax(axis=1).reshape(1))) return ''.join([vocab.idx_to_token[i] for i in outputs]) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python def predict_ch8(prefix, num_preds, net, vocab, device): #@save """在prefix后面生成新字符""" state = net.begin_state(batch_size=1, device=device) outputs = [vocab[prefix[0]]] get_input = lambda: torch.tensor([outputs[-1]], device=device).reshape((1, 1)) for y in prefix[1:]: # 预热期 _, state = net(get_input(), state) outputs.append(vocab[y]) for _ in range(num_preds): # 预测num_preds步 y, state = net(get_input(), state) outputs.append(int(y.argmax(dim=1).reshape(1))) return ''.join([vocab.idx_to_token[i] for i in outputs]) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python def predict_ch8(prefix, num_preds, net, vocab): #@save """在prefix后面生成新字符""" state = net.begin_state(batch_size=1, dtype=tf.float32) outputs = [vocab[prefix[0]]] get_input = lambda: tf.reshape(tf.constant([outputs[-1]]), (1, 1)).numpy() for y in prefix[1:]: # 预热期 _, state = net(get_input(), state) outputs.append(vocab[y]) for _ in range(num_preds): # 预测num_preds步 y, state = net(get_input(), state) outputs.append(int(y.numpy().argmax(axis=1).reshape(1))) return ''.join([vocab.idx_to_token[i] for i in outputs]) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python def predict_ch8(prefix, num_preds, net, vocab, device): #@save """在prefix后面生成新字符""" state = net.begin_state(batch_size=1) outputs = [vocab[prefix[0]]] get_input = lambda: paddle.to_tensor(outputs[-1], place=device).reshape((1, 1)) for y in prefix[1:]: # 预热期 _, state = net(get_input(), state) outputs.append(vocab[y]) for _ in range(num_preds): # 预测num_preds步 y, state = net(get_input(), state) outputs.append(int(paddle.reshape(paddle.argmax(y,axis=1),shape=[1]))) return ''.join([vocab.idx_to_token[i] for i in outputs]) .. raw:: html
.. raw:: html
现在我们可以测试\ ``predict_ch8``\ 函数。 我们将前缀指定为\ ``time traveller``\ , 并基于这个前缀生成10个后续字符。 鉴于我们还没有训练网络,它会生成荒谬的预测结果。 .. raw:: html
mxnetpytorchtensorflowpaddle
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python predict_ch8('time traveller ', 10, net, vocab, d2l.try_gpu()) .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output 'time traveller iiiiiiiiii' .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python predict_ch8('time traveller ', 10, net, vocab, d2l.try_gpu()) .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output 'time traveller aaaaaaaaaa' .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python predict_ch8('time traveller ', 10, net, vocab) .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output 'time traveller krrtmxdvcs' .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python predict_ch8('time traveller ', 10, net, vocab, d2l.try_gpu()) .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output 'time traveller sbdtgor s' .. raw:: html
.. raw:: html
梯度裁剪 -------- 对于长度为\ :math:`T`\ 的序列,我们在迭代中计算这\ :math:`T`\ 个时间步上的梯度, 将会在反向传播过程中产生长度为\ :math:`\mathcal{O}(T)`\ 的矩阵乘法链。 如 :numref:`sec_numerical_stability`\ 所述, 当\ :math:`T`\ 较大时,它可能导致数值不稳定, 例如可能导致梯度爆炸或梯度消失。 因此,循环神经网络模型往往需要额外的方式来支持稳定训练。 一般来说,当解决优化问题时,我们对模型参数采用更新步骤。 假定在向量形式的\ :math:`\mathbf{x}`\ 中, 或者在小批量数据的负梯度\ :math:`\mathbf{g}`\ 方向上。 例如,使用\ :math:`\eta > 0`\ 作为学习率时,在一次迭代中, 我们将\ :math:`\mathbf{x}`\ 更新为\ :math:`\mathbf{x} - \eta \mathbf{g}`\ 。 如果我们进一步假设目标函数\ :math:`f`\ 表现良好, 即函数\ :math:`f`\ 在常数\ :math:`L`\ 下是\ *利普希茨连续的*\ (Lipschitz continuous)。 也就是说,对于任意\ :math:`\mathbf{x}`\ 和\ :math:`\mathbf{y}`\ 我们有: .. math:: |f(\mathbf{x}) - f(\mathbf{y})| \leq L \|\mathbf{x} - \mathbf{y}\|. 在这种情况下,我们可以安全地假设: 如果我们通过\ :math:`\eta \mathbf{g}`\ 更新参数向量,则 .. math:: |f(\mathbf{x}) - f(\mathbf{x} - \eta\mathbf{g})| \leq L \eta\|\mathbf{g}\|, 这意味着我们不会观察到超过\ :math:`L \eta \|\mathbf{g}\|`\ 的变化。 这既是坏事也是好事。 坏的方面,它限制了取得进展的速度; 好的方面,它限制了事情变糟的程度,尤其当我们朝着错误的方向前进时。 有时梯度可能很大,从而优化算法可能无法收敛。 我们可以通过降低\ :math:`\eta`\ 的学习率来解决这个问题。 但是如果我们很少得到大的梯度呢? 在这种情况下,这种做法似乎毫无道理。 一个流行的替代方案是通过将梯度\ :math:`\mathbf{g}`\ 投影回给定半径 (例如\ :math:`\theta`\ )的球来裁剪梯度\ :math:`\mathbf{g}`\ 。 如下式: .. math:: \mathbf{g} \leftarrow \min\left(1, \frac{\theta}{\|\mathbf{g}\|}\right) \mathbf{g}. 通过这样做,我们知道梯度范数永远不会超过\ :math:`\theta`\ , 并且更新后的梯度完全与\ :math:`\mathbf{g}`\ 的原始方向对齐。 它还有一个值得拥有的副作用, 即限制任何给定的小批量数据(以及其中任何给定的样本)对参数向量的影响, 这赋予了模型一定程度的稳定性。 梯度裁剪提供了一个快速修复梯度爆炸的方法, 虽然它并不能完全解决问题,但它是众多有效的技术之一。 下面我们定义一个函数来裁剪模型的梯度, 模型是从零开始实现的模型或由高级API构建的模型。 我们在此计算了所有模型参数的梯度的范数。 .. raw:: html
mxnetpytorchtensorflowpaddle
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python def grad_clipping(net, theta): #@save """裁剪梯度""" if isinstance(net, gluon.Block): params = [p.data() for p in net.collect_params().values()] else: params = net.params norm = math.sqrt(sum((p.grad ** 2).sum() for p in params)) if norm > theta: for param in params: param.grad[:] *= theta / norm .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python def grad_clipping(net, theta): #@save """裁剪梯度""" if isinstance(net, nn.Module): params = [p for p in net.parameters() if p.requires_grad] else: params = net.params norm = torch.sqrt(sum(torch.sum((p.grad ** 2)) for p in params)) if norm > theta: for param in params: param.grad[:] *= theta / norm .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python def grad_clipping(grads, theta): #@save """裁剪梯度""" theta = tf.constant(theta, dtype=tf.float32) new_grad = [] for grad in grads: if isinstance(grad, tf.IndexedSlices): new_grad.append(tf.convert_to_tensor(grad)) else: new_grad.append(grad) norm = tf.math.sqrt(sum((tf.reduce_sum(grad ** 2)).numpy() for grad in new_grad)) norm = tf.cast(norm, tf.float32) if tf.greater(norm, theta): for i, grad in enumerate(new_grad): new_grad[i] = grad * theta / norm else: new_grad = new_grad return new_grad .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python def grad_clipping(net, theta): #@save """裁剪梯度""" if isinstance(net, nn.Layer): params = [p for p in net.parameters() if not p.stop_gradient] else: params = net.params norm = paddle.sqrt(sum(paddle.sum((p.grad ** 2)) for p in params)) if norm > theta: with paddle.no_grad(): for param in params: param.grad.set_value(param.grad * theta / norm) .. raw:: html
.. raw:: html
训练 ---- 在训练模型之前,让我们定义一个函数在一个迭代周期内训练模型。 它与我们训练 :numref:`sec_softmax_scratch`\ 模型的方式有三个不同之处。 1. 序列数据的不同采样方法(随机采样和顺序分区)将导致隐状态初始化的差异。 2. 我们在更新模型参数之前裁剪梯度。 这样的操作的目的是,即使训练过程中某个点上发生了梯度爆炸,也能保证模型不会发散。 3. 我们用困惑度来评价模型。如 :numref:`subsec_perplexity`\ 所述, 这样的度量确保了不同长度的序列具有可比性。 具体来说,当使用顺序分区时, 我们只在每个迭代周期的开始位置初始化隐状态。 由于下一个小批量数据中的第\ :math:`i`\ 个子序列样本 与当前第\ :math:`i`\ 个子序列样本相邻, 因此当前小批量数据最后一个样本的隐状态, 将用于初始化下一个小批量数据第一个样本的隐状态。 这样,存储在隐状态中的序列的历史信息 可以在一个迭代周期内流经相邻的子序列。 然而,在任何一点隐状态的计算, 都依赖于同一迭代周期中前面所有的小批量数据, 这使得梯度计算变得复杂。 为了降低计算量,在处理任何一个小批量数据之前, 我们先分离梯度,使得隐状态的梯度计算总是限制在一个小批量数据的时间步内。 当使用随机抽样时,因为每个样本都是在一个随机位置抽样的, 因此需要为每个迭代周期重新初始化隐状态。 与 :numref:`sec_softmax_scratch`\ 中的 ``train_epoch_ch3``\ 函数相同, ``updater``\ 是更新模型参数的常用函数。 它既可以是从头开始实现的\ ``d2l.sgd``\ 函数, 也可以是深度学习框架中内置的优化函数。 .. raw:: html
mxnetpytorchtensorflowpaddle
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python #@save def train_epoch_ch8(net, train_iter, loss, updater, device, use_random_iter): """训练模型一个迭代周期(定义见第8章)""" state, timer = None, d2l.Timer() metric = d2l.Accumulator(2) # 训练损失之和,词元数量 for X, Y in train_iter: if state is None or use_random_iter: # 在第一次迭代或使用随机抽样时初始化state state = net.begin_state(batch_size=X.shape[0], ctx=device) else: for s in state: s.detach() y = Y.T.reshape(-1) X, y = X.as_in_ctx(device), y.as_in_ctx(device) with autograd.record(): y_hat, state = net(X, state) l = loss(y_hat, y).mean() l.backward() grad_clipping(net, 1) updater(batch_size=1) # 因为已经调用了mean函数 metric.add(l * d2l.size(y), d2l.size(y)) return math.exp(metric[0] / metric[1]), metric[1] / timer.stop() .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python #@save def train_epoch_ch8(net, train_iter, loss, updater, device, use_random_iter): """训练网络一个迭代周期(定义见第8章)""" state, timer = None, d2l.Timer() metric = d2l.Accumulator(2) # 训练损失之和,词元数量 for X, Y in train_iter: if state is None or use_random_iter: # 在第一次迭代或使用随机抽样时初始化state state = net.begin_state(batch_size=X.shape[0], device=device) else: if isinstance(net, nn.Module) and not isinstance(state, tuple): # state对于nn.GRU是个张量 state.detach_() else: # state对于nn.LSTM或对于我们从零开始实现的模型是个张量 for s in state: s.detach_() y = Y.T.reshape(-1) X, y = X.to(device), y.to(device) y_hat, state = net(X, state) l = loss(y_hat, y.long()).mean() if isinstance(updater, torch.optim.Optimizer): updater.zero_grad() l.backward() grad_clipping(net, 1) updater.step() else: l.backward() grad_clipping(net, 1) # 因为已经调用了mean函数 updater(batch_size=1) metric.add(l * y.numel(), y.numel()) return math.exp(metric[0] / metric[1]), metric[1] / timer.stop() .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python #@save def train_epoch_ch8(net, train_iter, loss, updater, use_random_iter): """训练模型一个迭代周期(定义见第8章)""" state, timer = None, d2l.Timer() metric = d2l.Accumulator(2) # 训练损失之和,词元数量 for X, Y in train_iter: if state is None or use_random_iter: # 在第一次迭代或使用随机抽样时初始化state state = net.begin_state(batch_size=X.shape[0], dtype=tf.float32) with tf.GradientTape(persistent=True) as g: y_hat, state = net(X, state) y = tf.reshape(tf.transpose(Y), (-1)) l = loss(y, y_hat) params = net.trainable_variables grads = g.gradient(l, params) grads = grad_clipping(grads, 1) updater.apply_gradients(zip(grads, params)) # Keras默认返回一个批量中的平均损失 metric.add(l * d2l.size(y), d2l.size(y)) return math.exp(metric[0] / metric[1]), metric[1] / timer.stop() .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python #@save def train_epoch_ch8(net, train_iter, loss, updater, device, use_random_iter): """训练网络一个迭代周期(定义见第8章)""" state, timer = None, d2l.Timer() metric = d2l.Accumulator(2) # 训练损失之和,词元数量 for X, Y in train_iter: if state is None or use_random_iter: # 在第一次迭代或使用随机抽样时初始化state state = net.begin_state(batch_size=X.shape[0]) else: if isinstance(net, nn.Layer) and not isinstance(state, tuple): # state对于nn.GRU是个张量 state.stop_gradient=True else: # state对于nn.LSTM或对于我们从零开始实现的模型是个张量 for s in state: s.stop_gradient=True y = paddle.reshape(Y.T,shape=[-1]) X = paddle.to_tensor(X, place=device) y = paddle.to_tensor(y, place=device) y_hat, state = net(X, state) l = loss(y_hat, y).mean() if isinstance(updater, paddle.optimizer.Optimizer): updater.clear_grad() l.backward() grad_clipping(net, 1) updater.step() else: l.backward() grad_clipping(net, 1) # 因为已经调用了mean函数 updater(batch_size=1) metric.add(l * y.numel(), y.numel()) return math.exp(metric[0] / metric[1]), metric[1] / timer.stop() .. raw:: html
.. raw:: html
循环神经网络模型的训练函数既支持从零开始实现, 也可以使用高级API来实现。 .. raw:: html
mxnetpytorchtensorflowpaddle
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python def train_ch8(net, train_iter, vocab, lr, num_epochs, device, #@save use_random_iter=False): """训练模型(定义见第8章)""" loss = gluon.loss.SoftmaxCrossEntropyLoss() animator = d2l.Animator(xlabel='epoch', ylabel='perplexity', legend=['train'], xlim=[10, num_epochs]) # 初始化 if isinstance(net, gluon.Block): net.initialize(ctx=device, force_reinit=True, init=init.Normal(0.01)) trainer = gluon.Trainer(net.collect_params(), 'sgd', {'learning_rate': lr}) updater = lambda batch_size: trainer.step(batch_size) else: updater = lambda batch_size: d2l.sgd(net.params, lr, batch_size) predict = lambda prefix: predict_ch8(prefix, 50, net, vocab, device) # 训练和预测 for epoch in range(num_epochs): ppl, speed = train_epoch_ch8( net, train_iter, loss, updater, device, use_random_iter) if (epoch + 1) % 10 == 0: animator.add(epoch + 1, [ppl]) print(f'困惑度 {ppl:.1f}, {speed:.1f} 词元/秒 {str(device)}') print(predict('time traveller')) print(predict('traveller')) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python #@save def train_ch8(net, train_iter, vocab, lr, num_epochs, device, use_random_iter=False): """训练模型(定义见第8章)""" loss = nn.CrossEntropyLoss() animator = d2l.Animator(xlabel='epoch', ylabel='perplexity', legend=['train'], xlim=[10, num_epochs]) # 初始化 if isinstance(net, nn.Module): updater = torch.optim.SGD(net.parameters(), lr) else: updater = lambda batch_size: d2l.sgd(net.params, lr, batch_size) predict = lambda prefix: predict_ch8(prefix, 50, net, vocab, device) # 训练和预测 for epoch in range(num_epochs): ppl, speed = train_epoch_ch8( net, train_iter, loss, updater, device, use_random_iter) if (epoch + 1) % 10 == 0: print(predict('time traveller')) animator.add(epoch + 1, [ppl]) print(f'困惑度 {ppl:.1f}, {speed:.1f} 词元/秒 {str(device)}') print(predict('time traveller')) print(predict('traveller')) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python #@save def train_ch8(net, train_iter, vocab, lr, num_epochs, strategy, use_random_iter=False): """训练模型(定义见第8章)""" with strategy.scope(): loss = tf.keras.losses.SparseCategoricalCrossentropy( from_logits=True) updater = tf.keras.optimizers.SGD(lr) animator = d2l.Animator(xlabel='epoch', ylabel='perplexity', legend=['train'], xlim=[10, num_epochs]) predict = lambda prefix: predict_ch8(prefix, 50, net, vocab) # 训练和预测 for epoch in range(num_epochs): ppl, speed = train_epoch_ch8(net, train_iter, loss, updater, use_random_iter) if (epoch + 1) % 10 == 0: print(predict('time traveller')) animator.add(epoch + 1, [ppl]) device = d2l.try_gpu()._device_name print(f'困惑度 {ppl:.1f}, {speed:.1f} 词元/秒 {str(device)}') print(predict('time traveller')) print(predict('traveller')) .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python #@save def train_ch8(net, train_iter, vocab, lr, num_epochs, device, use_random_iter=False): """训练模型(定义见第8章)""" loss = nn.CrossEntropyLoss() animator = d2l.Animator(xlabel='epoch', ylabel='perplexity', legend=['train'], xlim=[10, num_epochs]) # 初始化 if isinstance(net, nn.Layer): updater = paddle.optimizer.SGD( learning_rate=lr, parameters=net.parameters()) else: updater = lambda batch_size: d2l.sgd(net.params, lr, batch_size) predict = lambda prefix: predict_ch8(prefix, 50, net, vocab, device) # 训练和预测 for epoch in range(num_epochs): ppl, speed = train_epoch_ch8( net, train_iter, loss, updater, device, use_random_iter) if (epoch + 1) % 10 == 0: print(predict('time traveller')) animator.add(epoch + 1, [ppl]) print(f'困惑度 {ppl:.1f}, {speed:.1f} 词元/秒 {str(device)}') print(predict('time traveller')) print(predict('traveller')) .. raw:: html
.. raw:: html
现在,我们训练循环神经网络模型。 因为我们在数据集中只使用了10000个词元, 所以模型需要更多的迭代周期来更好地收敛。 .. raw:: html
mxnetpytorchtensorflowpaddle
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python num_epochs, lr = 500, 1 train_ch8(net, train_iter, vocab, lr, num_epochs, d2l.try_gpu()) .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output 困惑度 1.0, 23960.0 词元/秒 gpu(0) time traveller for so it will be convenient to speak of himwas e travelleryou can show black is white by argument said filby .. figure:: output_rnn-scratch_546c4d_199_1.svg .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python num_epochs, lr = 500, 1 train_ch8(net, train_iter, vocab, lr, num_epochs, d2l.try_gpu()) .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output 困惑度 1.0, 67212.6 词元/秒 cuda:0 time traveller for so it will be convenient to speak of himwas e travelleryou can show black is white by argument said filby .. figure:: output_rnn-scratch_546c4d_202_1.svg .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python num_epochs, lr = 500, 1 train_ch8(net, train_iter, vocab, lr, num_epochs, strategy) .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output 困惑度 1.0, 10855.9 词元/秒 /GPU:0 time travelleryou can show black is white by argument said filby travelleryou can show black is white by argument said filby .. figure:: output_rnn-scratch_546c4d_205_1.svg .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python num_epochs, lr = 500, 1 train_ch8(net, train_iter, vocab, lr, num_epochs, d2l.try_gpu()) .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output 困惑度 1.0, 36922.4 词元/秒 Place(gpu:0) time travelleryou can show black is white by argument said filby traveller with a slight accession ofcheerfulness really thi .. figure:: output_rnn-scratch_546c4d_208_1.svg .. raw:: html
.. raw:: html
最后,让我们检查一下使用随机抽样方法的结果。 .. raw:: html
mxnetpytorchtensorflowpaddle
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python net = RNNModelScratch(len(vocab), num_hiddens, d2l.try_gpu(), get_params, init_rnn_state, rnn) train_ch8(net, train_iter, vocab, lr, num_epochs, d2l.try_gpu(), use_random_iter=True) .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output 困惑度 1.4, 24839.2 词元/秒 gpu(0) time travellerit s against reason said filbycan a cube that does travellerit s against reason said filbycan a cube that does .. figure:: output_rnn-scratch_546c4d_214_1.svg .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python net = RNNModelScratch(len(vocab), num_hiddens, d2l.try_gpu(), get_params, init_rnn_state, rnn) train_ch8(net, train_iter, vocab, lr, num_epochs, d2l.try_gpu(), use_random_iter=True) .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output 困惑度 1.5, 65222.3 词元/秒 cuda:0 time traveller held in his hand was a glitteringmetallic framewo traveller but now you begin to seethe object of my investig .. figure:: output_rnn-scratch_546c4d_217_1.svg .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python with strategy.scope(): net = RNNModelScratch(len(vocab), num_hiddens, init_rnn_state, rnn, get_params) train_ch8(net, train_iter, vocab_random_iter, lr, num_epochs, strategy, use_random_iter=True) .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output 困惑度 1.5, 11393.2 词元/秒 /GPU:0 time travellerit s against reason said filbywhat fill and he put travelleryou can show beacc betich his oand huw yer connilm .. figure:: output_rnn-scratch_546c4d_220_1.svg .. raw:: html
.. raw:: html
.. raw:: latex \diilbookstyleinputcell .. code:: python net = RNNModelScratch(len(vocab), num_hiddens, get_params, init_rnn_state, rnn) train_ch8(net, train_iter, vocab, lr, num_epochs, d2l.try_gpu(), use_random_iter=True) .. raw:: latex \diilbookstyleoutputcell .. parsed-literal:: :class: output 困惑度 1.4, 38504.7 词元/秒 Place(gpu:0) time traveller proceeded anyreal body must have extension in fou traveller held in his hand was a glitteringmetallic framewo .. figure:: output_rnn-scratch_546c4d_223_1.svg .. raw:: html
.. raw:: html
从零开始实现上述循环神经网络模型, 虽然有指导意义,但是并不方便。 在下一节中,我们将学习如何改进循环神经网络模型。 例如,如何使其实现地更容易,且运行速度更快。 小结 ---- - 我们可以训练一个基于循环神经网络的字符级语言模型,根据用户提供的文本的前缀生成后续文本。 - 一个简单的循环神经网络语言模型包括输入编码、循环神经网络模型和输出生成。 - 循环神经网络模型在训练以前需要初始化状态,不过随机抽样和顺序划分使用初始化方法不同。 - 当使用顺序划分时,我们需要分离梯度以减少计算量。 - 在进行任何预测之前,模型通过预热期进行自我更新(例如,获得比初始值更好的隐状态)。 - 梯度裁剪可以防止梯度爆炸,但不能应对梯度消失。 练习 ---- 1. 尝试说明独热编码等价于为每个对象选择不同的嵌入表示。 2. 通过调整超参数(如迭代周期数、隐藏单元数、小批量数据的时间步数、学习率等)来改善困惑度。 - 困惑度可以降到多少? - 用可学习的嵌入表示替换独热编码,是否会带来更好的表现? - 如果用H.G.Wells的其他书作为数据集时效果如何, 例如\ `世界大战 `__\ ? 3. 修改预测函数,例如使用采样,而不是选择最有可能的下一个字符。 - 会发生什么? - 调整模型使之偏向更可能的输出,例如,当\ :math:`\alpha > 1`\ ,从\ :math:`q(x_t \mid x_{t-1}, \ldots, x_1) \propto P(x_t \mid x_{t-1}, \ldots, x_1)^\alpha`\ 中采样。 4. 在不裁剪梯度的情况下运行本节中的代码会发生什么? 5. 更改顺序划分,使其不会从计算图中分离隐状态。运行时间会有变化吗?困惑度呢? 6. 用ReLU替换本节中使用的激活函数,并重复本节中的实验。我们还需要梯度裁剪吗?为什么? .. raw:: html
.. raw:: html
`Discussions `__ .. raw:: html
.. raw:: html
`Discussions `__ .. raw:: html
.. raw:: html
`Discussions `__ .. raw:: html
.. raw:: html
`Discussions `__ .. raw:: html
.. raw:: html