add embedding tutorial

docs/source/tutorials/tutorial_3_embedding.rst

@@ -1,3 +1,214 @@
-===================
-Embedding 教程
-===================
+=========================================
+使用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])

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
 

docs/source/tutorials/tutorial_8_batch.rst → 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)

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 官网 <https://pytorch.org/get-started/locally/>`_ 。
 在依赖包安装完成的情况，您可以在命令行执行如下指令完成安装
@@ -18,3 +20,4 @@ fastNLP 依赖如下包::
 ..  code:: shell
 
    >>> pip install fastNLP
+   >>> python -m spacy download en

docs/source/user/tutorials.rst

@@ -1,15 +1,17 @@
-===============
-详细指南
-===============
+===================
+fastNLP详细使用教程
+===================
 
 .. toctree::
    :maxdepth: 1
 
-   1. 数据格式及预处理教程 </tutorials/tutorial_1_data_preprocess>
-   2. 数据集加载教程 </tutorials/tutorial_2_load_dataset>
-   3. Embedding 教程 </tutorials/tutorial_3_embedding>
-   4. Loss, optimizer 教程 </tutorials/tutorial_4_loss_optimizer>
-   5. Modules 和 models 教程 </tutorials/tutorial_5_modules_models>
-   6. 序列标注教程 </tutorials/tutorial_6_seq_labeling>
-   7. Metric 教程 </tutorials/tutorial_7_metrics>
+   1. 使用DataSet预处理文本 </tutorials/tutorial_1_data_preprocess>
+   2. 使用DataSetLoader加载数据集 </tutorials/tutorial_2_load_dataset>
+   3. 使用Embedding模块将文本转成向量 </tutorials/tutorial_3_embedding>
+   4. 动手实现一个文本分类器I-使用Trainer和Tester快速训练和测试 </tutorials/tutorial_4_loss_optimizer>
+   5. 动手实现一个文本分类器II-使用DataSetIter实现自定义训练过程 </tutorials/tutorial_5_datasetiter>
+   6. 快速实现序列标注模型 </tutorials/tutorial_6_seq_labeling>
+   7. 使用Modules和Models快速搭建自定义模型 </tutorials/tutorial_7_modules_models>
+   8. 使用Metric快速评测你的模型 </tutorials/tutorial_8_metrics>
+   9. 使用Callback自定义你的训练过程 </tutorials/tutorial_9_callback>