refine codes and doc of nce.

hsigmoid/infer.py

@@ -11,7 +11,7 @@
 logger.setLevel(logging.WARNING)
 
 
-def decode_res(infer_res, dict_size):
+def decode_result(infer_res, dict_size):
     """
     Inferring probabilities are orginized as a complete binary tree.
     The actual labels are leaves (indices are counted from class number).
@@ -41,10 +41,10 @@ def decode_res(infer_res, dict_size):
     return predict_lbls
 
 
-def predict(batch_ins, idx_word_dict, dict_size, inferer):
+def infer_a_batch(batch_ins, idx_word_dict, dict_size, inferer):
     infer_res = inferer.infer(input=batch_ins)
 
-    predict_lbls = decode_res(infer_res, dict_size)
+    predict_lbls = decode_result(infer_res, dict_size)
     predict_words = [idx_word_dict[lbl] for lbl in predict_lbls]  # map to word
 
     # Ouput format: word1 word2 word3 word4 -> predict label
@@ -53,7 +53,7 @@ def predict(batch_ins, idx_word_dict, dict_size, inferer):
                         for w in ins]) + " -> " + predict_words[i])
 
 
-def main(model_path):
+def infer(model_path, batch_size):
     assert os.path.exists(model_path), "trained model does not exist."
 
     paddle.init(use_gpu=False, trainer_count=1)
@@ -68,19 +68,17 @@ def main(model_path):
     inferer = paddle.inference.Inference(
         output_layer=prediction_layer, parameters=parameters)
     idx_word_dict = dict((v, k) for k, v in word_dict.items())
-    batch_size = 64
-    batch_ins = []
-    ins_iter = paddle.dataset.imikolov.test(word_dict, 5)
 
-    for ins in ins_iter():
+    batch_ins = []
+    for ins in paddle.dataset.imikolov.test(word_dict, 5)():
         batch_ins.append(ins[:-1])
         if len(batch_ins) == batch_size:
-            predict(batch_ins, idx_word_dict, dict_size, inferer)
+            infer_a_batch(batch_ins, idx_word_dict, dict_size, inferer)
             batch_ins = []
 
     if len(batch_ins) > 0:
-        predict(batch_ins, idx_word_dict, dict_size, inferer)
+        infer_a_batch(batch_ins, idx_word_dict, dict_size, inferer)
 
 
 if __name__ == "__main__":
-    main("models/hsigmoid_batch_00010.tar.gz")
+    infer("models/hsigmoid_batch_00010.tar.gz", 20)

nce_cost/.gitignore

@@ -0,0 +1,3 @@
+*.pyc
+*.tar.gz
+models

nce_cost/README.md

@@ -1,12 +1,12 @@
 # 噪声对比估计加速词向量训练
-## 背景介绍
-在自然语言处理领域中，通常使用特征向量来表示一个单词，但是如何使用准确的词向量来表示语义却是一个难点，详细内容可以在[词向量章节](https://github.com/PaddlePaddle/book/blob/develop/04.word2vec/README.cn.md)中查阅到，原作者使用神经概率语言模型（Neural Probabilistic Language Model, NPLM）来训练词向量，尽管 NPLM 有优异的精度表现，但是相对于传统的 N-gram 统计模型，训练时间还是太漫长了\[[3](#参考文献)\]。常用的优化这个问题算法主要有两个：一个是 hierarchical-sigmoid \[[2](#参考文献)\] 另一个 噪声对比估计（Noise-contrastive estimation, NCE）\[[1](#参考文献)\]。为了克服这个问题本文引入了 NCE 方法。本文将以训练 NPLM 作为例子来讲述如何使用 NCE。
 
-## NCE 概览
-NCE 是一种快速对离散分布进行估计的方法，应用到本文中的问题：训练 NPLM 计算开销很大，原因是 softmax 函数计算时需要考虑每个类别的指数项，必须计算字典中的所有单词，而在一般语料集上面字典往往非常大\[[3](#参考文献)\]，从而导致整个训练过程十分耗时。与常用的 hierarchical-sigmoid \[[2](#参考文献)\] 方法相比，NCE 不再使用复杂的二叉树来构造目标函数，而是采用相对简单的随机负采样，以大幅提升计算效率。
+词向量是许多自然语言处理任务的基础，详细介绍可见 PaddleBook 中的[词向量](https://github.com/PaddlePaddle/book/blob/develop/04.word2vec/README.cn.md)一节，其中通过训练神经概率语言模型（Neural Probabilistic Language Model, NPLM）得到词向量，是一种流行的方式。然而，神经概率语言模型的最后一层往往需要计算一个词典之上的概率分布，词典越大这一层的计算量也就越大，往往非常耗时。在models的另一篇我们已经介绍了[Hsigmoid加速词向量训练](https://github.com/PaddlePaddle/models/tree/develop/hsigmoid)，这里我们介绍另一种加速词向量训练的方法：使用噪声对比估计（Noise-contrastive estimation, NCE）损失函数\[[1](#参考文献)\]。
 
+## NCE
+NPLM 的最后一层 `softmax` 函数计算时需要考虑每个类别的指数项，必须计算字典中的所有单词，而在一般语料集上面字典往往非常大\[[3](#参考文献)\]，从而导致整个训练过程十分耗时。NCE 是一种快速对离散分布进行估计的方法。与常用的 hierarchical-sigmoid \[[2](#参考文献)\] 方法相比，NCE 不再使用复杂的二叉树来构造目标函数，而是采用相对简单的随机负采样，以大幅提升计算效率。
 
-假设已知具体的上下文 $h$，并且知道这个分布为 $P^h(w)$ ，并将从中抽样出来的数据作为正样例，而从一个噪音分布 $P_n(w)$ 抽样的数据作为负样例。我们可以任意选择合适的噪音分布，默认为无偏的均匀分布。这里我们同时假设噪音样例 k 倍于数据样例，则训练数据被抽中的概率为\[[1](#参考文献)\]：
+
+假设已知具体的上下文 $h$，并且知道这个分布为 $P^h(w)$ ，并将从中抽样出来的数据作为正样例，而从一个噪音分布 $P_n(w)$ 抽样的数据作为负样例。我们可以任意选择合适的噪音分布，默认为无偏的均匀分布。这里我们同时假设噪音样例 $k$ 倍于数据样例，则训练数据被抽中的概率为\[[1](#参考文献)\]：
 
 $$P^h(D=1|w,\theta)=\frac { P_\theta^h(w) }{ P^h_\theta(w)+kP_n(w) } =\sigma (\Delta s_\theta(w,h))$$
 
@@ -17,7 +17,7 @@ J^h(\theta )=E_{ P_d^h }\left[ \log { P^h(D=1|w,\theta ) }  \right] +kE_{ P_n }\
 $$
  \\\\\qquad =E_{ P_d^h }\left[ \log { \sigma (\Delta s_\theta(w,h)) }  \right] +kE_{ P_n }\left[ \log (1-\sigma (\Delta s_\theta(w,h)))  \right]$$
 
-总体上来说，NCE 是通过构造逻辑回归（logistic regression），对正样例和负样例做二分类，对于每一个样本，将自身的预测词 label 作为正样例，同时采样出 $k$ 个其他词 label 作为负样例，从而只需要计算样本在这 $k+1$ 个 label 上的概率。相比原始的 softmax 分类需要计算每个类别的分数，然后归一化得到概率，节约了大量的时间消耗。
+总体上来说，NCE 是通过构造逻辑回归（logistic regression），对正样例和负样例做二分类，对于每一个样本，将自身的预测词 label 作为正样例，同时采样出 $k$ 个其他词 label 作为负样例，从而只需要计算样本在这 $k+1$ 个 label 上的概率。相比原始的 `softmax ` 分类需要计算每个类别的分数，然后归一化得到概率，节约了大量的计算时间。
 
 ## 实验数据
 本文采用 Penn Treebank (PTB) 数据集（[Tomas Mikolov预处理版本](http://www.fit.vutbr.cz/~imikolov/rnnlm/simple-examples.tgz)）来训练语言模型。PaddlePaddle 提供 [paddle.dataset.imikolov](https://github.com/PaddlePaddle/Paddle/blob/develop/python/paddle/v2/dataset/imikolov.py) 接口来方便调用这些数据，如果当前目录没有找到数据它会自动下载并验证文件的完整性。并提供大小为5的滑动窗口对数据做预处理工作，方便后期处理。语料语种为英文，共有42068句训练数据，3761句测试数据。
@@ -42,70 +42,60 @@ N-gram 神经概率语言模型详细网络结构见图1：
 5. **NCE层**：训练时可以直接实用 PaddlePaddle 提供的 NCE Layer。
 
 
-## 训练阶段
-训练直接运行``` python train.py ```。程序第一次运行会检测用户缓存文件夹中是否包含 ptb 数据集，如果未包含，则自动下载。运行过程中，每1000个 iteration 会打印模型训练信息，主要包含训练损失，每个 pass 会计算测试数据集上的损失，并同时会保存最新的模型快照。在 PaddlePaddle 中有已经实现好的 NCE Layer，一些参数需要自行根据实际场景进行设计，可参考的调参方案如下：
-
-
-| 参数名  | 参数作用  | 介绍 |
-|:------ |:-------| :--------|
-| param\_attr / bias\_attr | 用来设置参数名字 |         可以方便后面预测阶段好来实现网络的参数共享，具体内容在下一个章节里会陈述。|
-| num\_neg\_samples | 参数负责控制对负样例的采样个数。        |           可以控制正负样本比例，这个值取值区间为 [1, 字典大小-1]，负样本个数越多则整个模型的训练速度越慢，模型精度也会越高 |
-| neg\_distribution | 控制生成负样例标签的分布，默认是一个均匀分布。 | 可以自行控制负样本采样时各个类别的采样权重，比如希望正样例为“晴天”时，负样例“洪水”在训练时更被着重区分，则可以将“洪水”这个类别的采样权重增加。 |
-| act | 表示使用何种激活函数。 | 根据 NCE 的原理，这里应该使用 sigmoid 函数。 |
+## 训练
+在命令行窗口运行命令``` python train.py ```可以直接开启训练任务。
 
+- 程序第一次运行会检测用户缓存文件夹中是否包含 ptb 数据集，如果未包含，则自动下载。
+- 运行过程中，每10个 batch 会打印模型训练在训练集上的代价值
+- 每个 pass 结束后，会计算测试数据集上的损失，并同时会保存最新的模型快照。
 
-具体代码实现如下：
+在模型文件`network_conf.py`中 NCE 调用代码如下：
 
 ```python
 cost = paddle.layer.nce(
-    input=hidden_layer,
-    label=next_word,
-    num_classes=dict_size,
-    param_attr=paddle.attr.Param(name='nce_w'),
-    bias_attr=paddle.attr.Param(name='nce_b'),
-    act=paddle.activation.Sigmoid(),
-    num_neg_samples=25,
-    neg_distribution=None)
+            input=hidden_layer,
+            label=next_word,
+            num_classes=dict_size,
+            param_attr=paddle.attr.Param(name="nce_w"),
+            bias_attr=paddle.attr.Param(name="nce_b"),
+            act=paddle.activation.Sigmoid(),
+            num_neg_samples=25,
+            neg_distribution=None)
 ```
 
+NCE 层的一些重要参数解释如下：
 
-## 预测阶段
-预测直接运行` python infer.py `，程序首先会加载最新模型，然后按照 batch 大小依次进行预测，并打印预测结果。因为训练和预测计算逻辑不一样，预测阶段需要共享 NCE Layer 中的逻辑回归训练时得到的参数，所以要写一个推断层，推断层的参数为预先训练好的参数。
-
-具体实现推断层的方法：先是通过 `paddle.attr.Param` 方法获取参数值，然后使用 `paddle.layer.trans_full_matrix_projection` 对隐层输出向量 `hidden_layer` 做一个矩阵右乘，PaddlePaddle 会自行在模型中寻找相同参数名的参数并获取。右乘求和后得到类别向量，将类别向量输入 softmax 做一个归一操作，和为1，从而得到最后的类别概率分布。
-
-代码实现如下：
-
-```python
-with paddle.layer.mixed(
-        size=dict_size,
-        act=paddle.activation.Softmax(),
-        bias_attr=paddle.attr.Param(name='nce_b')) as prediction:
-    prediction += paddle.layer.trans_full_matrix_projection(
-        input=hidden_layer, param_attr=paddle.attr.Param(name='nce_w'))
-```
-
-预测的输出形式为：
-
-```
---------------------------
-No.68 Input: ' <unk> for possible
-Ground Truth Output: <unk>
-Predict Output: <unk>
-
---------------------------
-No.69 Input: <unk> for possible <unk>
-Ground Truth Output: on
-Predict Output: <e>
-
---------------------------
-No.70 Input: for possible <unk> on
-Ground Truth Output: the
-Predict Output: the
-
-```
+| 参数名  | 参数作用  | 介绍 |
+|:------ |:-------| :--------|
+| param\_attr / bias\_attr | 用来设置参数名字 |方便预测阶段加载参数，具体在预测一节中介绍。|
+| num\_neg\_samples | 负样本采样个数|可以控制正负样本比例，这个值取值区间为 [1, 字典大小-1]，负样本个数越多则整个模型的训练速度越慢，模型精度也会越高 |
+| neg\_distribution | 生成负样例标签的分布，默认是一个均匀分布| 可以自行控制负样本采样时各个类别的采样权重。例如：希望正样例为“晴天”时，负样例“洪水”在训练时更被着重区分，则可以将“洪水”这个类别的采样权重增加|
+| act | 使用何种激活函数| 根据 NCE 的原理，这里应该使用 sigmoid 函数 |
+
+## 预测
+1. 首先修改 `infer.py` 脚本的 `main` 函数指定需要测试的模型。
+2. 需要注意的是，**预测和训练的计算逻辑不同**，需要以一个全连接层:`paddle.layer.fc`替换训练使用的`paddle.train.nce`层， 并直接加载NCE学习到的参数，代码如下：
+
+	```python
+	prediction = paddle.layer.fc(
+	    size=dict_size,
+	    act=paddle.activation.Softmax(),
+	    bias_attr=paddle.attr.Param(name="nce_b"),
+	    input=hidden_layer,
+	    param_attr=paddle.attr.Param(name="nce_w"))
+	```
+3. 运行 `python infer.py`。程序首先会加载指定的模型，然后按照 batch 大小依次进行预测，并打印预测结果。预测的输出格式如下：
+
+	```text
+	0.6734  their   may want to move
+
+	```
+
+	每一行是一条预测结果，内部以“\t”分隔，共计3列：
+	- 第一列：下一个词的概率。
+	- 第二列：模型预测的下一个词。
+	- 第三列：输入的 $n$ 个词语，内部以空格分隔。
 
-每一个短线表示一次的预测，第二行显示第几条测试样例，并给出输入的4个单词，第三行为真实的标签，第四行为预测的标签。
 
 ## 参考文献
 1. Mnih A, Kavukcuoglu K. [Learning word embeddings efficiently with noise-contrastive estimation](https://papers.nips.cc/paper/5165-learning-word-embeddings-efficiently-with-noise-contrastive-estimation.pdf)[C]//Advances in neural information processing systems. 2013: 2265-2273.