Complete document.

kwin-wang · May 24, 2015 · ce24849 · ce24849
1 parent cdb9399
commit ce24849
Show file tree

Hide file tree

Showing 5 changed files with 133 additions and 67 deletions.
diff --git a/doc/conf.py b/doc/conf.py
@@ -53,7 +53,7 @@
 # The short X.Y version.
 version = '3.3'
 # The full version, including alpha/beta/rc tags.
-release = '3.2'
+release = '3.3'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/doc/ltptest.rst b/doc/ltptest.rst
@@ -80,12 +80,14 @@ ltp_test通过命令行参数指定分析任务与模型路径。其中，
 * srl-data：指定语言角色标注模型
 * threads：指定线程数
 * input：指定输入文件，如果输入文件未指定或打开失败，将使用标准输入
-* last-stage：指定分析的最终步骤。这一参数将在Pipeline与last-stage中详细说明
+* last-stage：指定分析的最终步骤。这一参数将在 :ref:`pipeline-reference-label` 中详细说明
 
-分析结果以xml格式显示在stdout中。关于xml如何表示分析结果，请参考**使用ltp_server**结果一节。
+分析结果以xml格式显示在stdout中。关于xml如何表示分析结果，请参考理解 :ref:`ltml-reference-label` 一节。
+
+.. _pipeline-reference-label:
 
 Pipeline与last-stage参数
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 分词、词性标注、句法分析一系列任务之间存在依赖关系。举例来讲，对于词性标注，必须在分词结果之上进行才有意。LTP中提供的5种分析之间的依赖关系如下所示：
 
@@ -105,8 +107,27 @@ Pipeline与last-stage参数
 
 默认情况下，LTP将进行至语义角色标注的分析。但是，对于一部分用户，某些分析并不必要。举例来讲，如果用户只需进行词性标注，则ltp_test的pipeline分析只需进行到pos，`last-stage`用来指明分析的最后状态。同时，如果`last-stage`指定为pos，句法分析、命名实体识别和语义角色标注的模型将不被加载。
 
+xxx_cmdline
+-----------
+除了 :code:`ltp_test` 将全部分析器整合起来，LTP也提供拆分各模块单独分析的命令行程序。他们包括：
 
-分析结果以xml格式显示在stdout中。关于xml如何表示分析结果，请参考理解 :ref:`ltml-reference-label` 一节。
+* :file:`cws_cmdline` ：分词命令行
+* :file:`pos_cmdline` ：词性标注命令行
+* :file:`par_cmdline` ：句法分析命令行
+* :file:`ner_cmdline` ：命名实体识别命令行
+
+xxx_cmdline的主要目标是提供不同于xml，同时可自由组合的语言分析模块。举在已经切分好的结果上做词性标注为例。::
+
+    $ cat input 
+    这 是 测试 文本 。
+    $ cat input | ./bin/pos_cmdline --postagger-model ./ltp_data/pos.model 
+    TRACE: Model is loaded
+    TRACE: Running 1 thread(s)
+    WARN: Cann't open file! use stdin instead.
+    这_r    是_v    测试_v  文本_n  。_wp
+    TRACE: consume 0.000832081 seconds.
+
+关于各模块的用法，与ltp_test基本类似。细节请参考 :code:`xxx_cmdline -h`。
 
 Window动态链接库
 -----------------

diff --git a/doc/news.rst b/doc/news.rst
@@ -1,11 +1,12 @@
 新闻
 =====
 
-语言技术平台3.2.0版 发布
+语言技术平台3.3.0版 发布
 
-* [增加] 分词模块增量模型训练工具。使用户可以在语言技术平台基线模型的基础之上增加训练数据，从而获得特定领域性能更好的模型。
-* [修改] Boost.Regex到1.56.0，由于旧版本Boost.Regex的 `match_results` 类存在竞争问题，这一修改修复了 `multi_cws_cmdline` 随机出错的问题。
-* [修改] 使自动化测试脚本支持Windows运行以及多线程测试
-* [修改] 将原 `examples` 文件夹下的示例文件转移到 `test` 文件夹下并纳入语言技术平台的编译链
-* [测试] 新版语言技术平台通过 `cygwin` 编译测试
-* [测试] 多线程程序 `multi_ltp_test` ， `multi_cws_cmdline` 以及 `multi_pos_cmdline` 在Windows通过测试
+* [增加] 词性标注模型加入微博数据，使得在开放域上的词性标注性能更好(+3.3 precision)
+* [增加] 依存句法分析模型加入微博数据，使得在开放域上的句法分析性能更好(+3 UAS)
+* [增加] 依存句法分析算法切换到transition-based neural network parser，速度从40 tokens/s提升到8000 tokens/s。同时通过加入聚类特征以及优化训练算法，（在新闻领域）准确率也得到小幅提升(+0.2 UAS)
+* [增加] `ltp_test`默认支持多线程，线程数可配置。
+* [增加] 新加入子模块命令行程序，`cws_cmdline`，`pos_cmdline`，`par_cmdline`，`ner_cmdline`，使用户可以很容易替换中间模块，从而实现语言分析的组合。
+* [修改] 优化了训练套件的交互方式
+* [增加] 添加模型验证，单元测试模块。
diff --git a/doc/theory.rst b/doc/theory.rst
@@ -11,18 +11,86 @@
 
 在自然语言处理领域，在线学习已经被广泛地应用在分词、词性标注、依存句法分析等结构化学习任务中。
 
+.. _truncate-reference-label:
+
 模型裁剪
 ---------
 
 在LTP中，词性标注、句法分析两个模块还存在模型比较大的问题。为了缩小模型的大小，我们参考 `Learning Sparser Perceptron Model <http://www.cs.bgu.ac.il/~yoavg/publications/acl2011sparse.pdf>`_ ，将其中提到的特征裁剪策略加入了LTP。
 
 具体来讲，LTP特征映射是以特征前缀为单位进行组织的。对应的，我们裁剪了同一前缀下更新次数较少的所有特征。
 
+.. _customized-cws-reference-label:
+
+个性化分词
+----------
+
+个性化分词是LTP的特色功能。个性化分词为了解决测试数据切换到如小说、财经等不同于新闻领域的领域。
+在切换到新领域时，用户只需要标注少量数据。
+个性化分词会在原有新闻数据基础之上进行增量训练。
+从而达到即利用新闻领域的丰富数据，又兼顾目标领域特殊性的目的。
+
+准备基础模型
+~~~~~~~~~~~~
+用户可以从百度云托管上获得符合北大切词规范的基础模型。
+如果需要利用其它切词规范的数据作为基础模型，使用 :file:`./tools/train/otcws learn` 训练模型时需要指定 :code:`--dump-details` 选项为true。
+
+个性化训练
+~~~~~~~~~~
+
+个性化分词模型的训练同样可以通过分词训练套件 :file:`otcws` 来实现。::
+
+    $ ./tools/train/otcws customized-learn
+    otcws(customized-learn) in LTP 3.3.0 - (C) 2012-2015 HIT-SCIR
+    Customized training suite for Chinese word segmentation
+
+    usage: ./otcws learn <options>
+
+    options:
+      --baseline-model arg         The baseline model, which should be saved with 
+                                   --dump-details options.
+      --model arg                  The prefix of the model file, model will be 
+                                   stored as model.$iter.
+      --reference arg              The path to the reference file.
+      --development arg            The path to the development file.
+      --algorithm arg              The learning algorithm
+                                    - ap: averaged perceptron
+                                    - pa: passive aggressive [default]
+      --max-iter arg               The number of iteration [default=10].
+      --rare-feature-threshold arg The threshold for rare feature, used in model 
+                                   truncation. [default=0]
+      -h [ --help ]                Show help information
+
+这种情况下，需要指定 :code:`--baseline-model` 参数为前面获得的基础模型。其余选项与 :code:`./tools/train/otcws learn` 一致。
+
+个性化测试
+~~~~~~~~~~
+个性化分词模型的训练同样可以通过分词训练套件 :file:`otcws` 来实现。::
+
+    $ ./tools/train/otcws customized-test
+    otcws(customized-test) in LTP 3.3.0 - (C) 2012-2015 HIT-SCIR
+    Customized testing suite for Chinese word segmentation
+
+    usage: ./otcws test <options>
+
+    options:
+      --baseline-model arg  The path to the baseline model.
+      --model arg           The path to the model file.
+      --lexicon arg         The lexicon file, (optional, if configured, constrained
+                            decoding will be performed).
+      --input arg           The path to the reference file.
+      --evaluate arg        if configured, perform evaluation, input words in 
+                            sentence should be separated by space.
+      -h [ --help ]         Show help information
+
+与customized-learn类似，需指定 :code:`--baseline-model` 参数为前面获得的基础模型。其余选项与 :code:`./tools/train/otcws test` 一致。
+
 测试设置
 ---------
 
 下述实验的测试硬件环境如下：
-* CPU: Intel(R) Xeon(R) CPU E5-1620 0 @ 3.60GHz
+
+* CPU: Intel(R) Xeon(R) CPU E5-2620 0 @ 2.00GHz
 * RAM: 128G
 
 分词模块
@@ -160,48 +228,20 @@
 依存句法分析模块
 -----------------
 
-基于图的依存分析方法由McDonald首先提出，他将依存分析问题归结为在一个有向图中寻找最大生成树(Maximum Spanning Tree)的问题。
-在依存句法分析模块中，LTP分别实现了
-
-    * 一阶解码(1o)
-    * 二阶利用子孙信息解码(2o-sib)
-    * 二阶利用子孙和父子信息(2o-carreras)
-
-三种不同的解码方式。依存句法分析模块中使用的特征请参考对应的 `代码 <https://github.com/HIT-SCIR/ltp/blob/master/src/parser/extractor.cpp>`_ 。
-
+依存句法分析模块的主要算法依据神经网络依存句法分析算法，Chen and Manning (2014)。同时加入丰富的全局特征和聚类特征。在模型训练时，我们也参考了Yoav等人关于dynamic oracle的工作。
 在 `Chinese Dependency Treebank(CDT) <https://catalog.ldc.upenn.edu/LDC2012T05>`_ 数据集上，三种不同解码方式对应的性能如下表所示，其中运行速度和内存开销从CDT测试集（平均29.13词/句）上结果中获得。
 
-+------------+------------------------+-----------------+-----------------+
-| model      | 1o                     | 2o-sib          | 2o-carreras     |
-+============+===============+========+========+========+========+========+
-|            | UAS           | LAS    | UAS    | LAS    | UAS    | LAS    |
-+------------+---------------+--------+--------+--------+--------+--------+
-| 开发集     | 0.8192        | 0.7904 | 0.8501 | 0.8213 | 0.8582 | 0.8294 |
-+------------+---------------+--------+--------+--------+--------+--------+
-| 测试集     | 0.8118        | 0.7813 | 0.8421 | 0.8106 | 0.8447 | 0.8138 |
-+------------+---------------+--------+--------+--------+--------+--------+
-| 速度       | 81.71 sent./s          | 15.21 sent./s   |                 |
-+------------+------------------------+-----------------+-----------------+
-| 运行时内存 | 338.06M                | 974.64M         |                 |
-+------------+------------------------+-----------------+-----------------+
-
-特征裁剪对于句法分析模块的运行时内存开销（亦即模型大小）有较大的影响。在进行特征裁剪后，上表性能变化为：
-
-+------------+-----------------+-----------------+-----------------+
-| model      | 1o              | 2o-sib          | 2o-carreras     |
-+============+=================+=================+=================+
-| 裁剪阈值   | 5               | 3               |                 |
-+------------+--------+--------+--------+--------+--------+--------+
-|            | UAS    | LAS    | UAS    | LAS    | UAS    | LAS    |
-+------------+--------+--------+--------+--------+--------+--------+
-| 开发集     | 0.8172 | 0.7886 | 0.8497 | 0.8214 |        |        |
-+------------+--------+--------+--------+--------+--------+--------+
-| 测试集     | 0.8096 | 0.7790 | 0.8408 | 0.8089 |        |        |
-+------------+--------+--------+--------+--------+--------+--------+
-| 速度       | 82.85 sent./s   | 14.84 sent./s   |                 |
-+------------+-----------------+-----------------+-----------------+
-| 运行时内存 | 221.18M         | 584.29M         |                 |
-+------------+-----------------+-----------------+-----------------+
++------------+-------+-------+
+|            | UAS   | LAS   |
++============+=======+=======+
+| 开发集     | 85.80 | 83.19 |
++------------+-------+-------+
+| 测试集     | 84.11 | 81.17 |
++------------+-------+-------+
+| 速度       | 8000 tok./sed |
++------------+---------------+
+| 运行时内存 | 338.06M       |
++------------+---------------+
 
 语义角色标注模块
 -----------------

diff --git a/doc/train.rst b/doc/train.rst
@@ -4,7 +4,7 @@
 分词训练套件otcws用法
 -----------------------
 
-otcws是ltp分词模型的训练套件，用户可以使用otcws训练获得ltp的分词模型。otcws支持从人工切分数据中训练分词模型和调用分词模型对句子进行切分。人工切分的句子的样例如下：
+otcws是ltp分词模型的训练套件，用户可以使用otcws训练获得ltp的分词模型。otcws支持从人工切分数据中训练分词模型和调用分词模型对句子进行切分。人工切分的句子的样例如下：::
 
 	对外	，	他们	代表	国家	。
 
@@ -16,12 +16,13 @@ otcws是ltp分词模型的训练套件，用户可以使用otcws训练获得ltp
 
     usage: ./otcws [learn|customized-learn|test|customized-test|dump] <options>
 
-其中第二个参数调用训练(learn)或测试(test)或可视化模型(dump)，对于customized-learn以及customized-test，请参考**分词个性化**
+其中第二个参数调用训练(learn)或测试(test)或可视化模型(dump)，对于customized-learn以及customized-test，请参考 :ref:`customized-cws-reference-label`
 
 训练一个模型
 ~~~~~~~~~~~~
 
 如果进行模型训练(learn)，::
+
     $ ./tools/train/otcws learn
     otcws(learn) in LTP 3.3.0 - (C) 2012-2015 HIT-SCIR
     Training suite for Chinese word segmentation
@@ -50,8 +51,8 @@ otcws是ltp分词模型的训练套件，用户可以使用otcws训练获得ltp
 * algorithm：指定参数学习方法，现在LTP在线学习框架支持两种参数学习方法，分别是passive aggressive(pa)和average perceptron(ap)。
 * model：指定输出模型文件名前缀，模型采用model.$iter方式命名
 * max-iter：指定最大迭代次数
-* rare-feature-threshold：模型裁剪力度，如果rare-feature-threshold为0，则只去掉为0的特征；rare-feature-threshold；如果大于0时将进一步去掉更新次数低于阈值的特征。关于模型裁剪算法细节，请参考**模型裁剪**部分。
-* dump-details：指定保存模型时输出所有模型信息，这一参数用于**分词个性化**，具体请参考**分词个性化**。
+* rare-feature-threshold：模型裁剪力度，如果rare-feature-threshold为0，则只去掉为0的特征；rare-feature-threshold；如果大于0时将进一步去掉更新次数低于阈值的特征。关于模型裁剪算法细节，请参考 :ref:`truncate-reference-label` 部分。
+* dump-details：指定保存模型时输出所有模型信息，这一参数用于 :ref:`customized-cws-reference-label` ，具体请参考 :ref:`customized-cws-reference-label` 。
 
 需要注意的是，reference和development都需要是人工切分的句子。
 
@@ -87,7 +88,7 @@ otcws是ltp分词模型的训练套件，用户可以使用otcws训练获得ltp
 词性标注训练套件otpos用法
 --------------------------
 
-otpos是ltp分词模型的训练套件，用户可以使用otpos训练获得ltp的分词模型。otpos支持从人工切分并标注词性的数据中训练词性标注模型和调用词性标注模型对切分好的句子进行词性标注。人工标注的词性标注句子样例如下：
+otpos是ltp分词模型的训练套件，用户可以使用otpos训练获得ltp的分词模型。otpos支持从人工切分并标注词性的数据中训练词性标注模型和调用词性标注模型对切分好的句子进行词性标注。人工标注的词性标注句子样例如下：::
 
 	对外_v	，_wp	他们_r	代表_v	国家_n	。_wp
 
@@ -108,7 +109,7 @@ otpos是ltp分词模型的训练套件，用户可以使用otpos训练获得ltp
                             '_' concatenated tag
       -h [ --help ]         Show help information
 
-lexicon文件样例如下所示。每行指定一个词，第一列指定单词，第二列之后指定该词的候选词性（可以有多项，每一项占一列），列与列之间用空格区分。
+lexicon文件样例如下所示。每行指定一个词，第一列指定单词，第二列之后指定该词的候选词性（可以有多项，每一项占一列），列与列之间用空格区分。::
 
 	雷人 v a
 	】 wp
@@ -123,8 +124,8 @@ otner是ltp命名实体识别模型的训练套件，用户可以使用otner训
 
 编译之后，在tools/train下面会产生名为otner的二进制程序。otner的使用方法与otcws非常相似，同名参数含义也完全相同。
 
-依存句法分析训练套件lgdpj用法
-------------------------------
+依存句法分析训练套件nndepparser用法
+-----------------------------------
 
 nndepparser是ltp神经网络依存句法分析模型的训练套件，用户可以使用nndepparser训练获得ltp的依存句法分析模型。nndepparser分别支持从人工标注依存句法的数据中训练依存句法分析模型和调用依存句法分析模型对句子进行依存句法分析。人工标注的词性标注依存句法的句子遵从conll格式，其样例如下：::
 
@@ -143,6 +144,7 @@ nndepparser是ltp神经网络依存句法分析模型的训练套件，用户可
 ~~~~~~~~~~~~~~
 
 运行./nndepparser learn，可见如下参数::
+
     $ ./tools/train/nndepparser learn
     nndepparser(learn) in ltp 3.3.0 - (c) 2012-2015 hit-scir
     training suite for neural network parser
@@ -181,9 +183,11 @@ nndepparser是ltp神经网络依存句法分析模型的训练套件，用户可
       --verbose                 logging more details.
       -h [ --help ]             show help information.
 
-nndepparser具有较多参数，但大部分与Chen and Manning (2014)中的定义一直。希望使用nndepparser的用户需要首先阅读其论文。另，经验表明，大部分参数采用默认值亦可取得较好的效果。
+nndepparser具有较多参数，但大部分与Chen and Manning (2014)中的定义一致。希望使用nndepparser的用户需要首先阅读其论文。
+另，经验表明，大部分参数采用默认值亦可取得较好的效果。
+所以在不能明确各参数含义的情况下，可以直接使用默认值。
 
-nndepparser中独有的参数包括：
+相较Chen and Manning (2014)，nndepparser中特有的参数包括：
 
 * oracle：指定oracle函数类型，可选的oracle包括static，nondet和explore。一般来讲，explore效果最好，具体算法请参考Yoav et. al, (2014)
 * use-distance：指定使用距离特征，具体参考Zhang and Nivre (2011)
@@ -193,8 +197,8 @@ nndepparser中独有的参数包括：
 
 参考文献
 --------
-- Danqi Chen and Christopher Manning, 2014, A Fast and Accurate Dependency Parser using Neural Networks, In Proc. _EMNLP2014_
-- Yue Zhang and Joakim Nivre, 2011, Transition-based Dependency Parsing with Rich Non-local Features, In Proc _ACL2011_
-- Yoav Goldberg, Francesco Sartorioand Giorgio Satta, 2014, A Tabular Method for Dynamic Oracles in Transition-Based Parsing, In _TACL2014_
-- Jiang Guo, Wanxiang Che, David Yarowsky, Haifeng Wang and Ting Liu, 2015, Cross-lingual Dependency Parsing Based on Distributed Representations, (to apper) In Proc _ACL2015_
+- Danqi Chen and Christopher Manning, 2014, A Fast and Accurate Dependency Parser using Neural Networks, In Proc. of *EMNLP2014*
+- Yue Zhang and Joakim Nivre, 2011, Transition-based Dependency Parsing with Rich Non-local Features, In Proc. of *ACL2011*
+- Yoav Goldberg, Francesco Sartorioand Giorgio Satta, 2014, A Tabular Method for Dynamic Oracles in Transition-Based Parsing, In *TACL2014*
+- Jiang Guo, Wanxiang Che, David Yarowsky, Haifeng Wang and Ting Liu, 2015, Cross-lingual Dependency Parsing Based on Distributed Representations, (to apper) In Proc. of *ACL2015*