From 1fef29e37228fd71541b6c63c8c92d721e8b678c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=99=88=E6=80=A1=E7=84=B6?= <845465009@qq.com> Date: Fri, 5 Jul 2019 20:11:24 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E6=94=B9docs/source/user/tutorials.rs?= =?UTF-8?q?t=E5=92=8Cdocs/source/tutorials/tutorial=5F1=5Fbatcher=5Floss?= =?UTF-8?q?=5Foptimizer.rst?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../tutorial_1_batcher_loss_optimizer.rst | 354 ++++++++++++++++++ docs/source/user/tutorials.rst | 1 + 2 files changed, 355 insertions(+) create mode 100644 docs/source/tutorials/tutorial_1_batcher_loss_optimizer.rst diff --git a/docs/source/tutorials/tutorial_1_batcher_loss_optimizer.rst b/docs/source/tutorials/tutorial_1_batcher_loss_optimizer.rst new file mode 100644 index 00000000..aa97da83 --- /dev/null +++ b/docs/source/tutorials/tutorial_1_batcher_loss_optimizer.rst @@ -0,0 +1,354 @@ + +============================================================================== +Tutorial for batcher, loss, optimizer----text classification example +============================================================================== + +我们使用和 :doc:`/user/quickstart` 中一样的任务来进行详细的介绍。给出一段评价性文字，预测其情感倾向是积极（label=1）还是消极（label=0） + +-------------- +数据处理 +-------------- + +数据读入 + 我们可以使用 fastNLP :mod:`fastNLP.io` 模块中的 :class:`~fastNLP.io.CSVLoader` 类，轻松地从 csv 文件读取我们的数据。 + 这里的 dataset 是 fastNLP 中 :class:`~fastNLP.DataSet` 类的对象 + + .. code-block:: python + + from fastNLP.io import CSVLoader + + loader = CSVLoader(headers=('text', 'label'), sep='\t') + dataset = loader.load("./sentiment_analysis_sample.csv") + print(dataset[0]) + + 输出数据如下:: + + {'text': if you like movies , do n't watch this movie . type=str, + 'label': 0 type=str} + 除了读取数据外，fastNLP 还提供了读取其它文件类型的 Loader 类、读取 Embedding的 Loader 等。详见 :doc:`/fastNLP.io` 。 + + +数据处理 + 我们使用 :class:`~fastNLP.DataSet` 类的 :meth:`~fastNLP.DataSet.apply` 方法将 ``raw_sentence`` 中字母变成小写，并将句子分词。 + 同时也将 ``label`` :mod:`~fastNLP.core.field` 转化为整数并改名为 ``target``。 + + .. code-block:: python + + # 将所有字母转为小写, 使所有句子变成单词序列 + dataset.apply(lambda x: x['text'].lower(), new_field_name='text') + dataset.apply_field(lambda x: x.split(), field_name='text', new_field_name='words') + + # 将label转为整数 + dataset.apply(lambda x: int(x['label']), new_field_name='target') + + + ``words`` 和 ``target`` 已经足够用于 :class:`~fastNLP.models.CNNText` 的训练了，但我们从其文档 + :class:`~fastNLP.models.CNNText` 中看到，在 :meth:`~fastNLP.models.CNNText.forward` 的时候，还可以传入可选参数 ``seq_len`` 。 + 所以，我们再使用 :meth:`~fastNLP.DataSet.apply_field` 方法增加一个名为 ``seq_len`` 的 :mod:`~fastNLP.core.field` 。 + + .. code-block:: python + + # 增加长度信息 + dataset.apply_field(lambda x: len(x), field_name='words', new_field_name='seq_len') + + 观察可知： :meth:`~fastNLP.DataSet.apply_field` 与 :meth:`~fastNLP.DataSet.apply` 类似， + 但所传入的 `lambda` 函数是针对一个 :class:`~fastNLP.Instance` 中的一个 :mod:`~fastNLP.core.field` 的； + 而 :meth:`~fastNLP.DataSet.apply` 所传入的 `lambda` 函数是针对整个 :class:`~fastNLP.Instance` 的。 + + .. note:: + `lambda` 函数即匿名函数，是 Python 的重要特性。 ``lambda x: len(x)`` 和下面的这个函数的作用相同:: + + def func_lambda(x): + return len(x) + + 你也可以编写复杂的函数做为 :meth:`~fastNLP.DataSet.apply_field` 与 :meth:`~fastNLP.DataSet.apply` 的参数 + +Vocabulary 的使用 + 我们再用 :class:`~fastNLP.Vocabulary` 类来统计数据中出现的单词，并使用 :meth:`~fastNLP.Vocabulary.index_dataset` + 将单词序列转化为训练可用的数字序列。 + + .. code-block:: python + + from fastNLP import Vocabulary + + # 使用Vocabulary类统计单词，并将单词序列转化为数字序列 + vocab = Vocabulary(min_freq=2).from_dataset(dataset, field_name='words') + vocab.index_dataset(dataset, field_name='words',new_field_name='words') + print(dataset[0]) + + 输出数据如下:: + + {'text': if you like movies , do n't watch this movie . type=str, + 'label': 0 type=str, + 'words': [41, 22, 43, 78, 4, 46, 27, 81, 11, 14, 2] type=list, + 'target': 0 type=int, + 'seq_len': 11 type=int} + + +--------------------- +使用内置模型训练 +--------------------- + +内置模型的输入输出命名 + fastNLP内置了一些完整的神经网络模型，详见 :doc:`/fastNLP.models` , 我们使用其中的 :class:`~fastNLP.models.CNNText` 模型进行训练。 + 为了使用内置的 :class:`~fastNLP.models.CNNText`，我们必须修改 :class:`~fastNLP.DataSet` 中 :mod:`~fastNLP.core.field` 的名称。 + 在这个例子中模型输入 (forward方法的参数) 为 ``words`` 和 ``seq_len`` ; 预测输出为 ``pred`` ;标准答案为 ``target`` 。 + 具体的命名规范可以参考 :doc:`/fastNLP.core.const` 。 + + 如果不想查看文档，您也可以使用 :class:`~fastNLP.Const` 类进行命名。下面的代码展示了给 :class:`~fastNLP.DataSet` 中 + :mod:`~fastNLP.core.field` 改名的 :meth:`~fastNLP.DataSet.rename_field` 方法，以及 :class:`~fastNLP.Const` 类的使用方法。 + + .. code-block:: python + + from fastNLP import Const + + dataset.rename_field('words', Const.INPUT) + dataset.rename_field('seq_len', Const.INPUT_LEN) + dataset.rename_field('target', Const.TARGET) + + print(Const.INPUT) + print(Const.INPUT_LEN) + print(Const.TARGET) + print(Const.OUTPUT) + + 输出结果为:: + + words + seq_len + target + pred + + 在给 :class:`~fastNLP.DataSet` 中 :mod:`~fastNLP.core.field` 改名后，我们还需要设置训练所需的输入和目标，这里使用的是 + :meth:`~fastNLP.DataSet.set_input` 和 :meth:`~fastNLP.DataSet.set_target` 两个函数。 + + .. code-block:: python + + #使用dataset的 set_input 和 set_target函数，告诉模型dataset中那些数据是输入，那些数据是标签（目标输出） + dataset.set_input(Const.INPUT, Const.INPUT_LEN) + dataset.set_target(Const.TARGET) + +数据集分割 + 除了修改 :mod:`~fastNLP.core.field` 之外，我们还可以对 :class:`~fastNLP.DataSet` 进行分割，以供训练、开发和测试使用。 + 下面这段代码展示了 :meth:`~fastNLP.DataSet.split` 的使用方法 + + .. code-block:: python + + train_dev_data, test_data = dataset.split(0.1) + train_data, dev_data = train_dev_data.split(0.1) + print(len(train_data), len(dev_data), len(test_data)) + + 输出结果为:: + + 1620 180 200 + +损失函数 + 训练模型需要提供一个损失函数 + ,fastNLP中提供了直接可以导入使用的四种loss，分别为： + + * :class:`~fastNLP.CrossEntropyLoss`：包装了torch.nn.functional.cross_entropy()函数，返回交叉熵损失（可以运用于多分类场景） + * :class:`~fastNLP.BCELoss`：包装了torch.nn.functional.binary_cross_entropy()函数，返回二分类的交叉熵 + * :class:`~fastNLP.L1Loss`：包装了torch.nn.functional.l1_loss()函数，返回L1 损失 + * :class:`~fastNLP.NLLLoss`：包装了torch.nn.functional.nll_loss()函数，返回负对数似然损失 + + 下面提供了一个在分类问题中常用的交叉熵损失。注意它的 **初始化参数** 。 + ``pred`` 参数对应的是模型的 forward 方法返回的 dict 中的一个 key 的名字。 + ``target`` 参数对应的是 :class:`~fastNLP.DataSet` 中作为标签的 :mod:`~fastNLP.core.field` 的名字。 + 这里我们用 :class:`~fastNLP.Const` 来辅助命名，如果你自己编写模型中 forward 方法的返回值或 + 数据集中 :mod:`~fastNLP.core.field` 的名字与本例不同， 你可以把 ``pred`` 参数和 ``target`` 参数设定符合自己代码的值。 + + .. code-block:: python + + from fastNLP import CrossEntropyLoss + + # loss = CrossEntropyLoss() 在本例中与下面这行代码等价 + loss = CrossEntropyLoss(pred=Const.OUTPUT, target=Const.TARGET) + +评价指标 + 训练模型需要提供一个评价指标。这里使用准确率做为评价指标。参数的 `命名规则` 跟上面类似。 + ``pred`` 参数对应的是模型的 forward 方法返回的 dict 中的一个 key 的名字。 + ``target`` 参数对应的是 :class:`~fastNLP.DataSet` 中作为标签的 :mod:`~fastNLP.core.field` 的名字。 + + .. code-block:: python + + from fastNLP import AccuracyMetric + + # metrics=AccuracyMetric() 在本例中与下面这行代码等价 + metrics=AccuracyMetric(pred=Const.OUTPUT, target=Const.TARGET) + +优化器 + 定义模型运行的时候使用的优化器，可以使用fastNLP包装好的优化器： + + * :class:`~fastNLP.SGD` ：包装了torch.optim.SGD优化器 + * :class:`~fastNLP.Adam` ：包装了torch.optim.Adam优化器 + + 也可以直接使用torch.optim.Optimizer中的优化器，并在实例化 :class:`~fastNLP.Trainer` 类的时候传入优化器实参 + + .. code-block:: python + + import torch.optim as optim + from fastNLP import Adam + + #使用 torch.optim 定义优化器 + optimizer_1=optim.RMSprop(model_cnn.parameters(), lr=0.01, alpha=0.99, eps=1e-08, weight_decay=0, momentum=0, centered=False) + #使用fastNLP中包装的 Adam 定义优化器 + optimizer_2=Adam(lr=4e-3, betas=(0.9, 0.999), eps=1e-08, weight_decay=0, model_params=model_cnn.parameters()) + +快速训练 + 现在我们可以导入 fastNLP 内置的文本分类模型 :class:`~fastNLP.models.CNNText` ，并使用 :class:`~fastNLP.Trainer` 进行训练了 + + .. code-block:: python + + from fastNLP.models import CNNText + + #词嵌入的维度、训练的轮数和batch size + EMBED_DIM = 100 + N_EPOCHS = 10 + BATCH_SIZE = 16 + + #使用CNNText的时候第一个参数输入一个tuple,作为模型定义embedding的参数 + #还可以传入 kernel_nums, kernel_sizes, padding, dropout的自定义值 + model_cnn = CNNText((len(vocab),EMBED_DIM), num_classes=2, padding=2, dropout=0.1) + + #如果在定义trainer的时候没有传入optimizer参数，模型默认的优化器为torch.optim.Adam且learning rate为lr=4e-3 + #这里只使用了optimizer_1作为优化器输入，感兴趣可以尝试optimizer_2或者其他优化器作为输入 + #这里只使用了loss作为损失函数输入，感兴趣可以尝试其他损失函数输入 + trainer = Trainer(model=model_cnn, train_data=train_data, dev_data=dev_data, loss=loss, metrics=metrics, + optimizer=optimizer_1,n_epochs=N_EPOCHS, batch_size=BATCH_SIZE) + trainer.train() + + 训练过程的输出如下:: + + input fields after batch(if batch size is 2): + words: (1)type:torch.Tensor (2)dtype:torch.int64, (3)shape:torch.Size([2, 26]) + seq_len: (1)type:torch.Tensor (2)dtype:torch.int64, (3)shape:torch.Size([2]) + target fields after batch(if batch size is 2): + target: (1)type:torch.Tensor (2)dtype:torch.int64, (3)shape:torch.Size([2]) + + training epochs started 2019-07-05-16-18-39 + Evaluation at Epoch 1/10. Step:102/1020. AccuracyMetric: acc=0.7 + + Evaluation at Epoch 2/10. Step:204/1020. AccuracyMetric: acc=0.672222 + + Evaluation at Epoch 3/10. Step:306/1020. AccuracyMetric: acc=0.683333 + + Evaluation at Epoch 4/10. Step:408/1020. AccuracyMetric: acc=0.722222 + + Evaluation at Epoch 5/10. Step:510/1020. AccuracyMetric: acc=0.75 + + Evaluation at Epoch 6/10. Step:612/1020. AccuracyMetric: acc=0.738889 + + Evaluation at Epoch 7/10. Step:714/1020. AccuracyMetric: acc=0.738889 + + Evaluation at Epoch 8/10. Step:816/1020. AccuracyMetric: acc=0.794444 + + Evaluation at Epoch 9/10. Step:918/1020. AccuracyMetric: acc=0.755556 + + Evaluation at Epoch 10/10. Step:1020/1020. AccuracyMetric: acc=0.75 + + + In Epoch:8/Step:816, got best dev performance:AccuracyMetric: acc=0.794444 + Reloaded the best model. + +快速测试 + 与 :class:`~fastNLP.Trainer` 对应，fastNLP 也提供了 :class:`~fastNLP.Tester` 用于快速测试，用法如下 + + .. code-block:: python + + from fastNLP import Tester + + tester = Tester(test_data, model_cnn, metrics=AccuracyMetric()) + tester.test() + + 训练过程输出如下:: + + [tester] + AccuracyMetric: acc=0.66 + +-------------------------- +自己编写训练过程 +-------------------------- + + 如果你想用类似 PyTorch 的使用方法，自己编写训练过程，你可以参考下面这段代码。 + 其中使用了 fastNLP 提供的 :class:`~fastNLP.Batch`来获得小批量训练的小批量数据， + 使用 :class:`~fastNLP.BucketSampler` 做为 :class:`~fastNLP.Batch` 的参数来选择采样的方式。 + +Batch + fastNLP定义的 :class:`~fastNLP.Batch` 类在初始化时传入的参数有： + + * dataset: :class:`~fastNLP.DataSet` 对象, 数据集 + * batch_size: 取出的batch大小 + * sampler: 规定使用的 :class:`~fastNLP.Sampler` 若为 None, 使用 :class:`~fastNLP.RandomSampler` （Default: None） + * as_numpy: 若为 True, 输出batch为 `numpy.array`. 否则为 `torch.Tensor` （Default: False） + * prefetch: 若为 True使用多进程预先取出下一batch. （Default: False） + +sampler + fastNLP 实现的采样器有： + + * :class:`~fastNLP.BucketSampler` 可以随机地取出长度相似的元素 【初始化参数: num_buckets：bucket的数量； batch_size：batch大小； seq_len_field_name：dataset中对应序列长度的 :mod:`~fastNLP.core.field` 的名字】 + * SequentialSampler： 顺序取出元素的采样器【无初始化参数】 + * RandomSampler：随机化取元素的采样器【无初始化参数】 + +以下代码使用BucketSampler作为Batch初始化的输入，运用Batch自己写训练程序 + +.. code-block:: python + + from fastNLP import BucketSampler + from fastNLP import Batch + import torch + import time + + model = CNNText((len(vocab),embed_dim), num_classes=2, padding=2, dropout=0.1) + + def train(epoch, data, devdata): + optimizer = torch.optim.Adam(model.parameters(), lr=0.001) + lossfunc = torch.nn.CrossEntropyLoss() + batch_size = 32 + + # 定义一个Batch，传入DataSet，规定batch_size和去batch的规则。 + # 顺序（Sequential），随机（Random），相似长度组成一个batch（Bucket） + train_sampler = BucketSampler(batch_size=batch_size, seq_len_field_name='seq_len') + train_batch = Batch(batch_size=batch_size, dataset=data, sampler=train_sampler) + + start_time = time.time() + print("-"*5+"start training"+"-"*5) + for i in range(epoch): + loss_list = [] + for batch_x, batch_y in train_batch: + optimizer.zero_grad() + output = model(batch_x['words']) + loss = lossfunc(output['pred'], batch_y['target']) + loss.backward() + optimizer.step() + loss_list.append(loss.item()) + + #这里verbose如果为0，在调用Tester对象的test()函数时不输出任何信息，返回评估信息; 如果为1，打印出验证结果，返回评估信息 + #在调用过Tester对象的test()函数后，调用其_format_eval_results(res)函数，结构化输出验证结果 + tester_tmp = Tester(devdata, model, metrics=AccuracyMetric(), verbose=0) + res=tester_tmp.test() + + print('Epoch {:d} Avg Loss: {:.2f}'.format(i, sum(loss_list) / len(loss_list)),end=" ") + print(tester._format_eval_results(res),end=" ") + print('{:d}ms'.format(round((time.time()-start_time)*1000))) + loss_list.clear() + + train(10, train_data, dev_data) + tester = Tester(test_data, model, metrics=AccuracyMetric()) + tester.test() + +这段代码的输出如下:: + + -----start training----- + Epoch 0 Avg Loss: 0.91 AccuracyMetric: acc=0.533333 9411ms + Epoch 1 Avg Loss: 0.69 AccuracyMetric: acc=0.627778 18625ms + Epoch 2 Avg Loss: 0.63 AccuracyMetric: acc=0.661111 27047ms + Epoch 3 Avg Loss: 0.56 AccuracyMetric: acc=0.605556 36406ms + Epoch 4 Avg Loss: 0.52 AccuracyMetric: acc=0.622222 46076ms + Epoch 5 Avg Loss: 0.46 AccuracyMetric: acc=0.633333 55052ms + Epoch 6 Avg Loss: 0.40 AccuracyMetric: acc=0.666667 64419ms + Epoch 7 Avg Loss: 0.35 AccuracyMetric: acc=0.644444 74495ms + Epoch 8 Avg Loss: 0.30 AccuracyMetric: acc=0.666667 84331ms + Epoch 9 Avg Loss: 0.26 AccuracyMetric: acc=0.655556 93642ms + [tester] + AccuracyMetric: acc=0.65 + + diff --git a/docs/source/user/tutorials.rst b/docs/source/user/tutorials.rst index a8db6201..e3255b13 100644 --- a/docs/source/user/tutorials.rst +++ b/docs/source/user/tutorials.rst @@ -7,5 +7,6 @@ 语法样例 指南样例 <../tutorials/tutorial_0_xxxx> + 文本分类样例 <../tutorials/tutorial_1_batcher_loss_optimizer>