update document

FederatedAI · Sep 14, 2021 · 74d2584 · 74d2584
1 parent 9ec48a6
commit 74d2584
Show file tree

Hide file tree

Showing 23 changed files with 243 additions and 202 deletions.
diff --git a/document/docs/algo/base.md b/document/docs/algo/base.md
@@ -4,8 +4,7 @@ PipelineModelProcessor类是模型处理逻辑的实现类，serving-server在
 2) 合并远端数据 （这一步只在Guest方存在）  
 
 BaseComponent 类是所有算法组件的基类，它实现了LocalInferenceAware接口  
-```yml
-xxxxxxxxxx
+```java
 public interface LocalInferenceAware {
 
     public Map<String, Object> localInference(Context context, List<Map<String, Object>> input);
@@ -14,15 +13,14 @@ public interface LocalInferenceAware {
 ```
 PipelineModelProcessor中的pipeline在检测到组件为LocalInferenceAware时，会调用localInference方法来进行本地预测。
 另外一个重要的接口MergeInferenceAware，实现该接口的组件可以执行合并远端返回数据的逻辑。  
-```yml
-xxxxxxxxxx
+```java
 public interface MergeInferenceAware {
 
     public Map<String, Object> mergeRemoteInference(Context context, List<Map<String, Object>> localData, Map<String, Object> remoteData);
 }
 ```
 
-### HeteroSecureBoost 组件
+### HeteroSecureBoost 在线推理
 HeteroSecureBoost 为纵向联邦SecureBoost在线推理的实现过程，与离线不同的是，目前serving只支持单个host的预测。  
 它主要包含3个文件"HeteroSecureBoost", "HeteroSecureBoostingTreeGuest", "HeteroSecureBoostingTreeHost"，下面对这三个文件展开说明
 
@@ -67,14 +65,16 @@ HeteroLR是HeteroLRGuest和HeteroLRHost的模型基类，该基类提供了模
 
 1. HeteroLR继承自BaseComponent类，BaseComponent类为所有模型的基类，所有算法模型必须继承该类和实现相关接口，用于统一的调度。
 2. 模型初始化: initModel函数，功能是对输入的Meta和Param两个序列化的模型文件进行反序列话，同时，初始化相关的类属性，初始化的内容包括:  
-    a. weight: LR模型的权值  
-    b. intercept: LR模型的偏置
+    >weight: LR模型的权值  
+    >intercept: LR模型的偏置
+
 3. 功能函数说明:  
-    a. forward: 计算score = weight * value + intercept, 若是host方，则intercept为0
+    forward: 计算score = weight * value + intercept, 若是host方，则intercept为0
 
 #### HeteroLRGuest and HeteroLRHost
-HeteroLRGuest和HeteroLRHost是party guest和host对应的实现代码，其中party guest收到请求后，会执行推理过程，与此同时，需要与host也一起进行推理，下面给出具体说明。
-
+HeteroLRGuest和HeteroLRHost是party guest和host对应的实现代码，其中party guest收到请求后，会执行推理过程，与此同时，需要与host也一起进行推理，下面给出具体说明：
+```text
 1. 系统针对请求的id，同时给guest和host发起推理请求
 2. Host接收到推理指令后，执行forward函数的前向计算流程，并将结果返回，由系统调度给guest
 3. Guest接收到推理指令后，执行forward函数的前向计算流程，并且获取host的计算结果，组合一起，并计算sigmod得到最终评分，完成完整的推理流程  
+```
diff --git a/document/docs/algo/feature.md b/document/docs/algo/feature.md
@@ -1,8 +1,8 @@
-目前FATE-serving提供了以下特征工程组件，下面将会一一介绍。
+目前FATE-serving提供了以下特征工程组件:
 ### 纵向特征分箱（Hetero Feature Binning）
 该模块利用训练得到的模型，根据训练时输入的不同参数，将数据转化为数据所在分箱的index。
 #### 文件结构
-该模块由三个文件组成，分别是"HeteroFeatureBinning"， "HeteroFeatureBinningGuest"，"HeteroFeatureBinningHost"。 
+该模块由三个文件组成，分别是"HeteroFeatureBinning"、"HeteroFeatureBinningGuest"、"HeteroFeatureBinningHost"
 
 其中HeteroFeatureBinning是HeteroFeatureBinningGuest和HeteroFeatureBinningHost的基类。而HeteroFeatureBinning继承了BaseComponent。BaseComponent是所有模型组件的基类。
 #### 参数和方法说明

diff --git a/document/docs/config/admin.md b/document/docs/config/admin.md
@@ -1,4 +1,6 @@
 ### application.properties配置
+>源码中的配置文件没有罗列出所有配置，只保留了必需的配置，其他配置都采用了默认值。如果需要可以根据以下表格来在配置文件中新增条目。
+
 <table>
   <tr>
     <td>配置项</td>

diff --git a/document/docs/config/proxy.md b/document/docs/config/proxy.md
@@ -116,7 +116,10 @@
 </table>
 
 ### route_table配置
-**在2.1.0版本开始支持HTTP接口配置，2.1.0之前的版本只支持GRPC配置。**     
+下面的json代码大致说明了router_table.json的填写规则，根据具体案例来配置。
+
+>启动注册中心时，只配置默认对外转发地址（default）即可 ;   
+>在2.1.0版本开始支持HTTP接口配置，2.1.0之前的版本只支持GRPC配置。     
 
 1.GRPC
 ```yaml

diff --git a/document/docs/config/security.md b/document/docs/config/security.md
@@ -1,9 +1,9 @@
 FATE-Serving 2.0.4 版本开始支持TLS双向认证，数据使用方和数据提供方分别作为客户端和服务端，启用TLS认证后双方交互时会进行安全性认证，配置所需文件由服务端生成提供给客户端。要使用TLS，需要以PEM格式指定证书链和私钥。  
 开启TLS认证需要在serving-proxy组件中配置，配置如下：  
-### 服务端配置  
+
+## 服务端配置  
 •	application.properties配置   
-```yml
-xxxxxxxxxx
+```yaml
 # only support PLAINTEXT, TLS(we use Mutual TLS here), if use TSL authentication
 proxy.grpc.inter.negotiationType=TLS
 # only needs to be set when negotiationType is TLS
@@ -13,11 +13,10 @@ proxy.grpc.inter.server.certChain.file=/data/projects/fate-serving/serving-proxy
 proxy.grpc.inter.server.privateKey.file=/data/projects/fate-serving/serving-proxy/conf/ssl/server.pem
 ```
 
-### 客户端配置
-2.1.0之前：  
+## 客户端配置 
+#### 2.1.0之前：
 •	application.properties配置  
-```yml
-xxxxxxxxxx
+```yaml
 # only support PLAINTEXT, TLS(we use Mutual TLS here), if use TSL authentication
 proxy.grpc.inter.negotiationType=TLS
 # only needs to be set when negotiationType is TLS
@@ -28,7 +27,7 @@ proxy.grpc.inter.client.privateKey.file=/data/projects/fate-serving/serving-prox
 ```
 
 •	route_table.json配置  
-```yml
+```json
 {
   "route_table": {
     "default": {
@@ -40,21 +39,16 @@ proxy.grpc.inter.client.privateKey.file=/data/projects/fate-serving/serving-prox
         }
       ]
     },
-    "10000": {
-      "serving": [
-        {
-          "ip": "127.0.0.1",
-          "port": 8080
-        }
-      ]
-    }
+      ......
   }
 }
 ```
 
-由于在2.1.0之后FATE-Serving支持多host预测，所以guest需要在route_table内配置安全证书  
-•	route_table.json配置  
-```yml
+#### 2.1.0之后：
+由于FATE-Serving要支持多host预测，所以客户端guest方需要在route_table内配置安全证书。 
+
+•   route_table.json配置如下：
+```json
 {
   "route_table": {
     "default": {
@@ -70,14 +64,7 @@ proxy.grpc.inter.client.privateKey.file=/data/projects/fate-serving/serving-prox
         }
       ]
     },
-    "10000": {
-      "serving": [
-        {
-          "ip": "127.0.0.1",
-          "port": 8080
-        }
-      ]
-    }
+    ......
   }
 }
 

diff --git a/document/docs/example/deploy.md b/document/docs/example/deploy.md
@@ -11,7 +11,9 @@ zk.url=172.168.0.1:2181,172.168.0.2:2181,172.168.0.3:2181
 proxy.grpc.intra.port=8879
 proxy.grpc.inter.port=9370
 ```
-•	guest 的serving-proxy router_table.json配置：  
+•	guest 的serving-proxy router_table.json配置： 
+
+由于guest的请求只会向外发送，所以只需要配置出口ip端口就好， 如下代码所示只需要配置default转发规则，则会将所有请求转发至出口ip，而出口ip需要与host端proxy.grpc.inter.port对齐。
 ```yml
 xxxxxxxxxx
 {
@@ -30,7 +32,6 @@ xxxxxxxxxx
   }
 }
 ```
-由于guest的请求只会向外发送，所以只需要配置出口ip端口就好， 如以上代码所示只需要配置default转发规则，则会将所有请求转发至出口ip。而出口ip需要与host端proxy.grpc.inter.port对齐
 
 •	guest 的 serving-server application.properties 配置： 
 ```yml

diff --git a/document/docs/example/nginx.md b/document/docs/example/nginx.md
diff --git a/document/docs/index.md b/document/docs/index.md
@@ -2,6 +2,22 @@
 ### 什么是Fate-Serving
 fate-serving是FATE的在线部分，在使用FATE进行联邦建模完成之后，可以使用fate-serving进行包括单笔预测、多笔预测以及多host预测在内的在线联合预测。
 
+### Fate-Serving 服务特性
+* 订阅与注册的可靠性保证  
+
+目前订阅/取消订阅  、  注册/取消注册操作都使用了定时重试的机制来保证操作的最终成功。
+
+* 客户端服订阅务信息的缓存与持久化  
+
+默认在serving-server实例部署目录下（2.1版本之前是在当前用户目录下）生成.fate 的文件夹，所有的持久化信息都会放入该文件夹。 使用服务治理管理的模块启动之后，首先会从本地缓存文件加载之前订阅的接口，然后再从注册中心拉取并更新本地文件。在极端情况下，如注册中心宕机，本地的持久化文件将继续服务，不会影响业务流量。
+
+* 客户端的负载均衡  
+>目前支持加权随机（可以通过serving-admin页面调整接口权重）。
+
+* 服务端的优雅停机     
+
+服务端会在jvm 退出时，主动取消注册在注册中心的接口，拒绝新的请求，并等待当前正在处理的请求退出。 需要注意的是，不能使用kill -9 命令退出，这样不会触发jvm退出前的动作，若进程强制退出，虽然zookeeper会判断心跳超时并将所创建的临时节点消失，但是在心跳还未超时的这段时间里业务流量还会被路由到当前已被kill的实例上来，造成风险。建议使用kill。
+
 ### 组件简介
 •	serving-server  
 serving-server用于实时处理在线预测请求, 理论上serving-server需要从fate-flow加载模型成功之后才能对外提供服务。 在FATE中建好模型之后，通过fate-flow的推送模型脚本可以将模型推送至serving-server。 推送成功之后，serving-server会将该模型相关的预测接口注册进zookeeper， 外部系统可以通过服务发现获取接口地址并调用。 同时本地文件持久化该模型,以便在serving-server实例在集群中某些组件不可用的情况下， 仍然能够从本地文件中恢复模型。支持多host的算法模型：纵向LR+纵向SBT
@@ -10,7 +26,7 @@ serving-server用于实时处理在线预测请求, 理论上serving-server需
 serving-proxy 是serving-server的代理，对外提供了grpc接口以及http的接口， 主要用于联邦预测请求的路由转发鉴权。在离线的联邦建模时， 每一个参与方都会分配一个唯一的partId。serving-proxy维护了一个各参与方partId的路由表， 并通过路由表中的信息来转发请求。
 
 •	serving-admin  
-serving-admin 提供在线集群的可视化操作界面， 可以查看管理集群中各节点的配置以及状态、查看模型列表、流量的调控、并能提供一定的监控的功能。[点击查看详情](./example/admin.md)    
+serving-admin 提供在线集群的可视化操作界面， 可以查看管理集群中各节点的配置以及状态、查看模型列表、流量的调控、并能提供一定的监控的功能。[点击查看详情](./service/admin.md)    
 
 •	zookeeper  
 zookeeper 用户各组件的信息同步协调以及服务注册与发现
@@ -32,35 +48,3 @@ zookeeper 用户各组件的信息同步协调以及服务注册与发现
 •	fate-serving-sdk：提供sdk代码，用于代码接入serving-server服务  
 •	fate-serving-server：serving-server模块，主要处理在线联邦预测业务和模型算法逻辑  
 •	fate-serving-cli：golang实现，命令行工具的代码，提供serving-server的查询和预测  
-
-## 服务介绍
-[点击查看详情](./service/service.md)
-
-## 部署示例
-[点击查看详情](./example/deploy.md)
-
-## quickstart
-[点击查看详情](./quickstart/quickstart.md)
-
-## 加载模型及发布模型
-[点击查看详情](./model/load.md)
-
-## HOST如何获取特征
-[点击查看详情](./service/adapter.md)
-
-## 推理接口
-[usage](./inference/usage.md)   
-[单笔推理](./inference/single.md)   
-[批量推理](./inference/batch.md)    
-
-## 日志简介
-[点击查看详情](./log/log.md)
-
-## TLS安全证书
-[点击查看详情](config/security.md)
-
-## 算法相关
-[基础类](./algo/base.md)   
-[特征工程组件介绍](./algo/feature.md)   
-[其他组件](./algo/components.md)    
-
diff --git a/document/docs/inference/batch.md b/document/docs/inference/batch.md
@@ -33,8 +33,7 @@ content-application/json
 </table>
 
 #### 请求示例
-```yml
-xxxxxxxxxx
+```json
 {
     "head": {
         "serviceId": "test-lr"
@@ -127,8 +126,7 @@ xxxxxxxxxx
   </tr>
 </table>
 
-```yml
-xxxxxxxxxx
+```json
 {
     "retcode": 0,
     "retmsg": "",
@@ -194,8 +192,7 @@ xxxxxxxxxx
 ```
 
 #### 示例
-```yml
-xxxxxxxxxx
+```java
 package com.webank.ai.fate.serving.sdk.client;
 import com.google.common.collect.Lists;
 import com.google.common.collect.Maps;
@@ -237,7 +234,7 @@ public class RegisterClientExample {
 		featureData.put("x7", 0.102345);
 		inferenceRequest.setFeatureData(featureData);
 		Map<String,Object>  sendToRemote = Maps.newHashMap();
-		sendToRemote.put("device_id","helloworld");
+		sendToRemote.put("id","123");
 	/**
 		* sendToRemote 数据会发送到host ，需要谨慎检查是否是敏感数据
 		*/

diff --git a/document/docs/inference/single.md b/document/docs/inference/single.md
@@ -31,8 +31,7 @@ content-application/json
 </table>
 
 #### 请求示例
-```yml
-xxxxxxxxxx
+```json
 {
   "head": {
     "serviceId": "test-lr"
@@ -98,8 +97,7 @@ xxxxxxxxxx
   </tr>
 </table>
 
-```yml
-xxxxxxxxxx
+```json
 {
     "retcode": 0,
     "retmsg": "",
@@ -119,7 +117,6 @@ xxxxxxxxxx
 
 #### 操作步骤
 ```yml
-xxxxxxxxxx
 1.cd  fate-serving源码根目录，执行 mvn clean  install -pl com.webank.ai.fate:fate-serving-core,com.webank.ai.fate:fate-serving-sdk,com.webank.ai.fate:fate-serving-register,com.webank.ai.fate:fate-serving 
 2.在目标工程文件中加入依赖         
     <dependency>
@@ -131,8 +128,7 @@ xxxxxxxxxx
 
 #### 示例
 
-```yml
- xxxxxxxxxx
+```java
 package com.webank.ai.fate.serving.sdk.client;
 import com.google.common.collect.Lists;
 import com.google.common.collect.Maps;
@@ -174,7 +170,7 @@ public class RegisterClientExample {
         featureData.put("x7", 0.102345);
     inferenceRequest.setFeatureData(featureData);
     Map<String,Object>  sendToRemote = Maps.newHashMap();
-    sendToRemote.put("device_id","helloworld");
+    sendToRemote.put("id","123");
   /**
     * sendToRemote 数据会发送到host ，需要谨慎检查是否是敏感数据
     */

diff --git a/document/docs/inference/usage.md b/document/docs/inference/usage.md
@@ -9,10 +9,10 @@
 优点：接入简单，可在serving-proxy前面增加nginx作为反向代理。
 
 3.使用源码中自带的SDK访问serving-server。  
-优点：省去了中间serving-proxy作为转发节点 ，提高通信效率。并将使用fate-serving的服务注册以及发现等功能，直接调用serving-server的grpc接口
+优点：省去了中间serving-proxy作为转发节点 ，提高通信效率。并将使用fate-serving的服务注册以及发现等功能，直接调用serving-server的grpc接口。
 
 4.自行开发并直接调用serving-server提供的grpc接口。     
-优点：目前sdk部分只提供了java版，若是其他未支持的语言，可以自行开发并调用相关接口 。部署时可以采用 nginx前置部署，用于反向代理grpc请求。
+优点：目前sdk部分只提供了java版，若是其他未支持的语言，可以自行开发并调用相关接口 。部署时可以采用 [nginx前置部署](example/nginx.md)，用于反向代理grpc请求。
 
 ### serving-proxy错误码表
 <table>

diff --git a/document/docs/log/log.md b/document/docs/log/log.md
@@ -1,7 +1,6 @@
 ### 配置
 目前fate-serving 使用log4j2作为日志组件，使用log4j2.xml来作为配置文件。
-```yml
-xxxxxxxxxx
+```xml
 <Configuration status="ERROR" monitorInterval="60">
     <Properties>
         <Property name="logdir">logs</Property>
@@ -101,7 +100,7 @@ xxxxxxxxxx
 
 ### 可选打印内容
 工程的配置文件中现提供两个可选参数，启动即可在flow日志中打印请求的参数和返回值，可以根据自己需要修改参数并重启系统
-```yml
+```properties
 print.input.data=true   // flow日志打印参数
 print.output.data=true  // flow日志打印返回值
 ```