[DOCS] Algorithm Standardization

yaps · Jun 12, 2017 · b3c00be · b3c00be
1 parent ce2a9e6
commit b3c00be
Show file tree

Hide file tree

Showing 6 changed files with 146 additions and 58 deletions.
diff --git a/docs/algo/gbdt_on_angel.md b/docs/algo/gbdt_on_angel.md
@@ -1,27 +1,28 @@
 # GBDT on Angel
 
-**GBDT(Gradient Boosting Decision Tree)：梯度提升决策树 [1][2]**，是一种集成使用多个弱分类器（决策树）来提升分类效果的机器学习算法，在很多分类和回归的场景中，都有不错的效果。
+> **GBDT(Gradient Boosting Decision Tree)：梯度提升决策树 [1][2]**，是一种集成使用多个弱分类器（决策树）来提升分类效果的机器学习算法，在很多分类和回归的场景中，都有不错的效果。
 
-## 算法场景
+## 1. 算法介绍
 
 ![fileUsersandyyehooDocumentsMy20Work201703Angel开源文档GBDT-on-Angelgbdt-on-angel-1.png](/tdw/angel/uploads/A54C332C8CA44EF181B7B0E6854B9228/fileUsersandyyehooDocumentsMy20Work201703Angel开源文档GBDT-on-Angelgbdt-on-angel-1.png)
 
 
 如图1所示，这是是对一群消费者的消费力进行预测的例子。简单来说，处理流程为：
 
-	1. 在第一棵树中，根节点选取的特征是年龄，年龄小于30的被分为左子节点，年龄大于30的被分为右叶子节点，右叶子节点的预测值为1；
-	2. 第一棵树的左一节点继续分裂，分裂特征是月薪，小于10K划分为左叶子节点，预测值为5；工资大于10k的划分右叶子节点，预测值为10
-	2. 建立完第一棵树之后，C、D和E的预测值被更新为1，A为5，B为10
-	3. 根据新的预测值，开始建立第二棵树，第二棵树的根节点的性别，女性预测值为0.5，男性预测值为1.5
-	4. 建立完第二棵树之后，将第二棵树的预测值加到每个消费者已有的预测值上，比如A的预测值为两棵树的预测值之和：5+0.5=5.5
-	5. 通过这种方式，不断地优化预测准确率。
+1. 在第一棵树中，根节点选取的特征是年龄，年龄小于30的被分为左子节点，年龄大于30的被分为右叶子节点，右叶子节点的预测值为1；
+2. 第一棵树的左一节点继续分裂，分裂特征是月薪，小于10K划分为左叶子节点，预测值为5；工资大于10k的划分右叶子节点，预测值为10
+2. 建立完第一棵树之后，C、D和E的预测值被更新为1，A为5，B为10
+3. 根据新的预测值，开始建立第二棵树，第二棵树的根节点的性别，女性预测值为0.5，男性预测值为1.5
+4. 建立完第二棵树之后，将第二棵树的预测值加到每个消费者已有的预测值上，比如A的预测值为两棵树的预测值之和：5+0.5=5.5
+5. 通过这种方式，不断地优化预测准确率。
 
 
-## **实现逻辑**
 
-### 1. 参数存储
 
-![fileUsersandyyehooDocumentsMy20Work201703Angel开源文档GBDT-on-Angelgbdt-on-angel-2.png](/tdw/angel/uploads/1F19EF3B9ABD49BBBAC2D8CF4D71EDC3/fileUsersandyyehooDocumentsMy20Work201703Angel开源文档GBDT-on-Angelgbdt-on-angel-2.png)
+## 2. 分布式实现 on Angel
+
+---
+### 1. 参数存储
 
 如图2所示，为了优化算法性能，在参数服务器上，需要存储如下几个参数矩阵，包括：
 
@@ -61,10 +62,7 @@ GBDT的流程包括几大步骤
 4. **分裂树节点：**  PS并将分裂特征、分裂特征值和目标函数增益返回给Workder。Worker根据计算得到的最佳分裂点，创建叶子节点，将本节点的训练数据切分到两个叶子节点上。如果树的高度没有达到最大限制，则将两个叶子节点加入到待处理树节点的队列。
 
 ![fileUsersandyyehooDocumentsMy20Work201703Angel开源文档GBDT-on-Angelgbdt-on-angel-4.png](/tdw/angel/uploads/F93D941F7E6C4779A7E3F69E215A3EEE/fileUsersandyyehooDocumentsMy20Work201703Angel开源文档GBDT-on-Angelgbdt-on-angel-4.png)
-
-
-### 4. Angel的优势
-
+
 
 从上面的算法逻辑剖析可以看出，GBDT这个算法，存在这大量的模型更新和同步操作，非常适合PS和Angel。具体来说，包括：
 
@@ -75,5 +73,11 @@ GBDT的流程包括几大步骤
 3. **分布式训练：**最佳决策分裂点的技术，可以在多个PS服务器节点上并行进行，然后再同步给Worker，互不干扰
 
 整体来看，Angel的PS优势，使得它在这个算法上，性能远远超越了Spark版本的GBDT实现，而和MPI版本的xgBoost也略胜一筹。
+
+## 3. 运行 & 性能
+
+### 输入格式
+### 参数
+### 性能
 
 
diff --git a/docs/algo/kmeans_on_angel.md b/docs/algo/kmeans_on_angel.md
@@ -1,6 +1,10 @@
 # KMeans
-## KMeans算法
-KMeans是一种简单的聚类算法，将数据集划分为多个簇，K为簇的个数，是一个提前设定的值。每个样本被划分到距离最近的簇。每个簇所有样本的几何中心为这个簇的簇心，样本到簇心的距离为样本到簇的距离。Kmeans算法一般以迭代的方式训练，如下所示：
+
+> KMeans是一种简单的聚类算法，将数据集划分为多个簇，K为簇的个数。传统的KMeans算法，有一定的性能瓶颈，通过PS实现的KMeans，在准确率一致的情况下，性能更佳。
+
+## 1. 算法介绍
+
+每个样本被划分到距离最近的簇。每个簇所有样本的几何中心为这个簇的簇心，样本到簇心的距离为样本到簇的距离。Kmeans算法一般以迭代的方式训练，如下所示：
 <div align=center>![image.png](/tdw/angel/uploads/89523DACE2E547E385C1797297714B35/image.png)</div>
 其中：![xi.gif](/tdw/angel/uploads/574113621AFC4E36A47AEAB98DD66A58/xi.gif)代表第i个样本，![ci.gif](/tdw/angel/uploads/E809FF8E555442719B551C778935A579/ci.gif)代表与第i个样本距离最近的簇，![miui.gif](/tdw/angel/uploads/D080E78FD43346D7A698C9CFF7458F33/miui.gif)代表第j个簇的簇心。
 
@@ -9,16 +13,24 @@ KMeans是一种简单的聚类算法，将数据集划分为多个簇，K为簇
 "Web-Scale K-Means Clustering"提出一种在朴素KMeans算法基础上改进的KMeans算法，用mini-batch方法训练，每次迭代选择一个mini-batch的样本更新簇心，如下所示：
 <div align=center>![minibatchkmeans.png](/tdw/angel/uploads/9EDED211A2444A85913D7A6CF302A2E5/minibatchkmeans.png)</div>
 
-## KMeans on Angel
+## 2. 分布式实现 on Angel
+
 ### 模型存储
 Angel实现的KMeans算法将K个簇心存储在ParameterServer上，用一个K×N维的矩阵表示，其中：K为簇心的个数，N为数据的维度，即特征的个数。
+
 ### 模型更新
 KMeans on Angel以迭代的方式训练，每次训练以上文提到的mini-batch KMeans算法更新簇心。
+
 ### 算法逻辑
 KMeans on Angel的算法流程如下图所示：
 <div align=center>![KMeansonAngel.png](/tdw/angel/uploads/6D56A5EAC512408DB980F8B53DB26B3B/KMeansonAngel.png)</div>
-### 参数
-输入输出参数
+
+
+## 3. 运行 & 性能
+
+### 输入格式
+
+### 参数
 * IO参数
   * angel.train.data.path：输入数据路径
   * ml.feature.num：数据特征个数
@@ -29,3 +41,5 @@ KMeans on Angel的算法流程如下图所示：
   * ml.kmeans.center.num：K值，即簇的个数
   * ml.kmeans.sample.ratio.perbath：每次迭代选择mini-batch样本的采样率
   * ml.kmeans.c：学习速率参数
+
+### 性能
diff --git a/docs/algo/lda_on_angel.md b/docs/algo/lda_on_angel.md
@@ -1,8 +1,12 @@
-# Latent Dirichlet Allocation
+# LDA（Latent Dirichlet Allocation）
 
+> LDA是一种常见的主题模型算法。简单来说它是一个贝叶斯概率生成模型，用于对文档集进行降维或者潜在语义分析。
 
-## LDA 模型
-LDA是一个贝叶斯概率生成模型，用于对文档集进行降维或者潜在语义分析。
+
+
+## 1. 算法介绍
+
+### 整体说明
 给定一个语料库``$ C $``，该语料库由一系列文档`` $ \{D_1, \cdots, D_{M}\} $``构成。
 每个文档``$ D_i $`` 则由一个序列的词构成，``$ D_i = (t_1, t_2, \cdots, t_{N_i}) $``。
 语料库中的词整体构成了一个词汇表``$ V $``。
@@ -18,7 +22,7 @@ LDA模型对每个文档的生成过程进行了建模。
 中采样出该词的话题``$ z_{dn} $``，
 然后再从多项分布``$ Mult(\phi_{z_{dn}}) $``中采样出单词``$ w_{dn} \in V $``。
 
-## Gibbs Sampling
+### Gibbs Sampling
 求解LDA模型的过程通常使用Gibbs Sampling方法，通过采样出大量符合后验分布的样本``$ z_{dn} $``，
 从而对每个文档的话题分布和话题的词分布进行估计估计。
 目前对LDA的Gibbs Sampling方法有大概6中，包括Collapsed Gibbs Sampling(CGS)，SparseLDA，
@@ -48,7 +52,8 @@ F+LDA通过将概率公式进行了分解成两部分``$ C_{dk} \frac{C_{wk} + \
 对于另一个部分，F+LDA采用F+树来进行查找，可以将复杂度降低到O(logK)。
 从而F+LDA的复杂度为``$ O(K_d) $``，``$ K_d $``是文档-话题矩阵中非零元素的个数。
 
-## 分布式训练
+## 2. 分布式训练 on Angel
+
 在Angel中进行LDA模型的训练，整体的框架如下图所示。
 对于LDA模型中的两个较大的矩阵``$ C_w $``和``$ C_d $``，
 我们将C_d矩阵划分到不同的worker上，将C_w矩阵划分到不同的server上。
@@ -57,7 +62,17 @@ F+LDA通过将概率公式进行了分解成两部分``$ C_{dk} \frac{C_{wk} + \
 
 ![Architecture for LDA on Angel](../img/lda_ps.png)
 
-## 参数和数据格式
+## 3. 运行 & 性能
+
+### 输入格式
+
+输入数据分为多行，每行是一个文档，每个文档由一系列的词id构成，词id之间由空格隔开
+
+```math
+	wid_0, wid_1, ..., wid_n 
+```
+
+### 参数
 
 * 数据参数
   * angel.train.data.path: 输入数据路径
@@ -68,7 +83,5 @@ F+LDA通过将概率公式进行了分解成两部分``$ C_{dk} \frac{C_{wk} + \
   * angel.lda.topic.num：话题个数
   * angel.lda.worker.parallel.num：worker内部并行度
 
-输入数据分为多行，每行是一个文档，每个文档由一系列的词id构成，词id之间由空格隔开
-```math
-wid_0, wid_1, ..., wid_n 
-```
+### 性能
+
diff --git a/docs/algo/lr_on_angel.md b/docs/algo/lr_on_angel.md
@@ -1,5 +1,9 @@
-# LogisticRegression
-## 逻辑回归模型
+# LogisticRegression
+
+> 逻辑回归模型（logistic regression model）是一种分类模型。它是最常见和常用的一种分类方法，在传统的广告推荐中被大量使用，朴实但有效。
+
+## 1. 算法介绍
+
 逻辑回归模型（logistic regression model）是一种分类模型。样本x属于类别y的概率P(y|x)服从logistic分布：   
 <div align=center>![](http://i.imgur.com/5UZuenh.gif)</div>
 综合两种情况，有：  
@@ -8,12 +12,36 @@
 <div align=center>![3.png](/tdw/angel/uploads/3A11081478244509AFB192FBC8C19283/3.png)</div>
 其中：![](http://i.imgur.com/c0AJnPE.gif) 为L2正则项。
 
-## Gradient Descent LR on Angel
+## 2. 分布式实现 on Angel
+
 Angel MLLib提供了用mini-batch gradient descent优化方法求解的Logistic Regression算法，算法逻辑如下
-<div align=center>![sgdCode.png](/tdw/angel/uploads/9875CF7F229C478BBB5CEB366B33E83E/sgdCode.png)</div>
-学习速率在迭代过程中衰减，其中N为迭代次数，α为衰减系数，T为迭代次数：![6.gif](/tdw/angel/uploads/D31BABAED76C49C0B69D9C0C8FAB38FC/6.gif)。
+<div align=center>![sgdCode.png](/tdw/angel/uploads/9875CF7F229C478BBB5CEB366B33E83E/sgdCode.png)</div>
+
+学习速率在迭代过程中衰减，其中
+
+* N为迭代次数
+* α为衰减系数
+* T为迭代次数
+
+![6.gif](/tdw/angel/uploads/D31BABAED76C49C0B69D9C0C8FAB38FC/6.gif)
 
-### Gradient Descent LR 参数
+## 3. 运行 & 性能
+
+### 输入格式
+
+数据的格式通过“ml.data.type”参数设置；数据特征的个数，即特征向量的维度通过参数“ml.feature.num”设置。
+
+LR on Angel支持“libsvm”、“dummy”两种数据格式，分别如下所示：
+
+* **dummy格式**
+
+每行文本表示一个样本，每个样本的格式为"y index1 index2 index3 ..."。其中：index特征的ID；训练数据的y为样本的类别，可以取1、-1两个值；预测数据的y为样本的ID值。比如，属于正类的样本[2.0, 3.1, 0.0, 0.0, -1, 2.2]的文本表示为“1 0 1 4 5”，其中“1”为类别，“0 1 4 5”表示特征向量的第0、1、4、5个维度的值不为0。同理，属于负类的样本[2.0, 0.0, 0.1, 0.0, 0.0, 0.0]被表示为“-1 0 2”。
+
+ * **libsvm格式**
+
+每行文本表示一个样本，每个样本的格式为"y index1:value1 index2:value1 index3:value3 ..."。其中：index为特征的ID,value为对应的特征值；训练数据的y为样本的类别，可以取1、-1两个值；预测数据的y为样本的ID值。比如，属于正类的样本[2.0, 3.1, 0.0, 0.0, -1, 2.2]的文本表示为“1 0:2.0 1:3.1 4:-1 5:2.2”，其中“1”为类别，"0:2.0"表示第0个特征的值为2.0。同理，属于负类的样本[2.0, 0.0, 0.1, 0.0, 0.0, 0.0]被表示为“-1 0:2.0 2：0.1”。
+
+###  参数
 * 算法参数  
   * ml.epochnum：迭代次数
   * ml.batch.sample.ratio：每次迭代的样本采样率
@@ -23,16 +51,7 @@ Angel MLLib提供了用mini-batch gradient descent优化方法求解的Logistic
   * ml.learn.decay：学习速率衰减系数 
   * ml.reg.l2：L2惩罚项系数
 
-## ADMM LR on Angel
 
-## 其它
-* 数据格式
-  数据的格式通过“ml.data.type”参数设置；数据特征的个数，即特征向量的维度通过参数“ml.feature.num”设置。
-LR on Angel支持“libsvm”、“dummy”两种数据格式，分别如下所示：
-  * dummy格式：
-    每行文本表示一个样本，每个样本的格式为"y index1 index2 index3 ..."。其中：index特征的ID；训练数据的y为样本的类别，可以取1、-1两个值；预测数据的y为样本的ID值。比如，属于正类的样本[2.0, 3.1, 0.0, 0.0, -1, 2.2]的文本表示为“1 0 1 4 5”，其中“1”为类别，“0 1 4 5”表示特征向量的第0、1、4、5个维度的值不为0。同理，属于负类的样本[2.0, 0.0, 0.1, 0.0, 0.0, 0.0]被表示为“-1 0 2”。
-  * libsvm格式：
-    每行文本表示一个样本，每个样本的格式为"y index1:value1 index2:value1 index3:value3 ..."。其中：index为特征的ID,value为对应的特征值；训练数据的y为样本的类别，可以取1、-1两个值；预测数据的y为样本的ID值。比如，属于正类的样本[2.0, 3.1, 0.0, 0.0, -1, 2.2]的文本表示为“1 0:2.0 1:3.1 4:-1 5:2.2”，其中“1”为类别，"0:2.0"表示第0个特征的值为2.0。同理，属于负类的样本[2.0, 0.0, 0.1, 0.0, 0.0, 0.0]被表示为“-1 0:2.0 2：0.1”。
 
 * 输入输出参数
   * angel.train.data.path：输入数据路径
@@ -47,10 +66,9 @@ LR on Angel支持“libsvm”、“dummy”两种数据格式，分别如下所
   * angel.worker.task.number：每个Worker上的task的个数，默认为1
   * angel.ps.number：PS个数
   * angel.ps.memory.mb：PS申请内存大小!
-
-* 其它参数配置
-  * 模型输出路径删除：
-   为了防止误删除模型，Angel默认不自动删除模型输出路径的文件。如果需要删除，要在Angel参数框内填入angel.output.path.deleteonexist=true
+
+
+### 性能