Merge pull request #3 from fastnlp/dev0.5.0

Dev0.5.0

.travis.yml

@@ -1,6 +1,9 @@
 language: python
 python:
   - "3.6"
+
+env:
+  - TRAVIS=1
 # command to install dependencies
 install:
   - pip install --quiet -r requirements.txt

README.md

@@ -6,50 +6,70 @@
 ![Hex.pm](https://img.shields.io/hexpm/l/plug.svg)
 [![Documentation Status](https://readthedocs.org/projects/fastnlp/badge/?version=latest)](http://fastnlp.readthedocs.io/?badge=latest)
 
-fastNLP 是一款轻量级的 NLP 处理套件。你既可以使用它快速地完成一个序列标注（[NER](reproduction/seqence_labelling/ner/)、POS-Tagging等）、中文分词、文本分类、[Matching](reproduction/matching/)、指代消解、摘要等任务； 也可以使用它构建许多复杂的网络模型，进行科研。它具有如下的特性：
+fastNLP 是一款轻量级的 NLP 工具包。你既可以使用它快速地完成一个序列标注（[NER](reproduction/seqence_labelling/ner)、POS-Tagging等）、中文分词、[文本分类](reproduction/text_classification)、[Matching](reproduction/matching)、[指代消解](reproduction/coreference_resolution)、[摘要](reproduction/Summarization)等任务； 也可以使用它快速构建许多复杂的网络模型，进行科研。它具有如下的特性：
 
-- 统一的Tabular式数据容器，让数据预处理过程简洁明了。内置多种数据集的DataSet Loader，省去预处理代码;
+- 统一的Tabular式数据容器，让数据预处理过程简洁明了。内置多种数据集的Loader和Pipe，省去预处理代码;
 - 多种训练、测试组件，例如训练器Trainer；测试器Tester；以及各种评测metrics等等;
-- 各种方便的NLP工具，例如预处理embedding加载（包括EMLo和BERT）; 中间数据cache等;
-- 详尽的中文[文档](https://fastnlp.readthedocs.io/)、教程以供查阅;
+- 各种方便的NLP工具，例如预处理embedding加载（包括ELMo和BERT）; 中间数据cache等;
+- 部分[数据集与预训练模型](https://docs.qq.com/sheet/DVnpkTnF6VW9UeXdh?c=A1A0A0)的自动下载
+- 详尽的中文[文档](https://fastnlp.readthedocs.io/)、[教程](https://fastnlp.readthedocs.io/zh/latest/user/tutorials.html)以供查阅;
 - 提供诸多高级模块，例如Variational LSTM, Transformer, CRF等;
-- 在序列标注、中文分词、文本分类、Matching、指代消解、摘要等任务上封装了各种模型可供直接使用; [详细链接](reproduction/)
+- 在序列标注、中文分词、文本分类、Matching、指代消解、摘要等任务上封装了各种模型可供直接使用，详细内容见 [reproduction](reproduction) 部分;
 - 便捷且具有扩展性的训练器; 提供多种内置callback函数，方便实验记录、异常捕获等。
 
 
 ## 安装指南
 
-fastNLP 依赖如下包:
+fastNLP 依赖以下包:
 
 + numpy>=1.14.2
 + torch>=1.0.0
 + tqdm>=4.28.1
 + nltk>=3.4.1
 + requests
++ spacy
 
 其中torch的安装可能与操作系统及 CUDA 的版本相关，请参见 [PyTorch 官网](https://pytorch.org/) 。 
 在依赖包安装完成后，您可以在命令行执行如下指令完成安装
 
 ```shell
 pip install fastNLP
+python -m spacy download en
 ```
 
+目前使用pypi安装fastNLP的版本是0.4.1，有较多功能仍未更新，最新内容以master分支为准。
+fastNLP0.5.0版本将在近期推出，请密切关注。
 
-## 参考资源
 
-- [文档](https://fastnlp.readthedocs.io/zh/latest/)
-- [源码](https://github.com/fastnlp/fastNLP)
+## fastNLP教程
+
+- [0. 快速入门](https://fastnlp.readthedocs.io/zh/latest/user/quickstart.html)
+- [1. 使用DataSet预处理文本](https://fastnlp.readthedocs.io/zh/latest/tutorials/tutorial_1_data_preprocess.html)
+- [2. 使用Loader和Pipe加载并处理数据集](https://fastnlp.readthedocs.io/zh/latest/tutorials/tutorial_2_load_dataset.html)
+- [3. 使用Embedding模块将文本转成向量](https://fastnlp.readthedocs.io/zh/latest/tutorials/tutorial_3_embedding.html)
+- [4. 动手实现一个文本分类器I-使用Trainer和Tester快速训练和测试](https://fastnlp.readthedocs.io/zh/latest/tutorials/tutorial_4_loss_optimizer.html)
+- [5. 动手实现一个文本分类器II-使用DataSetIter实现自定义训练过程](https://fastnlp.readthedocs.io/zh/latest/tutorials/tutorial_5_datasetiter.html)
+- [6. 快速实现序列标注模型](https://fastnlp.readthedocs.io/zh/latest/tutorials/tutorial_6_seq_labeling.html)
+- [7. 使用Modules和Models快速搭建自定义模型](https://fastnlp.readthedocs.io/zh/latest/tutorials/tutorial_7_modules_models.html)
+- [8. 使用Metric快速评测你的模型](https://fastnlp.readthedocs.io/zh/latest/tutorials/tutorial_8_metrics.html)
+- [9. 使用Callback自定义你的训练过程](https://fastnlp.readthedocs.io/zh/latest/tutorials/tutorial_9_callback.html)
+- [10. 使用fitlog 辅助 fastNLP 进行科研](https://fastnlp.readthedocs.io/zh/latest/tutorials/tutorial_10_fitlog.html)
 
 
 
 ## 内置组件
 
-大部分用于的 NLP 任务神经网络都可以看做由编码（encoder）、聚合（aggregator）、解码（decoder）三种模块组成。
+大部分用于的 NLP 任务神经网络都可以看做由词嵌入（embeddings）和两种模块：编码器（encoder）、解码器（decoder）组成。
+
+以文本分类任务为例，下图展示了一个BiLSTM+Attention实现文本分类器的模型流程图：
 
 
 ![](./docs/source/figures/text_classification.png)
 
-fastNLP 在 modules 模块中内置了三种模块的诸多组件，可以帮助用户快速搭建自己所需的网络。 三种模块的功能和常见组件如下:
+fastNLP 在 embeddings 模块中内置了几种不同的embedding：静态embedding（GloVe、word2vec）、上下文相关embedding
+（ELMo、BERT）、字符embedding（基于CNN或者LSTM的CharEmbedding）
+
+与此同时，fastNLP 在 modules 模块中内置了两种模块的诸多组件，可以帮助用户快速搭建自己所需的网络。 两种模块的功能和常见组件如下:
 
 <table>
 <tr>
@@ -59,32 +79,20 @@ fastNLP 在 modules 模块中内置了三种模块的诸多组件，可以帮助
 </tr>
 <tr>
     <td> encoder </td>
-    <td> 将输入编码为具有具 有表示能力的向量 </td>
+    <td> 将输入编码为具有具有表示能力的向量 </td>
     <td> embedding, RNN, CNN, transformer
 </tr>
-<tr>
-    <td> aggregator </td>
-    <td> 从多个向量中聚合信息 </td>
-    <td> self-attention, max-pooling </td>
-</tr>
 <tr>
     <td> decoder </td>
-    <td> 将具有某种表示意义的 向量解码为需要的输出 形式 </td>
+    <td> 将具有某种表示意义的向量解码为需要的输出形式 </td>
     <td> MLP, CRF </td>
 </tr>
 </table>
 
 
-## 完整模型
-fastNLP 为不同的 NLP 任务实现了许多完整的模型，它们都经过了训练和测试。
-
-你可以在以下两个地方查看相关信息
-- [模型介绍](reproduction/)
-- [模型源码](fastNLP/models/)
-
 ## 项目结构
 
-![](./docs/source/figures/workflow.png)
+<img src="./docs/source/figures/workflow.png" width="60%" height="60%">
 
 fastNLP的大致工作流程如上图所示，而项目结构如下：
 
@@ -105,9 +113,13 @@ fastNLP的大致工作流程如上图所示，而项目结构如下：
     <td><b> fastNLP.modules </b></td>
     <td> 实现了用于搭建神经网络模型的诸多组件 </td>
 </tr>
+<tr>
+    <td><b> fastNLP.embeddings </b></td>
+    <td> 实现了将序列index转为向量序列的功能，包括读取预训练embedding等 </td>
+</tr>
 <tr>
     <td><b> fastNLP.io </b></td>
-    <td> 实现了读写功能，包括数据读入，模型读写等 </td>
+    <td> 实现了读写功能，包括数据读入与预处理，模型读写，自动下载等 </td>
 </tr>
 </table>
 

docs/Makefile

@@ -14,11 +14,14 @@ help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 apidoc:
-	$(SPHINXAPIDOC) -efM -o source ../$(SPHINXPROJ)
+	$(SPHINXAPIDOC) -efM -o source ../$(SPHINXPROJ) && python3 format.py
 
 server:
 	cd build/html && python -m http.server
 
+dev:
+	rm -rf build && make html && make server
+
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new

docs/README.md

@@ -0,0 +1,41 @@
+# 快速入门 fastNLP 文档编写
+
+本教程为 fastNLP 文档编写者创建，文档编写者包括合作开发人员和文档维护人员。您在一般情况下属于前者，
+只需要了解整个框架的部分内容即可。
+
+## 合作开发人员
+
+FastNLP的文档使用基于[reStructuredText标记语言](http://docutils.sourceforge.net/rst.html)的
+[Sphinx](http://sphinx.pocoo.org/)工具生成，由[Read the Docs](https://readthedocs.org/)网站自动维护生成。
+一般开发者只要编写符合reStructuredText语法规范的文档并通过[PR](https://help.github.com/en/articles/about-pull-requests)，
+就可以为fastNLP的文档贡献一份力量。
+
+如果你想在本地编译文档并进行大段文档的编写，您需要安装Sphinx工具以及sphinx-rtd-theme主题：
+```bash
+fastNLP/docs> pip install sphinx
+fastNLP/docs> pip install sphinx-rtd-theme
+```
+然后在本目录下执行 `make dev` 命令。该命令只支持Linux和MacOS系统，期望看到如下输出：
+```bash
+fastNLP/docs> make dev
+rm -rf build/html && make html && make server
+Running Sphinx v1.5.6
+making output directory...
+......
+Build finished. The HTML pages are in build/html.
+cd build/html && python -m http.server
+Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
+```
+现在您浏览器访问 http://localhost:8000/ 查看文档。如果你在远程服务器尚进行工作，则访问地址为 http://{服务器的ip地址}:8000/ 。
+但您必须保证服务器的8000端口是开放的。如果您的电脑或远程服务器的8000端口被占用，程序会顺延使用8001、8002……等端口。
+当你结束访问时，您可以使用Control(Ctrl) + C 来结束进程。
+
+我们在[这里](./source/user/example.rst)列举了fastNLP文档经常用到的reStructuredText语法（网页查看请结合Raw模式），
+您可以通过阅读它进行快速上手。FastNLP大部分的文档都是写在代码中通过Sphinx工具进行抽取生成的，
+您还可以参考这篇[未完成的文章](./source/user/docs_in_code.rst)了解代码内文档编写的规范。
+
+## 文档维护人员
+
+文档维护人员需要了解 Makefile 中全部命令的含义，并了解到目前的文档结构
+是在 sphinx-apidoc 自动抽取的基础上进行手动修改得到的。
+文档维护人员应进一步提升整个框架的自动化程度，并监督合作开发人员不要破坏文档项目的整体结构。

docs/count.py

@@ -0,0 +1,107 @@
+import inspect
+import os
+import sys
+
+
+def _colored_string(string: str, color: str or int) -> str:
+    """在终端中显示一串有颜色的文字
+    :param string: 在终端中显示的文字
+    :param color: 文字的颜色
+    :return:
+    """
+    if isinstance(color, str):
+        color = {
+            "black": 30, "Black": 30, "BLACK": 30,
+            "red": 31, "Red": 31, "RED": 31,
+            "green": 32, "Green": 32, "GREEN": 32,
+            "yellow": 33, "Yellow": 33, "YELLOW": 33,
+            "blue": 34, "Blue": 34, "BLUE": 34,
+            "purple": 35, "Purple": 35, "PURPLE": 35,
+            "cyan": 36, "Cyan": 36, "CYAN": 36,
+            "white": 37, "White": 37, "WHITE": 37
+        }[color]
+    return "\033[%dm%s\033[0m" % (color, string)
+
+
+def find_all_modules():
+    modules = {}
+    children = {}
+    to_doc = set()
+    root = '../fastNLP'
+    for path, dirs, files in os.walk(root):
+        for file in files:
+            if file.endswith('.py'):
+                name = ".".join(path.split('/')[1:])
+                if file.split('.')[0] != "__init__":
+                    name = name + '.' + file.split('.')[0]
+                __import__(name)
+                m = sys.modules[name]
+                modules[name] = m
+                try:
+                    m.__all__
+                except:
+                    print(name, "__all__ missing")
+                    continue
+                if m.__doc__ is None:
+                    print(name, "__doc__ missing")
+                    continue
+                if "undocumented" not in m.__doc__:
+                    to_doc.add(name)
+    for module in to_doc:
+        t = ".".join(module.split('.')[:-1])
+        if t in to_doc:
+            if t not in children:
+                children[t] = set()
+            children[t].add(module)
+    for m in children:
+        children[m] = sorted(children[m])
+    return modules, to_doc, children
+
+
+def create_rst_file(modules, name, children):
+    m = modules[name]
+    with open("./source/" + name + ".rst", "w") as fout:
+        t = "=" * len(name)
+        fout.write(name + "\n")
+        fout.write(t + "\n")
+        fout.write("\n")
+        fout.write(".. automodule:: " + name + "\n")
+        if len(m.__all__) > 0:
+            fout.write("   :members: " + ", ".join(m.__all__) + "\n")
+            fout.write("   :inherited-members:\n")
+        fout.write("\n")
+        if name in children:
+            fout.write("子模块\n------\n\n.. toctree::\n\n")
+            for module in children[name]:
+                fout.write("   " + module + "\n")
+
+
+def check_file(m, name):
+    for item, obj in inspect.getmembers(m):
+        if inspect.isclass(obj) and obj.__module__ == name:
+            print(obj)
+        if inspect.isfunction(obj) and obj.__module__ == name:
+            print("FUNC", obj)
+
+
+def check_files(modules):
+    for name in sorted(modules.keys()):
+        if name == 'fastNLP.core.utils':
+            check_file(modules[name], name)
+
+
+def main():
+    print(_colored_string('Getting modules...', "Blue"))
+    modules, to_doc, children = find_all_modules()
+    print(_colored_string('Done!', "Green"))
+    print(_colored_string('Creating rst files...', "Blue"))
+    for name in to_doc:
+        create_rst_file(modules, name, children)
+    print(_colored_string('Done!', "Green"))
+    print(_colored_string('Checking all files...', "Blue"))
+    check_files(modules)
+    print(_colored_string('Done!', "Green"))
+
+
+if __name__ == "__main__":
+    main()

docs/make.bat

@@ -1,36 +0,0 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
-)
-set SOURCEDIR=source
-set BUILDDIR=build
-set SPHINXPROJ=fastNLP
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
-	exit /b 1
-)
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
-
-:end
-popd

docs/quick_tutorial.md

@@ -1,2 +0,0 @@
-# FastNLP Quick Tutorial
-

docs/source/conf.py

@@ -24,9 +24,9 @@ copyright = '2018, xpqiu'
 author = 'xpqiu'
 
 # The short X.Y version
-version = '0.4'
+version = '0.4.5'
 # The full version, including alpha/beta/rc tags
-release = '0.4'
+release = '0.4.5'
 
 # -- General configuration ---------------------------------------------------
 
@@ -48,12 +48,14 @@ extensions = [
 autodoc_default_options = {
     'member-order': 'bysource',
     'special-members': '__init__',
-    'undoc-members': True,
+    'undoc-members': False,
 }
 
+autoclass_content = "class"
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
-
+# template_bridge
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
@@ -113,7 +115,7 @@ html_static_path = ['_static']
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'fastNLPdoc'
+htmlhelp_basename = 'fastNLP doc'
 
 # -- Options for LaTeX output ------------------------------------------------
 

docs/source/fastNLP.core.batch.rst

@@ -2,6 +2,6 @@ fastNLP.core.batch
 ==================
 
 .. automodule:: fastNLP.core.batch
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: BatchIter, DataSetIter, TorchLoaderIter
+   :inherited-members:
+

docs/source/fastNLP.core.callback.rst

@@ -2,6 +2,6 @@ fastNLP.core.callback
 =====================
 
 .. automodule:: fastNLP.core.callback
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: Callback, GradientClipCallback, EarlyStopCallback, FitlogCallback, EvaluateCallback, LRScheduler, ControlC, LRFinder, TensorboardCallback, WarmupCallback, SaveModelCallback, EchoCallback, TesterCallback, CallbackException, EarlyStopError
+   :inherited-members:
+

docs/source/fastNLP.core.const.rst

@@ -2,6 +2,6 @@ fastNLP.core.const
 ==================
 
 .. automodule:: fastNLP.core.const
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: Const
+   :inherited-members:
+

docs/source/fastNLP.core.dataset.rst

@@ -2,6 +2,6 @@ fastNLP.core.dataset
 ====================
 
 .. automodule:: fastNLP.core.dataset
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: DataSet
+   :inherited-members:
+

docs/source/fastNLP.core.field.rst

@@ -2,6 +2,6 @@ fastNLP.core.field
 ==================
 
 .. automodule:: fastNLP.core.field
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: Padder, AutoPadder, EngChar2DPadder
+   :inherited-members:
+

docs/source/fastNLP.core.instance.rst

@@ -2,6 +2,6 @@ fastNLP.core.instance
 =====================
 
 .. automodule:: fastNLP.core.instance
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: Instance
+   :inherited-members:
+

docs/source/fastNLP.core.losses.rst

@@ -2,6 +2,6 @@ fastNLP.core.losses
 ===================
 
 .. automodule:: fastNLP.core.losses
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: LossBase, LossFunc, LossInForward, CrossEntropyLoss, BCELoss, L1Loss, NLLLoss
+   :inherited-members:
+

docs/source/fastNLP.core.metrics.rst

@@ -2,6 +2,6 @@ fastNLP.core.metrics
 ====================
 
 .. automodule:: fastNLP.core.metrics
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: MetricBase, AccuracyMetric, SpanFPreRecMetric, ExtractiveQAMetric
+   :inherited-members:
+

docs/source/fastNLP.core.optimizer.rst

@@ -2,6 +2,6 @@ fastNLP.core.optimizer
 ======================
 
 .. automodule:: fastNLP.core.optimizer
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: Optimizer, SGD, Adam, AdamW
+   :inherited-members:
+

docs/source/fastNLP.core.rst

@@ -2,15 +2,13 @@ fastNLP.core
 ============
 
 .. automodule:: fastNLP.core
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: DataSet, Instance, FieldArray, Padder, AutoPadder, EngChar2DPadder, Vocabulary, DataSetIter, BatchIter, TorchLoaderIter, Const, Tester, Trainer, cache_results, seq_len_to_mask, get_seq_len, logger, Callback, GradientClipCallback, EarlyStopCallback, FitlogCallback, EvaluateCallback, LRScheduler, ControlC, LRFinder, TensorboardCallback, WarmupCallback, SaveModelCallback, EchoCallback, TesterCallback, CallbackException, EarlyStopError, LossFunc, CrossEntropyLoss, L1Loss, BCELoss, NLLLoss, LossInForward, AccuracyMetric, SpanFPreRecMetric, ExtractiveQAMetric, Optimizer, SGD, Adam, AdamW, SequentialSampler, BucketSampler, RandomSampler, Sampler
+   :inherited-members:
 
 子模块
-----------
+------
 
 .. toctree::
-   :titlesonly:
 
    fastNLP.core.batch
    fastNLP.core.callback
@@ -26,4 +24,3 @@ fastNLP.core
    fastNLP.core.trainer
    fastNLP.core.utils
    fastNLP.core.vocabulary
-

docs/source/fastNLP.core.sampler.rst

@@ -2,6 +2,6 @@ fastNLP.core.sampler
 ====================
 
 .. automodule:: fastNLP.core.sampler
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: Sampler, BucketSampler, SequentialSampler, RandomSampler
+   :inherited-members:
+

docs/source/fastNLP.core.tester.rst

@@ -2,6 +2,6 @@ fastNLP.core.tester
 ===================
 
 .. automodule:: fastNLP.core.tester
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: Tester
+   :inherited-members:
+

docs/source/fastNLP.core.trainer.rst

@@ -2,6 +2,6 @@ fastNLP.core.trainer
 ====================
 
 .. automodule:: fastNLP.core.trainer
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: Trainer
+   :inherited-members:
+

docs/source/fastNLP.core.utils.rst

@@ -2,6 +2,6 @@ fastNLP.core.utils
 ==================
 
 .. automodule:: fastNLP.core.utils
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: cache_results, seq_len_to_mask, get_seq_len
+   :inherited-members:
+

docs/source/fastNLP.core.vocabulary.rst

@@ -2,6 +2,6 @@ fastNLP.core.vocabulary
 =======================
 
 .. automodule:: fastNLP.core.vocabulary
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: Vocabulary, VocabularyOption
+   :inherited-members:
+

docs/source/fastNLP.embeddings.bert_embedding.rst

@@ -0,0 +1,7 @@
+fastNLP.embeddings.bert_embedding
+=================================
+
+.. automodule:: fastNLP.embeddings.bert_embedding
+   :members: BertEmbedding, BertWordPieceEncoder
+   :inherited-members:
+

docs/source/fastNLP.embeddings.char_embedding.rst

@@ -0,0 +1,7 @@
+fastNLP.embeddings.char_embedding
+=================================
+
+.. automodule:: fastNLP.embeddings.char_embedding
+   :members: CNNCharEmbedding, LSTMCharEmbedding
+   :inherited-members:
+

docs/source/fastNLP.embeddings.contextual_embedding.rst

@@ -0,0 +1,7 @@
+fastNLP.embeddings.contextual_embedding
+=======================================
+
+.. automodule:: fastNLP.embeddings.contextual_embedding
+   :members: ContextualEmbedding
+   :inherited-members:
+

docs/source/fastNLP.embeddings.elmo_embedding.rst

@@ -0,0 +1,7 @@
+fastNLP.embeddings.elmo_embedding
+=================================
+
+.. automodule:: fastNLP.embeddings.elmo_embedding
+   :members: ElmoEmbedding
+   :inherited-members:
+

docs/source/fastNLP.embeddings.embedding.rst

@@ -0,0 +1,7 @@
+fastNLP.embeddings.embedding
+============================
+
+.. automodule:: fastNLP.embeddings.embedding
+   :members: Embedding, TokenEmbedding
+   :inherited-members:
+

docs/source/fastNLP.embeddings.rst

@@ -0,0 +1,20 @@
+fastNLP.embeddings
+==================
+
+.. automodule:: fastNLP.embeddings
+   :members: Embedding, TokenEmbedding, StaticEmbedding, ElmoEmbedding, BertEmbedding, BertWordPieceEncoder, StackEmbedding, LSTMCharEmbedding, CNNCharEmbedding, get_embeddings
+   :inherited-members:
+
+子模块
+------
+
+.. toctree::
+
+   fastNLP.embeddings.bert_embedding
+   fastNLP.embeddings.char_embedding
+   fastNLP.embeddings.contextual_embedding
+   fastNLP.embeddings.elmo_embedding
+   fastNLP.embeddings.embedding
+   fastNLP.embeddings.stack_embedding
+   fastNLP.embeddings.static_embedding
+   fastNLP.embeddings.utils

docs/source/fastNLP.embeddings.stack_embedding.rst

@@ -0,0 +1,7 @@
+fastNLP.embeddings.stack_embedding
+==================================
+
+.. automodule:: fastNLP.embeddings.stack_embedding
+   :members: StackEmbedding
+   :inherited-members:
+

docs/source/fastNLP.embeddings.static_embedding.rst

@@ -0,0 +1,7 @@
+fastNLP.embeddings.static_embedding
+===================================
+
+.. automodule:: fastNLP.embeddings.static_embedding
+   :members: StaticEmbedding
+   :inherited-members:
+

docs/source/fastNLP.embeddings.utils.rst

@@ -0,0 +1,7 @@
+fastNLP.embeddings.utils
+========================
+
+.. automodule:: fastNLP.embeddings.utils
+   :members: get_embeddings
+   :inherited-members:
+

docs/source/fastNLP.io.base_loader.rst

@@ -1,7 +0,0 @@
-fastNLP.io.base\_loader
-=======================
-
-.. automodule:: fastNLP.io.base_loader
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/source/fastNLP.io.data_bundle.rst

@@ -0,0 +1,7 @@
+fastNLP.io.data_bundle
+======================
+
+.. automodule:: fastNLP.io.data_bundle
+   :members: DataBundle
+   :inherited-members:
+

docs/source/fastNLP.io.dataset_loader.rst

@@ -1,7 +1,6 @@
-fastNLP.io.dataset\_loader
-==========================
+fastNLP.io.dataset_loader
+=========================
 
 .. automodule:: fastNLP.io.dataset_loader
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: CSVLoader, JsonLoader
+

docs/source/fastNLP.io.embed_loader.rst

@@ -1,7 +1,7 @@
-fastNLP.io.embed\_loader
-========================
+fastNLP.io.embed_loader
+=======================
 
 .. automodule:: fastNLP.io.embed_loader
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: EmbedLoader, EmbeddingOption
+   :inherited-members:
+

docs/source/fastNLP.io.file_utils.rst

@@ -0,0 +1,7 @@
+fastNLP.io.file_utils
+=====================
+
+.. automodule:: fastNLP.io.file_utils
+   :members: cached_path, get_filepath, get_cache_path, split_filename_suffix, get_from_cache
+   :inherited-members:
+

docs/source/fastNLP.io.loader.rst

@@ -0,0 +1,7 @@
+fastNLP.io.loader
+=================
+
+.. automodule:: fastNLP.io.loader
+   :members: Loader, YelpLoader, YelpFullLoader, YelpPolarityLoader, IMDBLoader, SSTLoader, SST2Loader, ConllLoader, Conll2003Loader, Conll2003NERLoader, OntoNotesNERLoader, CTBLoader, MsraNERLoader, PeopleDailyNERLoader, WeiboNERLoader, CSVLoader, JsonLoader, CWSLoader, MNLILoader, QuoraLoader, SNLILoader, QNLILoader, RTELoader
+   :inherited-members:
+

docs/source/fastNLP.io.model_io.rst

@@ -1,7 +1,7 @@
-fastNLP.io.model\_io
-====================
+fastNLP.io.model_io
+===================
 
 .. automodule:: fastNLP.io.model_io
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: ModelLoader, ModelSaver
+   :inherited-members:
+

docs/source/fastNLP.io.pipe.rst

@@ -0,0 +1,7 @@
+fastNLP.io.pipe
+===============
+
+.. automodule:: fastNLP.io.pipe
+   :members: Pipe, CWSPipe, YelpFullPipe, YelpPolarityPipe, SSTPipe, SST2Pipe, IMDBPipe, Conll2003NERPipe, OntoNotesNERPipe, MsraNERPipe, WeiboNERPipe, PeopleDailyPipe, Conll2003Pipe, MatchingBertPipe, RTEBertPipe, SNLIBertPipe, QuoraBertPipe, QNLIBertPipe, MNLIBertPipe, MatchingPipe, RTEPipe, SNLIPipe, QuoraPipe, QNLIPipe, MNLIPipe
+   :inherited-members:
+

docs/source/fastNLP.io.rst

@@ -2,18 +2,18 @@ fastNLP.io
 ==========
 
 .. automodule:: fastNLP.io
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: DataBundle, EmbedLoader, Loader, YelpLoader, YelpFullLoader, YelpPolarityLoader, IMDBLoader, SSTLoader, SST2Loader, ConllLoader, Conll2003Loader, Conll2003NERLoader, OntoNotesNERLoader, CTBLoader, MsraNERLoader, WeiboNERLoader, PeopleDailyNERLoader, CSVLoader, JsonLoader, CWSLoader, MNLILoader, QuoraLoader, SNLILoader, QNLILoader, RTELoader, Pipe, YelpFullPipe, YelpPolarityPipe, SSTPipe, SST2Pipe, IMDBPipe, Conll2003Pipe, Conll2003NERPipe, OntoNotesNERPipe, MsraNERPipe, PeopleDailyPipe, WeiboNERPipe, CWSPipe, MatchingBertPipe, RTEBertPipe, SNLIBertPipe, QuoraBertPipe, QNLIBertPipe, MNLIBertPipe, MatchingPipe, RTEPipe, SNLIPipe, QuoraPipe, QNLIPipe, MNLIPipe, ModelLoader, ModelSaver
+   :inherited-members:
 
 子模块
-----------
+------
 
 .. toctree::
-   :titlesonly:
 
-   fastNLP.io.base_loader
-   fastNLP.io.dataset_loader
+   fastNLP.io.data_bundle
    fastNLP.io.embed_loader
+   fastNLP.io.file_utils
+   fastNLP.io.loader
    fastNLP.io.model_io
-
+   fastNLP.io.pipe
+   fastNLP.io.utils

docs/source/fastNLP.io.utils.rst

@@ -0,0 +1,7 @@
+fastNLP.io.utils
+================
+
+.. automodule:: fastNLP.io.utils
+   :members: check_loader_paths
+   :inherited-members:
+

docs/source/fastNLP.models.biaffine_parser.rst

@@ -1,7 +1,7 @@
-fastNLP.models.biaffine\_parser
-===============================
+fastNLP.models.biaffine_parser
+==============================
 
 .. automodule:: fastNLP.models.biaffine_parser
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: BiaffineParser, GraphParser
+   :inherited-members:
+

docs/source/fastNLP.models.cnn_text_classification.rst

@@ -1,7 +1,7 @@
-fastNLP.models.cnn\_text\_classification
-========================================
+fastNLP.models.cnn_text_classification
+======================================
 
 .. automodule:: fastNLP.models.cnn_text_classification
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: CNNText
+   :inherited-members:
+

docs/source/fastNLP.models.rst

@@ -2,19 +2,16 @@ fastNLP.models
 ==============
 
 .. automodule:: fastNLP.models
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: CNNText, SeqLabeling, AdvSeqLabel, ESIM, StarTransEnc, STSeqLabel, STNLICls, STSeqCls, BiaffineParser, GraphParser
+   :inherited-members:
 
 子模块
-----------
+------
 
 .. toctree::
-   :titlesonly:
 
    fastNLP.models.biaffine_parser
    fastNLP.models.cnn_text_classification
    fastNLP.models.sequence_labeling
    fastNLP.models.snli
    fastNLP.models.star_transformer
-

docs/source/fastNLP.models.sequence_labeling.rst

@@ -1,7 +1,7 @@
-fastNLP.models.sequence\_labeling
-=================================
+fastNLP.models.sequence_labeling
+================================
 
 .. automodule:: fastNLP.models.sequence_labeling
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: SeqLabeling, AdvSeqLabel
+   :inherited-members:
+

docs/source/fastNLP.models.snli.rst

@@ -2,6 +2,6 @@ fastNLP.models.snli
 ===================
 
 .. automodule:: fastNLP.models.snli
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: ESIM
+   :inherited-members:
+

docs/source/fastNLP.models.star_transformer.rst

@@ -1,7 +1,7 @@
-fastNLP.models.star\_transformer
-================================
+fastNLP.models.star_transformer
+===============================
 
 .. automodule:: fastNLP.models.star_transformer
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: StarTransEnc, STNLICls, STSeqCls, STSeqLabel
+   :inherited-members:
+

docs/source/fastNLP.modules.aggregator.attention.rst

@@ -1,7 +0,0 @@
-fastNLP.modules.aggregator.attention
-====================================
-
-.. automodule:: fastNLP.modules.aggregator.attention
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/source/fastNLP.modules.aggregator.pooling.rst

@@ -1,7 +0,0 @@
-fastNLP.modules.aggregator.pooling
-==================================
-
-.. automodule:: fastNLP.modules.aggregator.pooling
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/source/fastNLP.modules.aggregator.rst

@@ -1,17 +0,0 @@
-fastNLP.modules.aggregator
-==========================
-
-.. automodule:: fastNLP.modules.aggregator
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-子模块
-----------
-
-.. toctree::
-   :titlesonly:
-
-   fastNLP.modules.aggregator.attention
-   fastNLP.modules.aggregator.pooling
-

docs/source/fastNLP.modules.decoder.crf.rst

@@ -1,7 +0,0 @@
-fastNLP.modules.decoder.CRF
-===========================
-
-.. automodule:: fastNLP.modules.decoder.crf
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/source/fastNLP.modules.decoder.mlp.rst

@@ -1,7 +0,0 @@
-fastNLP.modules.decoder.MLP
-===========================
-
-.. automodule:: fastNLP.modules.decoder.mlp
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/source/fastNLP.modules.decoder.rst

@@ -2,17 +2,6 @@ fastNLP.modules.decoder
 =======================
 
 .. automodule:: fastNLP.modules.decoder
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-子模块
-----------
-
-.. toctree::
-   :titlesonly:
-
-   fastNLP.modules.decoder.crf
-   fastNLP.modules.decoder.mlp
-   fastNLP.modules.decoder.utils
+   :members: MLP, ConditionalRandomField, viterbi_decode, allowed_transitions
+   :inherited-members:
 

docs/source/fastNLP.modules.decoder.utils.rst

@@ -1,7 +0,0 @@
-fastNLP.modules.decoder.utils
-=============================
-
-.. automodule:: fastNLP.modules.decoder.utils
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/source/fastNLP.modules.encoder.bert.rst

@@ -1,7 +0,0 @@
-fastNLP.modules.encoder.bert
-============================
-
-.. automodule:: fastNLP.modules.encoder.bert
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/source/fastNLP.modules.encoder.char_encoder.rst

@@ -1,7 +0,0 @@
-fastNLP.modules.encoder.char\_encoder
-=====================================
-
-.. automodule:: fastNLP.modules.encoder.char_encoder
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/source/fastNLP.modules.encoder.conv_maxpool.rst

@@ -1,7 +0,0 @@
-fastNLP.modules.encoder.conv\_maxpool
-=====================================
-
-.. automodule:: fastNLP.modules.encoder.conv_maxpool
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/source/fastNLP.modules.encoder.embedding.rst

@@ -1,7 +0,0 @@
-fastNLP.modules.encoder.embedding
-=================================
-
-.. automodule:: fastNLP.modules.encoder.embedding
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/source/fastNLP.modules.encoder.lstm.rst

@@ -1,7 +0,0 @@
-fastNLP.modules.encoder.lstm
-============================
-
-.. automodule:: fastNLP.modules.encoder.lstm
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/source/fastNLP.modules.encoder.rst

@@ -2,22 +2,6 @@ fastNLP.modules.encoder
 =======================
 
 .. automodule:: fastNLP.modules.encoder
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-子模块
-----------
-
-.. toctree::
-   :titlesonly:
-
-   fastNLP.modules.encoder.bert
-   fastNLP.modules.encoder.char_encoder
-   fastNLP.modules.encoder.conv_maxpool
-   fastNLP.modules.encoder.embedding
-   fastNLP.modules.encoder.lstm
-   fastNLP.modules.encoder.star_transformer
-   fastNLP.modules.encoder.transformer
-   fastNLP.modules.encoder.variational_rnn
+   :members: ConvolutionCharEncoder, LSTMCharEncoder, ConvMaxpool, LSTM, StarTransformer, TransformerEncoder, VarRNN, VarLSTM, VarGRU, MaxPool, MaxPoolWithMask, AvgPool, AvgPoolWithMask, MultiHeadAttention
+   :inherited-members:
 

docs/source/fastNLP.modules.encoder.star_transformer.rst

@@ -1,7 +0,0 @@
-fastNLP.modules.encoder.star\_transformer
-=========================================
-
-.. automodule:: fastNLP.modules.encoder.star_transformer
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/source/fastNLP.modules.encoder.transformer.rst

@@ -1,7 +0,0 @@
-fastNLP.modules.encoder.transformer
-===================================
-
-.. automodule:: fastNLP.modules.encoder.transformer
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/source/fastNLP.modules.encoder.variational_rnn.rst

@@ -1,7 +0,0 @@
-fastNLP.modules.encoder.variational\_rnn
-========================================
-
-.. automodule:: fastNLP.modules.encoder.variational_rnn
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/source/fastNLP.modules.rst

@@ -2,16 +2,14 @@ fastNLP.modules
 ===============
 
 .. automodule:: fastNLP.modules
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: ConvolutionCharEncoder, LSTMCharEncoder, ConvMaxpool, LSTM, StarTransformer, TransformerEncoder, VarRNN, VarLSTM, VarGRU, MaxPool, MaxPoolWithMask, AvgPool, AvgPoolWithMask, MultiHeadAttention, MLP, ConditionalRandomField, viterbi_decode, allowed_transitions, TimestepDropout
+   :inherited-members:
 
 子模块
------------
+------
 
 .. toctree::
-    :titlesonly:
 
-    fastNLP.modules.aggregator
-    fastNLP.modules.decoder
-    fastNLP.modules.encoder
+   fastNLP.modules.decoder
+   fastNLP.modules.encoder
+   fastNLP.modules.utils

docs/source/fastNLP.modules.utils.rst

@@ -0,0 +1,7 @@
+fastNLP.modules.utils
+=====================
+
+.. automodule:: fastNLP.modules.utils
+   :members: initial_parameter, summary
+   :inherited-members:
+

docs/source/fastNLP.rst

@@ -1,20 +1,17 @@
-API 文档
-===============
+fastNLP
+=======
 
 .. automodule:: fastNLP
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members: Instance, FieldArray, DataSetIter, BatchIter, TorchLoaderIter, Vocabulary, DataSet, Const, Trainer, Tester, Callback, GradientClipCallback, EarlyStopCallback, TensorboardCallback, LRScheduler, ControlC, LRFinder, Padder, AutoPadder, EngChar2DPadder, AccuracyMetric, SpanFPreRecMetric, ExtractiveQAMetric, Optimizer, SGD, Adam, AdamW, Sampler, SequentialSampler, BucketSampler, RandomSampler, LossFunc, CrossEntropyLoss, L1Loss, BCELoss, NLLLoss, LossInForward, cache_results, logger
+   :inherited-members:
 
-内部模块
------------
+子模块
+------
 
 .. toctree::
-    :titlesonly:
-    :maxdepth: 3
-
-    fastNLP.core
-    fastNLP.io
-    fastNLP.modules
-    fastNLP.models
 
+   fastNLP.core
+   fastNLP.embeddings
+   fastNLP.io
+   fastNLP.models
+   fastNLP.modules

docs/source/index.rst

@@ -1,62 +1,28 @@
 fastNLP 中文文档
 =====================
 
-fastNLP 是一款轻量级的 NLP 处理套件。你既可以使用它快速地完成一个命名实体识别（NER）、中文分词或文本分类任务；
-也可以使用他构建许多复杂的网络模型，进行科研。它具有如下的特性:
+`fastNLP <https://github.com/fastnlp/fastNLP/>`_ 是一款轻量级的 NLP 处理套件。你既可以使用它快速地完成一个序列标注
+（NER、POS-Tagging等）、中文分词、文本分类、Matching、指代消解、摘要等任务
+（详见 `reproduction <https://github.com/fastnlp/fastNLP/tree/master/reproduction>`_ ）；
+也可以使用它构建许多复杂的网络模型，进行科研。它具有如下的特性：
 
-- 统一的Tabular式数据容器，让数据预处理过程简洁明了。内置多种数据集的DataSet Loader，省去预处理代码。
-- 各种方便的NLP工具，例如预处理embedding加载; 中间数据cache等;
-- 详尽的中文文档以供查阅；
-- 提供诸多高级模块，例如Variational LSTM, Transformer, CRF等;
-- 封装CNNText，Biaffine等模型可供直接使用;
-- 便捷且具有扩展性的训练器; 提供多种内置callback函数，方便实验记录、异常捕获等。
+- 统一的Tabular式数据容器，让数据预处理过程简洁明了。内置多种数据集的 :mod:`~fastNLP.io.data_loader` ，省去预处理代码;
+- 多种训练、测试组件，例如训练器 :class:`~fastNLP.Trainer` ；测试器 :class:`~fastNLP.Tester` ；以及各种评测 :mod:`~fastNLP.core.metrics` 等等;
+- 各种方便的NLP工具，例如预处理 :mod:`embedding<fastNLP.embeddings>` 加载（包括ELMo和BERT）; 中间数据存储 :func:`cache <fastNLP.cache_results>` 等;
+- 提供诸多高级模块 :mod:`~fastNLP.modules`，例如 :class:`~fastNLP.modules.VarLSTM` , :class:`Transformer<fastNLP.modules.TransformerEncoder>` , :class:`CRF<fastNLP.modules.ConditionalRandomField>` 等;
+- 在序列标注、中文分词、文本分类、Matching、指代消解、摘要等任务上封装了各种 :mod:`~fastNLP.models` 可供直接使用;
+- 训练器便捷且具有扩展性，提供多种内置 :mod:`~fastNLP.core.callback` 函数，方便实验记录、异常捕获等。
 
 
-内置组件
-------------
-
-大部分用于的 NLP 任务神经网络都可以看做由编码（encoder）、聚合（aggregator）、解码（decoder）三种模块组成。
-
-.. image:: figures/text_classification.png
-
-fastNLP 在 :mod:`~fastNLP.modules` 模块中内置了三种模块的诸多组件，可以帮助用户快速搭建自己所需的网络。
-三种模块的功能和常见组件如下:
-
-+-----------------------+-----------------------+-----------------------+
-| module type           | functionality         | example               |
-+=======================+=======================+=======================+
-| encoder               | 将输入编码为具有具    | embedding, RNN, CNN,  |
-|                       | 有表示能力的向量      | transformer           |
-+-----------------------+-----------------------+-----------------------+
-| aggregator            | 从多个向量中聚合信息  | self-attention,       |
-|                       |                       | max-pooling           |
-+-----------------------+-----------------------+-----------------------+
-| decoder               | 将具有某种表示意义的  | MLP, CRF              |
-|                       | 向量解码为需要的输出  |                       |
-|                       | 形式                  |                       |
-+-----------------------+-----------------------+-----------------------+
-
-
-内置模型
-----------------
-
-fastNLP 在 :mod:`~fastNLP.models` 模块中内置了如 :class:`~fastNLP.models.CNNText` 、
-:class:`~fastNLP.models.SeqLabeling` 等完整的模型，以供用户直接使用。
-
-.. todo::
-    这些模型的介绍如下表所示：（模型名称 + 介绍 + 任务上的结果）
-
 用户手册
 ----------------
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
-    安装指南 <user/installation>
-    快速入门 <user/quickstart>
-    详细指南 <user/tutorial_one>
-    科研指南 <user/with_fitlog>
-    注释语法 <user/example>
+    安装指南 </user/installation>
+    快速入门 </user/quickstart>
+    详细教程 </user/tutorials>
 
 API 文档
 -------------
@@ -69,11 +35,11 @@ API 文档
    
    fastNLP
 
-fitlog
-------
+fitlog文档
+----------
 
-用户可以 `点此 <https://fitlog.readthedocs.io/zh/latest/>`_  查看fitlog的文档。
-fitlog 是由我们团队开发，用于帮助用户记录日志并管理代码的工具
+您可以 `点此 <https://fitlog.readthedocs.io/zh/latest/>`_  查看fitlog的文档。
+fitlog 是由我们团队开发的日志记录+代码管理的工具。
 
 索引与搜索
 ==================

docs/source/modules.rst

@@ -2,7 +2,6 @@ fastNLP
 =======
 
 .. toctree::
-   :titlesonly:
    :maxdepth: 4
 
    fastNLP

docs/source/user/with_fitlog.rst → docs/source/tutorials/tutorial_10_fitlog.rst

@@ -1,6 +1,6 @@
-=================
-科研向导
-=================
+============================================
+使用fitlog 辅助 fastNLP 进行科研
+============================================
 
 本文介绍结合使用 fastNLP 和 fitlog 进行科研的方法。
 

docs/source/tutorials/tutorial_1_data_preprocess.rst

@@ -0,0 +1,156 @@
+==============================
+使用DataSet预处理文本
+==============================
+
+:class:`~fastNLP.DataSet` 是fastNLP中用于承载数据的容器。可以将DataSet看做是一个表格，
+每一行是一个sample (在fastNLP中被称为 :mod:`~fastNLP.core.instance` )，
+每一列是一个feature (在fastNLP中称为 :mod:`~fastNLP.core.field` )。
+
+.. csv-table::
+   :header: "sentence", "words", "seq_len"
+
+   "This is the first instance .", "[This, is, the, first, instance, .]", 6
+   "Second instance .", "[Second, instance, .]", 3
+   "Third instance .", "[Third, instance, .]", 3
+   "...", "[...]", "..."
+
+上面是一个样例数据中 DataSet 的存储结构。其中它的每一行是一个 :class:`~fastNLP.Instance` 对象； 每一列是一个 :class:`~fastNLP.FieldArray` 对象。
+
+
+-----------------------------
+数据集构建和删除
+-----------------------------
+
+我们使用传入字典的方式构建一个数据集，这是 :class:`~fastNLP.DataSet` 初始化的最基础的方式
+
+.. code-block:: python
+
+    from fastNLP import DataSet
+    data = {'sentence':["This is the first instance .", "Second instance .", "Third instance ."],
+            'words': [['this', 'is', 'the', 'first', 'instance', '.'], ['Second', 'instance', '.'], ['Third', 'instance', '.']],
+            'seq_len': [6, 3, 3]}
+    dataset = DataSet(data)
+    # 传入的dict的每个key的value应该为具有相同长度的list
+
+我们还可以使用 :func:`~fastNLP.DataSet.append` 方法向数据集内增加数据
+
+.. code-block:: python
+
+    from fastNLP import DataSet
+    from fastNLP import Instance
+    dataset = DataSet()
+    instance = Instance(sentence="This is the first instance",
+                        words=['this', 'is', 'the', 'first', 'instance', '.'],
+                        seq_len=6)
+    dataset.append(instance)
+    # 可以继续append更多内容，但是append的instance应该和前面的instance拥有完全相同的field
+
+另外，我们还可以用 :class:`~fastNLP.Instance` 数组的方式构建数据集
+
+.. code-block:: python
+
+    from fastNLP import DataSet
+    from fastNLP import Instance
+    dataset = DataSet([
+        Instance(sentence="This is the first instance",
+            words=['this', 'is', 'the', 'first', 'instance', '.'],
+            seq_len=6),
+        Instance(sentence="Second instance .",
+            words=['Second', 'instance', '.'],
+            seq_len=3)
+        ])
+
+在初步构建完数据集之后，我们可以通过 `for` 循环遍历 :class:`~fastNLP.DataSet` 中的内容。
+
+.. code-block:: python
+
+    for instance in dataset:
+        # do something
+
+FastNLP 同样提供了多种删除数据的方法 :func:`~fastNLP.DataSet.drop` 、 :func:`~fastNLP.DataSet.delete_instance` 和 :func:`~fastNLP.DataSet.delete_field`
+
+.. code-block:: python
+
+    from fastNLP import DataSet
+    dataset = DataSet({'a': list(range(-5, 5))})
+    # 返回满足条件的instance,并放入DataSet中
+    dropped_dataset = dataset.drop(lambda ins:ins['a']<0, inplace=False)
+    # 在dataset中删除满足条件的instance
+    dataset.drop(lambda ins:ins['a']<0)  # dataset的instance数量减少
+    #  删除第3个instance
+    dataset.delete_instance(2)
+    #  删除名为'a'的field
+    dataset.delete_field('a')
+
+-----------------------------
+简单的数据预处理
+-----------------------------
+
+因为 fastNLP 中的数据是按列存储的，所以大部分的数据预处理操作是以列（ :mod:`~fastNLP.core.field` ）为操作对象的。
+首先，我们可以检查特定名称的 :mod:`~fastNLP.core.field` 是否存在，并对其进行改名。
+
+.. code-block:: python
+
+    #  检查是否存在名为'a'的field
+    dataset.has_field('a')  # 或 ('a' in dataset)
+    #  将名为'a'的field改名为'b'
+    dataset.rename_field('a', 'b')
+    #  DataSet的长度
+    len(dataset)
+
+其次，我们可以使用 :func:`~fastNLP.DataSet.apply` 或 :func:`~fastNLP.DataSet.apply_field` 进行数据预处理操作操作。
+这两个方法通过传入一个对单一 :mod:`~fastNLP.core.instance` 操作的函数，
+自动地帮助你对一个 :mod:`~fastNLP.core.field` 中的每个 :mod:`~fastNLP.core.instance` 调用这个函数，完成整体的操作。
+这个传入的函数可以是 lambda 匿名函数，也可以是完整定义的函数。同时，你还可以用 ``new_field_name`` 参数指定数据处理后存储的 :mod:`~fastNLP.core.field` 的名称。
+
+.. code-block:: python
+
+    from fastNLP import DataSet
+    data = {'sentence':["This is the first instance .", "Second instance .", "Third instance ."]}
+    dataset = DataSet(data)
+
+    # 将句子分成单词形式, 详见DataSet.apply()方法
+    dataset.apply(lambda ins: ins['sentence'].split(), new_field_name='words')
+
+    # 或使用DataSet.apply_field()
+    dataset.apply_field(lambda sent:sent.split(), field_name='sentence', new_field_name='words')
+
+    # 除了匿名函数，也可以定义函数传递进去
+    def get_words(instance):
+        sentence = instance['sentence']
+        words = sentence.split()
+        return words
+    dataset.apply(get_words, new_field_name='words')
+
+除了手动处理数据集之外，你还可以使用 fastNLP 提供的各种 :class:`~fastNLP.io.base_loader.DataSetLoader` 来进行数据处理。
+详细请参考这篇教程  :doc:`使用DataSetLoader加载数据集 </tutorials/tutorial_2_load_dataset>` 。
+
+-----------------------------
+DataSet与pad
+-----------------------------
+
+在fastNLP里，pad是与一个 :mod:`~fastNLP.core.field` 绑定的。即不同的 :mod:`~fastNLP.core.field` 可以使用不同的pad方式，比如在英文任务中word需要的pad和
+character的pad方式往往是不同的。fastNLP是通过一个叫做 :class:`~fastNLP.Padder` 的子类来完成的。
+默认情况下，所有field使用 :class:`~fastNLP.AutoPadder`
+。可以通过使用以下方式设置Padder(如果将padder设置为None，则该field不会进行pad操作)。
+大多数情况下直接使用 :class:`~fastNLP.AutoPadder` 就可以了。
+如果 :class:`~fastNLP.AutoPadder` 或 :class:`~fastNLP.EngChar2DPadder` 无法满足需求，
+也可以自己写一个 :class:`~fastNLP.Padder` 。
+
+.. code-block:: python
+
+    from fastNLP import DataSet
+    from fastNLP import EngChar2DPadder
+    import random
+    dataset = DataSet()
+    max_chars, max_words, sent_num = 5, 10, 20
+    contents = [[
+                    [random.randint(1, 27) for _ in range(random.randint(1, max_chars))]
+                        for _ in range(random.randint(1, max_words))
+                ]  for _ in range(sent_num)]
+    #  初始化时传入
+    dataset.add_field('chars', contents, padder=EngChar2DPadder())
+    #  直接设置
+    dataset.set_padder('chars', EngChar2DPadder())
+    #  也可以设置pad的value
+    dataset.set_pad_val('chars', -1)

docs/source/tutorials/tutorial_2_load_dataset.rst

@@ -0,0 +1,150 @@
+=======================================
+使用Loader和Pipe加载并处理数据集
+=======================================
+
+这一部分是一个关于如何加载数据集的教程
+
+教程目录：
+
+    - `Part I: 数据集容器DataBundle`_
+    - `Part II: 加载数据集的基类Loader`_
+    - `Part III: 不同格式类型的基础Loader`_
+    - `Part IV: 使用Pipe对数据集进行预处理`_
+    - `Part V: fastNLP封装好的Loader和Pipe`_
+
+
+------------------------------------
+Part I: 数据集容器DataBundle
+------------------------------------
+
+在fastNLP中，我们使用 :class:`~fastNLP.io.data_bundle.DataBundle` 来存储数据集信息。
+:class:`~fastNLP.io.data_bundle.DataBundle` 类包含了两个重要内容： `datasets` 和 `vocabs` 。
+
+`datasets` 是一个 `key` 为数据集名称（如 `train` ， `dev` ，和 `test` 等）， `value` 为 :class:`~fastNLP.DataSet` 的字典。
+
+`vocabs` 是一个 `key` 为词表名称（如 :attr:`fastNLP.Const.INPUT` 表示输入文本的词表名称， :attr:`fastNLP.Const.TARGET` 表示目标
+的真实标签词表的名称，等等）， `value` 为词表内容（ :class:`~fastNLP.Vocabulary` ）的字典。
+
+-------------------------------------
+Part II: 加载数据集的基类Loader
+-------------------------------------
+
+在fastNLP中，我们采用 :class:`~fastNLP.io.loader.Loader` 来作为加载数据集的基类。
+:class:`~fastNLP.io.loader.Loader` 定义了各种Loader所需的API接口，开发者应该继承它实现各种的Loader。
+在各种数据集的Loader当中，至少应该编写如下内容:
+
+    - _load 函数：从一个数据文件中读取数据，返回一个 :class:`~fastNLP.DataSet`
+    - load 函数：从文件或者文件夹中读取数据并组装成 :class:`~fastNLP.io.data_bundle.DataBundle`
+
+Loader的load函数返回的 :class:`~fastNLP.io.data_bundle.DataBundle` 里面包含了数据集的原始数据。
+
+--------------------------------------------------------
+Part III: 不同格式类型的基础Loader
+--------------------------------------------------------
+
+:class:`~fastNLP.io.loader.CSVLoader`
+    读取CSV类型的数据集文件。例子如下：
+
+    .. code-block:: python
+
+        from fastNLP.io.loader import CSVLoader
+        data_set_loader = CSVLoader(
+            headers=('words', 'target'), sep='\t'
+        )
+        # 表示将CSV文件中每一行的第一项填入'words' field，第二项填入'target' field。
+        # 其中每两项之间由'\t'分割开来
+
+        data_set = data_set_loader._load('path/to/your/file')
+
+    数据集内容样例如下 ::
+
+        But it does not leave you with much .	1
+        You could hate it for the same reason .	1
+        The performances are an absolute joy .	4
+
+
+:class:`~fastNLP.io.loader.JsonLoader`
+    读取Json类型的数据集文件，数据必须按行存储，每行是一个包含各类属性的Json对象。例子如下：
+
+    .. code-block:: python
+
+        from fastNLP.io.loader import JsonLoader
+        oader = JsonLoader(
+            fields={'sentence1': 'words1', 'sentence2': 'words2', 'gold_label': 'target'}
+        )
+        # 表示将Json对象中'sentence1'、'sentence2'和'gold_label'对应的值赋给'words1'、'words2'、'target'这三个fields
+
+        data_set = loader._load('path/to/your/file')
+
+    数据集内容样例如下 ::
+
+        {"annotator_labels": ["neutral"], "captionID": "3416050480.jpg#4", "gold_label": "neutral", "pairID": "3416050480.jpg#4r1n", "sentence1": "A person on a horse jumps over a broken down airplane.", "sentence1_binary_parse": "( ( ( A person ) ( on ( a horse ) ) ) ( ( jumps ( over ( a ( broken ( down airplane ) ) ) ) ) . ) )", "sentence1_parse": "(ROOT (S (NP (NP (DT A) (NN person)) (PP (IN on) (NP (DT a) (NN horse)))) (VP (VBZ jumps) (PP (IN over) (NP (DT a) (JJ broken) (JJ down) (NN airplane)))) (. .)))", "sentence2": "A person is training his horse for a competition.", "sentence2_binary_parse": "( ( A person ) ( ( is ( ( training ( his horse ) ) ( for ( a competition ) ) ) ) . ) )", "sentence2_parse": "(ROOT (S (NP (DT A) (NN person)) (VP (VBZ is) (VP (VBG training) (NP (PRP$ his) (NN horse)) (PP (IN for) (NP (DT a) (NN competition))))) (. .)))"}
+        {"annotator_labels": ["contradiction"], "captionID": "3416050480.jpg#4", "gold_label": "contradiction", "pairID": "3416050480.jpg#4r1c", "sentence1": "A person on a horse jumps over a broken down airplane.", "sentence1_binary_parse": "( ( ( A person ) ( on ( a horse ) ) ) ( ( jumps ( over ( a ( broken ( down airplane ) ) ) ) ) . ) )", "sentence1_parse": "(ROOT (S (NP (NP (DT A) (NN person)) (PP (IN on) (NP (DT a) (NN horse)))) (VP (VBZ jumps) (PP (IN over) (NP (DT a) (JJ broken) (JJ down) (NN airplane)))) (. .)))", "sentence2": "A person is at a diner, ordering an omelette.", "sentence2_binary_parse": "( ( A person ) ( ( ( ( is ( at ( a diner ) ) ) , ) ( ordering ( an omelette ) ) ) . ) )", "sentence2_parse": "(ROOT (S (NP (DT A) (NN person)) (VP (VBZ is) (PP (IN at) (NP (DT a) (NN diner))) (, ,) (S (VP (VBG ordering) (NP (DT an) (NN omelette))))) (. .)))"}
+        {"annotator_labels": ["entailment"], "captionID": "3416050480.jpg#4", "gold_label": "entailment", "pairID": "3416050480.jpg#4r1e", "sentence1": "A person on a horse jumps over a broken down airplane.", "sentence1_binary_parse": "( ( ( A person ) ( on ( a horse ) ) ) ( ( jumps ( over ( a ( broken ( down airplane ) ) ) ) ) . ) )", "sentence1_parse": "(ROOT (S (NP (NP (DT A) (NN person)) (PP (IN on) (NP (DT a) (NN horse)))) (VP (VBZ jumps) (PP (IN over) (NP (DT a) (JJ broken) (JJ down) (NN airplane)))) (. .)))", "sentence2": "A person is outdoors, on a horse.", "sentence2_binary_parse": "( ( A person ) ( ( ( ( is outdoors ) , ) ( on ( a horse ) ) ) . ) )", "sentence2_parse": "(ROOT (S (NP (DT A) (NN person)) (VP (VBZ is) (ADVP (RB outdoors)) (, ,) (PP (IN on) (NP (DT a) (NN horse)))) (. .)))"}
+
+------------------------------------------
+Part IV: 使用Pipe对数据集进行预处理
+------------------------------------------
+
+在fastNLP中，我们采用 :class:`~fastNLP.io.pipe.Pipe` 来作为加载数据集的基类。
+:class:`~fastNLP.io.pipe.Pipe` 定义了各种Pipe所需的API接口，开发者应该继承它实现各种的Pipe。
+在各种数据集的Pipe当中，至少应该编写如下内容:
+
+    - process 函数：对输入的 :class:`~fastNLP.io.data_bundle.DataBundle` 进行处理（如构建词表、
+      将dataset的文本内容转成index等等），然后返回该 :class:`~fastNLP.io.data_bundle.DataBundle`
+    - process_from_file 函数：输入数据集所在文件夹，读取内容并组装成 :class:`~fastNLP.io.data_bundle.DataBundle` ，
+      然后调用相对应的process函数对数据进行预处理
+
+以SNLI数据集为例，写一个自定义Pipe的例子如下：
+
+.. code-block:: python
+
+    from fastNLP.io.loader import SNLILoader
+    from fastNLP.io.pipe import MatchingPipe
+
+    class MySNLIPipe(MatchingPipe):
+
+        def process(self, data_bundle):
+            data_bundle = super(MySNLIPipe, self).process(data_bundle)
+            # MatchingPipe类里封装了一个关于matching任务的process函数，可以直接继承使用
+            # 如果有需要进行额外的预处理操作可以在这里加入您的代码
+            return data_bundle
+
+        def process_from_file(self, paths=None):
+            data_bundle = SNLILoader().load(paths) # 使用SNLILoader读取原始数据集
+            # SNLILoader的load函数中，paths如果为None则会自动下载
+            return self.process(data_bundle)  # 调用相对应的process函数对data_bundle进行处理
+
+调用Pipe示例：
+
+.. code-block:: python
+
+    from fastNLP.io.pipe import SNLIBertPipe
+    data_bundle = SNLIBertPipe(lower=True, tokenizer=arg.tokenizer).process_from_file()
+    print(data_bundle)
+
+输出的内容是::
+
+    In total 3 datasets:
+            train has 549367 instances.
+            dev has 9842 instances.
+            test has 9824 instances.
+    In total 2 vocabs:
+            words has 34184 entries.
+            target has 3 entries.
+
+这里表示一共有3个数据集和2个词表。其中：
+
+    - 3个数据集分别为train、dev、test数据集，分别有549367、9842、9824个instance
+    - 2个词表分别为words词表与target词表。其中words词表为句子文本所构建的词表，一共有34184个单词；
+      target词表为目标标签所构建的词表，一共有3种标签。（注：如果有多个输入，则句子文本所构建的词表将
+      会被命名为words1以对应相对应的列名）
+
+------------------------------------------
+Part V: fastNLP封装好的Loader和Pipe
+------------------------------------------
+
+fastNLP封装了多种任务/数据集的Loader和Pipe并提供自动下载功能，具体参见文档
+
+`fastNLP可加载的embedding与数据集 <https://docs.qq.com/sheet/DVnpkTnF6VW9UeXdh?c=A1A0A0>`_
+

docs/source/tutorials/tutorial_3_embedding.rst

@@ -0,0 +1,167 @@
+=========================================
+使用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 VII: fastNLP支持的预训练Embedding`_
+
+
+
+
+---------------------------------------
+Part I: embedding介绍
+---------------------------------------
+
+与torch.nn.Embedding类似，fastNLP的embedding接受的输入是一个被index好的序列，输出的内容是这个序列的embedding结果。
+
+fastNLP的embedding包括了预训练embedding和随机初始化embedding。
+
+
+---------------------------------------
+Part II: 使用随机初始化的embedding
+---------------------------------------
+
+使用随机初始化的embedding参见 :class:`~fastNLP.embeddings.embedding.Embedding` 。
+
+可以传入词表大小和embedding维度：
+
+.. code-block:: python
+
+    from fastNLP import Embedding
+    embed = Embedding(10000, 50)
+
+也可以传入一个初始化的参数矩阵：
+
+.. code-block:: python
+
+    from fastNLP import Embedding
+    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.embeddings.StaticEmbedding` 这一个类。
+通过 :class:`~fastNLP.embeddings.StaticEmbedding` 可以加载预训练好的静态
+Embedding，例子如下：
+
+.. code-block:: python
+
+    from fastNLP import StaticEmbedding
+    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目录下找到模型则会
+    自动加载；如果找不到则会自动下载到cache目录。默认的cache目录为 `~/.fastNLP` 文件夹。可以通过环境
+    变量 ``FASTNLP_CACHE_DIR`` 来自定义cache目录，如::
+
+        $ FASTNLP_CACHE_DIR=~/fastnlp_cache_dir python your_python_file.py
+
+这个命令表示fastNLP将会在 `~/fastnlp_cache_dir` 这个目录下寻找模型，找不到则会自动将模型下载到这个目录
+
+-----------------------------------------------------------
+Part IV: 使用预训练的Contextual Embedding(ELMo & BERT)
+-----------------------------------------------------------
+
+在fastNLP中，我们提供了ELMo和BERT的embedding： :class:`~fastNLP.embeddings.ElmoEmbedding`
+和 :class:`~fastNLP.embeddings.BertEmbedding` 。
+
+与静态embedding类似，ELMo的使用方法如下：
+
+.. code-block:: python
+
+    from fastNLP import ElmoEmbedding
+    embed = ElmoEmbedding(vocab, model_dir_or_name='small', requires_grad=False)
+
+BERT-embedding的使用方法如下：
+
+.. code-block:: python
+
+    from fastNLP import BertEmbedding
+    embed = BertEmbedding(
+        vocab, model_dir_or_name='en-base-cased', requires_grad=False, layers='4,-2,-1'
+    )
+
+其中layers变量表示需要取哪几层的encode结果。
+
+-----------------------------------------------------
+Part V: 使用character-level的embedding
+-----------------------------------------------------
+
+除了预训练的embedding以外，fastNLP还提供了CharEmbedding： :class:`~fastNLP.embeddings.CNNCharEmbedding` 和
+:class:`~fastNLP.embeddings.LSTMCharEmbedding` 。
+
+CNNCharEmbedding的使用例子如下：
+
+.. code-block:: python
+
+    from fastNLP import CNNCharEmbedding
+    embed = CNNCharEmbedding(vocab, embed_size=100, char_emb_size=50)
+
+这表示这个CNNCharEmbedding当中character的embedding维度大小为50，返回的embedding结果维度大小为100。
+
+与CNNCharEmbedding类似，LSTMCharEmbedding的使用例子如下：
+
+.. code-block:: python
+
+    from fastNLP import LSTMCharEmbedding
+    embed = LSTMCharEmbedding(vocab, embed_size=100, char_emb_size=50)
+
+这表示这个LSTMCharEmbedding当中character的embedding维度大小为50，返回的embedding结果维度大小为100。
+
+
+-----------------------------------------------------
+Part VI: 叠加使用多个embedding
+-----------------------------------------------------
+
+在fastNLP中，我们使用 :class:`~fastNLP.embeddings.StackEmbedding` 来叠加多个embedding
+
+例子如下：
+
+.. code-block:: python
+
+    from fastNLP import StaticEmbedding, StackEmbedding
+    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
+
+    from fastNLP import StaticEmbedding, StackEmbedding, ElmoEmbedding
+    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])
+
+------------------------------------------
+Part VII: fastNLP支持的预训练Embedding
+------------------------------------------
+
+fastNLP支持多种预训练Embedding并提供自动下载功能，具体参见文档
+
+`fastNLP可加载的embedding与数据集 <https://docs.qq.com/sheet/DVnpkTnF6VW9UeXdh?c=A1A0A0>`_
+

docs/source/tutorials/tutorial_4_loss_optimizer.rst

@@ -0,0 +1,271 @@
+==============================================================================
+动手实现一个文本分类器I-使用Trainer和Tester快速训练和测试
+==============================================================================
+
+我们使用和 :doc:`/user/quickstart` 中一样的任务来进行详细的介绍。给出一段评价性文字，预测其情感倾向是积极（label=1）、
+消极（label=0）还是中性（label=2），使用 :class:`~fastNLP.Trainer`  和  :class:`~fastNLP.Tester`  来进行快速训练和测试。
+
+--------------
+数据处理
+--------------
+
+数据读入
+    我们可以使用 fastNLP  :mod:`fastNLP.io` 模块中的 :class:`~fastNLP.io.SSTLoader` 类，轻松地读取SST数据集（数据来源：https://nlp.stanford.edu/sentiment/trainDevTestTrees_PTB.zip）。
+    这里的 dataset 是 fastNLP 中 :class:`~fastNLP.DataSet` 类的对象。
+
+    .. code-block:: python
+
+        from fastNLP.io import SSTLoader
+
+        loader = SSTLoader()
+        #这里的all.txt是下载好数据后train.txt、dev.txt、test.txt的组合
+        #loader.load(path)会首先判断path是否为none，若是则自动从网站下载数据，若不是则读入数据并返回databundle
+        databundle_ = loader.load("./trainDevTestTrees_PTB/trees/all.txt")
+        dataset = databundle_.datasets['train']
+        print(dataset[0])
+
+    输出数据如下::
+	
+        {'words': ['It', "'s", 'a', 'lovely', 'film', 'with', 'lovely', 'performances', 'by', 'Buy', 'and', 'Accorsi', '.'] type=list,
+        'target': positive type=str}
+
+    除了读取数据外，fastNLP 还提供了读取其它文件类型的 Loader 类、读取 Embedding的 Loader 等。详见 :doc:`/fastNLP.io` 。
+    
+
+数据处理
+    可以使用事先定义的 :class:`~fastNLP.io.SSTPipe` 类对数据进行基本预处理，这里我们手动进行处理。
+    我们使用 :class:`~fastNLP.DataSet` 类的 :meth:`~fastNLP.DataSet.apply` 方法将 ``target`` :mod:`~fastNLP.core.field` 转化为整数。
+    
+    .. code-block:: python
+
+        def label_to_int(x):
+            if x['target']=="positive":
+                return 1
+            elif x['target']=="negative":
+                return 0
+            else:
+                return 2
+
+        # 将label转为整数
+        dataset.apply(lambda x: label_to_int(x), 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])
+    
+    输出数据如下::
+
+        {'words': [27, 9, 6, 913, 16, 18, 913, 124, 31, 5715, 5, 1, 2] type=list,
+        'target': 1 type=int,
+        'seq_len': 13 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))
+
+    输出结果为::
+	
+        9603 1067 1185
+
+评价指标
+    训练模型需要提供一个评价指标。这里使用准确率做为评价指标。参数的 `命名规则` 跟上面类似。
+    ``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中提供了直接可以导入使用的四种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)
+	
+优化器
+    定义模型运行的时候使用的优化器，可以使用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` 进行训练，
+    除了使用 :class:`~fastNLP.Trainer`进行训练，我们也可以通过使用 :class:`~fastNLP.DataSetIter` 来编写自己的训练过程，具体见 :doc:`/tutorials/tutorial_5_datasetiter`
+
+    .. 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=3, 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, 40]) 
+                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-08-15-44-48
+        Evaluation at Epoch 1/10. Step:601/6010. AccuracyMetric: acc=0.59044
+
+        Evaluation at Epoch 2/10. Step:1202/6010. AccuracyMetric: acc=0.599813
+
+        Evaluation at Epoch 3/10. Step:1803/6010. AccuracyMetric: acc=0.508903
+
+        Evaluation at Epoch 4/10. Step:2404/6010. AccuracyMetric: acc=0.596064
+
+        Evaluation at Epoch 5/10. Step:3005/6010. AccuracyMetric: acc=0.47985
+
+        Evaluation at Epoch 6/10. Step:3606/6010. AccuracyMetric: acc=0.589503
+
+        Evaluation at Epoch 7/10. Step:4207/6010. AccuracyMetric: acc=0.311153
+
+        Evaluation at Epoch 8/10. Step:4808/6010. AccuracyMetric: acc=0.549203
+
+        Evaluation at Epoch 9/10. Step:5409/6010. AccuracyMetric: acc=0.581068
+
+        Evaluation at Epoch 10/10. Step:6010/6010. AccuracyMetric: acc=0.523899
+
+
+        In Epoch:2/Step:1202, got best dev performance:AccuracyMetric: acc=0.599813
+        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.565401

docs/source/tutorials/tutorial_5_datasetiter.rst

@@ -0,0 +1,253 @@
+==============================================================================
+动手实现一个文本分类器II-使用DataSetIter实现自定义训练过程
+==============================================================================
+
+我们使用和 :doc:`/user/quickstart` 中一样的任务来进行详细的介绍。给出一段评价性文字，预测其情感倾向是积极（label=1）、
+消极（label=0）还是中性（label=2），使用 :class:`~fastNLP.DataSetIter` 类来编写自己的训练过程。
+自己编写训练过程之前的内容与 :doc:`/tutorials/tutorial_4_loss_optimizer` 中的完全一样，如已经阅读过可以跳过。
+
+--------------
+数据处理
+--------------
+
+数据读入
+    我们可以使用 fastNLP  :mod:`fastNLP.io` 模块中的 :class:`~fastNLP.io.SSTLoader` 类，轻松地读取SST数据集（数据来源：https://nlp.stanford.edu/sentiment/trainDevTestTrees_PTB.zip）。
+    这里的 dataset 是 fastNLP 中 :class:`~fastNLP.DataSet` 类的对象。
+
+    .. code-block:: python
+
+        from fastNLP.io import SSTLoader
+
+        loader = SSTLoader()
+        #这里的all.txt是下载好数据后train.txt、dev.txt、test.txt的组合
+        #loader.load(path)会首先判断path是否为none，若是则自动从网站下载数据，若不是则读入数据并返回databundle
+        databundle_ = loader.load("./trainDevTestTrees_PTB/trees/all.txt")
+        dataset = databundle_.datasets['train']
+        print(dataset[0])
+
+    输出数据如下::
+	
+        {'words': ['It', "'s", 'a', 'lovely', 'film', 'with', 'lovely', 'performances', 'by', 'Buy', 'and', 'Accorsi', '.'] type=list,
+        'target': positive type=str}
+		
+    除了读取数据外，fastNLP 还提供了读取其它文件类型的 Loader 类、读取 Embedding的 Loader 等。详见 :doc:`/fastNLP.io` 。
+    
+
+数据处理
+    可以使用事先定义的 :class:`~fastNLP.io.SSTPipe` 类对数据进行基本预处理，这里我们手动进行处理。
+    我们使用 :class:`~fastNLP.DataSet` 类的 :meth:`~fastNLP.DataSet.apply` 方法将 ``target`` :mod:`~fastNLP.core.field` 转化为整数。
+    
+    .. code-block:: python
+
+        def label_to_int(x):
+            if x['target']=="positive":
+                return 1
+            elif x['target']=="negative":
+                return 0
+            else:
+                return 2
+
+        # 将label转为整数
+        dataset.apply(lambda x: label_to_int(x), 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])
+    
+    输出数据如下::
+	
+        {'words': [27, 9, 6, 913, 16, 18, 913, 124, 31, 5715, 5, 1, 2] type=list,
+        'target': 1 type=int,
+        'seq_len': 13 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))
+
+    输出结果为::
+	
+        9603 1067 1185
+
+评价指标
+    训练模型需要提供一个评价指标。这里使用准确率做为评价指标。参数的 `命名规则` 跟上面类似。
+    ``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)
+
+
+--------------------------
+自己编写训练过程
+--------------------------
+    如果你想用类似 PyTorch 的使用方法，自己编写训练过程，你可以参考下面这段代码。
+    其中使用了 fastNLP 提供的 :class:`~fastNLP.DataSetIter` 来获得小批量训练的小批量数据，
+    使用 :class:`~fastNLP.BucketSampler` 做为  :class:`~fastNLP.DataSetIter` 的参数来选择采样的方式。
+    
+DataSetIter
+    fastNLP定义的 :class:`~fastNLP.DataSetIter` 类，用于定义一个batch，并实现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作为 :class:`~fastNLP.DataSetIter` 初始化的输入，运用 :class:`~fastNLP.DataSetIter` 自己写训练程序
+
+    .. code-block:: python
+
+        from fastNLP import BucketSampler
+        from fastNLP import DataSetIter
+        from fastNLP.models import CNNText
+        from fastNLP import Tester
+        import torch
+        import time
+
+        embed_dim = 100
+        model = CNNText((len(vocab),embed_dim), num_classes=3, 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 = DataSetIter(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 = Tester(test_data, model, metrics=AccuracyMetric())
+        tester.test()
+
+    这段代码的输出如下::
+
+        -----start training-----
+        Epoch 0 Avg Loss: 1.09 AccuracyMetric: acc=0.480787 58989ms
+        Epoch 1 Avg Loss: 1.00 AccuracyMetric: acc=0.500469 118348ms
+        Epoch 2 Avg Loss: 0.93 AccuracyMetric: acc=0.536082 176220ms
+        Epoch 3 Avg Loss: 0.87 AccuracyMetric: acc=0.556701 236032ms
+        Epoch 4 Avg Loss: 0.78 AccuracyMetric: acc=0.562324 294351ms
+        Epoch 5 Avg Loss: 0.69 AccuracyMetric: acc=0.58388 353673ms
+        Epoch 6 Avg Loss: 0.60 AccuracyMetric: acc=0.574508 412106ms
+        Epoch 7 Avg Loss: 0.51 AccuracyMetric: acc=0.589503 471097ms
+        Epoch 8 Avg Loss: 0.44 AccuracyMetric: acc=0.581068 529174ms
+        Epoch 9 Avg Loss: 0.39 AccuracyMetric: acc=0.572634 586216ms
+        [tester]
+        AccuracyMetric: acc=0.527426
+
+

docs/source/tutorials/tutorial_6_seq_labeling.rst

@@ -0,0 +1,114 @@
+=====================
+快速实现序列标注模型
+=====================
+
+这一部分的内容主要展示如何使用fastNLP 实现序列标注任务。你可以使用fastNLP的各个组件快捷，方便地完成序列标注任务，达到出色的效果。
+在阅读这篇Tutorial前，希望你已经熟悉了fastNLP的基础使用，包括基本数据结构以及数据预处理，embedding的嵌入等，希望你对之前的教程有更进一步的掌握。
+我们将对CoNLL-03的英文数据集进行处理，展示如何完成命名实体标注任务整个训练的过程。
+
+载入数据
+===================================
+fastNLP可以方便地载入各种类型的数据。同时，针对常见的数据集，我们已经预先实现了载入方法，其中包含CoNLL-03数据集。
+在设计dataloader时，以DataSetLoader为基类，可以改写并应用于其他数据集的载入。
+
+.. code-block:: python
+
+    class Conll2003DataLoader(DataSetLoader):
+    def __init__(self, task:str='ner', encoding_type:str='bioes'):
+        assert task in ('ner', 'pos', 'chunk')
+        index = {'ner':3, 'pos':1, 'chunk':2}[task]
+        #ConllLoader是fastNLP内置的类
+        self._loader = ConllLoader(headers=['raw_words', 'target'], indexes=[0, index])
+        self._tag_converters = None
+        if task in ('ner', 'chunk'):
+            #iob和iob2bioes会对tag进行统一，标准化
+            self._tag_converters = [iob2]
+            if encoding_type == 'bioes':
+                self._tag_converters.append(iob2bioes)
+
+    def load(self, path: str):
+        dataset = self._loader.load(path)
+        def convert_tag_schema(tags):
+            for converter in self._tag_converters:
+                tags = converter(tags)
+            return tags
+        if self._tag_converters:
+        #使用apply实现convert_tag_schema函数，实际上也支持匿名函数
+            dataset.apply_field(convert_tag_schema, field_name=Const.TARGET, new_field_name=Const.TARGET)
+        return dataset
+
+输出数据格式如：
+
+    {'raw_words': ['on', 'Friday', ':'] type=list,
+    'target': ['O', 'O', 'O'] type=list},
+
+
+数据处理
+----------------------------
+我们进一步处理数据。将数据和词表封装在 :class:`~fastNLP.DataBundle` 类中。data是DataBundle的实例。
+我们输入模型的数据包括char embedding，以及word embedding。在数据处理部分，我们尝试完成词表的构建。
+使用fastNLP中的Vocabulary类来构建词表。
+
+.. code-block:: python
+
+    word_vocab = Vocabulary(min_freq=2)
+    word_vocab.from_dataset(data.datasets['train'], field_name=Const.INPUT)
+    word_vocab.index_dataset(*data.datasets.values(),field_name=Const.INPUT, new_field_name=Const.INPUT)
+
+处理后的data对象内部为：
+
+    dataset
+    vocabs
+    dataset保存了train和test中的数据，并保存为dataset类型
+    vocab保存了words，raw-words以及target的词表。
+
+模型构建
+--------------------------------
+我们使用CNN-BILSTM-CRF模型完成这一任务。在网络构建方面，fastNLP的网络定义继承pytorch的 :class:`nn.Module` 类。
+自己可以按照pytorch的方式定义网络。需要注意的是命名。fastNLP的标准命名位于 :class:`~fastNLP.Const` 类。
+
+模型的训练
+首先实例化模型，导入所需的char embedding以及word embedding。Embedding的载入可以参考教程。
+也可以查看 :mod:`~fastNLP.modules.encoder.embedding` 使用所需的embedding 载入方法。
+fastNLP将模型的训练过程封装在了 :class:`~fastnlp.trainer` 类中。
+根据不同的任务调整trainer中的参数即可。通常，一个trainer实例需要有：指定的训练数据集，模型，优化器，loss函数，评测指标，以及指定训练的epoch数，batch size等参数。
+
+.. code-block:: python
+
+    #实例化模型
+    model = CNNBiLSTMCRF(word_embed, char_embed, hidden_size=200, num_layers=1, tag_vocab=data.vocabs[Const.TARGET], encoding_type=encoding_type)
+    #定义优化器
+    optimizer = Adam(model.parameters(), lr=0.005)
+    #定义评估指标
+    Metrics=SpanFPreRecMetric(tag_vocab=data.vocabs[Const.TARGET], encoding_type=encoding_type)
+    #实例化trainer
+    trainer = Trainer(train_data=data.datasets['train'], model=model, optimizer=optimizer, dev_data=data.datasets['test'], batch_size=10, metrics=Metrics,callbacks=callbacks, n_epochs=100)
+    #开始训练
+    trainer.train()
+    
+训练中会保存最优的参数配置。
+训练的结果如下：
+
+.. code-block:: python
+
+    Evaluation on DataSet test:                                                                                          
+    SpanFPreRecMetric: f=0.727661, pre=0.732293, rec=0.723088
+    Evaluation at Epoch 1/100. Step:1405/140500. SpanFPreRecMetric: f=0.727661, pre=0.732293, rec=0.723088
+    
+    Evaluation on DataSet test:
+    SpanFPreRecMetric: f=0.784307, pre=0.779371, rec=0.789306
+    Evaluation at Epoch 2/100. Step:2810/140500. SpanFPreRecMetric: f=0.784307, pre=0.779371, rec=0.789306
+    
+    Evaluation on DataSet test:                                                                                          
+    SpanFPreRecMetric: f=0.810068, pre=0.811003, rec=0.809136
+    Evaluation at Epoch 3/100. Step:4215/140500. SpanFPreRecMetric: f=0.810068, pre=0.811003, rec=0.809136
+    
+    Evaluation on DataSet test:                                                                                          
+    SpanFPreRecMetric: f=0.829592, pre=0.84153, rec=0.817989
+    Evaluation at Epoch 4/100. Step:5620/140500. SpanFPreRecMetric: f=0.829592, pre=0.84153, rec=0.817989
+    
+    Evaluation on DataSet test:
+    SpanFPreRecMetric: f=0.828789, pre=0.837096, rec=0.820644
+    Evaluation at Epoch 5/100. Step:7025/140500. SpanFPreRecMetric: f=0.828789, pre=0.837096, rec=0.820644
+
+

docs/source/tutorials/tutorial_7_modules_models.rst

@@ -0,0 +1,207 @@
+======================================
+使用Modules和Models快速搭建自定义模型
+======================================
+
+:mod:`~fastNLP.modules` 和 :mod:`~fastNLP.models` 用于构建 fastNLP 所需的神经网络模型，它可以和 torch.nn 中的模型一起使用。
+下面我们会分三节介绍编写构建模型的具体方法。
+
+
+----------------------
+使用 models 中的模型
+----------------------
+
+fastNLP 在 :mod:`~fastNLP.models` 模块中内置了如 :class:`~fastNLP.models.CNNText` 、
+:class:`~fastNLP.models.SeqLabeling` 等完整的模型，以供用户直接使用。
+以 :class:`~fastNLP.models.CNNText` 为例，我们看一个简单的文本分类的任务的实现过程。
+
+首先是数据读入和处理部分，这里的代码和 :doc:`快速入门 </user/quickstart>` 中一致。
+
+.. code-block:: python
+
+    from fastNLP.io import CSVLoader
+    from fastNLP import Vocabulary, CrossEntropyLoss, AccuracyMetric
+
+    loader = CSVLoader(headers=('raw_sentence', 'label'), sep='\t')
+    dataset = loader.load("./sample_data/tutorial_sample_dataset.csv")
+
+    dataset.apply(lambda x: x['raw_sentence'].lower(), new_field_name='sentence')
+    dataset.apply_field(lambda x: x.split(), field_name='sentence', new_field_name='words', is_input=True)
+    dataset.apply(lambda x: int(x['label']), new_field_name='target', is_target=True)
+
+    train_dev_data, test_data = dataset.split(0.1)
+    train_data, dev_data = train_dev_data.split(0.1)
+
+    vocab = Vocabulary(min_freq=2).from_dataset(train_data, field_name='words')
+    vocab.index_dataset(train_data, dev_data, test_data, field_name='words', new_field_name='words')
+
+然后我们从 :mod:`~fastNLP.models` 中导入 ``CNNText`` 模型，用它进行训练
+
+.. code-block:: python
+
+    from fastNLP.models import CNNText
+    from fastNLP import Trainer
+
+    model_cnn = CNNText((len(vocab),50), num_classes=5, padding=2, dropout=0.1)
+
+    trainer = Trainer(model=model_cnn, train_data=train_data, dev_data=dev_data,
+                      loss=CrossEntropyLoss(), metrics=AccuracyMetric())
+    trainer.train()
+
+在 iPython 环境输入 `model_cnn` ，我们可以看到 ``model_cnn`` 的网络结构
+
+.. parsed-literal::
+
+    CNNText(
+      (embed): Embedding(
+        169, 50
+        (dropout): Dropout(p=0.0)
+      )
+      (conv_pool): ConvMaxpool(
+        (convs): ModuleList(
+          (0): Conv1d(50, 3, kernel_size=(3,), stride=(1,), padding=(2,))
+          (1): Conv1d(50, 4, kernel_size=(4,), stride=(1,), padding=(2,))
+          (2): Conv1d(50, 5, kernel_size=(5,), stride=(1,), padding=(2,))
+        )
+      )
+      (dropout): Dropout(p=0.1)
+      (fc): Linear(in_features=12, out_features=5, bias=True)
+    )
+
+FastNLP 中内置的 models 如下表所示，您可以点击具体的名称查看详细的 API：
+
+.. csv-table::
+   :header: 名称, 介绍
+
+   :class:`~fastNLP.models.CNNText` , 使用 CNN 进行文本分类的模型
+   :class:`~fastNLP.models.SeqLabeling` , 简单的序列标注模型
+   :class:`~fastNLP.models.AdvSeqLabel` , 更大网络结构的序列标注模型
+   :class:`~fastNLP.models.ESIM` , ESIM 模型的实现
+   :class:`~fastNLP.models.StarTransEnc` , 带 word-embedding的Star-Transformer模 型
+   :class:`~fastNLP.models.STSeqLabel` , 用于序列标注的 Star-Transformer 模型
+   :class:`~fastNLP.models.STNLICls` ,用于自然语言推断 (NLI) 的 Star-Transformer 模型
+   :class:`~fastNLP.models.STSeqCls` , 用于分类任务的 Star-Transformer 模型
+   :class:`~fastNLP.models.BiaffineParser` , Biaffine 依存句法分析网络的实现
+
+----------------------------
+使用 nn.torch 编写模型
+----------------------------
+
+FastNLP 完全支持使用 pyTorch 编写的模型，但与 pyTorch 中编写模型的常见方法不同，
+用于 fastNLP 的模型中 forward 函数需要返回一个字典，字典中至少需要包含 ``pred`` 这个字段。
+
+下面是使用 pyTorch 中的 torch.nn 模块编写的文本分类，注意观察代码中标注的向量维度。
+由于 pyTorch 使用了约定俗成的维度设置，使得 forward 中需要多次处理维度顺序
+
+.. code-block:: python
+
+    import torch
+    import torch.nn as nn
+
+    class LSTMText(nn.Module):
+        def __init__(self, vocab_size, embedding_dim, output_dim, hidden_dim=64, num_layers=2, dropout=0.5):
+            super().__init__()
+
+            self.embedding = nn.Embedding(vocab_size, embedding_dim)
+            self.lstm = nn.LSTM(embedding_dim, hidden_dim, num_layers=num_layers, bidirectional=True, dropout=dropout)
+            self.fc = nn.Linear(hidden_dim * 2, output_dim)
+            self.dropout = nn.Dropout(dropout)
+
+        def forward(self, words):
+            # (input) words : (batch_size, seq_len)
+            words = words.permute(1,0)
+            # words : (seq_len, batch_size)
+
+            embedded = self.dropout(self.embedding(words))
+            # embedded : (seq_len, batch_size, embedding_dim)
+            output, (hidden, cell) = self.lstm(embedded)
+            # output: (seq_len, batch_size, hidden_dim * 2)
+            # hidden: (num_layers * 2, batch_size, hidden_dim)
+            # cell: (num_layers * 2, batch_size, hidden_dim)
+
+            hidden = torch.cat((hidden[-2, :, :], hidden[-1, :, :]), dim=1)
+            hidden = self.dropout(hidden)
+            # hidden: (batch_size, hidden_dim * 2)
+
+            pred = self.fc(hidden.squeeze(0))
+            # result: (batch_size, output_dim)
+            return {"pred":pred}
+
+我们同样可以在 iPython 环境中查看这个模型的网络结构
+
+.. parsed-literal::
+
+    LSTMText(
+      (embedding): Embedding(169, 50)
+      (lstm): LSTM(50, 64, num_layers=2, dropout=0.5, bidirectional=True)
+      (fc): Linear(in_features=128, out_features=5, bias=True)
+      (dropout): Dropout(p=0.5)
+    )
+
+----------------------------
+使用 modules 编写模型
+----------------------------
+
+下面我们使用 :mod:`fastNLP.modules` 中的组件来构建同样的网络。由于 fastNLP 统一把 ``batch_size`` 放在第一维，
+在编写代码的过程中会有一定的便利。
+
+.. code-block:: python
+
+    from fastNLP.modules import Embedding, LSTM, MLP
+
+    class Model(nn.Module):
+        def __init__(self, vocab_size, embedding_dim, output_dim, hidden_dim=64, num_layers=2, dropout=0.5):
+            super().__init__()
+
+            self.embedding = Embedding((vocab_size, embedding_dim))
+            self.lstm = LSTM(embedding_dim, hidden_dim, num_layers=num_layers, bidirectional=True)
+            self.mlp = MLP([hidden_dim*2,output_dim], dropout=dropout)
+
+        def forward(self, words):
+            embedded = self.embedding(words)
+            _,(hidden,_) = self.lstm(embedded)
+            pred = self.mlp(torch.cat((hidden[-1],hidden[-2]),dim=1))
+            return {"pred":pred}
+
+我们自己编写模型的网络结构如下
+
+.. parsed-literal::
+
+    Model(
+      (embedding): Embedding(
+        169, 50
+        (dropout): Dropout(p=0.0)
+      )
+      (lstm): LSTM(
+        (lstm): LSTM(50, 64, num_layers=2, batch_first=True, bidirectional=True)
+      )
+      (mlp): MLP(
+        (hiddens): ModuleList()
+        (output): Linear(in_features=128, out_features=5, bias=True)
+        (dropout): Dropout(p=0.5)
+      )
+    )
+
+FastNLP 中包含的各种模块如下表，您可以点击具体的名称查看详细的 API，也可以通过 :doc:`/fastNLP.modules` 进行了解。
+
+.. csv-table::
+   :header: 名称, 介绍
+
+   :class:`~fastNLP.modules.ConvolutionCharEncoder` , char级别的卷积 encoder
+   :class:`~fastNLP.modules.LSTMCharEncoder` , char级别基于LSTM的 encoder
+   :class:`~fastNLP.modules.ConvMaxpool` , 结合了Convolution和Max-Pooling于一体的模块
+   :class:`~fastNLP.modules.LSTM` , LSTM模块, 轻量封装了PyTorch的LSTM
+   :class:`~fastNLP.modules.StarTransformer` , Star-Transformer 的encoder部分
+   :class:`~fastNLP.modules.TransformerEncoder` , Transformer的encoder模块，不包含embedding层
+   :class:`~fastNLP.modules.VarRNN` , Variational Dropout RNN 模块
+   :class:`~fastNLP.modules.VarLSTM` , Variational Dropout LSTM 模块
+   :class:`~fastNLP.modules.VarGRU` , Variational Dropout GRU 模块
+   :class:`~fastNLP.modules.MaxPool` , Max-pooling模块
+   :class:`~fastNLP.modules.MaxPoolWithMask` , 带mask矩阵的max pooling。在做 max-pooling的时候不会考虑mask值为0的位置。
+   :class:`~fastNLP.modules.AvgPool` , Average-pooling模块
+   :class:`~fastNLP.modules.AvgPoolWithMask` , 带mask矩阵的average pooling。在做 average-pooling的时候不会考虑mask值为0的位置。
+   :class:`~fastNLP.modules.MultiHeadAttention` , MultiHead Attention 模块
+   :class:`~fastNLP.modules.MLP` , 简单的多层感知器模块
+   :class:`~fastNLP.modules.ConditionalRandomField` , 条件随机场模块
+   :class:`~fastNLP.modules.viterbi_decode` , 给定一个特征矩阵以及转移分数矩阵，计算出最佳的路径以及对应的分数 （与 :class:`~fastNLP.modules.ConditionalRandomField` 配合使用）
+   :class:`~fastNLP.modules.allowed_transitions` , 给定一个id到label的映射表，返回所有可以跳转的列表（与 :class:`~fastNLP.modules.ConditionalRandomField` 配合使用）
+   :class:`~fastNLP.modules.TimestepDropout` , 简单包装过的Dropout 组件

docs/source/tutorials/tutorial_8_metrics.rst

@@ -0,0 +1,121 @@
+===============================
+使用Metric快速评测你的模型
+===============================
+
+在进行训练时，fastNLP提供了各种各样的 :mod:`~fastNLP.core.metrics` 。
+如 :doc:`/user/quickstart`  中所介绍的，:class:`~fastNLP.AccuracyMetric` 类的对象被直接传到 :class:`~fastNLP.Trainer` 中用于训练
+
+.. code-block:: python
+
+    from fastNLP import Trainer, CrossEntropyLoss, AccuracyMetric
+
+    trainer = Trainer(model=model, train_data=train_data, dev_data=dev_data,
+                      loss=CrossEntropyLoss(), metrics=AccuracyMetric())
+    trainer.train()
+
+除了 :class:`~fastNLP.AccuracyMetric` 之外，:class:`~fastNLP.SpanFPreRecMetric` 也是一种非常见的评价指标，
+例如在序列标注问题中，常以span的方式计算 F-measure, precision, recall。
+
+另外，fastNLP 还实现了用于抽取式QA（如SQuAD）的metric :class:`~fastNLP.ExtractiveQAMetric`。
+用户可以参考下面这个表格，点击第一列查看各个 :mod:`~fastNLP.core.metrics` 的详细文档。
+
+.. csv-table::
+   :header: 名称, 介绍
+
+   :class:`~fastNLP.core.metrics.MetricBase` , 自定义metrics需继承的基类
+   :class:`~fastNLP.core.metrics.AccuracyMetric` , 简单的正确率metric
+   :class:`~fastNLP.core.metrics.SpanFPreRecMetric` , "同时计算 F-measure, precision, recall 值的 metric"
+   :class:`~fastNLP.core.metrics.ExtractiveQAMetric` , 用于抽取式QA任务 的metric
+
+更多的 :mod:`~fastNLP.core.metrics` 正在被添加到 fastNLP 当中，敬请期待。
+
+------------------------------
+定义自己的metrics
+------------------------------
+
+在定义自己的metrics类时需继承 fastNLP 的 :class:`~fastNLP.core.metrics.MetricBase`,
+并覆盖写入 ``evaluate`` 和 ``get_metric`` 方法。
+
+    evaluate(xxx) 中传入一个批次的数据，将针对一个批次的预测结果做评价指标的累计
+
+    get_metric(xxx) 当所有数据处理完毕时调用该方法，它将根据 evaluate函数累计的评价指标统计量来计算最终的评价结果
+
+以分类问题中，Accuracy计算为例，假设model的forward返回dict中包含 `pred` 这个key, 并且该key需要用于Accuracy::
+
+    class Model(nn.Module):
+        def __init__(xxx):
+            # do something
+        def forward(self, xxx):
+            # do something
+            return {'pred': pred, 'other_keys':xxx} # pred's shape: batch_size x num_classes
+
+假设dataset中 `label` 这个field是需要预测的值，并且该field被设置为了target
+对应的AccMetric可以按如下的定义, version1, 只使用这一次::
+
+    class AccMetric(MetricBase):
+        def __init__(self):
+            super().__init__()
+
+            # 根据你的情况自定义指标
+            self.corr_num = 0
+            self.total = 0
+
+        def evaluate(self, label, pred): # 这里的名称需要和dataset中target field与model返回的key是一样的，不然找不到对应的value
+            # dev或test时，每个batch结束会调用一次该方法，需要实现如何根据每个batch累加metric
+            self.total += label.size(0)
+            self.corr_num += label.eq(pred).sum().item()
+
+        def get_metric(self, reset=True): # 在这里定义如何计算metric
+            acc = self.corr_num/self.total
+            if reset: # 是否清零以便重新计算
+                self.corr_num = 0
+                self.total = 0
+            return {'acc': acc} # 需要返回一个dict，key为该metric的名称，该名称会显示到Trainer的progress bar中
+
+
+version2，如果需要复用Metric，比如下一次使用AccMetric时，dataset中目标field不叫label而叫y，或者model的输出不是pred::
+
+    class AccMetric(MetricBase):
+        def __init__(self, label=None, pred=None):
+            # 假设在另一场景使用时，目标field叫y，model给出的key为pred_y。则只需要在初始化AccMetric时，
+            #   acc_metric = AccMetric(label='y', pred='pred_y')即可。
+            # 当初始化为acc_metric = AccMetric()，即label=None, pred=None, fastNLP会直接使用'label', 'pred'作为key去索取对
+            #   应的的值
+            super().__init__()
+            self._init_param_map(label=label, pred=pred) # 该方法会注册label和pred. 仅需要注册evaluate()方法会用到的参数名即可
+            # 如果没有注册该则效果与version1就是一样的
+
+            # 根据你的情况自定义指标
+            self.corr_num = 0
+            self.total = 0
+
+        def evaluate(self, label, pred): # 这里的参数名称需要和self._init_param_map()注册时一致。
+            # dev或test时，每个batch结束会调用一次该方法，需要实现如何根据每个batch累加metric
+            self.total += label.size(0)
+            self.corr_num += label.eq(pred).sum().item()
+
+        def get_metric(self, reset=True): # 在这里定义如何计算metric
+            acc = self.corr_num/self.total
+            if reset: # 是否清零以便重新计算
+                self.corr_num = 0
+                self.total = 0
+            return {'acc': acc} # 需要返回一个dict，key为该metric的名称，该名称会显示到Trainer的progress bar中
+
+
+``MetricBase`` 将会在输入的字典 ``pred_dict`` 和 ``target_dict`` 中进行检查.
+``pred_dict`` 是模型当中 ``forward()`` 函数或者 ``predict()`` 函数的返回值.
+``target_dict`` 是DataSet当中的ground truth, 判定ground truth的条件是field的 ``is_target`` 被设置为True.
+
+``MetricBase`` 会进行以下的类型检测:
+
+1. self.evaluate当中是否有varargs, 这是不支持的.
+2. self.evaluate当中所需要的参数是否既不在 ``pred_dict`` 也不在 ``target_dict`` .
+3. self.evaluate当中所需要的参数是否既在 ``pred_dict`` 也在 ``target_dict`` .
+
+除此以外，在参数被传入self.evaluate以前，这个函数会检测 ``pred_dict`` 和 ``target_dict`` 当中没有被用到的参数
+如果kwargs是self.evaluate的参数，则不会检测
+
+
+self.evaluate将计算一个批次(batch)的评价指标，并累计。 没有返回值
+self.get_metric将统计当前的评价指标并返回评价结果, 返回值需要是一个dict, key是指标名称，value是指标的值
+

docs/source/tutorials/tutorial_9_callback.rst

@@ -0,0 +1,67 @@
+===================================================
+使用Callback自定义你的训练过程
+===================================================
+
+在训练时，我们常常要使用trick来提高模型的性能（如调节学习率），或者要打印训练中的信息。
+这里我们提供Callback类，在Trainer中插入代码，完成一些自定义的操作。
+
+我们使用和 :doc:`/user/quickstart` 中一样的任务来进行详细的介绍。
+给出一段评价性文字，预测其情感倾向是积极（label=1）、消极（label=0）还是中性（label=2），使用 :class:`~fastNLP.Trainer`  和  :class:`~fastNLP.Tester`  来进行快速训练和测试。
+关于数据处理，Loss和Optimizer的选择可以看其他教程，这里仅在训练时加入学习率衰减。
+
+---------------------
+Callback的构建和使用
+---------------------
+
+创建Callback
+    我们可以继承fastNLP :class:`~fastNLP.Callback` 类来定义自己的Callback。
+    这里我们实现一个让学习率线性衰减的Callback。
+
+    .. code-block:: python
+
+        import fastNLP
+
+        class LRDecay(fastNLP.Callback):
+            def __init__(self):
+                super(MyCallback, self).__init__()
+                self.base_lrs = []
+                self.delta = []
+
+            def on_train_begin(self):
+                # 初始化，仅训练开始时调用
+                self.base_lrs = [pg['lr'] for pg in self.optimizer.param_groups]
+                self.delta = [float(lr) / self.n_epochs for lr in self.base_lrs]
+
+            def on_epoch_end(self):
+                # 每个epoch结束时，更新学习率
+                ep = self.epoch
+                lrs = [lr - d * ep for lr, d in zip(self.base_lrs, self.delta)]
+                self.change_lr(lrs)
+
+            def change_lr(self, lrs):
+                for pg, lr in zip(self.optimizer.param_groups, lrs):
+                    pg['lr'] = lr
+
+    这里，:class:`~fastNLP.Callback` 中所有以 ``on_`` 开头的类方法会在 :class:`~fastNLP.Trainer` 的训练中在特定时间调用。
+    如 on_train_begin() 会在训练开始时被调用，on_epoch_end() 会在每个 epoch 结束时调用。
+    具体有哪些类方法，参见文档 :class:`~fastNLP.Callback` 。
+
+    另外，为了使用方便，可以在 :class:`~fastNLP.Callback` 内部访问 :class:`~fastNLP.Trainer` 中的属性，如 optimizer, epoch, step，分别对应训练时的优化器，当前epoch数，和当前的总step数。
+    具体可访问的属性，参见文档 :class:`~fastNLP.Callback` 。
+
+使用Callback
+    在定义好 :class:`~fastNLP.Callback` 之后，就能将它传入Trainer的 ``callbacks`` 参数，在实际训练时使用。
+
+    .. code-block:: python
+
+        """
+        数据预处理，模型定义等等
+        """
+
+        trainer = fastNLP.Trainer(
+            model=model, train_data=train_data, dev_data=dev_data,
+            optimizer=optimizer, metrics=metrics,
+            batch_size=10, n_epochs=100,
+            callbacks=[LRDecay()])
+
+        trainer.train()

docs/source/user/docs_in_code.rst

@@ -0,0 +1,3 @@
+===============
+在代码中写文档
+===============

docs/source/user/example.rst

@@ -20,7 +20,13 @@
 小标题4
 -------------------
 
-参考 http://docutils.sourceforge.net/docs/user/rst/quickref.html
+推荐使用大标题、小标题3和小标题4
+
+官方文档 http://docutils.sourceforge.net/docs/user/rst/quickref.html
+
+`熟悉markdown的同学推荐参考这篇文章 <https://macplay.github.io/posts/cong-markdown-dao-restructuredtext/#id30>`_
+
+\<\>内表示的是链接地址，\<\>外的是显示到外面的文字
 
 常见语法
 ============
@@ -75,6 +81,7 @@ http://docutils.sf.net/ 孤立的网址会自动生成链接
     不显示冒号的代码块
 
 .. code-block:: python
+
     :linenos:
     :emphasize-lines: 1,3
 
@@ -83,22 +90,67 @@ http://docutils.sf.net/ 孤立的网址会自动生成链接
     print("有行号和高亮")
 
 数学块
+==========
 
 .. math::
 
     H_2O + Na = NaOH + H_2 \uparrow
 
+复杂表格
+==========
+
++------------------------+------------+----------+----------+
+| Header row, column 1   | Header 2   | Header 3 | Header 4 |
+| (header rows optional) |            |          |          |
++========================+============+==========+==========+
+| body row 1, column 1   | column 2   | column 3 | column 4 |
++------------------------+------------+----------+----------+
+| body row 2             | Cells may span columns.          |
++------------------------+------------+---------------------+
+| body row 3             | Cells may  | - Table cells       |
++------------------------+ span rows. | - contain           |
+| body row 4             |            | - body elements.    |
++------------------------+------------+---------------------+
+
+简易表格
+==========
+
+=====  =====  ======
+   Inputs     Output
+------------  ------
+  A      B    A or B
+=====  =====  ======
+False  False  False
+True   True   True
+=====  =====  ======
+
+csv 表格
+============
+
+.. csv-table::
+   :header: sentence, target
+
+   This is the first instance ., 0
+   Second instance ., 1
+   Third instance ., 1
+   ..., ...
+
+
+
+[重要]各种链接
+===================
+
+各种链接帮助我们连接到fastNLP文档的各个位置
 
-各种连接
-===========
+\<\>内表示的是链接地址，\<\>外的是显示到外面的文字
 
-:doc:`/user/with_fitlog`
+:doc:`根据文件名链接 </user/quickstart>`
 
 :mod:`~fastNLP.core.batch`
 
 :class:`~fastNLP.Batch`
 
-~表示指显示最后一项
+~表示只显示最后一项
 
 :meth:`fastNLP.DataSet.apply`
 

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/quickstart.rst

@@ -121,4 +121,4 @@
     In Epoch:6/Step:12, got best dev performance:AccuracyMetric: acc=0.8
     Reloaded the best model.
 
-这份教程只是简单地介绍了使用 fastNLP 工作的流程，具体的细节分析见 :doc:`/user/tutorial_one`
+这份教程只是简单地介绍了使用 fastNLP 工作的流程，更多的教程分析见 :doc:`/user/tutorials`

docs/source/user/tutorial_one.rst

@@ -1,371 +0,0 @@
-===============
-详细指南
-===============
-
-我们使用和 :doc:`/user/quickstart` 中一样的任务来进行详细的介绍。给出一段文字，预测它的标签是0~4中的哪一个
-(数据来源 `kaggle <https://www.kaggle.com/c/sentiment-analysis-on-movie-reviews>`_ )。
-
---------------
-数据处理
---------------
-
-数据读入
-    我们可以使用 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=('raw_sentence', 'label'), sep='\t')
-        dataset = loader.load("./sample_data/tutorial_sample_dataset.csv")
-
-    除了读取数据外，fastNLP 还提供了读取其它文件类型的 Loader 类、读取 Embedding的 Loader 等。详见 :doc:`/fastNLP.io` 。
-
-Instance 和 DataSet
-    fastNLP 中的 :class:`~fastNLP.DataSet` 类对象类似于二维表格，它的每一列是一个 :mod:`~fastNLP.core.field`
-    每一行是一个 :mod:`~fastNLP.core.instance` 。我们可以手动向数据集中添加 :class:`~fastNLP.Instance` 类的对象
-
-    .. code-block:: python
-
-        from fastNLP import Instance
-
-        dataset.append(Instance(raw_sentence='fake data', label='0'))
-
-    此时的 ``dataset[-1]`` 的值如下,可以看到，数据集中的每个数据包含 ``raw_sentence`` 和 ``label`` 两个
-    :mod:`~fastNLP.core.field` ，他们的类型都是 ``str`` ::
-
-        {'raw_sentence': fake data type=str, 'label': 0 type=str}
-
-field 的修改
-    我们使用 :class:`~fastNLP.DataSet` 类的 :meth:`~fastNLP.DataSet.apply` 方法将 ``raw_sentence`` 中字母变成小写，并将句子分词。
-    同时也将 ``label`` :mod:`~fastNLP.core.field` 转化为整数并改名为 ``target``
-
-    .. code-block:: python
-
-        dataset.apply(lambda x: x['raw_sentence'].lower(), new_field_name='sentence')
-        dataset.apply_field(lambda x: x.split(), field_name='sentence', new_field_name='words')
-        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.Vocabularyindex_dataset`
-    将单词序列转化为训练可用的数字序列。
-
-    .. code-block:: python
-
-        from fastNLP import Vocabulary
-
-        vocab = Vocabulary(min_freq=2).from_dataset(dataset, field_name='words')
-        vocab.index_dataset(dataset, field_name='words',new_field_name='words')
-
-数据集分割
-    除了修改 :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)
-        len(train_data), len(dev_data), len(test_data)
-
----------------------
-使用内置模型训练
----------------------
-
-内置模型的输入输出命名
-    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)
-
-    在给 :class:`~fastNLP.DataSet` 中 :mod:`~fastNLP.core.field` 改名后，我们还需要设置训练所需的输入和目标，这里使用的是
-    :meth:`~fastNLP.DataSet.set_input` 和 :meth:`~fastNLP.DataSet.set_target` 两个函数。
-
-    .. code-block:: python
-
-        dataset.set_input(Const.INPUT, Const.INPUT_LEN)
-        dataset.set_target(Const.TARGET)
-
-快速训练
-    现在我们可以导入 fastNLP 内置的文本分类模型 :class:`~fastNLP.models.CNNText` ，并使用 :class:`~fastNLP.Trainer` 进行训练了
-    （其中 ``loss`` 和 ``metrics`` 的定义，我们将在后续两段代码中给出）。
-
-    .. code-block:: python
-
-        from fastNLP.models import CNNText
-        from fastNLP import Trainer
-
-        model = CNNText((len(vocab),50), num_classes=5, padding=2, dropout=0.1)
-
-        trainer = Trainer(model=model_cnn, train_data=train_data, dev_data=dev_data,
-                        loss=loss, metrics=metrics)
-        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])
-        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-05-09-10-59-39
-        Evaluation at Epoch 1/10. Step:2/20. AccuracyMetric: acc=0.333333
-
-        Evaluation at Epoch 2/10. Step:4/20. AccuracyMetric: acc=0.533333
-
-        Evaluation at Epoch 3/10. Step:6/20. AccuracyMetric: acc=0.533333
-
-        Evaluation at Epoch 4/10. Step:8/20. AccuracyMetric: acc=0.533333
-
-        Evaluation at Epoch 5/10. Step:10/20. AccuracyMetric: acc=0.6
-
-        Evaluation at Epoch 6/10. Step:12/20. AccuracyMetric: acc=0.8
-
-        Evaluation at Epoch 7/10. Step:14/20. AccuracyMetric: acc=0.8
-
-        Evaluation at Epoch 8/10. Step:16/20. AccuracyMetric: acc=0.733333
-
-        Evaluation at Epoch 9/10. Step:18/20. AccuracyMetric: acc=0.733333
-
-        Evaluation at Epoch 10/10. Step:20/20. AccuracyMetric: acc=0.733333
-
-
-        In Epoch:6/Step:12, got best dev performance:AccuracyMetric: acc=0.8
-        Reloaded the best model.
-
-损失函数
-    训练模型需要提供一个损失函数, 下面提供了一个在分类问题中常用的交叉熵损失。注意它的 **初始化参数** 。
-    ``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)
-
-快速测试
-    与 :class:`~fastNLP.Trainer` 对应，fastNLP 也提供了 :class:`~fastNLP.Tester` 用于快速测试，用法如下
-
-    .. code-block:: python
-
-        from fastNLP import Tester
-
-        tester = Tester(test_data, model_cnn, metrics=AccuracyMetric())
-        tester.test()
-
----------------------
-编写自己的模型
----------------------
-
-因为 fastNLP 是基于 `PyTorch <https://pytorch.org/>`_ 开发的框架，所以我们可以基于 PyTorch 模型编写自己的神经网络模型。
-与标准的 PyTorch 模型不同，fastNLP 模型中 forward 方法返回的是一个字典，字典中至少需要包含 "pred" 这个字段。
-而 forward 方法的参数名称必须与 :class:`~fastNLP.DataSet` 中用 :meth:`~fastNLP.DataSet.set_input` 设定的名称一致。
-模型定义的代码如下:
-
-.. code-block:: python
-
-    import torch
-    import torch.nn as nn
-
-    class LSTMText(nn.Module):
-        def __init__(self, vocab_size, embedding_dim, output_dim, hidden_dim=64, num_layers=2, dropout=0.5):
-            super().__init__()
-
-            self.embedding = nn.Embedding(vocab_size, embedding_dim)
-            self.lstm = nn.LSTM(embedding_dim, hidden_dim, num_layers=num_layers, bidirectional=True, dropout=dropout)
-            self.fc = nn.Linear(hidden_dim * 2, output_dim)
-            self.dropout = nn.Dropout(dropout)
-
-        def forward(self, words):
-            # (input) words : (batch_size, seq_len)
-            words = words.permute(1,0)
-            # words : (seq_len, batch_size)
-
-            embedded = self.dropout(self.embedding(words))
-            # embedded : (seq_len, batch_size, embedding_dim)
-            output, (hidden, cell) = self.lstm(embedded)
-            # output: (seq_len, batch_size, hidden_dim * 2)
-            # hidden: (num_layers * 2, batch_size, hidden_dim)
-            # cell: (num_layers * 2, batch_size, hidden_dim)
-
-            hidden = torch.cat((hidden[-2, :, :], hidden[-1, :, :]), dim=1)
-            hidden = self.dropout(hidden)
-            # hidden: (batch_size, hidden_dim * 2)
-
-            pred = self.fc(hidden.squeeze(0))
-            # result: (batch_size, output_dim)
-            return {"pred":pred}
-
-模型的使用方法与内置模型 :class:`~fastNLP.models.CNNText`  一致
-
-.. code-block:: python
-
-    model_lstm = LSTMText(len(vocab),50,5)
-
-    trainer = Trainer(model=model_lstm, train_data=train_data, dev_data=dev_data,
-                    loss=loss, metrics=metrics)
-    trainer.train()
-
-    tester = Tester(test_data, model_lstm, metrics=AccuracyMetric())
-    tester.test()
-
-.. todo::
-    使用 :doc:`/fastNLP.modules` 编写模型
-
---------------------------
-自己编写训练过程
---------------------------
-
-如果你想用类似 PyTorch 的使用方法，自己编写训练过程，你可以参考下面这段代码。其中使用了 fastNLP 提供的 :class:`~fastNLP.Batch`
-来获得小批量训练的小批量数据，使用 :class:`~fastNLP.BucketSampler` 做为 :class:`~fastNLP.Batch` 的参数来选择采样的方式。
-这段代码中使用了 PyTorch 的 `torch.optim.Adam` 优化器 和 `torch.nn.CrossEntropyLoss` 损失函数，并自己计算了正确率
-
-.. code-block:: python
-
-    from fastNLP import BucketSampler
-    from fastNLP import Batch
-    import torch
-    import time
-
-    model = CNNText((len(vocab),50), num_classes=5, padding=2, dropout=0.1)
-
-    def train(epoch, data):
-        optim = torch.optim.Adam(model.parameters(), lr=0.001)
-        lossfunc = torch.nn.CrossEntropyLoss()
-        batch_size = 32
-
-        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()
-        for i in range(epoch):
-            loss_list = []
-            for batch_x, batch_y in train_batch:
-                optim.zero_grad()
-                output = model(batch_x['words'])
-                loss = lossfunc(output['pred'], batch_y['target'])
-                loss.backward()
-                optim.step()
-                loss_list.append(loss.item())
-            print('Epoch {:d} Avg Loss: {:.2f}'.format(i, sum(loss_list) / len(loss_list)),end=" ")
-            print('{:d}ms'.format(round((time.time()-start_time)*1000)))
-            loss_list.clear()
-
-    train(10, train_data)
-
-    tester = Tester(test_data, model, metrics=AccuracyMetric())
-    tester.test()
-
-这段代码的输出如下::
-
-    Epoch 0 Avg Loss: 2.76 17ms
-    Epoch 1 Avg Loss: 2.55 29ms
-    Epoch 2 Avg Loss: 2.37 41ms
-    Epoch 3 Avg Loss: 2.30 53ms
-    Epoch 4 Avg Loss: 2.12 65ms
-    Epoch 5 Avg Loss: 2.16 76ms
-    Epoch 6 Avg Loss: 1.88 88ms
-    Epoch 7 Avg Loss: 1.84 99ms
-    Epoch 8 Avg Loss: 1.71 111ms
-    Epoch 9 Avg Loss: 1.62 122ms
-    [tester]
-    AccuracyMetric: acc=0.142857
-
-----------------------------------
-使用 Callback 增强 Trainer
-----------------------------------
-
-如果你不想自己实现繁琐的训练过程，只希望在训练过程中实现一些自己的功能（比如：输出从训练开始到当前 batch 结束的总时间），
-你可以使用 fastNLP 提供的 :class:`~fastNLP.Callback` 类。下面的例子中，我们继承 :class:`~fastNLP.Callback` 类实现了这个功能。
-
-.. code-block:: python
-
-    from fastNLP import Callback
-
-    start_time = time.time()
-
-    class MyCallback(Callback):
-        def on_epoch_end(self):
-            print('Sum Time: {:d}ms\n\n'.format(round((time.time()-start_time)*1000)))
-
-
-    model = CNNText((len(vocab),50), num_classes=5, padding=2, dropout=0.1)
-    trainer = Trainer(model=model, train_data=train_data, dev_data=dev_data,
-                      loss=CrossEntropyLoss(), metrics=AccuracyMetric(), callbacks=[MyCallback()])
-    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, 16])
-        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-05-12-21-38-40
-    Evaluation at Epoch 1/10. Step:2/20. AccuracyMetric: acc=0.285714
-
-    Sum Time: 51ms
-
-
-    …………………………
-
-
-    Evaluation at Epoch 10/10. Step:20/20. AccuracyMetric: acc=0.857143
-
-    Sum Time: 212ms
-
-
-
-    In Epoch:10/Step:20, got best dev performance:AccuracyMetric: acc=0.857143
-    Reloaded the best model.
-
-这个例子只是介绍了 :class:`~fastNLP.Callback` 类的使用方法。实际应用（比如：负采样、Learning Rate Decay、Early Stop 等）中
-很多功能已经被 fastNLP 实现了。你可以直接 import 它们使用，详细请查看文档 :doc:`/fastNLP.core.callback` 。

docs/source/user/tutorials.rst

@@ -0,0 +1,20 @@
+========================
+fastNLP 详细使用教程
+========================
+
+这里是更详细的使用教程。对于大部分的用户，我们建议你从第一篇开始顺序阅读；如果你只想了解其中的一部分，也可以进行选读。
+
+.. toctree::
+   :maxdepth: 1
+
+   使用DataSet预处理文本 </tutorials/tutorial_1_data_preprocess>
+   使用Loader和Pipe加载并处理数据集 </tutorials/tutorial_2_load_dataset>
+   使用Embedding模块将文本转成向量 </tutorials/tutorial_3_embedding>
+   动手实现一个文本分类器I-使用Trainer和Tester快速训练和测试 </tutorials/tutorial_4_loss_optimizer>
+   动手实现一个文本分类器II-使用DataSetIter实现自定义训练过程 </tutorials/tutorial_5_datasetiter>
+   快速实现序列标注模型 </tutorials/tutorial_6_seq_labeling>
+   使用Modules和Models快速搭建自定义模型 </tutorials/tutorial_7_modules_models>
+   使用Metric快速评测你的模型 </tutorials/tutorial_8_metrics>
+   使用Callback自定义你的训练过程 </tutorials/tutorial_9_callback>
+   使用fitlog 辅助 fastNLP 进行科研 </tutorials/tutorial_10_fitlog>
+

fastNLP/__init__.py

@@ -1,22 +1,24 @@
 """
-fastNLP 由 :mod:`~fastNLP.core` 、 :mod:`~fastNLP.io` 、:mod:`~fastNLP.modules`、:mod:`~fastNLP.models`
-等子模块组成，你可以点进去查看每个模块的文档。
+fastNLP 由 :mod:`~fastNLP.core` 、 :mod:`~fastNLP.io` 、:mod:`~fastNLP.embeddings` 、 :mod:`~fastNLP.modules`、
+:mod:`~fastNLP.models` 等子模块组成，你可以查看每个模块的文档。
 
 - :mod:`~fastNLP.core` 是fastNLP 的核心模块，包括 DataSet、 Trainer、 Tester 等组件。详见文档 :doc:`/fastNLP.core`
 - :mod:`~fastNLP.io` 是实现输入输出的模块，包括了数据集的读取，模型的存取等功能。详见文档 :doc:`/fastNLP.io`
+- :mod:`~fastNLP.embeddings` 提供用于构建复杂网络模型所需的各种embedding。详见文档 :doc:`/fastNLP.embeddings`
 - :mod:`~fastNLP.modules`  包含了用于搭建神经网络模型的诸多组件，可以帮助用户快速搭建自己所需的网络。详见文档 :doc:`/fastNLP.modules`
-- :mod:`~fastNLP.models` 包含了一些使用 fastNLP 实现的完整网络模型，包括CNNText、SeqLabeling等常见模型。详见文档 :doc:`/fastNLP.models`
+- :mod:`~fastNLP.models` 包含了一些使用 fastNLP 实现的完整网络模型，包括 :class:`~fastNLP.models.CNNText` 、 :class:`~fastNLP.models.SeqLabeling` 等常见模型。详见文档 :doc:`fastNLP.models`
 
 fastNLP 中最常用的组件可以直接从 fastNLP 包中 import ，他们的文档如下：
 """
 __all__ = [
     "Instance",
     "FieldArray",
-
+    
+    
     "DataSetIter",
     "BatchIter",
     "TorchLoaderIter",
-
+    
     "Vocabulary",
     "DataSet",
     "Const",
@@ -30,6 +32,7 @@ __all__ = [
     "TensorboardCallback",
     "LRScheduler",
     "ControlC",
+    "LRFinder",
     
     "Padder",
     "AutoPadder",
@@ -37,12 +40,13 @@ __all__ = [
     
     "AccuracyMetric",
     "SpanFPreRecMetric",
-    "SQuADMetric",
+    "ExtractiveQAMetric",
     
     "Optimizer",
     "SGD",
     "Adam",
-    
+    "AdamW",
+
     "Sampler",
     "SequentialSampler",
     "BucketSampler",
@@ -50,14 +54,19 @@ __all__ = [
     
     "LossFunc",
     "CrossEntropyLoss",
-    "L1Loss", "BCELoss",
+    "L1Loss",
+    "BCELoss",
     "NLLLoss",
     "LossInForward",
     
-    "cache_results"
+    "cache_results",
+
+    'logger'
 ]
-__version__ = '0.4.0'
+__version__ = '0.4.5'
 
-from .core import *
+from . import embeddings
 from . import models
 from . import modules
+from .core import *
+from .io import loader, pipe

fastNLP/core/__init__.py

@@ -1,30 +1,94 @@
 """
 core 模块里实现了 fastNLP 的核心框架，常用的功能都可以从 fastNLP 包中直接 import。当然你也同样可以从 core 模块的子模块中 import，
-例如 Batch 组件有两种 import 的方式::
+例如 :class:`~fastNLP.DataSetIter` 组件有两种 import 的方式::
     
     # 直接从 fastNLP 中 import
-    from fastNLP import Batch
+    from fastNLP import DataSetIter
     
-    # 从 core 模块的子模块 batch 中 import
-    from fastNLP.core.batch import Batch
+    # 从 core 模块的子模块 batch 中 import DataSetIter
+    from fastNLP.core.batch import DataSetIter
 
 对于常用的功能，你只需要在 :doc:`fastNLP` 中查看即可。如果想了解各个子模块的具体作用，您可以在下面找到每个子模块的具体文档。
 
-.. todo::
-    介绍core 的子模块的分工，好像必要性不大
-    
 """
+__all__ = [
+    "DataSet",
+    
+    "Instance",
+    
+    "FieldArray",
+    "Padder",
+    "AutoPadder",
+    "EngChar2DPadder",
+    
+    "Vocabulary",
+    
+    "DataSetIter",
+    "BatchIter",
+    "TorchLoaderIter",
+    
+    "Const",
+    
+    "Tester",
+    "Trainer",
+    
+    "cache_results",
+    "seq_len_to_mask",
+    "get_seq_len",
+    "logger",
+    
+    "Callback",
+    "GradientClipCallback",
+    "EarlyStopCallback",
+    "FitlogCallback",
+    "EvaluateCallback",
+    "LRScheduler",
+    "ControlC",
+    "LRFinder",
+    "TensorboardCallback",
+    "WarmupCallback",
+    'SaveModelCallback',
+    "EchoCallback",
+    "TesterCallback",
+    "CallbackException",
+    "EarlyStopError",
+    
+    "LossFunc",
+    "CrossEntropyLoss",
+    "L1Loss",
+    "BCELoss",
+    "NLLLoss",
+    "LossInForward",
+    
+    "AccuracyMetric",
+    "SpanFPreRecMetric",
+    "ExtractiveQAMetric",
+    
+    "Optimizer",
+    "SGD",
+    "Adam",
+    "AdamW",
+    
+    "SequentialSampler",
+    "BucketSampler",
+    "RandomSampler",
+    "Sampler",
+]
+
+from ._logger import logger
 from .batch import DataSetIter, BatchIter, TorchLoaderIter
-from .callback import Callback, GradientClipCallback, EarlyStopCallback, TensorboardCallback, LRScheduler, ControlC
+from .callback import Callback, GradientClipCallback, EarlyStopCallback, FitlogCallback, EvaluateCallback, \
+    LRScheduler, ControlC, LRFinder, TensorboardCallback, WarmupCallback, SaveModelCallback, EchoCallback, \
+    TesterCallback, CallbackException, EarlyStopError
 from .const import Const
 from .dataset import DataSet
 from .field import FieldArray, Padder, AutoPadder, EngChar2DPadder
 from .instance import Instance
 from .losses import LossFunc, CrossEntropyLoss, L1Loss, BCELoss, NLLLoss, LossInForward
-from .metrics import AccuracyMetric, SpanFPreRecMetric, SQuADMetric
-from .optimizer import Optimizer, SGD, Adam
+from .metrics import AccuracyMetric, SpanFPreRecMetric, ExtractiveQAMetric
+from .optimizer import Optimizer, SGD, Adam, AdamW
 from .sampler import SequentialSampler, BucketSampler, RandomSampler, Sampler
 from .tester import Tester
 from .trainer import Trainer
-from .utils import cache_results, seq_len_to_mask
+from .utils import cache_results, seq_len_to_mask, get_seq_len
 from .vocabulary import Vocabulary

fastNLP/core/_logger.py

@@ -0,0 +1,155 @@
+"""undocumented"""
+
+__all__ = [
+    'logger',
+]
+
+import logging
+import logging.config
+import os
+import sys
+import warnings
+
+ROOT_NAME = 'fastNLP'
+
+try:
+    import fitlog
+except ImportError:
+    fitlog = None
+try:
+    from tqdm.auto import tqdm
+except ImportError:
+    tqdm = None
+
+if tqdm is not None:
+    class TqdmLoggingHandler(logging.Handler):
+        def __init__(self, level=logging.INFO):
+            super().__init__(level)
+        
+        def emit(self, record):
+            try:
+                msg = self.format(record)
+                tqdm.write(msg)
+                self.flush()
+            except (KeyboardInterrupt, SystemExit):
+                raise
+            except:
+                self.handleError(record)
+else:
+    class TqdmLoggingHandler(logging.StreamHandler):
+        def __init__(self, level=logging.INFO):
+            super().__init__(sys.stdout)
+            self.setLevel(level)
+
+
+def _get_level(level):
+    if isinstance(level, int):
+        pass
+    else:
+        level = level.lower()
+        level = {'info': logging.INFO, 'debug': logging.DEBUG,
+                 'warn': logging.WARN, 'warning': logging.WARN,
+                 'error': logging.ERROR}[level]
+    return level
+
+
+def _add_file_handler(logger, path, level='INFO'):
+    for h in logger.handlers:
+        if isinstance(h, logging.FileHandler):
+            if os.path.abspath(path) == h.baseFilename:
+                # file path already added
+                return
+    
+    # File Handler
+    if os.path.exists(path):
+        assert os.path.isfile(path)
+        warnings.warn('log already exists in {}'.format(path))
+    dirname = os.path.abspath(os.path.dirname(path))
+    os.makedirs(dirname, exist_ok=True)
+    
+    file_handler = logging.FileHandler(path, mode='a')
+    file_handler.setLevel(_get_level(level))
+    file_formatter = logging.Formatter(fmt='%(asctime)s - %(module)s - [%(levelname)s] - %(message)s',
+                                       datefmt='%Y/%m/%d %H:%M:%S')
+    file_handler.setFormatter(file_formatter)
+    logger.addHandler(file_handler)
+
+
+def _set_stdout_handler(logger, stdout='tqdm', level='INFO'):
+    level = _get_level(level)
+    if stdout not in ['none', 'plain', 'tqdm']:
+        raise ValueError('stdout must in one of {}'.format(['none', 'plain', 'tqdm']))
+    # make sure to initialize logger only once
+    stream_handler = None
+    for i, h in enumerate(logger.handlers):
+        if isinstance(h, (logging.StreamHandler, TqdmLoggingHandler)):
+            stream_handler = h
+            break
+    if stream_handler is not None:
+        logger.removeHandler(stream_handler)
+    
+    # Stream Handler
+    if stdout == 'plain':
+        stream_handler = logging.StreamHandler(sys.stdout)
+    elif stdout == 'tqdm':
+        stream_handler = TqdmLoggingHandler(level)
+    else:
+        stream_handler = None
+    
+    if stream_handler is not None:
+        stream_formatter = logging.Formatter('%(message)s')
+        stream_handler.setLevel(level)
+        stream_handler.setFormatter(stream_formatter)
+        logger.addHandler(stream_handler)
+
+
+class FastNLPLogger(logging.getLoggerClass()):
+    def __init__(self, name):
+        super().__init__(name)
+    
+    def add_file(self, path='./log.txt', level='INFO'):
+        """add log output file and level"""
+        _add_file_handler(self, path, level)
+    
+    def set_stdout(self, stdout='tqdm', level='INFO'):
+        """set stdout format and level"""
+        _set_stdout_handler(self, stdout, level)
+
+
+logging.setLoggerClass(FastNLPLogger)
+
+
+# print(logging.getLoggerClass())
+# print(logging.getLogger())
+
+def _init_logger(path=None, stdout='tqdm', level='INFO'):
+    """initialize logger"""
+    level = _get_level(level)
+    
+    # logger = logging.getLogger()
+    logger = logging.getLogger(ROOT_NAME)
+    logger.propagate = False
+    logger.setLevel(level)
+    
+    _set_stdout_handler(logger, stdout, level)
+    
+    # File Handler
+    if path is not None:
+        _add_file_handler(logger, path, level)
+    
+    return logger
+
+
+def _get_logger(name=None, level='INFO'):
+    level = _get_level(level)
+    if name is None:
+        name = ROOT_NAME
+    assert isinstance(name, str)
+    if not name.startswith(ROOT_NAME):
+        name = '{}.{}'.format(ROOT_NAME, name)
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+    return logger
+
+
+logger = _init_logger(path=None)

fastNLP/core/_parallel_utils.py

@@ -1,10 +1,14 @@
+"""undocumented"""
+
+__all__ = []
 
 import threading
+
 import torch
+from torch import nn
 from torch.nn.parallel.parallel_apply import get_a_var
-
-from torch.nn.parallel.scatter_gather import scatter_kwargs, gather
 from torch.nn.parallel.replicate import replicate
+from torch.nn.parallel.scatter_gather import scatter_kwargs, gather
 
 
 def parallel_apply(modules, func_name, inputs, kwargs_tup=None, devices=None):
@@ -26,11 +30,11 @@ def parallel_apply(modules, func_name, inputs, kwargs_tup=None, devices=None):
         assert len(modules) == len(devices)
     else:
         devices = [None] * len(modules)
-
+    
     lock = threading.Lock()
     results = {}
     grad_enabled = torch.is_grad_enabled()
-
+    
     def _worker(i, module, input, kwargs, device=None):
         torch.set_grad_enabled(grad_enabled)
         if device is None:
@@ -46,20 +50,20 @@ def parallel_apply(modules, func_name, inputs, kwargs_tup=None, devices=None):
         except Exception as e:
             with lock:
                 results[i] = e
-
+    
     if len(modules) > 1:
         threads = [threading.Thread(target=_worker,
                                     args=(i, module, input, kwargs, device))
                    for i, (module, input, kwargs, device) in
                    enumerate(zip(modules, inputs, kwargs_tup, devices))]
-
+        
         for thread in threads:
             thread.start()
         for thread in threads:
             thread.join()
     else:
         _worker(0, modules[0], inputs[0], kwargs_tup[0], devices[0])
-
+    
     outputs = []
     for i in range(len(inputs)):
         output = results[i]
@@ -78,6 +82,7 @@ def _data_parallel_wrapper(func_name, device_ids, output_device):
     :param output_device: nn.DataParallel中的output_device
     :return:
     """
+    
     def wrapper(network, *inputs, **kwargs):
         inputs, kwargs = scatter_kwargs(inputs, kwargs, device_ids, dim=0)
         if len(device_ids) == 1:
@@ -85,4 +90,18 @@ def _data_parallel_wrapper(func_name, device_ids, output_device):
         replicas = replicate(network, device_ids[:len(inputs)])
         outputs = parallel_apply(replicas, func_name, inputs, kwargs, device_ids[:len(replicas)])
         return gather(outputs, output_device)
+    
     return wrapper
+
+
+def _model_contains_inner_module(model):
+    """
+
+    :param nn.Module model: 模型文件，判断是否内部包含model.module, 多用于check模型是否是nn.DataParallel,
+        nn.parallel.DistributedDataParallel。主要是在做形参匹配的时候需要使用最内部的model的function。
+    :return: bool
+    """
+    if isinstance(model, nn.Module):
+        if isinstance(model, (nn.DataParallel, nn.parallel.DistributedDataParallel)):
+            return True
+    return False

fastNLP/core/batch.py

@@ -1,5 +1,5 @@
 """
-batch 模块实现了 fastNLP 所需的 Batch 类。
+batch 模块实现了 fastNLP 所需的 :class:`~fastNLP.core.batch.DataSetIter` 类。
 
 """
 __all__ = [
@@ -9,17 +9,15 @@ __all__ = [
 ]
 
 import atexit
-from queue import Empty, Full
 
 import numpy as np
 import torch
-import torch.multiprocessing as mp
 import torch.utils.data
 from numbers import Number
 
 from .sampler import SequentialSampler
 from .dataset import DataSet
-
+from ._logger import logger
 _python_is_exit = False
 
 
@@ -50,6 +48,12 @@ class DataSetGetter:
         return len(self.dataset)
 
     def collate_fn(self, batch: list):
+        """
+
+        :param batch: [[idx1, x_dict1, y_dict1], [idx2, x_dict2, y_dict2], [xx, xx, xx]]
+        :return:
+        """
+        # TODO 支持在DataSet中定义collate_fn，因为有时候可能需要不同的field之间融合，比如BERT的场景
         batch_x = {n:[] for n in self.inputs.keys()}
         batch_y = {n:[] for n in self.targets.keys()}
         indices = []
@@ -71,7 +75,7 @@ class DataSetGetter:
                         try:
                             data, flag = _to_tensor(data, f.dtype)
                         except TypeError as e:
-                            print(f"Field {n} cannot be converted to torch.tensor.")
+                            logger.error(f"Field {n} cannot be converted to torch.tensor.")
                             raise e
                     batch_dict[n] = data
             return batch_dict
@@ -94,9 +98,13 @@ class DataSetGetter:
 
 class SamplerAdapter(torch.utils.data.Sampler):
     def __init__(self, sampler, dataset):
+        super().__init__(dataset)
         self.sampler = sampler
         self.dataset = dataset
 
+    def __len__(self):
+        return len(self.dataset)
+
     def __iter__(self):
         return iter(self.sampler(self.dataset))
 
@@ -136,20 +144,49 @@ class BatchIter:
 
 
 class DataSetIter(BatchIter):
+    """
+    别名：:class:`fastNLP.DataSetIter` :class:`fastNLP.core.batch.DataSetIter`
+
+    DataSetIter 用于从 `DataSet` 中按一定的顺序, 依次按 ``batch_size`` 的大小将数据取出，
+    组成 `x` 和 `y`::
+
+        batch = DataSetIter(data_set, batch_size=16, sampler=SequentialSampler())
+        num_batch = len(batch)
+        for batch_x, batch_y in batch:
+            # do stuff ...
+
+    :param dataset: :class:`~fastNLP.DataSet` 对象, 数据集
+    :param int batch_size: 取出的batch大小
+    :param sampler: 规定使用的 :class:`~fastNLP.Sampler` 方式. 若为 ``None`` , 使用 :class:`~fastNLP.SequentialSampler`.
+
+        Default: ``None``
+    :param bool as_numpy: 若为 ``True`` , 输出batch为 numpy.array. 否则为 :class:`torch.Tensor`.
+
+        Default: ``False``
+    :param int num_workers: 使用多少个进程来预处理数据
+    :param bool pin_memory: 是否将产生的tensor使用pin memory, 可能会加快速度。
+    :param bool drop_last: 如果最后一个batch没有batch_size这么多sample，就扔掉最后一个
+    :param timeout:
+    :param worker_init_fn: 在每个worker启动时调用该函数，会传入一个值，该值是worker的index。
+    """
     def __init__(self, dataset, batch_size=1, sampler=None, as_numpy=False,
                  num_workers=0, pin_memory=False, drop_last=False,
                  timeout=0, worker_init_fn=None):
         super().__init__()
         assert isinstance(dataset, DataSet)
-        sampler = SamplerAdapter(sampler=sampler or SequentialSampler(), dataset=dataset)
+        if not isinstance(sampler, torch.utils.data.Sampler):
+            self.sampler = SamplerAdapter(sampler=sampler or SequentialSampler(), dataset=dataset)
+        else:
+            self.sampler = sampler
         dataset = DataSetGetter(dataset, as_numpy)
         collate_fn = dataset.collate_fn if hasattr(dataset, 'collate_fn') else None
         self.dataiter = torch.utils.data.DataLoader(
-            dataset=dataset, batch_size=batch_size, sampler=sampler,
+            dataset=dataset, batch_size=batch_size, sampler=self.sampler,
             collate_fn=collate_fn, num_workers=num_workers,
             pin_memory=pin_memory, drop_last=drop_last,
             timeout=timeout, worker_init_fn=worker_init_fn)
-        self.num_batches = self.get_num_batches(len(dataset), batch_size, drop_last)
+        # 以sampler的数量为准，因为DistributedSampler的时候每个进程上并不是所有的数据都用上了
+        self.num_batches = self.get_num_batches(len(self.dataiter.sampler), batch_size, drop_last)
         self.batch_size = batch_size
 
 
@@ -158,7 +195,7 @@ class TorchLoaderIter(BatchIter):
         super().__init__()
         assert isinstance(dataset, torch.utils.data.DataLoader)
         self.dataiter = dataset
-        self.num_batches = self.get_num_batches(len(dataset), dataset.batch_size, dataset.drop_last)
+        self.num_batches = self.get_num_batches(len(dataset.sampler), dataset.batch_size, dataset.drop_last)
         self.batch_size = dataset.batch_size
 
 
@@ -176,6 +213,13 @@ class OnlineDataIter(BatchIter):
 
 
 def _to_tensor(batch, field_dtype):
+    """
+
+    :param batch: np.array()
+    :param field_dtype: 数据类型
+    :return: batch, flag. 如果传入的数据支持转为tensor，返回的batch就是tensor，且flag为True；如果传入的数据不支持转为tensor，
+        返回的batch就是原来的数据，且flag为False
+    """
     try:
         if field_dtype is not None and isinstance(field_dtype, type)\
                 and issubclass(field_dtype, Number) \

fastNLP/core/callback.py

@@ -2,11 +2,11 @@ r"""
 callback模块实现了 fastNLP 中的许多 callback 类，用于增强 :class:`~fastNLP.Trainer` 类。
 
 虽然Trainer本身已经集成了一些功能，但仍然不足以囊括训练过程中可能需要到的功能，
-比如负采样，learning rate decay, Early Stop等。
-为了解决这个问题fastNLP引入了callback的机制，Callback 是一种在Trainer训练过程中特定阶段会运行的函数集合。
-关于Trainer的详细文档，请参见 :doc:`trainer 模块<fastNLP.core.trainer>`
+比如负采样，learning rate decay 和 early stop等。
+为了解决这个问题，fastNLP引入了callback的机制，:class:`~fastNLP.Callback` 是一种在Trainer训练过程中特定阶段会运行的函数集合。
+关于 :class:`~fastNLP.Trainer` 的详细文档，请参见 :doc:`trainer 模块<fastNLP.core.trainer>`
 
-我们将 :meth:`~fastNLP.Train.train` 这个函数内部分为以下的阶段，在对应阶段会触发相应的调用::
+我们将 :meth:`~fastNLP.Trainer.train` 这个函数内部分为以下的阶段，在对应阶段会触发相应的调用::
 
     callback.on_train_begin()  # 开始进行训练
     for i in range(1, n_epochs+1):
@@ -31,8 +31,8 @@ callback模块实现了 fastNLP 中的许多 callback 类，用于增强 :class:
     callback.on_train_end() # 训练结束
     callback.on_exception() # 这是一个特殊的步骤，在训练过程中遭遇exception会跳转到这里。
 
-如下面的例子所示，我们可以使用内置的 callback 类，或者继承 :class:`~fastNLP.core.callback.Callback`
-定义自己的 callback 类::
+如下面的例子所示，我们可以使用内置的 callback 组件，或者继承 :class:`~fastNLP.core.callback.Callback`
+定义自己的 callback 组件::
     
     from fastNLP import Callback, EarlyStopCallback, Trainer, CrossEntropyLoss, AccuracyMetric
     from fastNLP.models import CNNText
@@ -51,12 +51,19 @@ callback模块实现了 fastNLP 中的许多 callback 类，用于增强 :class:
 """
 __all__ = [
     "Callback",
+
     "GradientClipCallback",
     "EarlyStopCallback",
-    "TensorboardCallback",
     "FitlogCallback",
+    "EvaluateCallback",
     "LRScheduler",
     "ControlC",
+    "LRFinder",
+    "TensorboardCallback",
+    "WarmupCallback",
+    "SaveModelCallback",
+    "EchoCallback",
+    "TesterCallback",
     
     "CallbackException",
     "EarlyStopError"
@@ -66,6 +73,8 @@ import os
 
 import torch
 from copy import deepcopy
+import sys
+from .utils import _save_model
 
 try:
     from tensorboardX import SummaryWriter
@@ -74,9 +83,9 @@ try:
 except:
     tensorboardX_flag = False
 
-from ..io.model_io import ModelSaver, ModelLoader
 from .dataset import DataSet
 from .tester import Tester
+from ._logger import logger
 
 try:
     import fitlog
@@ -98,7 +107,8 @@ class Callback(object):
     def __init__(self):
         super(Callback, self).__init__()
         self._trainer = None  # 在Trainer内部被重新赋值
-    
+        self._disabled = False
+
     @property
     def trainer(self):
         """
@@ -156,7 +166,19 @@ class Callback(object):
     def batch_per_epoch(self):
         """每个epoch一共有多少个batch，只有在on_epoch_begin之后才能调用该属性。"""
         return self._trainer.batch_per_epoch
-    
+
+    @property
+    def is_master(self):
+        return self._trainer.is_master
+
+    @property
+    def disabled(self):
+        return self._disabled
+
+    @property
+    def logger(self):
+        return getattr(self._trainer, 'logger', logger)
+
     def on_train_begin(self):
         """
         在Train过程开始之前调用。
@@ -248,6 +270,14 @@ class Callback(object):
         :return:
         """
         pass
+
+    def on_validation(self):
+        """
+        如果Trainer中设置了验证，则会在每次需要验证时调用该函数
+
+        :return:
+        """
+        pass
     
     def on_epoch_end(self):
         """
@@ -279,6 +309,8 @@ def _transfer(func):
     def wrapper(manager, *arg):
         returns = []
         for callback in manager.callbacks:
+            if callback.disabled:
+                continue
             returns.append(getattr(callback, func.__name__)(*arg))
         return returns
     
@@ -295,22 +327,28 @@ class CallbackManager(Callback):
         """
         super(CallbackManager, self).__init__()
         # set attribute of trainer environment
-        
+        self._env = env
         self.callbacks = []
-        if callbacks is not None:
-            if isinstance(callbacks, list):
-                if all([isinstance(cb, Callback) for cb in callbacks]) is True:
-                    self.callbacks.extend(callbacks)
-                else:
-                    obj = [not isinstance(cb, Callback) for cb in callbacks][0]
-                    raise TypeError(f"Expect sub-classes of Callback. Got {type(obj)}")
+        if callbacks:
+            self.callbacks = self.prepare_callbacks(callbacks)
+
+    def prepare_callbacks(self, callbacks):
+        if not callbacks:
+            return []
+        if isinstance(callbacks, list):
+            if all([isinstance(cb, Callback) for cb in callbacks]) is True:
+                pass
             else:
-                raise TypeError(f"Expect callbacks in CallbackManager(callbacks) to be list. Got {type(callbacks)}.")
-        
-        for env_name, env_val in env.items():
-            for callback in self.callbacks:
+                obj = [not isinstance(cb, Callback) for cb in callbacks][0]
+                raise TypeError(f"Expect sub-classes of Callback. Got {type(obj)}")
+        else:
+            raise TypeError(f"Expect callbacks in CallbackManager(callbacks) to be list. Got {type(callbacks)}.")
+
+        for env_name, env_val in self._env.items():
+            for callback in callbacks:
                 setattr(callback, '_' + env_name, env_val)  # Callback.trainer
-    
+        return callbacks
+
     @_transfer
     def on_train_begin(self):
         pass
@@ -350,6 +388,10 @@ class CallbackManager(Callback):
     @_transfer
     def on_valid_end(self, eval_result, metric_key, optimizer, is_better_eval):
         pass
+
+    @_transfer
+    def on_validation(self):
+        pass
     
     @_transfer
     def on_epoch_end(self):
@@ -364,6 +406,33 @@ class CallbackManager(Callback):
         pass
 
 
+class DistCallbackManager(CallbackManager):
+    def __init__(self, env, callbacks_all=None, callbacks_master=None):
+        super(DistCallbackManager, self).__init__(env)
+        assert 'trainer' in env
+        self._trainer = env['trainer']
+        self.callbacks_master = []
+        self.callbacks_all = []
+        self.add_callback(callbacks_all, master=False)
+        self.add_callback(callbacks_master, master=True)
+
+    def patch_callback(self, callbacks, disabled):
+        if not callbacks:
+            return
+        if not isinstance(callbacks, (list, tuple)):
+            callbacks = [callbacks]
+        for cb in callbacks:
+            cb._disabled = disabled
+
+    def add_callback(self, cb, master=False):
+        if master:
+            self.patch_callback(cb, not self.is_master)
+            self.callbacks_master += self.prepare_callbacks(cb)
+        else:
+            self.callbacks_all += self.prepare_callbacks(cb)
+        self.callbacks = self.callbacks_all + self.callbacks_master
+
+
 class GradientClipCallback(Callback):
     """
     别名：:class:`fastNLP.GradientClipCallback` :class:`fastNLP.core.callback.GradientClipCallback`
@@ -401,6 +470,9 @@ class GradientClipCallback(Callback):
     def on_backward_end(self):
         if self.step%self.update_every==0:
             if self.parameters is None:
+                if getattr(self.trainer, 'fp16', ''):
+                    from apex import amp
+                    self.clip_fun(amp.master_params(self.optimizer), self.clip_value)
                 self.clip_fun(self.model.parameters(), self.clip_value)
             else:
                 self.clip_fun(self.parameters, self.clip_value)
@@ -432,7 +504,7 @@ class EarlyStopCallback(Callback):
     
     def on_exception(self, exception):
         if isinstance(exception, EarlyStopError):
-            print("Early Stopping triggered in epoch {}!".format(self.epoch))
+            logger.info("Early Stopping triggered in epoch {}!".format(self.epoch))
         else:
             raise exception  # 抛出陌生Error
 
@@ -446,10 +518,9 @@ class FitlogCallback(Callback):
         并将验证结果写入到fitlog中。这些数据集的结果是根据dev上最好的结果报道的，即如果dev在第3个epoch取得了最佳，则
         fitlog中记录的关于这些数据集的结果就是来自第三个epoch的结果。
 
-    :param DataSet,dict(DataSet) data: 传入DataSet对象，会使用多个Trainer中的metric对数据进行验证。如果需要传入多个
-        DataSet请通过dict的方式传入，dict的key将作为对应dataset的name传递给fitlog。若tester不为None时，data需要通过
-        dict的方式传入。如果仅传入DataSet, 则被命名为test
-    :param Tester tester: Tester对象，将在on_valid_end时调用。tester中的DataSet会被称为为`test`
+    :param ~fastNLP.DataSet,Dict[~fastNLP.DataSet] data: 传入DataSet对象，会使用多个Trainer中的metric对数据进行验证。如果需要
+        传入多个DataSet请通过dict的方式传入，dict的key将作为对应dataset的name传递给fitlog。data的结果的名称以'data'开头。
+    :param ~fastNLP.Tester,Dict[~fastNLP.Tester] tester: Tester对象，将在on_valid_end时调用。tester的结果的名称以'tester'开头
     :param int log_loss_every: 多少个step记录一次loss(记录的是这几个batch的loss平均值)，如果数据集较大建议将该值设置得
         大一些，不然会导致log文件巨大。默认为0, 即不要记录loss。
     :param int verbose: 是否在终端打印evaluation的结果，0不打印。
@@ -463,21 +534,24 @@ class FitlogCallback(Callback):
         self._log_exception = log_exception
         assert isinstance(log_loss_every, int) and log_loss_every>=0
         if tester is not None:
-            assert isinstance(tester, Tester), "Only fastNLP.Tester allowed."
-            assert isinstance(data, dict) or data is None, "If tester is not None, only dict[DataSet] allowed for data."
-            if data is not None:
-                assert 'test' not in data, "Cannot use `test` as DataSet key, when tester is passed."
-            setattr(tester, 'verbose', 0)
-            self.testers['test'] = tester
-        
+            if isinstance(tester, dict):
+                for name, test in tester.items():
+                    if not isinstance(test, Tester):
+                        raise TypeError(f"{name} in tester is not a valid fastNLP.Tester.")
+                    self.testers['tester-' + name] = test
+            if isinstance(tester, Tester):
+                self.testers['tester-test'] = tester
+            for tester in self.testers.values():
+                setattr(tester, 'verbose', 0)
+
         if isinstance(data, dict):
             for key, value in data.items():
                 assert isinstance(value, DataSet), f"Only DataSet object is allowed, not {type(value)}."
             for key, value in data.items():
-                self.datasets[key] = value
+                self.datasets['data-' + key] = value
         elif isinstance(data, DataSet):
-            self.datasets['test'] = data
-        else:
+            self.datasets['data-test'] = data
+        elif data is not None:
             raise TypeError("data receives dict[DataSet] or DataSet object.")
         
         self.verbose = verbose
@@ -490,8 +564,11 @@ class FitlogCallback(Callback):
         
         if len(self.datasets) > 0:
             for key, data in self.datasets.items():
-                tester = Tester(data=data, model=self.model, batch_size=self.batch_size, metrics=self.trainer.metrics,
-                                verbose=0)
+                tester = Tester(data=data, model=self.model,
+                                batch_size=self.trainer.kwargs.get('dev_batch_size', self.batch_size),
+                                metrics=self.trainer.metrics,
+                                verbose=0,
+                                use_tqdm=self.trainer.test_use_tqdm)
                 self.testers[key] = tester
         fitlog.add_progress(total_steps=self.n_steps)
     
@@ -531,6 +608,68 @@ class FitlogCallback(Callback):
             fitlog.add_other(repr(exception), name='except_info')
 
 
+class EvaluateCallback(Callback):
+    """
+    别名: :class:`fastNLP.EvaluateCallback` :class:`fastNLP.core.callback.EvaluateCallback`
+
+    该callback用于扩展Trainer训练过程中只能对dev数据进行验证的问题。
+
+    :param ~fastNLP.DataSet,Dict[~fastNLP.DataSet] data: 传入DataSet对象，会使用多个Trainer中的metric对数据进行验证。如果需要传入多个
+        DataSet请通过dict的方式传入。
+    :param ~fastNLP.Tester,Dict[~fastNLP.DataSet] tester: Tester对象，将在on_valid_end时调用。
+    """
+
+    def __init__(self, data=None, tester=None):
+        super().__init__()
+        self.datasets = {}
+        self.testers = {}
+        if tester is not None:
+            if isinstance(tester, dict):
+                for name, test in tester.items():
+                    if not isinstance(test, Tester):
+                        raise TypeError(f"{name} in tester is not a valid fastNLP.Tester.")
+                    self.testers['tester-' + name] = test
+            if isinstance(tester, Tester):
+                self.testers['tester-test'] = tester
+            for tester in self.testers.values():
+                setattr(tester, 'verbose', 0)
+
+        if isinstance(data, dict):
+            for key, value in data.items():
+                assert isinstance(value, DataSet), f"Only DataSet object is allowed, not {type(value)}."
+            for key, value in data.items():
+                self.datasets['data-' + key] = value
+        elif isinstance(data, DataSet):
+            self.datasets['data-test'] = data
+        elif data is not None:
+            raise TypeError("data receives dict[DataSet] or DataSet object.")
+
+    def on_train_begin(self):
+        if len(self.datasets) > 0 and self.trainer.dev_data is None:
+            raise RuntimeError("Trainer has no dev data, you cannot pass extra DataSet to do evaluation.")
+
+        if len(self.datasets) > 0:
+            for key, data in self.datasets.items():
+                tester = Tester(data=data, model=self.model,
+                                batch_size=self.trainer.kwargs.get('dev_batch_size', self.batch_size),
+                                metrics=self.trainer.metrics, verbose=0,
+                                use_tqdm=self.trainer.test_use_tqdm)
+                self.testers[key] = tester
+
+    def on_valid_end(self, eval_result, metric_key, optimizer, better_result):
+        if len(self.testers) > 0:
+            for key, tester in self.testers.items():
+                try:
+                    eval_result = tester.test()
+                    # self.pbar.write("Evaluation on {}:".format(key))
+                    self.logger.info("Evaluation on {}:".format(key))
+                    # self.pbar.write(tester._format_eval_results(eval_result))
+                    self.logger.info(tester._format_eval_results(eval_result))
+                except Exception:
+                    # self.pbar.write("Exception happens when evaluate on DataSet named `{}`.".format(key))
+                    self.logger.info("Exception happens when evaluate on DataSet named `{}`.".format(key))
+
+
 class LRScheduler(Callback):
     """
     别名：:class:`fastNLP.LRScheduler` :class:`fastNLP.core.callback.LRScheduler`
@@ -584,7 +723,7 @@ class SmoothValue(object):
         self.smooth = None
     
     def add_value(self, val: float) -> None:
-        "Add `val` to calculate updated smoothed value."
+        """Add `val` to calculate updated smoothed value."""
         self.n += 1
         self.mov_avg = self.beta * self.mov_avg + (1 - self.beta) * val
         self.smooth = self.mov_avg / (1 - self.beta ** self.n)
@@ -612,8 +751,7 @@ class LRFinder(Callback):
         self.smooth_value = SmoothValue(0.8)
         self.opt = None
         self.find = None
-        self.loader = ModelLoader()
-    
+
     @property
     def lr_gen(self):
         scale = (self.end_lr - self.start_lr) / self.batch_per_epoch
@@ -628,7 +766,7 @@ class LRFinder(Callback):
             self.opt = self.trainer.optimizer  # pytorch optimizer
             self.opt.param_groups[0]["lr"] = self.start_lr
             # save model
-            ModelSaver("tmp").save_pytorch(self.trainer.model, param_only=True)
+            torch.save(self.model.state_dict(), 'tmp')
             self.find = True
     
     def on_backward_begin(self, loss):
@@ -657,7 +795,9 @@ class LRFinder(Callback):
             self.opt.param_groups[0]["lr"] = self.best_lr
             self.find = False
             # reset model
-            ModelLoader().load_pytorch(self.trainer.model, "tmp")
+            states = torch.load('tmp')
+            self.model.load_state_dict(states)
+            os.remove('tmp')
             self.pbar.write("Model reset. \nFind best lr={}".format(self.best_lr))
 
 
@@ -672,7 +812,7 @@ class TensorboardCallback(Callback):
     
     .. warning::
         fastNLP 已停止对此功能的维护，请等待 fastNLP 兼容 PyTorch1.1 的下一个版本。
-        或者使用和 fastNLP 高度配合的 fitlog（参见 :doc:`/user/with_fitlog` ）。
+        或者使用和 fastNLP 高度配合的 fitlog（参见 :doc:`/tutorials/tutorial_10_fitlog` ）。
         
     """
     
@@ -737,6 +877,132 @@ class TensorboardCallback(Callback):
             del self._summary_writer
 
 
+class WarmupCallback(Callback):
+    """
+    按一定的周期调节Learning rate的大小。
+
+    :param int,float warmup: 如果warmup为int，则在该step之前，learning rate根据schedule的策略变化; 如果warmup为float，
+        如0.1, 则前10%的step是按照schedule策略调整learning rate。
+    :param str schedule: 以哪种方式调整。linear: 前warmup的step上升到指定的learning rate(从Trainer中的optimizer处获取的), 后
+        warmup的step下降到0； constant前warmup的step上升到指定learning rate，后面的step保持learning rate.
+    """
+    def __init__(self, warmup=0.1, schedule='constant'):
+        super().__init__()
+        self.warmup = max(warmup, 0.)
+
+        self.initial_lrs = []  # 存放param_group的learning rate
+        if schedule == 'constant':
+            self.get_lr = self._get_constant_lr
+        elif schedule == 'linear':
+            self.get_lr = self._get_linear_lr
+        else:
+            raise RuntimeError("Only support 'linear', 'constant'.")
+
+    def _get_constant_lr(self, progress):
+        if progress<self.warmup:
+            return progress/self.warmup
+        return 1
+
+    def _get_linear_lr(self, progress):
+        if progress<self.warmup:
+            return progress/self.warmup
+        return max((progress - 1.) / (self.warmup - 1.), 0.)
+
+    def on_train_begin(self):
+        self.t_steps = (len(self.trainer.train_data) // (self.batch_size*self.update_every) +
+                            int(len(self.trainer.train_data) % (self.batch_size*self.update_every)!= 0)) * self.n_epochs
+        if self.warmup>1:
+            self.warmup = self.warmup/self.t_steps
+        self.t_steps = max(2, self.t_steps)  # 不能小于2
+        # 获取param_group的初始learning rate
+        for group in self.optimizer.param_groups:
+            self.initial_lrs.append(group['lr'])
+
+    def on_backward_end(self):
+        if self.step%self.update_every==0:
+            progress = (self.step/self.update_every)/self.t_steps
+            for lr, group in zip(self.initial_lrs, self.optimizer.param_groups):
+                group['lr'] = lr * self.get_lr(progress)
+
+
+class SaveModelCallback(Callback):
+    """
+    由于Trainer在训练过程中只会保存最佳的模型， 该callback可实现多种方式的结果存储。
+    会根据训练开始的时间戳在save_dir下建立文件夹，再在文件夹下存放多个模型
+    -save_dir
+        -2019-07-03-15-06-36
+            -epoch:0_step:20_{metric_key}:{evaluate_performance}.pt   # metric是给定的metric_key, evaluate_performance是性能
+            -epoch:1_step:40_{metric_key}:{evaluate_performance}.pt
+        -2019-07-03-15-10-00
+            -epoch:0_step:20_{metric_key}:{evaluate_performance}.pt   # metric是给定的metric_key, evaluate_perfomance是性能
+    :param str save_dir: 将模型存放在哪个目录下，会在该目录下创建以时间戳命名的目录，并存放模型
+    :param int top: 保存dev表现top多少模型。-1为保存所有模型。
+    :param bool only_param: 是否只保存模型d饿权重。
+    :param save_on_exception: 发生exception时，是否保存一份发生exception的模型。模型名称为epoch:x_step:x_Exception:{exception_name}.
+    """
+    def __init__(self, save_dir, top=3, only_param=False, save_on_exception=False):
+        super().__init__()
+
+        if not os.path.isdir(save_dir):
+            raise IsADirectoryError("{} is not a directory.".format(save_dir))
+        self.save_dir = save_dir
+        if top < 0:
+            self.top = sys.maxsize
+        else:
+            self.top = top
+        self._ordered_save_models = []  # List[Tuple], Tuple[0]是metric， Tuple[1]是path。metric是依次变好的，所以从头删
+
+        self.only_param = only_param
+        self.save_on_exception = save_on_exception
+
+    def on_train_begin(self):
+        self.save_dir = os.path.join(self.save_dir, self.trainer.start_time)
+
+    def on_valid_end(self, eval_result, metric_key, optimizer, is_better_eval):
+        metric_value = list(eval_result.values())[0][metric_key]
+        self._save_this_model(metric_value)
+
+    def _insert_into_ordered_save_models(self, pair):
+        # pair:(metric_value, model_name)
+        # 返回save的模型pair与删除的模型pair. pair中第一个元素是metric的值，第二个元素是模型的名称
+        index = -1
+        for _pair in self._ordered_save_models:
+            if _pair[0]>=pair[0] and self.trainer.increase_better:
+                break
+            if not self.trainer.increase_better and _pair[0]<=pair[0]:
+                break
+            index += 1
+        save_pair = None
+        if len(self._ordered_save_models)<self.top or (len(self._ordered_save_models)>=self.top and index!=-1):
+            save_pair = pair
+            self._ordered_save_models.insert(index+1, pair)
+        delete_pair = None
+        if len(self._ordered_save_models)>self.top:
+            delete_pair = self._ordered_save_models.pop(0)
+        return save_pair, delete_pair
+
+    def _save_this_model(self, metric_value):
+        name = "epoch:{}_step:{}_{}:{:.6f}.pt".format(self.epoch, self.step, self.trainer.metric_key, metric_value)
+        save_pair, delete_pair = self._insert_into_ordered_save_models((metric_value, name))
+        if save_pair:
+            try:
+                _save_model(self.model, model_name=name, save_dir=self.save_dir, only_param=self.only_param)
+            except Exception as e:
+                logger.error(f"The following exception:{e} happens when save model to {self.save_dir}.")
+        if delete_pair:
+            try:
+                delete_model_path = os.path.join(self.save_dir, delete_pair[1])
+                if os.path.exists(delete_model_path):
+                    os.remove(delete_model_path)
+            except Exception as e:
+                logger.error(f"Fail to delete model {name} at {self.save_dir} caused by exception:{e}.")
+
+    def on_exception(self, exception):
+        if self.save_on_exception:
+            name = "epoch:{}_step:{}_Exception:{}.pt".format(self.epoch, self.step, exception.__class__.__name__)
+            _save_model(self.model, model_name=name, save_dir=self.save_dir, only_param=self.only_param)
+
+
 class CallbackException(BaseException):
     """
    当需要通过callback跳出训练的时候可以通过抛出CallbackException并在on_exception中捕获这个值。
@@ -756,3 +1022,70 @@ class EarlyStopError(CallbackException):
     
     def __init__(self, msg):
         super(EarlyStopError, self).__init__(msg)
+
+
+class EchoCallback(Callback):
+    def __init__(self, name, out=sys.stdout):
+        super(EchoCallback, self).__init__()
+        self.name = name
+        self.out = out
+
+    def __getattribute__(self, item):
+        if item.startswith('on_'):
+            logger.info('{}.{} has been called at pid: {}'.format(self.name, item, os.getpid()),
+                  file=self.out)
+        return super(EchoCallback, self).__getattribute__(item)
+
+
+class TesterCallback(Callback):
+    def __init__(self, data, model, metrics, metric_key=None, batch_size=16, num_workers=None):
+        super(TesterCallback, self).__init__()
+        self.tester = Tester(data, model,
+                             metrics=metrics, batch_size=batch_size,
+                             num_workers=num_workers, verbose=0)
+        # parse metric_key
+        # increase_better is True. It means the exp result gets better if the indicator increases.
+        # It is true by default.
+        self.increase_better = True
+        if metric_key is not None:
+            self.increase_better = False if metric_key[0] == "-" else True
+            self.metric_key = metric_key[1:] if metric_key[0] == "+" or metric_key[0] == "-" else metric_key
+        else:
+            self.metric_key = None
+        self.score = None
+
+    def on_validation(self):
+        cur_score = self.tester.test()
+        eval_str = "Evaluation at Epoch {}/{}. Step:{}/{}. - {}".format(
+                    self.epoch, self.n_epochs, self.step, self.n_steps,
+                    self.tester._format_eval_results(cur_score))
+        self.logger.info(eval_str)
+        is_better = self.compare_better(cur_score)
+        if is_better:
+            self.score = cur_score
+        return cur_score, is_better
+
+    def _get_score(self, metric_dict, key):
+        for metric in metric_dict.items():
+            if key in metric:
+                return metric[key]
+        return None
+
+    def compare_better(self, a):
+        if self.score is None:
+            return True
+        if self.metric_key is None:
+            self.metric_key = list(list(self.score.values())[0].keys())[0]
+        k = self.metric_key
+        score = self._get_score(self.score, k)
+        new_score = self._get_score(a, k)
+        if score is None or new_score is None:
+            return False
+        if self.increase_better:
+            return score <= new_score
+        else:
+            return score >= new_score
+
+    def on_train_end(self):
+        self.logger.info('Evaluate on training ends.')
+        self.on_validation()

fastNLP/core/const.py

@@ -1,3 +1,13 @@
+"""
+.. todo::
+    doc
+"""
+
+__all__ = [
+    "Const"
+]
+
+
 class Const:
     """
     fastNLP中field命名常量。
@@ -7,12 +17,14 @@ class Const:
         
     具体列表::
 
-        INPUT       模型的序列输入      words（复数words1, words2）
-        CHAR_INPUT  模型character输入  chars（复数chars1， chars2）
-        INPUT_LEN   序列长度           seq_len（复数seq_len1，seq_len2）
-        OUTPUT      模型输出           pred（复数pred1， pred2）
-        TARGET      真实目标           target（复数target1，target2）
-        LOSS        损失函数           loss （复数loss1，loss2）
+        INPUT       模型的序列输入      words（具有多列words时，依次使用words1, words2, ）
+        CHAR_INPUT  模型character输入  chars（具有多列chars时，依次使用chars1， chars2）
+        INPUT_LEN   序列长度           seq_len（具有多列seq_len时，依次使用seq_len1，seq_len2）
+        OUTPUT      模型输出           pred（具有多列pred时，依次使用pred1， pred2）
+        TARGET      真实目标           target（具有多列target时，依次使用target1，target2）
+        LOSS        损失函数           loss （具有多列loss时，依次使用loss1，loss2）
+        RAW_WORD    原文的词           raw_words  (具有多列raw_words时，依次使用raw_words1, raw_words2)
+        RAW_CHAR    原文的字           raw_chars  (具有多列raw_chars时，依次使用raw_chars1, raw_chars2)
 
     """
     INPUT = 'words'
@@ -21,37 +33,49 @@ class Const:
     OUTPUT = 'pred'
     TARGET = 'target'
     LOSS = 'loss'
-
+    RAW_WORD = 'raw_words'
+    RAW_CHAR = 'raw_chars'
+    
     @staticmethod
     def INPUTS(i):
         """得到第 i 个 ``INPUT`` 的命名"""
         i = int(i) + 1
         return Const.INPUT + str(i)
-
+    
     @staticmethod
     def CHAR_INPUTS(i):
         """得到第 i 个 ``CHAR_INPUT`` 的命名"""
         i = int(i) + 1
         return Const.CHAR_INPUT + str(i)
-
+    
+    @staticmethod
+    def RAW_WORDS(i):
+        i = int(i) + 1
+        return Const.RAW_WORD + str(i)
+    
+    @staticmethod
+    def RAW_CHARS(i):
+        i = int(i) + 1
+        return Const.RAW_CHAR + str(i)
+    
     @staticmethod
     def INPUT_LENS(i):
         """得到第 i 个 ``INPUT_LEN`` 的命名"""
         i = int(i) + 1
         return Const.INPUT_LEN + str(i)
-
+    
     @staticmethod
     def OUTPUTS(i):
         """得到第 i 个 ``OUTPUT`` 的命名"""
         i = int(i) + 1
         return Const.OUTPUT + str(i)
-
+    
     @staticmethod
     def TARGETS(i):
         """得到第 i 个 ``TARGET`` 的命名"""
         i = int(i) + 1
         return Const.TARGET + str(i)
-
+    
     @staticmethod
     def LOSSES(i):
         """得到第 i 个 ``LOSS`` 的命名"""

fastNLP/core/dataset.py

@@ -1,7 +1,7 @@
 """
 :class:`~fastNLP.core.dataset.DataSet` 是fastNLP中用于承载数据的容器。可以将DataSet看做是一个表格，
-每一行是一个sample (在fastNLP中被称为 :mod:`~.instance` )，
-每一列是一个feature (在fastNLP中称为 :mod:`.field` )。
+每一行是一个sample (在fastNLP中被称为 :mod:`~fastNLP.core.instance` )，
+每一列是一个feature (在fastNLP中称为 :mod:`~fastNLP.core.field` )。
 
 .. csv-table:: Following is a demo layout of DataSet
    :header: "sentence", "words", "seq_len"
@@ -13,57 +13,64 @@
 
 在fastNLP内部每一行是一个 :class:`~fastNLP.Instance` 对象； 每一列是一个 :class:`~fastNLP.FieldArray` 对象。
 
-1 DataSet的创建
-    创建DataSet主要有以下的3种方式
+----------------------------
+1.DataSet的创建
+----------------------------
 
-1.1 传入dict
+创建DataSet主要有以下的3种方式
 
-  Example::
+1.1 传入dict
+----------------------------
 
-    from fastNLP import DataSet
-    data = {'sentence':["This is the first instance .", "Second instance .", "Third instance ."],
-            'words': [['this', 'is', 'the', 'first', 'instance', '.'], ['Second', 'instance', '.'], ['Third', 'instance', '.'],
-            'seq_len': [6, 3, 3]}
-    dataset = DataSet(data)
-    # 传入的dict的每个key的value应该为具有相同长度的list
+    .. code-block::
 
-1.2 通过构建Instance
+        from fastNLP import DataSet
+        data = {'sentence':["This is the first instance .", "Second instance .", "Third instance ."],
+                'words': [['this', 'is', 'the', 'first', 'instance', '.'], ['Second', 'instance', '.'], ['Third', 'instance', '.'],
+                'seq_len': [6, 3, 3]}
+        dataset = DataSet(data)
+        # 传入的dict的每个key的value应该为具有相同长度的list
 
-  Example::
+1.2 通过 Instance 构建
+----------------------------
 
-    from fastNLP import DataSet
-    from fastNLP import Instance
-    dataset = DataSet()
-    instance = Instance(sentence="This is the first instance",
-                        words=['this', 'is', 'the', 'first', 'instance', '.'],
-                        seq_len=6)
-    dataset.append(instance)
-    # 可以继续append更多内容，但是append的instance应该和第一个instance拥有完全相同的field
+    .. code-block::
 
-1.3 通过list(Instance)
+        from fastNLP import DataSet
+        from fastNLP import Instance
+        dataset = DataSet()
+        instance = Instance(sentence="This is the first instance",
+                            words=['this', 'is', 'the', 'first', 'instance', '.'],
+                            seq_len=6)
+        dataset.append(instance)
+        # 可以继续append更多内容，但是append的instance应该和第一个instance拥有完全相同的field
 
-   Example::
+1.3 通过 List[Instance] 构建
+--------------------------------------
 
-    from fastNLP import DataSet
-    from fastNLP import Instance
-    instances = []
-    instances.append(Instance(sentence="This is the first instance",
-                        words=['this', 'is', 'the', 'first', 'instance', '.'],
-                        seq_len=6))
-    instances.append(Instance(sentence="Second instance .",
-                        words=['Second', 'instance', '.'],
-                        seq_len=3))
-    dataset = DataSet(instances)
+    .. code-block::
 
-2 DataSet与预处理
-    常见的预处理有如下几种
+        from fastNLP import DataSet
+        from fastNLP import Instance
+        instances = []
+        winstances.append(Instance(sentence="This is the first instance",
+                            ords=['this', 'is', 'the', 'first', 'instance', '.'],
+                            seq_len=6))
+        instances.append(Instance(sentence="Second instance .",
+                            words=['Second', 'instance', '.'],
+                            seq_len=3))
+        dataset = DataSet(instances)
+        
+--------------------------------------
+2.DataSet与预处理
+--------------------------------------
 
-2.1 从某个文本文件读取内容 #
+常见的预处理有如下几种
 
-    .. todo::
-        引用DataLoader
+2.1 从某个文本文件读取内容
+--------------------------------------
 
-    Example::
+    .. code-block::
 
         from fastNLP import DataSet
         from fastNLP import Instance
@@ -78,21 +85,13 @@
                 sent, label = line.strip().split('\t')
                 dataset.append(Instance(sentence=sent, label=label))
 
-2.2 index, 返回结果为对DataSet对象的浅拷贝
+    .. note::
+        直接读取特定数据集的数据请参考  :doc:`/tutorials/tutorial_2_load_dataset`
 
-    Example::
+2.2 对DataSet中的内容处理
+--------------------------------------
 
-        import numpy as np
-        from fastNLP import DataSet
-        dataset = DataSet({'a': np.arange(10), 'b': [[_] for _ in range(10)]})
-        d[0]  # 使用一个下标获取一个instance
-        >>{'a': 0 type=int,'b': [2] type=list} # 得到一个instance
-        d[1:3]  # 使用slice获取一个新的DataSet
-        >>DataSet({'a': 1 type=int, 'b': [2] type=list}, {'a': 2 type=int, 'b': [2] type=list})
-
-2.3 对DataSet中的内容处理
-
-    Example::
+    .. code-block::
 
         from fastNLP import DataSet
         data = {'sentence':["This is the first instance .", "Second instance .", "Third instance ."]}
@@ -108,9 +107,10 @@
             return words
         dataset.apply(get_words, new_field_name='words')
 
-2.4 删除DataSet的内容
+2.3 删除DataSet的内容
+--------------------------------------
 
-    Example::
+    .. code-block::
 
         from fastNLP import DataSet
         dataset = DataSet({'a': list(range(-5, 5))})
@@ -124,16 +124,18 @@
         dataset.delete_field('a')
 
 
-2.5 遍历DataSet的内容
+2.4 遍历DataSet的内容
+--------------------------------------
 
-    Example::
+    .. code-block::
 
         for instance in dataset:
             # do something
 
-2.6 一些其它操作
+2.5 一些其它操作
+--------------------------------------
 
-    Example::
+    .. code-block::
 
         #  检查是否存在名为'a'的field
         dataset.has_field('a')  # 或 ('a' in dataset)
@@ -141,21 +143,25 @@
         dataset.rename_field('a', 'b')
         #  DataSet的长度
         len(dataset)
+        
+--------------------------------------
+3.DataSet与自然语言处理(NLP)
+--------------------------------------
 
-3 DataSet与自然语言处理(NLP)
-    在目前深度学习的模型中，大都依赖于随机梯度下降法(SGD)进行模型的优化。随机梯度下降需要将数据切分成一个一个的Batch，
-    一个Batch进行一次前向计算(forward)与梯度后向传播(backward)。在自然语言处理的场景下，往往还需要对数据进行pad。这是
-    由于句子的长度一般是不同的，但是一次Batch中的每个field都必须是一个tensor，所以需要将所有句子都补齐到相同的长度。
+在目前深度学习的模型中，大都依赖于随机梯度下降法(SGD)进行模型的优化。随机梯度下降需要将数据切分成一个个的 batch，
+一个batch进行一次前向计算(forward)与梯度后向传播(backward)。在自然语言处理的场景下，往往还需要对数据进行pad。这是
+由于句子的长度一般是不同的，但是一次batch中的每个field都必须是一个tensor，所以需要将所有句子都补齐到相同的长度。
 
-3.1 DataSet与Batch
+3.1 DataSet与DataSetIter
+--------------------------------------
 
-    我们先看fastNLP中如何将数据分成一个一个的Batch的例子, 这里我们使用随机生成的数据来模拟一个二分类文本分类任务，
+    我们先看fastNLP中如何将数据分成一个一个的batch的例子, 这里我们使用随机生成的数据来模拟一个二分类文本分类任务，
     words和characters是输入，labels是文本类别
 
-    Example::
+    .. code-block::
 
         from fastNLP import DataSet
-        from fastNLP import Batch
+        from fastNLP import DataSetIter
         from fastNLP import SequentialSampler
         from fastNLP import EngChar2DPadder
 
@@ -175,7 +181,7 @@
         d.set_target('label')
         d.set_input('words', 'chars')
 
-        for batch_x, batch_y in Batch(d, sampler=SequentialSampler(), batch_size=2):
+        for batch_x, batch_y in DataSetIter(d, sampler=SequentialSampler(), batch_size=2):
             print("batch_x:", batch_x)
             print("batch_y:", batch_y)
             break
@@ -194,23 +200,26 @@
             #      [ 0,  0,  0,  0,  0]]])}
             # {'label': tensor([0, 0])}
 
-    其中 :class:`~fastNLP.Batch` 是用于从DataSet中按照batch_size为大小取出batch的迭代器，
-    :class:`~fastNLP.SequentialSampler` 用于指示 Batch 以怎样的
+    其中 :class:`~fastNLP.DataSetIter` 是用于从DataSet中按照batch_size为大小取出batch的迭代器，
+    :class:`~fastNLP.SequentialSampler` 用于指示 :class:`~fastNLP.DataSetIter` 以怎样的
     顺序从DataSet中取出instance以组成一个batch，
-    更详细的说明请参照 :class:`~fastNLP.Batch` 和 :class:`~fastNLP.SequentialSampler` 文档。
+    更详细的说明请参照 :class:`~fastNLP.DataSetIter` 和 :class:`~fastNLP.SequentialSampler` 文档。
 
-    通过DataSet.set_input('words', 'chars'), fastNLP将认为'words'和'chars'这两个field都是input，并将它们都放入迭代器
-    生成的第一个dict中; DataSet.set_target('labels'), fastNLP将认为'labels'这个field是target，并将其放入到迭代器的第
+    通过 ``DataSet.set_input('words', 'chars')`` , fastNLP将认为 `words` 和 `chars` 这两个field都是input，并将它们都放入迭代器
+    生成的第一个dict中; ``DataSet.set_target('labels')`` , fastNLP将认为 `labels` 这个field是target，并将其放入到迭代器的第
     二个dict中。如上例中所打印结果。分为input和target的原因是由于它们在被 :class:`~fastNLP.Trainer` 所使用时会有所差异，
     详见  :class:`~fastNLP.Trainer`
 
-    当把某个field设置为'target'或者'input'的时候(两者不是互斥的，可以同时设为input和target)，fastNLP不仅仅只是将其放
-    置到不同的dict中，而还会对被设置为input或target的field进行类型检查。类型检查的目的是为了看能否把该field转为
-    pytorch的torch.LongTensor或torch.FloatTensor类型(也可以在Batch中设置输出numpy类型，参考 :class:`~fastNLP.Batch` )，如上例所示，
-    fastNLP已将words，chars和label转为了Tensor类型。如果field在每个instance都拥有相同的维度(不能超过两维)，且最内层
-    的元素都为相同的type(int, float, np.int*, np.float*)，则fastNLP默认将对该field进行pad。也支持全为str的field作为
-    target和input，这种情况下，fastNLP默认不进行pad。另外，当某个field已经被设置为了target或者input后，之后append的
-    instance对应的field必须要和前面已有的内容一致，否则会报错。
+    当把某个field设置为 `target` 或者 `input` 的时候(两者不是互斥的，可以同时设为两种)，fastNLP不仅仅只是将其放
+    置到不同的dict中，而还会对被设置为 `input` 或 `target` 的 field 进行类型检查。类型检查的目的是为了看能否把该 field 转为
+    pytorch的 :class:`torch.LongTensor` 或 :class:`torch.FloatTensor` 类型
+    (也可以在 :class:`~fastNLP.DataSetIter` 中设置输出numpy类型，参考 :class:`~fastNLP.DataSetIter` )。
+    
+    如上例所示，fastNLP已将 `words` ，`chars` 和 `label` 转为了 :class:`Tensor` 类型。
+    如果 field 在每个 `instance` 都拥有相同的维度(不能超过两维)，且最内层的元素都为相同的 type(int, float, np.int*, np.float*)，
+    则fastNLP默认将对该 field 进行pad。也支持全为str的field作为target和input，这种情况下，fastNLP默认不进行pad。
+    另外，当某个 field 已经被设置为了 target 或者 input 后，之后 `append` 的
+    `instance` 对应的 field 必须要和前面已有的内容一致，否则会报错。
 
     可以查看field的dtype::
         
@@ -229,6 +238,7 @@
     错误::
 
         from fastNLP import DataSet
+        
         d = DataSet({'data': [1, 'a']})
         d.set_input('data')
         >> RuntimeError: Mixed data types in Field data: [<class 'str'>, <class 'int'>]
@@ -243,6 +253,7 @@
     当某个field被设置为忽略type之后，fastNLP将不对其进行pad。
 
 3.2 DataSet与pad
+--------------------------------------
 
     在fastNLP里，pad是与一个field绑定的。即不同的field可以使用不同的pad方式，比如在英文任务中word需要的pad和
     character的pad方式往往是不同的。fastNLP是通过一个叫做 :class:`~fastNLP.Padder` 的子类来完成的。
@@ -252,7 +263,7 @@
     如果 :class:`~fastNLP.AutoPadder` 或 :class:`~fastNLP.EngChar2DPadder` 无法满足需求，
     也可以自己写一个 :class:`~fastNLP.Padder` 。
 
-    Example::
+    .. code-block::
 
         from fastNLP import DataSet
         from fastNLP import EngChar2DPadder
@@ -280,6 +291,7 @@ import _pickle as pickle
 import warnings
 
 import numpy as np
+from copy import deepcopy
 
 from .field import AutoPadder
 from .field import FieldArray
@@ -287,6 +299,8 @@ from .instance import Instance
 from .utils import _get_func_signature
 from .field import AppendToTargetOrInputException
 from .field import SetInputOrTargetException
+from .const import Const
+from ._logger import logger
 
 class DataSet(object):
     """
@@ -338,7 +352,11 @@ class DataSet(object):
                     self.idx])
                 assert self.idx < len(self.dataset.field_arrays[item]), "index:{} out of range".format(self.idx)
                 return self.dataset.field_arrays[item][self.idx]
-            
+
+            def items(self):
+                ins = self.dataset[self.idx]
+                return ins.items()
+
             def __repr__(self):
                 return self.dataset[self.idx].__repr__()
         
@@ -417,7 +435,7 @@ class DataSet(object):
         """
         将一个instance对象append到DataSet后面。
 
-        :param instance: :class:`~fastNLP.Instance` 类型。若DataSet不为空，则instance应该拥有和DataSet完全一样的field。
+        :param ~fastNLP.Instance instance: 若DataSet不为空，则instance应该拥有和DataSet完全一样的field。
 
         """
         if len(self.field_arrays) == 0:
@@ -435,7 +453,7 @@ class DataSet(object):
                 try:
                     self.field_arrays[name].append(field)
                 except AppendToTargetOrInputException as e:
-                    print(f"Cannot append to field:{name}.")
+                    logger.error(f"Cannot append to field:{name}.")
                     raise e
     
     def add_fieldarray(self, field_name, fieldarray):
@@ -443,7 +461,7 @@ class DataSet(object):
         将fieldarray添加到DataSet中.
 
         :param str field_name: 新加入的field的名称
-        :param fieldarray: :class:`~fastNLP.FieldArray` 类型。需要加入DataSet的field的内容
+        :param ~fastNLP.core.FieldArray fieldarray: 需要加入DataSet的field的内容
         :return:
         """
         if not isinstance(fieldarray, FieldArray):
@@ -459,8 +477,7 @@ class DataSet(object):
         
         :param str field_name: 新增的field的名称
         :param list fields: 需要新增的field的内容
-        :param None, padder: :class:`~fastNLP.Padder` 类型，
-                    如果为None,则不进行pad，默认使用 :class:`~fastNLP.AutoPadder` 自动判断是否需要做pad。
+        :param None,~fastNLP.Padder padder: 如果为None,则不进行pad，默认使用 :class:`~fastNLP.AutoPadder` 自动判断是否需要做pad。
         :param bool is_input: 新加入的field是否是input
         :param bool is_target: 新加入的field是否是target
         :param bool ignore_type: 是否忽略对新加入的field的类型检查
@@ -477,7 +494,7 @@ class DataSet(object):
         """
         删除第index个instance
 
-        :param int index: 需要删除的instance的index，从0开始
+        :param int index: 需要删除的instance的index，序号从0开始。
         """
         assert isinstance(index, int), "Only integer supported."
         if len(self) <= index:
@@ -487,6 +504,7 @@ class DataSet(object):
         else:
             for field in self.field_arrays.values():
                 field.pop(index)
+        return self
     
     def delete_field(self, field_name):
         """
@@ -495,7 +513,22 @@ class DataSet(object):
         :param str field_name: 需要删除的field的名称.
         """
         self.field_arrays.pop(field_name)
-    
+        return self
+
+    def copy_field(self, field_name, new_field_name):
+        """
+        深度copy名为field_name的field到new_field_name
+
+        :param str field_name: 需要copy的field。
+        :param str new_field_name: copy生成的field名称
+        :return: self
+        """
+        if not self.has_field(field_name):
+            raise KeyError(f"Field:{field_name} not found in DataSet.")
+        fieldarray = deepcopy(self.get_field(field_name))
+        self.add_fieldarray(field_name=new_field_name, fieldarray=fieldarray)
+        return self
+
     def has_field(self, field_name):
         """
         判断DataSet中是否有名为field_name这个field
@@ -522,7 +555,7 @@ class DataSet(object):
         """
         返回一个dict，key为field_name, value为对应的 :class:`~fastNLP.FieldArray`
 
-        :return: dict: 返回如上所述的字典
+        :return dict: 返回如上所述的字典
         """
         return self.field_arrays
     
@@ -530,7 +563,7 @@ class DataSet(object):
         """
         返回一个list，包含所有 field 的名字
 
-        :return: list: 返回如上所述的列表
+        :return list: 返回如上所述的列表
         """
         return sorted(self.field_arrays.keys())
     
@@ -556,7 +589,7 @@ class DataSet(object):
             raise KeyError("DataSet has no field named {}.".format(old_name))
         return self
     
-    def set_target(self, *field_names, flag=True):
+    def set_target(self, *field_names, flag=True, use_1st_ins_infer_dim_type=True):
         """
         将field_names的field设置为target
 
@@ -567,19 +600,23 @@ class DataSet(object):
 
         :param str field_names: field的名称
         :param bool flag: 将field_name的target状态设置为flag
+        :param bool use_1st_ins_infer_dim_type: 如果为True，将不会check该列是否所有数据都是同样的维度，同样的类型。将直接使用第一
+            行的数据进行类型和维度推断本列的数据的类型和维度。
         """
         assert isinstance(flag, bool), "Only bool type supported."
         for name in field_names:
             if name in self.field_arrays:
                 try:
+                    self.field_arrays[name]._use_1st_ins_infer_dim_type = bool(use_1st_ins_infer_dim_type)
                     self.field_arrays[name].is_target = flag
                 except SetInputOrTargetException as e:
-                    print(f"Cannot set field:{name} as target.")
+                    logger.error(f"Cannot set field:{name} as target.")
                     raise e
             else:
                 raise KeyError("{} is not a valid field name.".format(name))
+        return self
     
-    def set_input(self, *field_names, flag=True):
+    def set_input(self, *field_names, flag=True, use_1st_ins_infer_dim_type=True):
         """
         将field_names的field设置为input::
 
@@ -588,16 +625,20 @@ class DataSet(object):
 
         :param str field_names: field的名称
         :param bool flag: 将field_name的input状态设置为flag
+        :param bool use_1st_ins_infer_dim_type: 如果为True，将不会check该列是否所有数据都是同样的维度，同样的类型。将直接使用第一
+            行的数据进行类型和维度推断本列的数据的类型和维度。
         """
         for name in field_names:
             if name in self.field_arrays:
                 try:
+                    self.field_arrays[name]._use_1st_ins_infer_dim_type = bool(use_1st_ins_infer_dim_type)
                     self.field_arrays[name].is_input = flag
                 except SetInputOrTargetException as e:
-                    print(f"Cannot set field:{name} as input, exception happens at the {e.index} value.")
+                    logger.error(f"Cannot set field:{name} as input, exception happens at the {e.index} value.")
                     raise e
             else:
                 raise KeyError("{} is not a valid field name.".format(name))
+        return self
     
     def set_ignore_type(self, *field_names, flag=True):
         """
@@ -614,6 +655,7 @@ class DataSet(object):
                 self.field_arrays[name].ignore_type = flag
             else:
                 raise KeyError("{} is not a valid field name.".format(name))
+        return self
     
     def set_padder(self, field_name, padder):
         """
@@ -624,11 +666,12 @@ class DataSet(object):
             dataset.set_padder('chars', padder)  # 则chars这个field会使用EngChar2DPadder进行pad操作
 
         :param str field_name: 设置field的padding方式为padder
-        :param None, Padder padder: 设置为None即删除padder, 即对该field不进行pad操作。
+        :param None,~fastNLP.Padder padder: 设置为None即删除padder, 即对该field不进行pad操作。
         """
         if field_name not in self.field_arrays:
             raise KeyError("There is no field named {}.".format(field_name))
         self.field_arrays[field_name].set_padder(padder)
+        return self
     
     def set_pad_val(self, field_name, pad_val):
         """
@@ -640,6 +683,7 @@ class DataSet(object):
         if field_name not in self.field_arrays:
             raise KeyError("There is no field named {}.".format(field_name))
         self.field_arrays[field_name].set_pad_val(pad_val)
+        return self
     
     def get_input_name(self):
         """
@@ -672,7 +716,7 @@ class DataSet(object):
             2. is_target: bool, 如果为True则将名为 `new_field_name` 的field设置为target
 
             3. ignore_type: bool, 如果为True则将名为 `new_field_name` 的field的ignore_type设置为true, 忽略其类型
-        :return: list(Any), 里面的元素为func的返回值，所以list长度为DataSet的长度
+        :return List[Any]:   里面的元素为func的返回值，所以list长度为DataSet的长度
 
         """
         assert len(self) != 0, "Null DataSet cannot use apply_field()."
@@ -685,7 +729,7 @@ class DataSet(object):
                 results.append(func(ins[field_name]))
         except Exception as e:
             if idx != -1:
-                print("Exception happens at the `{}`th instance.".format(idx))
+                logger.error("Exception happens at the `{}`th(from 1) instance.".format(idx+1))
             raise e
         if not (new_field_name is None) and len(list(filter(lambda x: x is not None, results))) == 0:  # all None
             raise ValueError("{} always return None.".format(_get_func_signature(func=func)))
@@ -699,7 +743,7 @@ class DataSet(object):
         """
         将results作为加入到新的field中，field名称为new_field_name
 
-        :param list(str) results: 一般是apply*()之后的结果
+        :param List[str] results: 一般是apply*()之后的结果
         :param str new_field_name: 新加入的field的名称
         :param dict kwargs: 用户apply*()时传入的自定义参数
         :return:
@@ -742,7 +786,7 @@ class DataSet(object):
 
             3. ignore_type: bool, 如果为True则将 `new_field_name` 的field的ignore_type设置为true, 忽略其类型
             
-        :return: list(Any), 里面的元素为func的返回值，所以list长度为DataSet的长度
+        :return List[Any]: 里面的元素为func的返回值，所以list长度为DataSet的长度
         """
         assert len(self) != 0, "Null DataSet cannot use apply()."
         idx = -1
@@ -750,10 +794,11 @@ class DataSet(object):
             results = []
             for idx, ins in enumerate(self._inner_iter()):
                 results.append(func(ins))
-        except Exception as e:
+        except BaseException as e:
             if idx != -1:
-                print("Exception happens at the `{}`th instance.".format(idx))
+                logger.error("Exception happens at the `{}`th instance.".format(idx))
             raise e
+
         # results = [func(ins) for ins in self._inner_iter()]
         if not (new_field_name is None) and len(list(filter(lambda x: x is not None, results))) == 0:  # all None
             raise ValueError("{} always return None.".format(_get_func_signature(func=func)))
@@ -763,7 +808,7 @@ class DataSet(object):
         
         return results
 
-    def add_seq_len(self, field_name:str, new_field_name='seq_len'):
+    def add_seq_len(self, field_name:str, new_field_name=Const.INPUT_LEN):
         """
         将使用len()直接对field_name中每个元素作用，将其结果作为seqence length, 并放入seq_len这个field。
 
@@ -807,7 +852,7 @@ class DataSet(object):
 
         :param float ratio: 0<ratio<1, 返回的第一个DataSet拥有 `(1-ratio)` 这么多数据，第二个DataSet拥有`ratio`这么多数据
         :param bool shuffle: 在split前是否shuffle一下
-        :return: [DataSet, DataSet]
+        :return: [ :class:`~fastNLP.读取后的DataSet` , :class:`~fastNLP.读取后的DataSet` ]
         """
         assert isinstance(ratio, float)
         assert 0 < ratio < 1
@@ -829,48 +874,6 @@ class DataSet(object):
         
         return train_set, dev_set
     
-    @classmethod
-    def read_csv(cls, csv_path, headers=None, sep=",", dropna=True):
-        """
-        .. warning::
-            此方法会在下个版本移除，请使用 :class:`fastNLP.io.CSVLoader`
-        
-        从csv_path路径下以csv的格式读取数据。
-
-        :param str csv_path: 从哪里读取csv文件
-        :param list[str] headers: 如果为None，则使用csv文件的第一行作为header; 如果传入list(str), 则元素的个数必须
-            与csv文件中每行的元素个数相同。
-        :param str sep: 分割符
-        :param bool dropna: 是否忽略与header数量不一致行。
-        :return: 一个 :class:`~fastNLP.DataSet` 类型的对象
-        """
-        warnings.warn('DataSet.read_csv is deprecated, use CSVLoader instead',
-                      category=DeprecationWarning)
-        with open(csv_path, "r", encoding='utf-8') as f:
-            start_idx = 0
-            if headers is None:
-                headers = f.readline().rstrip('\r\n')
-                headers = headers.split(sep)
-                start_idx += 1
-            else:
-                assert isinstance(headers, (list, tuple)), "headers should be list or tuple, not {}.".format(
-                    type(headers))
-            _dict = {}
-            for col in headers:
-                _dict[col] = []
-            for line_idx, line in enumerate(f, start_idx):
-                contents = line.rstrip('\r\n').split(sep)
-                if len(contents) != len(headers):
-                    if dropna:
-                        continue
-                    else:
-                        # TODO change error type
-                        raise ValueError("Line {} has {} parts, while header has {} parts." \
-                                         .format(line_idx, len(contents), len(headers)))
-                for header, content in zip(headers, contents):
-                    _dict[header].append(content)
-        return cls(_dict)
-    
     def save(self, path):
         """
         保存DataSet.
@@ -882,11 +885,11 @@ class DataSet(object):
     
     @staticmethod
     def load(path):
-        """
+        r"""
         从保存的DataSet pickle文件的路径中读取DataSet
 
         :param str path: 从哪里读取DataSet
-        :return: 一个 :class:`~fastNLP.DataSet` 类型的对象
+        :return: 读取后的 :class:`~fastNLP.读取后的DataSet`。
         """
         with open(path, 'rb') as f:
             d = pickle.load(f)

fastNLP/core/dist_trainer.py

@@ -0,0 +1,356 @@
+"""undocumented
+正在开发中的分布式训练代码
+"""
+import logging
+import os
+import time
+from datetime import datetime
+
+import torch
+import torch.cuda
+import torch.distributed as dist
+import torch.optim
+from pkg_resources import parse_version
+from torch.nn.parallel import DistributedDataParallel as DDP
+from torch.utils.data.distributed import DistributedSampler
+from tqdm import tqdm
+
+from ._logger import logger
+from .batch import DataSetIter, BatchIter
+from .callback import DistCallbackManager, CallbackException, TesterCallback
+from .dataset import DataSet
+from .losses import _prepare_losser
+from .optimizer import Optimizer
+from .utils import _build_args
+from .utils import _get_func_signature
+from .utils import _move_dict_value_to_device
+
+__all__ = [
+    'get_local_rank',
+    'DistTrainer',
+]
+
+
+def get_local_rank():
+    if 'LOCAL_RANK' in os.environ:
+        return int(os.environ['LOCAL_RANK'])
+    from argparse import ArgumentParser
+    parser = ArgumentParser()
+    parser.add_argument('--local_rank', type=int)
+    args, _ = parser.parse_known_args()
+    if 'local_rank' in args and args.local_rank:
+        os.environ['LOCAL_RANK'] = str(args.local_rank) # for multiple calls for this function
+        return args.local_rank
+    raise RuntimeError('Please use "python -m torch.distributed.launch --nproc_per_node=N train_script.py')
+
+
+class DistTrainer():
+    """
+    Distributed Trainer that support distributed and mixed precision training
+    """
+    def __init__(self, train_data, model, optimizer=None, loss=None,
+                 callbacks_all=None, callbacks_master=None,
+                 batch_size_per_gpu=8, n_epochs=1,
+                 num_workers=1, drop_last=False,
+                 dev_data=None, metrics=None, metric_key=None,
+                 update_every=1, print_every=10, validate_every=-1,
+                 save_every=-1, save_path=None, device='auto',
+                 fp16='', backend=None, init_method=None):
+
+        assert device in ['auto', 'cuda', 'cpu'], "Please set correct device in [auto', 'cuda', 'cpu']"
+        if device == 'auto':
+            device = 'cuda' if torch.cuda.is_available() else 'cpu'
+        if backend is None:
+            backend = 'nccl' if device == 'cuda' else 'gloo'
+
+        # init distributed
+        if device == 'cuda':
+            torch.cuda.set_device(get_local_rank())
+            self.device = torch.device("cuda", get_local_rank())
+        else:
+            self.device = torch.device(device)
+
+        dist.init_process_group(backend=backend, init_method=init_method)
+        self.world_size = dist.get_world_size()
+        self.rank = dist.get_rank() # unique id for each process
+
+        self.model = model
+        self.train_data = train_data
+        self.batch_size_per_gpu = int(batch_size_per_gpu)
+        self.n_epochs = int(n_epochs)
+        self.num_data_workers = int(num_workers)
+        self.drop_last = drop_last
+        self.update_every = int(update_every)
+        self.print_every = int(print_every)
+        self.validate_every = int(validate_every)
+        self.save_every = int(save_every)
+        self.save_path = save_path
+        self.losser = _prepare_losser(loss)
+        self.fp16 = fp16
+        self.init_method = init_method
+        self.backend = backend
+        self.local_rank = get_local_rank()
+        self._forward_func = model.forward
+        self.callback_manager = DistCallbackManager(
+            env={"trainer": self}, callbacks_all=callbacks_all,
+            callbacks_master=callbacks_master)
+        self.metric_key = metric_key
+
+        model.to(self.device)
+        optimizer = self._get_optimizer(optimizer)
+
+        # init fp16, must before DataParallel init
+        if len(self.fp16):
+            assert isinstance(self.fp16, str), "Please set Apex AMP optimization level selected in ['O0', 'O1', 'O2', 'O3']"
+            try:
+                from apex import amp
+            except ImportError:
+                raise ImportError("Please install apex from https://www.github.com/nvidia/apex to use fp16 training.")
+            assert torch.backends.cudnn.enabled, "Amp requires cudnn backend to be enabled."
+            assert device == 'cuda', "Amp requires cuda device"
+            model, optimizer = amp.initialize(model, optimizer, opt_level=self.fp16)
+
+        # init DataParallel
+        if parse_version(torch.__version__)>=parse_version('1.1'):
+            self.model = DDP(model, device_ids=[self.local_rank],
+                             output_device=self.local_rank, find_unused_parameters=True)
+        else:
+            self.model = DDP(model, device_ids=[self.local_rank],
+                             output_device=self.local_rank)
+
+        self.optimizer = optimizer
+        self.sampler = DistributedSampler(self.train_data)
+        self.data_iterator = self._get_data_iter(self.train_data)
+        self.n_steps = self._get_n_steps()
+
+        # for evaluation, only run eval on master proc
+        if dev_data and metrics:
+            cb = TesterCallback(
+                dev_data, model, metrics,
+                batch_size=batch_size_per_gpu, num_workers=num_workers)
+            self.callback_manager.add_callback([cb], master=True)
+
+        # Setup logging
+        dist.barrier()
+        self.start_time = datetime.now().strftime('%m_%d_%Y-%H_%M')
+        if self.save_path:
+            self.cp_save_path = os.path.join(self.save_path, 'checkpoints', self.start_time)
+        else:
+            self.cp_save_path = None
+
+        # use INFO in the master, WARN for others
+        logger.setLevel(logging.INFO  if self.is_master else logging.WARNING)
+        self.logger = logger
+        self.logger.info("Setup Distributed Trainer")
+        self.logger.warning("Process pid: {}, rank: {}, local rank: {}, device: {}, fp16: {}".format(
+                        os.getpid(), self.rank, self.local_rank, self.device, self.fp16 if self.fp16 else False))
+        self.logger.info("Num of processes: {}".format(self.world_size))
+        self.logger.info("Use device: {}".format(device))
+        self.logger.info("Training with fp16: {}, optimization level: {}".format(
+                        len(self.fp16) > 0, self.fp16 if self.fp16 else None))
+
+    def _get_n_steps(self):
+        batch_size = self.world_size * self.batch_size_per_gpu
+        return (len(self.train_data) // batch_size + int(
+            len(self.train_data) % batch_size != 0)) * int(self.drop_last == 0) * self.n_epochs
+
+    def _get_data_iter(self, dataset):
+        if isinstance(dataset, DataSet):
+            return DataSetIter(
+                dataset=dataset, batch_size=self.batch_size_per_gpu,
+                num_workers=self.num_data_workers, sampler=self.sampler,
+                drop_last=self.drop_last
+            )
+        elif isinstance(dataset, BatchIter):
+            return dataset
+        else:
+            raise TypeError("train_data type {} not support".format(type(dataset)))
+
+    def _get_optimizer(self, optimizer):
+        if isinstance(optimizer, torch.optim.Optimizer):
+            return optimizer
+        elif isinstance(optimizer, Optimizer):
+            return optimizer.construct_from_pytorch(self.model.parameters())
+        elif optimizer is None:
+            return torch.optim.Adam(self.model.parameters(), lr=4e-3)
+        else:
+            raise TypeError("optimizer can only be torch.optim.Optimizer type, not {}.".format(type(optimizer)))
+
+    @property
+    def is_master(self):
+        return self.rank == 0
+
+    def train(self, on_exception='auto'):
+        try:
+            self.logger.info("###### Training epochs started ######")
+            self.logger.info('Total epochs: %d'% self.n_epochs)
+            self.logger.info('Total steps: %d'% self.n_steps)
+            self.logger.info('Num instances per GPU %d'% self.batch_size_per_gpu)
+            self.logger.info('Total batch_size: %d'% self.batch_size_per_gpu * dist.get_world_size())
+            self.logger.info('Total num of samples: %d'% len(self.train_data))
+            self.logger.info("Num of callbacks for all workers: {}".format(
+                                len(self.callback_manager.callbacks_all)))
+            self.logger.info("Num of callbacks for master workers: {}".format(
+                                len(self.callback_manager.callbacks_master)))
+            self.logger.info("Callbacks for all workers: {}".format(
+                    [repr(cb) for cb in self.callback_manager.callbacks_all]))
+            self.logger.info("Callbacks for master workers: {}".format(
+                    [repr(cb) for cb in self.callback_manager.callbacks_master]))
+
+            start_time = time.time()
+            results = {}
+            if self.n_epochs <= 0:
+                self.logger.info("Training epoch is {}, nothing was done.".format(self.n_epochs))
+                results['seconds'] = 0.
+                return results
+
+            try:
+                self.callback_manager.on_train_begin()
+                self._train()
+                self.callback_manager.on_train_end()
+
+            except BaseException as e:
+                self.callback_manager.on_exception(e)
+                if on_exception == 'auto':
+                    if not isinstance(e, (CallbackException, KeyboardInterrupt)):
+                        raise e
+                    else:
+                        self.logger.info('Catch {}, ignored.'.format(e.__class__.__name__))
+                elif on_exception == 'raise':
+                    raise e
+
+            results['seconds'] = round(time.time() - start_time, 2)
+            self.logger.info("###### Train finished ######")
+            self.logger.info('Total train time: {} seconds.'. format(results['seconds']))
+            return results
+        finally:
+            self.close()
+
+    def _train(self):
+        if self.fp16:
+            # skip check, done in __init__()
+            from apex import amp
+        self.step = 0
+        self.epoch = 0
+        self.pbar = tqdm(total=self.n_steps, postfix='loss:{0:<6.5f}',
+                        leave=False, dynamic_ncols=True, disable=not self.is_master)
+        pbar = self.pbar
+        avg_loss = 0
+        data_iterator = self.data_iterator
+        self.model.zero_grad()
+        for epoch in range(1, self.n_epochs + 1):
+            self.epoch = epoch
+            pbar.set_description_str(desc="Epoch {}/{}".format(epoch, self.n_epochs))
+            # early stopping
+            self.callback_manager.on_epoch_begin()
+            for batch_x, batch_y in data_iterator:
+                self.model.train()
+                self.step += 1
+                _move_dict_value_to_device(batch_x, batch_y, device=self.device)
+                indices = data_iterator.get_batch_indices()
+                # negative sampling; replace unknown; re-weight batch_y
+                self.callback_manager.on_batch_begin(batch_x, batch_y, indices)
+                prediction = self._data_forward(self.model, batch_x)
+
+                # edit prediction
+                self.callback_manager.on_loss_begin(batch_y, prediction)
+                loss = self._compute_loss(prediction, batch_y)
+                avg_loss += loss.item()
+
+                # Is loss NaN or inf? requires_grad = False
+                self.callback_manager.on_backward_begin(loss)
+
+                if self.fp16:
+                    with amp.scale_loss(loss, self.optimizer) as scale_loss:
+                        scale_loss.backward()
+                else:
+                    loss.backward()
+
+                self.callback_manager.on_backward_end()
+
+                self._update()
+                self.callback_manager.on_step_end()
+
+                if self.step % self.print_every == 0:
+                    avg_loss = float(avg_loss) / self.print_every
+                    print_output = "loss:{:<6.5f}".format(avg_loss)
+                    pbar.update(self.print_every)
+                    pbar.set_postfix_str(print_output)
+                    avg_loss = 0
+
+                self.callback_manager.on_batch_end()
+
+                if (self.validate_every > 0 and self.step % self.validate_every == 0):
+                    self._do_validation()
+
+                if self.cp_save_path and \
+                        self.save_every > 0 and \
+                        self.step % self.save_every == 0:
+                    self.save_check_point()
+
+            # ================= mini-batch end ==================== #
+            if self.validate_every < 0:
+                self._do_validation()
+
+        if self.save_every < 0 and self.cp_save_path:
+            self.save_check_point()
+            # lr decay; early stopping
+            self.callback_manager.on_epoch_end()
+        # =============== epochs end =================== #
+        pbar.close()
+        self.pbar = None
+    # ============ tqdm end ============== #
+
+    def _update(self):
+        """Perform weight update on a model.
+
+        """
+        if self.step % self.update_every == 0:
+            self.optimizer.step()
+            self.model.zero_grad()
+
+    def _data_forward(self, network, x):
+        x = _build_args(self._forward_func, **x)
+        y = network(**x)
+        if not isinstance(y, dict):
+            raise TypeError(
+                f"The return value of {_get_func_signature(self._forward_func)} should be dict, got {type(y)}.")
+        return y
+
+    def _compute_loss(self, predict, truth):
+        """Compute loss given prediction and ground truth.
+
+        :param predict: prediction dict, produced by model.forward
+        :param truth: ground truth dict, produced by batch_y
+        :return: a scalar
+        """
+        loss = self.losser(predict, truth)
+        if self.update_every > 1:
+            loss = loss / self.update_every
+        return loss.mean()
+
+    def save_check_point(self, only_params=False):
+        # only master save models
+        if self.is_master:
+            os.makedirs(self.cp_save_path, exist_ok=True)
+            path = os.path.join(self.cp_save_path, 'checkpoint-{}.bin'.format(self.step))
+            self.logger.info("Save checkpoint to {}".format(path))
+            model_to_save = self.model.module
+            if only_params:
+                model_to_save = model_to_save.state_dict()
+            torch.save(model_to_save, path)
+
+    def _do_validation(self):
+        self.callback_manager.on_valid_begin()
+        eval_res = self.callback_manager.on_validation()
+        eval_res = list(filter(lambda x: x is not None, eval_res))
+        if len(eval_res):
+            eval_res, is_better = list(zip(*eval_res))
+        else:
+            eval_res, is_better = None, None
+        self.callback_manager.on_valid_end(
+            eval_res, self.metric_key, self.optimizer, is_better)
+        dist.barrier()
+
+    def close(self):
+        dist.destroy_process_group()

fastNLP/core/field.py

@@ -1,36 +1,53 @@
+"""
+.. todo::
+    doc
+"""
 
+__all__ = [
+    "Padder",
+    "AutoPadder",
+    "EngChar2DPadder",
+]
 
-from numbers import Number
-import torch
-import numpy as np
-from typing import Any
 from abc import abstractmethod
-from copy import deepcopy
 from collections import Counter
+from copy import deepcopy
+from numbers import Number
+from typing import Any
+
+import numpy as np
+import torch
+
+from ._logger import logger
+from .utils import _is_iterable
+
 
 class SetInputOrTargetException(Exception):
     def __init__(self, msg, index=None, field_name=None):
         super().__init__(msg)
         self.msg = msg
         self.index = index  # 标示在哪个数据遭遇到问题了
-        self.field_name = field_name # 标示当前field的名称
+        self.field_name = field_name  # 标示当前field的名称
+
 
 class AppendToTargetOrInputException(Exception):
     def __init__(self, msg, index=None, field_name=None):
         super().__init__(msg)
         self.msg = msg
         self.index = index  # 标示在哪个数据遭遇到问题了
-        self.field_name = field_name # 标示当前field的名称
+        self.field_name = field_name  # 标示当前field的名称
+
 
 class FieldArray:
-    def __init__(self, name, content, is_target=False, is_input=False, padder=None, ignore_type=False):
-        if len(content)==0:
+    def __init__(self, name, content, is_target=False, is_input=False, padder=None, ignore_type=False,
+                 use_1st_ins_infer_dim_type=True):
+        if len(content) == 0:
             raise RuntimeError("Empty fieldarray is not allowed.")
         _content = content
         try:
             _content = list(_content)
         except BaseException as e:
-            print(f"Cannot convert content(of type:{type(content)}) into list.")
+            logger.error(f"Cannot convert content(of type:{type(content)}) into list.")
             raise e
         self.name = name
         self.content = _content
@@ -38,36 +55,37 @@ class FieldArray:
         #  根据input的情况设置input，target等
         self._cell_ndim = None  # 多少维度
         self.dtype = None  # 最内层的element都是什么类型的
+        self._use_1st_ins_infer_dim_type = bool(use_1st_ins_infer_dim_type)
         self._is_input = False
         self._is_target = False
-
+        
         if is_input:
             self.is_input = is_input
         if is_target:
             self.is_target = is_target
-
+        
         if padder is None:
             padder = AutoPadder(pad_val=0)
         else:
             assert isinstance(padder, Padder), "padder must be of type fastNLP.Padder."
             padder = deepcopy(padder)
         self.set_padder(padder)
-
+    
     @property
     def ignore_type(self):
         return self._ignore_type
-
+    
     @ignore_type.setter
     def ignore_type(self, value):
         if value:
             self._cell_ndim = None
             self.dtype = None
         self._ignore_type = value
-
+    
     @property
     def is_input(self):
         return self._is_input
-
+    
     @is_input.setter
     def is_input(self, value):
         """
@@ -77,16 +95,16 @@ class FieldArray:
         if value is True and \
                 self._is_target is False and \
                 self._ignore_type is False:
-            self._check_dtype_and_ndim()
+            self._check_dtype_and_ndim(only_check_1st_ins_dim_type=self._use_1st_ins_infer_dim_type)
         if value is False and self._is_target is False:
             self.dtype = None
             self._cell_ndim = None
         self._is_input = value
-
+    
     @property
     def is_target(self):
         return self._is_target
-
+    
     @is_target.setter
     def is_target(self, value):
         """
@@ -95,70 +113,82 @@ class FieldArray:
         if value is True and \
                 self._is_input is False and \
                 self._ignore_type is False:
-            self._check_dtype_and_ndim()
+            self._check_dtype_and_ndim(only_check_1st_ins_dim_type=self._use_1st_ins_infer_dim_type)
         if value is False and self._is_input is False:
             self.dtype = None
             self._cell_ndim = None
         self._is_target = value
-
-    def _check_dtype_and_ndim(self):
+    
+    def _check_dtype_and_ndim(self, only_check_1st_ins_dim_type=True):
         """
         检查当前content所有的element是否是同一个类型，且是否每个元素具有相同的维度。通过的话，设置_cell_ndim与_ele_type属性；没有
             通过将直接报错.
 
+        :param bool only_check_1st_ins_dim_type: 是否只检查第一个元素的type和dim
         :return:
         """
         cell_0 = self.content[0]
         index = 0
         try:
             type_0, dim_0 = _get_ele_type_and_dim(cell_0)
-            for cell in self.content[1:]:
-                index += 1
-                type_i, dim_i = _get_ele_type_and_dim(cell)
-                if type_i!=type_0:
-                    raise SetInputOrTargetException("Type:{} in index {} is different from the first element with type:{}."
-                                                    ".".format(type_i, index, type_0))
-                if dim_0!=dim_i:
-                    raise SetInputOrTargetException("Dimension:{} in index {} is different from the first element with "
-                                                    "dimension:{}.".format(dim_i, index, dim_0))
+            if not only_check_1st_ins_dim_type:
+                for cell in self.content[1:]:
+                    index += 1
+                    type_i, dim_i = _get_ele_type_and_dim(cell)
+                    if type_i != type_0:
+                        raise SetInputOrTargetException(
+                            "Type:{} in index {} is different from the first element with type:{}."
+                            ".".format(type_i, index, type_0))
+                    if dim_0 != dim_i:
+                        raise SetInputOrTargetException(
+                            "Dimension:{} in index {} is different from the first element with "
+                            "dimension:{}.".format(dim_i, index, dim_0))
             self._cell_ndim = dim_0
             self.dtype = type_0
         except SetInputOrTargetException as e:
             e.index = index
             raise e
-
-    def append(self, val:Any):
+    
+    def append(self, val: Any):
         """
         :param val: 把该val append到fieldarray。
         :return:
         """
-        if (self._is_target or self._is_input) and self._ignore_type is False:
+        if (self._is_target or self._is_input) and self._ignore_type is False and not self._use_1st_ins_infer_dim_type:
             type_, dim_ = _get_ele_type_and_dim(val)
-            if self.dtype!=type_:
+            if self.dtype != type_:
                 raise AppendToTargetOrInputException(f"Value(type:{type_}) are of different types with "
                                                      f"previous values(type:{self.dtype}).")
-            if self._cell_ndim!=dim_:
+            if self._cell_ndim != dim_:
                 raise AppendToTargetOrInputException(f"Value(dim:{dim_}) are of different dimensions with "
                                                      f"previous values(dim:{self._cell_ndim}).")
             self.content.append(val)
         else:
             self.content.append(val)
-
+    
+    def pop(self, index):
+        """
+        删除该field中index处的元素
+        :param int index: 从0开始的数据下标。
+        :return:
+        """
+        self.content.pop(index)
+    
     def __getitem__(self, indices):
         return self.get(indices, pad=False)
-
+    
     def __setitem__(self, idx, val):
         assert isinstance(idx, int)
         if (self._is_target or self._is_input) and self.ignore_type is False:  # 需要检测类型
             type_, dim_ = _get_ele_type_and_dim(val)
-            if self.dtype!=type_:
+            if self.dtype != type_:
                 raise RuntimeError(f"Value(type:{type_}) are of different types with "
-                                                     f"other values(type:{self.dtype}).")
-            if self._cell_ndim!=dim_:
+                                   f"other values(type:{self.dtype}).")
+            if self._cell_ndim != dim_:
                 raise RuntimeError(f"Value(dim:{dim_}) are of different dimensions with "
-                                                     f"previous values(dim:{self._cell_ndim}).")
+                                   f"previous values(dim:{self._cell_ndim}).")
         self.content[idx] = val
-
+    
     def get(self, indices, pad=True):
         """
         根据给定的indices返回内容
@@ -171,16 +201,16 @@ class FieldArray:
             return self.content[indices]
         if self.is_input is False and self.is_target is False:
             raise RuntimeError("Please specify either is_input or is_target to True for {}".format(self.name))
-
+        
         contents = [self.content[i] for i in indices]
         if self.padder is None or pad is False:
             return np.array(contents)
         else:
             return self.pad(contents)
-
+    
     def pad(self, contents):
         return self.padder(contents, field_name=self.name, field_ele_dtype=self.dtype, dim=self._cell_ndim)
-
+    
     def set_padder(self, padder):
         """
         设置padder，在这个field进行pad的时候用这个padder进行pad，如果为None则不进行pad。
@@ -192,7 +222,7 @@ class FieldArray:
             self.padder = deepcopy(padder)
         else:
             self.padder = None
-
+    
     def set_pad_val(self, pad_val):
         """
         修改padder的pad_val.
@@ -202,7 +232,7 @@ class FieldArray:
         if self.padder is not None:
             self.padder.set_pad_val(pad_val)
         return self
-
+    
     def __len__(self):
         """
         Returns the size of FieldArray.
@@ -210,7 +240,7 @@ class FieldArray:
         :return int length:
         """
         return len(self.content)
-
+    
     def to(self, other):
         """
         将other的属性复制给本FieldArray(other必须为FieldArray类型).
@@ -220,15 +250,15 @@ class FieldArray:
         :return: :class:`~fastNLP.FieldArray`
         """
         assert isinstance(other, FieldArray), "Only supports fastNLP.FieldArray type, not {}.".format(type(other))
-
+        
         self.ignore_type = other.ignore_type
         self.is_input = other.is_input
         self.is_target = other.is_target
         self.padder = other.padder
-
+        
         return self
-
-    def split(self, sep:str=None, inplace:bool=True):
+    
+    def split(self, sep: str = None, inplace: bool = True):
         """
         依次对自身的元素使用.split()方法，应该只有当本field的元素为str时，该方法才有用。将返回值
 
@@ -241,11 +271,11 @@ class FieldArray:
             try:
                 new_contents.append(cell.split(sep))
             except Exception as e:
-                print(f"Exception happens when process value in index {index}.")
+                logger.error(f"Exception happens when process value in index {index}.")
                 raise e
         return self._after_process(new_contents, inplace=inplace)
-
-    def int(self, inplace:bool=True):
+    
+    def int(self, inplace: bool = True):
         """
         将本field中的值调用int(cell). 支持field中内容为以下两种情况(1)['1', '2', ...](即field中每个值为str的)，
             (2) [['1', '2', ..], ['3', ..], ...](即field中每个值为一个list，list中的值会被依次转换。)
@@ -261,10 +291,10 @@ class FieldArray:
                 else:
                     new_contents.append(int(cell))
             except Exception as e:
-                print(f"Exception happens when process value in index {index}.")
-                print(e)
+                logger.error(f"Exception happens when process value in index {index}.")
+                raise e
         return self._after_process(new_contents, inplace=inplace)
-
+    
     def float(self, inplace=True):
         """
         将本field中的值调用float(cell). 支持field中内容为以下两种情况(1)['1', '2', ...](即field中每个值为str的)，
@@ -281,10 +311,10 @@ class FieldArray:
                 else:
                     new_contents.append(float(cell))
             except Exception as e:
-                print(f"Exception happens when process value in index {index}.")
+                logger.error(f"Exception happens when process value in index {index}.")
                 raise e
         return self._after_process(new_contents, inplace=inplace)
-
+    
     def bool(self, inplace=True):
         """
         将本field中的值调用bool(cell). 支持field中内容为以下两种情况(1)['1', '2', ...](即field中每个值为str的)，
@@ -301,11 +331,11 @@ class FieldArray:
                 else:
                     new_contents.append(bool(cell))
             except Exception as e:
-                print(f"Exception happens when process value in index {index}.")
+                logger.error(f"Exception happens when process value in index {index}.")
                 raise e
-
+        
         return self._after_process(new_contents, inplace=inplace)
-
+    
     def lower(self, inplace=True):
         """
         将本field中的值调用cell.lower(). 支持field中内容为以下两种情况(1)['1', '2', ...](即field中每个值为str的)，
@@ -322,10 +352,10 @@ class FieldArray:
                 else:
                     new_contents.append(cell.lower())
             except Exception as e:
-                print(f"Exception happens when process value in index {index}.")
+                logger.error(f"Exception happens when process value in index {index}.")
                 raise e
         return self._after_process(new_contents, inplace=inplace)
-
+    
     def upper(self, inplace=True):
         """
         将本field中的值调用cell.lower(). 支持field中内容为以下两种情况(1)['1', '2', ...](即field中每个值为str的)，
@@ -342,10 +372,10 @@ class FieldArray:
                 else:
                     new_contents.append(cell.upper())
             except Exception as e:
-                print(f"Exception happens when process value in index {index}.")
+                logger.error(f"Exception happens when process value in index {index}.")
                 raise e
         return self._after_process(new_contents, inplace=inplace)
-
+    
     def value_count(self):
         """
         返回该field下不同value的数量。多用于统计label数量
@@ -353,17 +383,18 @@ class FieldArray:
         :return: Counter, key是label，value是出现次数
         """
         count = Counter()
-
+        
         def cum(cell):
             if _is_iterable(cell) and not isinstance(cell, str):
                 for cell_ in cell:
                     cum(cell_)
             else:
                 count[cell] += 1
+        
         for cell in self.content:
             cum(cell)
         return count
-
+    
     def _after_process(self, new_contents, inplace):
         """
         当调用处理函数之后，决定是否要替换field。
@@ -378,14 +409,14 @@ class FieldArray:
                 self.is_input = self.is_input
                 self.is_target = self.is_input
             except SetInputOrTargetException as e:
-                print("The newly generated field cannot be set as input or target.")
+                logger.error("The newly generated field cannot be set as input or target.")
                 raise e
             return self
         else:
             return new_contents
 
 
-def _get_ele_type_and_dim(cell:Any, dim=0):
+def _get_ele_type_and_dim(cell: Any, dim=0):
     """
     识别cell的类别与dimension的数量
 
@@ -401,13 +432,13 @@ def _get_ele_type_and_dim(cell:Any, dim=0):
     elif isinstance(cell, list):
         dim += 1
         res = [_get_ele_type_and_dim(cell_i, dim) for cell_i in cell]
-        types = set([i for i,j in res])
-        dims = set([j for i,j in res])
-        if len(types)>1:
+        types = set([i for i, j in res])
+        dims = set([j for i, j in res])
+        if len(types) > 1:
             raise SetInputOrTargetException("Mixed types detected: {}.".format(list(types)))
-        elif len(types)==0:
+        elif len(types) == 0:
             raise SetInputOrTargetException("Empty value encountered.")
-        if len(dims)>1:
+        if len(dims) > 1:
             raise SetInputOrTargetException("Mixed dimension detected: {}.".format(list(dims)))
         return types.pop(), dims.pop()
     elif isinstance(cell, torch.Tensor):
@@ -418,28 +449,19 @@ def _get_ele_type_and_dim(cell:Any, dim=0):
         # 否则需要继续往下iterate
         dim += 1
         res = [_get_ele_type_and_dim(cell_i, dim) for cell_i in cell]
-        types = set([i for i,j in res])
-        dims = set([j for i,j in res])
-        if len(types)>1:
+        types = set([i for i, j in res])
+        dims = set([j for i, j in res])
+        if len(types) > 1:
             raise SetInputOrTargetException("Mixed types detected: {}.".format(list(types)))
-        elif len(types)==0:
+        elif len(types) == 0:
             raise SetInputOrTargetException("Empty value encountered.")
-        if len(dims)>1:
+        if len(dims) > 1:
             raise SetInputOrTargetException("Mixed dimension detected: {}.".format(list(dims)))
         return types.pop(), dims.pop()
-    else: # 包含tuple, set, dict以及其它的类型
+    else:  # 包含tuple, set, dict以及其它的类型
         raise SetInputOrTargetException(f"Cannot process type:{type(cell)}.")
 
 
-def _is_iterable(value):
-    # 检查是否是iterable的, duck typing
-    try:
-        iter(value)
-        return True
-    except BaseException as e:
-        return False
-
-
 class Padder:
     """
     别名：:class:`fastNLP.Padder` :class:`fastNLP.core.field.Padder`
@@ -448,28 +470,29 @@ class Padder:
     用于对batch进行padding操作。传入的element是inplace的，即直接修改element可能导致数据变化，建议inplace修改之前deepcopy一份。
 
     .. py:function:: __call__(self, contents, field_name, field_ele_dtype):
+        
         传入的是List内容。假设有以下的DataSet。
 
-        :param list(Any) contents: 传入的element是inplace的，即直接修改element可能导致数据变化，建议inplace修改之前
+        :param List[Any] contents: 传入的element是inplace的，即直接修改element可能导致数据变化，建议inplace修改之前
             deepcopy一份。
         :param str, field_name: field的名称。
         :param np.int64,np.float64,np.str,None, field_ele_dtype: 该field的内层元素的类型。如果该field的ignore_type为True，该这个值为None。
         :return: np.array([padded_element])
 
     """
-
+    
     def __init__(self, pad_val=0, **kwargs):
         self.pad_val = pad_val
-
+    
     def set_pad_val(self, pad_val):
         self.pad_val = pad_val
-
+    
     @abstractmethod
-    def __call__(self, contents, field_name, field_ele_dtype, dim:int):
+    def __call__(self, contents, field_name, field_ele_dtype, dim: int):
         """
         传入的是List内容。假设有以下的DataSet。
 
-        :param list(Any) contents: 传入的element是inplace的，即直接修改element可能导致数据变化，建议inplace修改之前
+        :param List[Any] contents: 传入的element是inplace的，即直接修改element可能导致数据变化，建议inplace修改之前
             deepcopy一份。
         :param str, field_name: field的名称。
         :param np.int64,np.float64,np.str,None, field_ele_dtype: 该field的内层元素的类型。如果该field的ignore_type为True，
@@ -532,23 +555,24 @@ class AutoPadder(Padder):
 
     3 其它情况不进行处理，返回一个np.array类型。
     """
+    
     def __init__(self, pad_val=0):
         super().__init__(pad_val=pad_val)
-
+    
     def __call__(self, contents, field_name, field_ele_dtype, dim):
         if field_ele_dtype:
-            if dim>3:
+            if dim > 3:
                 return np.array(contents)
             if isinstance(field_ele_dtype, type) and \
                     (issubclass(field_ele_dtype, np.number) or issubclass(field_ele_dtype, Number)):
-                if dim==0:
+                if dim == 0:
                     array = np.array(contents, dtype=field_ele_dtype)
-                elif dim==1:
+                elif dim == 1:
                     max_len = max(map(len, contents))
                     array = np.full((len(contents), max_len), self.pad_val, dtype=field_ele_dtype)
                     for i, content_i in enumerate(contents):
                         array[i, :len(content_i)] = content_i
-                elif dim==2:
+                elif dim == 2:
                     max_len = max(map(len, contents))
                     max_word_len = max([max([len(content_ii) for content_ii in content_i]) for
                                         content_i in contents])
@@ -558,20 +582,21 @@ class AutoPadder(Padder):
                             array[i, j, :len(content_ii)] = content_ii
                 else:
                     shape = np.shape(contents)
-                    if len(shape)==4: # 说明各dimension是相同的大小
+                    if len(shape) == 4:  # 说明各dimension是相同的大小
                         array = np.array(contents, dtype=field_ele_dtype)
                     else:
-                        raise RuntimeError(f"Field:{field_name} has 3 dimensions, every sample should have the same shape.")
+                        raise RuntimeError(
+                            f"Field:{field_name} has 3 dimensions, every sample should have the same shape.")
                 return array
             elif str(field_ele_dtype).startswith('torch'):
-                if dim==0:
+                if dim == 0:
                     tensor = torch.tensor(contents).to(field_ele_dtype)
-                elif dim==1:
+                elif dim == 1:
                     max_len = max(map(len, contents))
                     tensor = torch.full((len(contents), max_len), fill_value=self.pad_val, dtype=field_ele_dtype)
                     for i, content_i in enumerate(contents):
                         tensor[i, :len(content_i)] = torch.tensor(content_i)
-                elif dim==2:
+                elif dim == 2:
                     max_len = max(map(len, contents))
                     max_word_len = max([max([len(content_ii) for content_ii in content_i]) for
                                         content_i in contents])
@@ -582,15 +607,18 @@ class AutoPadder(Padder):
                             tensor[i, j, :len(content_ii)] = torch.tensor(content_ii)
                 else:
                     shapes = set([np.shape(content_i) for content_i in contents])
-                    if len(shapes)>1:
-                        raise RuntimeError(f"Field:{field_name} has 3 dimensions, every sample should have the same shape.")
+                    if len(shapes) > 1:
+                        raise RuntimeError(
+                            f"Field:{field_name} has 3 dimensions, every sample should have the same shape.")
                     shape = shapes.pop()
-                    if len(shape)==3:
-                        tensor = torch.full([len(contents)]+list(shape), fill_value=self.pad_val, dtype=field_ele_dtype)
+                    if len(shape) == 3:
+                        tensor = torch.full([len(contents)] + list(shape), fill_value=self.pad_val,
+                                            dtype=field_ele_dtype)
                         for i, content_i in enumerate(contents):
                             tensor[i] = torch.tensor(content_i, dtype=field_ele_dtype)
                     else:
-                        raise RuntimeError(f"Field:{field_name} has 3 dimensions, every sample should have the same shape.")
+                        raise RuntimeError(
+                            f"Field:{field_name} has 3 dimensions, every sample should have the same shape.")
                 return tensor
             else:
                 return np.array(contents)  # 不进行任何操作
@@ -621,7 +649,7 @@ class EngChar2DPadder(Padder):
         dataset.set_padder('chars', padder)  # chars这个field的设置为了EnChar2DPadder
 
     """
-
+    
     def __init__(self, pad_val=0, pad_length=0):
         """
         :param pad_val: int, pad的位置使用该index
@@ -629,9 +657,9 @@ class EngChar2DPadder(Padder):
             都pad或截取到该长度.
         """
         super().__init__(pad_val=pad_val)
-
+        
         self.pad_length = pad_length
-
+    
     def __call__(self, contents, field_name, field_ele_dtype, dim):
         """
         期望输入类似于
@@ -650,7 +678,7 @@ class EngChar2DPadder(Padder):
             raise TypeError('dtype of Field:{} should be np.int64 or np.float64 to do 2D padding, get {}.'.format(
                 field_name, field_ele_dtype
             ))
-        assert dim==2, f"Field:{field_name} has {dim}, EngChar2DPadder only supports input with 2 dimensions."
+        assert dim == 2, f"Field:{field_name} has {dim}, EngChar2DPadder only supports input with 2 dimensions."
         if self.pad_length < 1:
             max_char_length = max([max(len(char_lst) for char_lst in word_lst) for word_lst in contents])
         else:
@@ -658,12 +686,12 @@ class EngChar2DPadder(Padder):
         max_sent_length = max(len(word_lst) for word_lst in contents)
         batch_size = len(contents)
         dtype = type(contents[0][0][0])
-
+        
         padded_array = np.full((batch_size, max_sent_length, max_char_length), fill_value=self.pad_val,
                                dtype=dtype)
         for b_idx, word_lst in enumerate(contents):
             for c_idx, char_lst in enumerate(word_lst):
                 chars = char_lst[:max_char_length]
                 padded_array[b_idx, c_idx, :len(chars)] = chars
-
+        
         return padded_array

fastNLP/core/instance.py

@@ -35,6 +35,13 @@ class Instance(object):
         :param Any field: 新增field的内容
         """
         self.fields[field_name] = field
+
+    def items(self):
+        """
+        返回一个迭代器，迭代器返回两个内容，第一个内容是field_name, 第二个内容是field_value
+        :return:
+        """
+        return self.fields.items()
     
     def __getitem__(self, name):
         if name in self.fields:

fastNLP/core/losses.py

@@ -28,6 +28,7 @@ from .utils import _check_arg_dict_list
 from .utils import _check_function_or_method
 from .utils import _get_func_signature
 from .utils import seq_len_to_mask
+import warnings
 
 
 class LossBase(object):
@@ -205,10 +206,14 @@ class CrossEntropyLoss(LossBase):
     
     :param pred: 参数映射表中 `pred` 的映射关系，None表示映射关系为 `pred` -> `pred`
     :param target: 参数映射表中 `target` 的映射关系，None表示映射关系为 `target` -> `target`
-    :param seq_len: 句子的长度, 长度之外的token不会计算loss。。
+    :param seq_len: 句子的长度, 长度之外的token不会计算loss。
+    :param int class_in_dim: 在序列标注的场景中，pred可能的shape为(batch_size, max_len, num_classes)
+        或(batch_size, num_classes, max_len)， CrossEntropyLoss需要知道哪一维是class的维度以计算loss。如果为-1，就根据pred的第
+        二维是否等于target的第二维来判断是否需要交换pred的第二维和第三维，因为target的第二维是length的维度，如果这一维度上和pred相等，
+        那么pred可能第二维也是长度维(存在误判的可能，如果有误判的情况，请显示设置该值)。其它大于0的值则认为该维度是class的维度。
     :param padding_idx: padding的index，在计算loss时将忽略target中标号为padding_idx的内容, 可以通过该值代替
         传入seq_len.
-    :param str reduction: 支持'mean'，'sum'和'none'.
+    :param str reduction: 支持 `mean` ，`sum` 和 `none` .
 
     Example::
 
@@ -216,17 +221,21 @@ class CrossEntropyLoss(LossBase):
         
     """
     
-    def __init__(self, pred=None, target=None, seq_len=None, padding_idx=-100, reduction='mean'):
+    def __init__(self, pred=None, target=None, seq_len=None, class_in_dim=-1, padding_idx=-100, reduction='mean'):
         super(CrossEntropyLoss, self).__init__()
         self._init_param_map(pred=pred, target=target, seq_len=seq_len)
         self.padding_idx = padding_idx
         assert reduction in ('mean', 'sum', 'none')
         self.reduction = reduction
+        self.class_in_dim = class_in_dim
     
     def get_loss(self, pred, target, seq_len=None):
         if pred.dim() > 2:
-            if pred.size(1) != target.size(1):
-                pred = pred.transpose(1, 2)
+            if self.class_in_dim == -1:
+                if pred.size(1) != target.size(1):  # 有可能顺序替换了
+                    pred = pred.transpose(1, 2)
+            else:
+                pred = pred.tranpose(-1, pred)
             pred = pred.reshape(-1, pred.size(-1))
             target = target.reshape(-1)
         if seq_len is not None:
@@ -265,9 +274,9 @@ class BCELoss(LossBase):
 
     二分类交叉熵损失函数
     
-    :param pred: 参数映射表中`pred`的映射关系，None表示映射关系为`pred`->`pred`
-    :param target: 参数映射表中`target`的映射关系，None表示映射关系为`target`->`target`
-    :param str reduction: 支持'mean'，'sum'和'none'.
+    :param pred: 参数映射表中 `pred` 的映射关系，None表示映射关系为 `pred` -> `pred`
+    :param target: 参数映射表中 `target` 的映射关系，None表示映射关系为 `target` -> `target`
+    :param str reduction: 支持 `mean` ，`sum` 和 `none` .
     """
     
     def __init__(self, pred=None, target=None, reduction='mean'):
@@ -286,11 +295,11 @@ class NLLLoss(LossBase):
     
     负对数似然损失函数
     
-    :param pred: 参数映射表中`pred`的映射关系，None表示映射关系为`pred`->`pred`
-    :param target: 参数映射表中`target`的映射关系，None表示映射关系为`target`->`target`
+    :param pred: 参数映射表中 `pred` 的映射关系，None表示映射关系为 `pred` -> `pred`
+    :param target: 参数映射表中 `target` 的映射关系，None表示映射关系为 `target` -> `target`
     :param ignore_idx: ignore的index，在计算loss时将忽略target中标号为ignore_idx的内容, 可以通过该值代替
         传入seq_len.
-    :param str reduction: 支持'mean'，'sum'和'none'.
+    :param str reduction: 支持 `mean` ，`sum` 和 `none` .
     """
     
     def __init__(self, pred=None, target=None, ignore_idx=-100, reduction='mean'):

fastNLP/core/metrics.py

@@ -6,7 +6,7 @@ __all__ = [
     "MetricBase",
     "AccuracyMetric",
     "SpanFPreRecMetric",
-    "SQuADMetric"
+    "ExtractiveQAMetric"
 ]
 
 import inspect
@@ -24,16 +24,17 @@ from .utils import seq_len_to_mask
 from .vocabulary import Vocabulary
 from abc import abstractmethod
 
+
 class MetricBase(object):
     """
-    所有metrics的基类,，所有的传入到Trainer, Tester的Metric需要继承自该对象，需要覆盖写入evaluate(), get_metric()方法。
+    所有metrics的基类,所有的传入到Trainer, Tester的Metric需要继承自该对象，需要覆盖写入evaluate(), get_metric()方法。
     
         evaluate(xxx)中传入的是一个batch的数据。
         
         get_metric(xxx)当所有数据处理完毕，调用该方法得到最终的metric值
         
     以分类问题中，Accuracy计算为例
-    假设model的forward返回dict中包含'pred'这个key, 并且该key需要用于Accuracy::
+    假设model的forward返回dict中包含 `pred` 这个key, 并且该key需要用于Accuracy::
     
         class Model(nn.Module):
             def __init__(xxx):
@@ -42,7 +43,7 @@ class MetricBase(object):
                 # do something
                 return {'pred': pred, 'other_keys':xxx} # pred's shape: batch_size x num_classes
                 
-    假设dataset中'label'这个field是需要预测的值，并且该field被设置为了target
+    假设dataset中 `label` 这个field是需要预测的值，并且该field被设置为了target
     对应的AccMetric可以按如下的定义, version1, 只使用这一次::
     
         class AccMetric(MetricBase):
@@ -117,6 +118,7 @@ class MetricBase(object):
     def __init__(self):
         self._param_map = {}  # key is param in function, value is input param.
         self._checked = False
+        self._metric_name = self.__class__.__name__
 
     @property
     def param_map(self):
@@ -134,6 +136,23 @@ class MetricBase(object):
     @abstractmethod
     def get_metric(self, reset=True):
         raise NotImplemented
+
+    def set_metric_name(self, name:str):
+        """
+        设置metric的名称，默认是Metric的class name.
+
+        :param str name:
+        :return: self
+        """
+        self._metric_name = name
+        return self
+
+    def get_metric_name(self):
+        """
+        返回metric的名称
+        :return:
+        """
+        return self._metric_name
     
     def _init_param_map(self, key_map=None, **kwargs):
         """检查key_map和其他参数map，并将这些映射关系添加到self._param_map
@@ -357,6 +376,7 @@ def _bmes_tag_to_spans(tags, ignore_labels=None):
     """
     给定一个tags的lis，比如['S-song', 'B-singer', 'M-singer', 'E-singer', 'S-moive', 'S-actor']。
     返回[('song', (0, 1)), ('singer', (1, 4)), ('moive', (4, 5)), ('actor', (5, 6))] (左闭右开区间)
+    也可以是单纯的['S', 'B', 'M', 'E', 'B', 'M', 'M',...]序列
 
     :param tags: List[str],
     :param ignore_labels: List[str], 在该list中的label将被忽略
@@ -477,7 +497,7 @@ class SpanFPreRecMetric(MetricBase):
     别名：:class:`fastNLP.SpanFPreRecMetric` :class:`fastNLP.core.metrics.SpanFPreRecMetric`
 
     在序列标注问题中，以span的方式计算F, pre, rec.
-    比如中文Part of speech中，会以character的方式进行标注，句子'中国在亚洲'对应的POS可能为(以BMES为例)
+    比如中文Part of speech中，会以character的方式进行标注，句子 `中国在亚洲` 对应的POS可能为(以BMES为例)
     ['B-NN', 'E-NN', 'S-DET', 'B-NN', 'E-NN']。该metric就是为类似情况下的F1计算。
     最后得到的metric结果为::
     
@@ -501,15 +521,15 @@ class SpanFPreRecMetric(MetricBase):
 
     :param tag_vocab: 标签的 :class:`~fastNLP.Vocabulary` 。支持的标签为"B"(没有label)；或"B-xxx"(xxx为某种label，比如POS中的NN)，
         在解码时，会将相同xxx的认为是同一个label，比如['B-NN', 'E-NN']会被合并为一个'NN'.
-    :param str pred: 用该key在evaluate()时从传入dict中取出prediction数据。 为None，则使用'pred'取数据
-    :param str target: 用该key在evaluate()时从传入dict中取出target数据。 为None，则使用'target'取数据
-    :param str seq_len: 用该key在evaluate()时从传入dict中取出sequence length数据。为None，则使用'seq_len'取数据。
+    :param str pred: 用该key在evaluate()时从传入dict中取出prediction数据。 为None，则使用 `pred` 取数据
+    :param str target: 用该key在evaluate()时从传入dict中取出target数据。 为None，则使用 `target` 取数据
+    :param str seq_len: 用该key在evaluate()时从传入dict中取出sequence length数据。为None，则使用 `seq_len` 取数据。
     :param str encoding_type: 目前支持bio, bmes, bmeso, bioes
     :param list ignore_labels: str 组成的list. 这个list中的class不会被用于计算。例如在POS tagging时传入['NN']，则不会计算'NN'这
         个label
     :param bool only_gross: 是否只计算总的f1, precision, recall的值；如果为False，不仅返回总的f1, pre, rec, 还会返回每个
         label的f1, pre, rec
-    :param str f_type: 'micro'或'macro'. 'micro':通过先计算总体的TP，FN和FP的数量，再计算f, precision, recall; 'macro':
+    :param str f_type: `micro` 或 `macro` . `micro` :通过先计算总体的TP，FN和FP的数量，再计算f, precision, recall; `macro` :
         分布计算每个类别的f, precision, recall，然后做平均（各类别f的权重相同）
     :param float beta: f_beta分数， :math:`f_{beta} = \frac{(1 + {beta}^{2})*(pre*rec)}{({beta}^{2}*pre + rec)}` .
         常用为beta=0.5, 1, 2. 若为0.5则精确率的权重高于召回率；若为1，则两者平等；若为2，则召回率权重高于精确率。
@@ -623,7 +643,7 @@ class SpanFPreRecMetric(MetricBase):
                 f, pre, rec = self._compute_f_pre_rec(tp, fn, fp)
                 f_sum += f
                 pre_sum += pre
-                rec_sum + rec
+                rec_sum += rec
                 if not self.only_gross and tag != '':  # tag!=''防止无tag的情况
                     f_key = 'f-{}'.format(tag)
                     pre_key = 'pre-{}'.format(tag)
@@ -735,11 +755,11 @@ def _pred_topk(y_prob, k=1):
     return y_pred_topk, y_prob_topk
 
 
-class SQuADMetric(MetricBase):
+class ExtractiveQAMetric(MetricBase):
     r"""
-    别名：:class:`fastNLP.SQuADMetric` :class:`fastNLP.core.metrics.SQuADMetric`
+    别名：:class:`fastNLP.ExtractiveQAMetric` :class:`fastNLP.core.metrics.ExtractiveQAMetric`
 
-    SQuAD数据集metric
+    抽取式QA（如SQuAD）的metric.
     
     :param pred1: 参数映射表中 `pred1` 的映射关系，None表示映射关系为 `pred1` -> `pred1`
     :param pred2: 参数映射表中 `pred2` 的映射关系，None表示映射关系为 `pred2` -> `pred2`
@@ -755,7 +775,7 @@ class SQuADMetric(MetricBase):
     def __init__(self, pred1=None, pred2=None, target1=None, target2=None,
                  beta=1, right_open=True, print_predict_stat=False):
         
-        super(SQuADMetric, self).__init__()
+        super(ExtractiveQAMetric, self).__init__()
         
         self._init_param_map(pred1=pred1, pred2=pred2, target1=target1, target2=target2)
         
@@ -813,8 +833,8 @@ class SQuADMetric(MetricBase):
             if not self.right_open:
                 e += 1
                 te += 1
-            if ts == 0 and te == int(not self.right_open):
-                if s == 0 and e == int(not self.right_open):
+            if ts == 0 and te == 1:
+                if s == 0 and e == 1:
                     self.no_ans_correct += 1
                     self.no2no += 1
                 else: