diff --git a/docs/source/tutorials/tutorial_3_embedding.rst b/docs/source/tutorials/tutorial_3_embedding.rst index 4f7dc38d..5e0a9107 100644 --- a/docs/source/tutorials/tutorial_3_embedding.rst +++ b/docs/source/tutorials/tutorial_3_embedding.rst @@ -1,3 +1,214 @@ -=================== -Embedding 教程 -=================== \ No newline at end of file +========================================= +使用Embedding模块将文本转成向量 +========================================= + +这一部分是一个关于在fastNLP当中使用embedding的教程。 + +教程目录： + + - `Part I: embedding介绍`_ + - `Part II: 使用随机初始化的embedding`_ + - `Part III: 使用预训练的静态embedding`_ + - `Part IV: 使用预训练的Contextual Embedding(ELMo & BERT)`_ + - `Part V: 使用character-level的embedding`_ + - `Part VI: 叠加使用多个embedding`_ + + + + +--------------------------------------- +Part I: embedding介绍 +--------------------------------------- + +与torch.nn.Embedding类似，fastNLP的embedding接受的输入是一个被index好的序列，输出的内容是这个序列的embedding结果。 + +fastNLP的embedding包括了预训练embedding和随机初始化embedding。 + + +--------------------------------------- +Part II: 使用随机初始化的embedding +--------------------------------------- + +使用随机初始化的embedding参见 :class:`~fastNLP.modules.encoder.embedding.Embedding` 。 + +可以传入词表大小和embedding维度： + +.. code-block:: python + + embed = Embedding(10000, 50) + +也可以传入一个初始化的参数矩阵： + +.. code-block:: python + + embed = Embedding(init_embed) + +其中的init_embed可以是torch.FloatTensor、torch.nn.Embedding或者numpy.ndarray。 + + +--------------------------------------- +Part III: 使用预训练的静态embedding +--------------------------------------- + +在使用预训练的embedding之前，需要根据数据集的内容构建一个词表 :class:`~fastNLP.core.vocabulary.Vocabulary` ，在 +预训练embedding类初始化的时候需要将这个词表作为参数传入。 + +在fastNLP中，我们提供了 :class:`~fastNLP.modules.encoder.embedding.StaticEmbedding` 这一个类。 +通过 :class:`~fastNLP.modules.encoder.embedding.StaticEmbedding` 可以加载预训练好的静态 +Embedding，例子如下： + +.. code-block:: python + + embed = StaticEmbedding(vocab, model_dir_or_name='en-glove-6b-50', requires_grad=True) + +vocab为根据数据集构建的词表，model_dir_or_name可以是一个路径，也可以是embedding模型的名称： + + 1 如果传入的是路径，那么fastNLP将会根据该路径来读取预训练的权重文件并将embedding加载进来(glove + 和word2vec类型的权重文件都支持) + + 2 如果传入的是模型名称，那么fastNLP将会根据名称查找embedding模型，如果在cache目录下找到模型则会 + 自动加载；如果找不到则会自动下载。可以通过环境变量 ``FASTNLP_CACHE_DIR`` 来自定义cache目录，如:: + + $ FASTNLP_CACHE_DIR=~/fastnlp_cache_dir python your_python_file.py + +这个命令表示fastNLP将会在 `~/fastnlp_cache_dir` 这个目录下寻找模型，找不到则会自动将模型下载到这个目录 + +目前支持的静态embedding模型有： + + ========================== ================================ + 模型名称 模型 + -------------------------- -------------------------------- + en glove.840B.300d + -------------------------- -------------------------------- + en-glove-840d-300 glove.840B.300d + -------------------------- -------------------------------- + en-glove-6b-50 glove.6B.50d + -------------------------- -------------------------------- + en-word2vec-300 谷歌word2vec 300维 + -------------------------- -------------------------------- + en-fasttext 英文fasttext 300维 + -------------------------- -------------------------------- + cn 腾讯中文词向量 200维 + -------------------------- -------------------------------- + cn-fasttext 中文fasttext 300维 + ========================== ================================ + + + +----------------------------------------------------------- +Part IV: 使用预训练的Contextual Embedding(ELMo & BERT) +----------------------------------------------------------- + +在fastNLP中，我们提供了ELMo和BERT的embedding： :class:`~fastNLP.modules.encoder.embedding.ElmoEmbedding` +和 :class:`~fastNLP.modules.encoder.embedding.BertEmbedding` 。 + +与静态embedding类似，ELMo的使用方法如下： + +.. code-block:: python + + embed = ElmoEmbedding(vocab, model_dir_or_name='small', requires_grad=False) + +目前支持的ElmoEmbedding模型有： + + ========================== ================================ + 模型名称 模型 + -------------------------- -------------------------------- + small allennlp ELMo的small + -------------------------- -------------------------------- + medium allennlp ELMo的medium + -------------------------- -------------------------------- + original allennlp ELMo的original + -------------------------- -------------------------------- + 5.5b-original allennlp ELMo的5.5B original + ========================== ================================ + +BERT-embedding的使用方法如下： + +.. code-block:: python + + embed = BertEmbedding( + vocab, model_dir_or_name='en-base-cased', requires_grad=False, layers='4,-2,-1' + ) + +其中layers变量表示需要取哪几层的encode结果。 + +目前支持的BertEmbedding模型有： + + ========================== ==================================== + 模型名称 模型 + -------------------------- ------------------------------------ + en bert-base-cased + -------------------------- ------------------------------------ + en-base-uncased bert-base-uncased + -------------------------- ------------------------------------ + en-base-cased bert-base-cased + -------------------------- ------------------------------------ + en-large-uncased bert-large-uncased + -------------------------- ------------------------------------ + en-large-cased bert-large-cased + -------------------------- ------------------------------------ + -------------------------- ------------------------------------ + en-large-cased-wwm bert-large-cased-whole-word-mask + -------------------------- ------------------------------------ + en-large-uncased-wwm bert-large-uncased-whole-word-mask + -------------------------- ------------------------------------ + en-base-cased-mrpc bert-base-cased-finetuned-mrpc + -------------------------- ------------------------------------ + -------------------------- ------------------------------------ + multilingual bert-base-multilingual-cased + -------------------------- ------------------------------------ + multilingual-base-uncased bert-base-multilingual-uncased + -------------------------- ------------------------------------ + multilingual-base-cased bert-base-multilingual-cased + ========================== ==================================== + +----------------------------------------------------- +Part V: 使用character-level的embedding +----------------------------------------------------- + +除了预训练的embedding以外，fastNLP还提供了CharEmbedding： :class:`~fastNLP.modules.encoder.embedding.CNNCharEmbedding` 和 +:class:`~fastNLP.modules.encoder.embedding.LSTMCharEmbedding` 。 + +CNNCharEmbedding的使用例子如下： + +.. code-block:: python + + embed = CNNCharEmbedding(vocab, embed_size=100, char_emb_size=50) + +这表示这个CNNCharEmbedding当中character的embedding维度大小为50，返回的embedding结果维度大小为100。 + +与CNNCharEmbedding类似，LSTMCharEmbedding的使用例子如下： + +.. code-block:: python + + embed = LSTMCharEmbedding(vocab, embed_size=100, char_emb_size=50) + +这表示这个LSTMCharEmbedding当中character的embedding维度大小为50，返回的embedding结果维度大小为100。 + + + +----------------------------------------------------- +Part VI: 叠加使用多个embedding +----------------------------------------------------- + +在fastNLP中，我们使用 :class:`~fastNLP.modules.encoder.embedding.StackEmbedding` 来叠加多个embedding + +例子如下： + +.. code-block:: python + + embed_1 = StaticEmbedding(vocab, model_dir_or_name='en-glove-6b-50', requires_grad=True) + embed_2 = StaticEmbedding(vocab, model_dir_or_name='en-word2vec-300', requires_grad=True) + + stack_embed = StackEmbedding([embed_1, embed_2]) + +StackEmbedding会把多个embedding的结果拼接起来，如上面例子的stack_embed返回的embedding维度为350维。 + +除此以外，还可以把静态embedding跟上下文相关的embedding拼接起来： + +.. code-block:: python + + elmo_embedding = ElmoEmbedding(vocab, model_dir_or_name='medium', layers='0,1,2', requires_grad=False) + glove_embedding = StaticEmbedding(vocab, model_dir_or_name='en-glove-6b-50', requires_grad=True) + + stack_embed = StackEmbedding([elmo_embedding, glove_embedding]) diff --git a/docs/source/tutorials/tutorial_4_loss_optimizer.rst b/docs/source/tutorials/tutorial_4_loss_optimizer.rst index 6a5605e7..04b4833b 100644 --- a/docs/source/tutorials/tutorial_4_loss_optimizer.rst +++ b/docs/source/tutorials/tutorial_4_loss_optimizer.rst @@ -3,7 +3,7 @@ Loss 和 optimizer 教程 ———— 以文本分类为例 ============================================================================== -我们使用和 :doc:`/user/quickstart` 中一样的任务来进行详细的介绍。给出一段评价性文字，预测其情感倾向是积极（label=1）、消极（label=0）还是中性（label=2），使用 :class:`~fastNLP.Trainer` 和 :class:`~fastNLP.Tester` 来进行快速训练和测试，损失函数之前的内容与 :doc:`/tutorials/tutorial_8_batch` 中的完全一样，如已经阅读过可以跳过。 +我们使用和 :doc:`/user/quickstart` 中一样的任务来进行详细的介绍。给出一段评价性文字，预测其情感倾向是积极（label=1）、消极（label=0）还是中性（label=2），使用 :class:`~fastNLP.Trainer` 和 :class:`~fastNLP.Tester` 来进行快速训练和测试，损失函数之前的内容与 :doc:`/tutorials/tutorial_5_datasetiter` 中的完全一样，如已经阅读过可以跳过。 -------------- 数据处理 @@ -196,7 +196,7 @@ Vocabulary 的使用 快速训练 现在我们可以导入 fastNLP 内置的文本分类模型 :class:`~fastNLP.models.CNNText` ，并使用 :class:`~fastNLP.Trainer` 进行训练， - 除了使用 :class:`~fastNLP.Trainer`进行训练，我们也可以通过使用 :class:`~fastNLP.Batch` 来编写自己的训练过程，具体见 :doc:`/tutorials/tutorial_8_batch` + 除了使用 :class:`~fastNLP.Trainer`进行训练，我们也可以通过使用 :class:`~fastNLP.DataSetIter` 来编写自己的训练过程，具体见 :doc:`/tutorials/tutorial_5_datasetiter` .. code-block:: python diff --git a/docs/source/tutorials/tutorial_8_batch.rst b/docs/source/tutorials/tutorial_5_datasetiter.rst similarity index 91% rename from docs/source/tutorials/tutorial_8_batch.rst rename to docs/source/tutorials/tutorial_5_datasetiter.rst index 2abb963a..8188d928 100644 --- a/docs/source/tutorials/tutorial_8_batch.rst +++ b/docs/source/tutorials/tutorial_5_datasetiter.rst @@ -1,9 +1,9 @@  ============================================================================== -Batch 教程 ———— 以文本分类为例 +DataSetIter 教程 ———— 以文本分类为例 ============================================================================== -我们使用和 :doc:`/user/quickstart` 中一样的任务来进行详细的介绍。给出一段评价性文字，预测其情感倾向是积极（label=1）、消极（label=0）还是中性（label=2），使用:class:`~fastNLP.Batch` 类来编写自己的训练过程。自己编写训练过程之前的内容与 :doc:`/tutorials/tutorial_4_loss_optimizer` 中的完全一样，如已经阅读过可以跳过。 +我们使用和 :doc:`/user/quickstart` 中一样的任务来进行详细的介绍。给出一段评价性文字，预测其情感倾向是积极（label=1）、消极（label=0）还是中性（label=2），使用:class:`~fastNLP.DataSetIter` 类来编写自己的训练过程。自己编写训练过程之前的内容与 :doc:`/tutorials/tutorial_4_loss_optimizer` 中的完全一样，如已经阅读过可以跳过。 -------------- 数据处理 @@ -160,11 +160,11 @@ Vocabulary 的使用 自己编写训练过程 -------------------------- 如果你想用类似 PyTorch 的使用方法，自己编写训练过程，你可以参考下面这段代码。 - 其中使用了 fastNLP 提供的 :class:`~fastNLP.Batch` 来获得小批量训练的小批量数据， - 使用 :class:`~fastNLP.BucketSampler` 做为 :class:`~fastNLP.Batch` 的参数来选择采样的方式。 + 其中使用了 fastNLP 提供的 :class:`~fastNLP.DataSetIter` 来获得小批量训练的小批量数据， + 使用 :class:`~fastNLP.BucketSampler` 做为 :class:`~fastNLP.DataSetIter` 的参数来选择采样的方式。 -Batch - fastNLP定义的 :class:`~fastNLP.Batch` 类在初始化时传入的参数有： +DataSetIter + fastNLP定义的 :class:`~fastNLP.DataSetIter` 类，用于定义一个batch，并实现batch的多种功能，在初始化时传入的参数有： * dataset: :class:`~fastNLP.DataSet` 对象, 数据集 * batch_size: 取出的batch大小 @@ -179,12 +179,12 @@ sampler * SequentialSampler： 顺序取出元素的采样器【无初始化参数】 * RandomSampler：随机化取元素的采样器【无初始化参数】 -以下代码使用BucketSampler作为Batch初始化的输入，运用Batch自己写训练程序 +以下代码使用BucketSampler作为:class:`~fastNLP.DataSetIter`初始化的输入，运用:class:`~fastNLP.DataSetIter`自己写训练程序 .. code-block:: python from fastNLP import BucketSampler - from fastNLP import Batch + from fastNLP import DataSetIter from fastNLP.models import CNNText from fastNLP import Tester import torch @@ -201,7 +201,7 @@ sampler # 定义一个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) + train_batch = DataSetIter(batch_size=batch_size, dataset=data, sampler=train_sampler) start_time = time.time() print("-"*5+"start training"+"-"*5) diff --git a/docs/source/tutorials/tutorial_5_modules_models.rst b/docs/source/tutorials/tutorial_7_modules_models.rst similarity index 100% rename from docs/source/tutorials/tutorial_5_modules_models.rst rename to docs/source/tutorials/tutorial_7_modules_models.rst diff --git a/docs/source/tutorials/tutorial_7_metrics.rst b/docs/source/tutorials/tutorial_8_metrics.rst similarity index 100% rename from docs/source/tutorials/tutorial_7_metrics.rst rename to docs/source/tutorials/tutorial_8_metrics.rst diff --git a/docs/source/user/installation.rst b/docs/source/user/installation.rst index c218b3e1..42ea402c 100644 --- a/docs/source/user/installation.rst +++ b/docs/source/user/installation.rst @@ -7,10 +7,12 @@ fastNLP 依赖如下包:: - torch>=0.4.0 - numpy - tqdm - nltk + numpy>=1.14.2 + torch>=1.0.0 + tqdm>=4.28.1 + nltk>=3.4.1 + requests + spacy 其中torch的安装可能与操作系统及 CUDA 的版本相关，请参见 `PyTorch 官网 `_ 。 在依赖包安装完成的情况，您可以在命令行执行如下指令完成安装 @@ -18,3 +20,4 @@ fastNLP 依赖如下包:: .. code:: shell >>> pip install fastNLP + >>> python -m spacy download en diff --git a/docs/source/user/tutorials.rst b/docs/source/user/tutorials.rst index 516d8ee5..9fa10472 100644 --- a/docs/source/user/tutorials.rst +++ b/docs/source/user/tutorials.rst @@ -1,15 +1,17 @@ -=============== -详细指南 -=============== +=================== +fastNLP详细使用教程 +=================== .. toctree:: :maxdepth: 1 - 1. 数据格式及预处理教程 - 2. 数据集加载教程 - 3. Embedding 教程 - 4. Loss, optimizer 教程 - 5. Modules 和 models 教程 - 6. 序列标注教程 - 7. Metric 教程 + 1. 使用DataSet预处理文本 + 2. 使用DataSetLoader加载数据集 + 3. 使用Embedding模块将文本转成向量 + 4. 动手实现一个文本分类器I-使用Trainer和Tester快速训练和测试 + 5. 动手实现一个文本分类器II-使用DataSetIter实现自定义训练过程 + 6. 快速实现序列标注模型 + 7. 使用Modules和Models快速搭建自定义模型 + 8. 使用Metric快速评测你的模型 + 9. 使用Callback自定义你的训练过程