update document

FederatedAI · Sep 14, 2021 · 485851d · 485851d
1 parent 74d2584
commit 485851d
Show file tree

Hide file tree

Showing 12 changed files with 185 additions and 26 deletions.
diff --git a/document/docs/config/server.md b/document/docs/config/server.md
@@ -1,4 +1,4 @@
-### application.properties配置   
+### serving-server.properties配置   
 以下为conf/serving-server.properties文件配置详解。源码中的配置文件没有罗列出所有配置，只保留了必需的配置，其他配置都采用了默认值。如果需要可以根据以下表格来在配置文件中新增条目
 
 <table>

diff --git a/document/docs/example/nginx.md b/document/docs/example/nginx.md
@@ -0,0 +1,65 @@
+FATE-Serving 之间的交互可以通过nginx反向代理转发grpc请求，以下几种场景配置如下：
+
+* 场景一：双方不配置TLS，通过nginx四层代理转发
+![场景一](../img/nginx_1.jpg)
+
+* 场景二：双方配置TLS，通过nginx四层代理转发，双方分别进行证书校验
+![场景二](../img/nginx_2.jpg)
+
+* 场景三：数据使用方配置Client端证书，Nginx配置Server端证书，Host不配置证书，通过nginx七层代理转发，由Client端和nginx进行证书校验
+![场景三](../img/nginx_3.jpg)
+
+四层代理转发配置
+```editorconfig
+stream {
+  log_format proxy '$remote_addr [$time_local] '
+      '$protocol $status $bytes_sent $bytes_received '
+      '$session_time "$upstream_addr" '
+      '"$upstream_bytes_sent" "$upstream_bytes_received" "$upstream_connect_time"';
+    
+    upstream next_rollsite {
+        hash $remote_addr consistent;
+        server 127.0.0.1:8869;      # 转发到下游服务的地址
+    }
+    
+    server {
+    listen 8443;          # nginx 监听端口
+    proxy_connect_timeout 8s;
+    proxy_timeout 24h;
+    proxy_pass next_rollsite;
+    }
+}
+```
+
+七层代理转发配置
+```editorconfig
+http {
+    server {
+        listen 8443 ssl http2;          # gRPC基于HTTP/2
+        server_name localhost;
+        
+    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;  # 证书协议类型
+        ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!DH:!DHE:!RC4:!MD5:!NULL:!aNULL;
+    ssl_certificate      ssl/server.crt;  # 证书文件
+        ssl_certificate_key  ssl/server.key;  # 私钥
+    ssl_session_cache    shared:SSL:10m;
+    ssl_session_timeout  5m;
+        ssl_verify_client on;
+    ssl_prefer_server_ciphers  on;
+    ssl_client_certificate ssl/ca.crt;    # 根证书
+        
+        location / {
+            grpc_pass grpc://127.0.0.1:8869;  # 转发到下游服务的地址
+            error_page 502 = /error502grpc;   # 错误页面
+        }
+        
+        location = /error502grpc {
+            internal;
+            default_type application/grpc;
+            add_header grpc-status 14;
+            add_header grpc-message "unavailable";
+            return 204;
+        }
+    }
+}
+```
diff --git a/document/docs/img/client_connect.jpg b/document/docs/img/client_connect.jpg
diff --git a/document/docs/img/client_showconfig.jpg b/document/docs/img/client_showconfig.jpg
diff --git a/document/docs/img/client_showmodel.jpg b/document/docs/img/client_showmodel.jpg
diff --git a/document/docs/img/nginx_1.jpg b/document/docs/img/nginx_1.jpg
diff --git a/document/docs/img/nginx_2.jpg b/document/docs/img/nginx_2.jpg
diff --git a/document/docs/img/nginx_3.jpg b/document/docs/img/nginx_3.jpg
diff --git a/document/docs/img/sequence_diagram.jpg b/document/docs/img/sequence_diagram.jpg
diff --git a/document/docs/index.md b/document/docs/index.md
@@ -1,4 +1,6 @@
 ## 简介
+**目前的文档只适用于2.0以上版本**
+
 ### 什么是Fate-Serving
 fate-serving是FATE的在线部分，在使用FATE进行联邦建模完成之后，可以使用fate-serving进行包括单笔预测、多笔预测以及多host预测在内的在线联合预测。
 
@@ -17,34 +19,32 @@ fate-serving是FATE的在线部分，在使用FATE进行联邦建模完成之后
 * 服务端的优雅停机     
 
 服务端会在jvm 退出时，主动取消注册在注册中心的接口，拒绝新的请求，并等待当前正在处理的请求退出。 需要注意的是，不能使用kill -9 命令退出，这样不会触发jvm退出前的动作，若进程强制退出，虽然zookeeper会判断心跳超时并将所创建的临时节点消失，但是在心跳还未超时的这段时间里业务流量还会被路由到当前已被kill的实例上来，造成风险。建议使用kill。
+### 功能架构图  
+![架构1](img/Structure1.jpg)  
 
-### 组件简介
-•	serving-server  
-serving-server用于实时处理在线预测请求, 理论上serving-server需要从fate-flow加载模型成功之后才能对外提供服务。 在FATE中建好模型之后，通过fate-flow的推送模型脚本可以将模型推送至serving-server。 推送成功之后，serving-server会将该模型相关的预测接口注册进zookeeper， 外部系统可以通过服务发现获取接口地址并调用。 同时本地文件持久化该模型,以便在serving-server实例在集群中某些组件不可用的情况下， 仍然能够从本地文件中恢复模型。支持多host的算法模型：纵向LR+纵向SBT
+### 部署架构
+fate-serving 的部署架构图如下
+![架构2](img/Structure2.jpg)
 
-•	serving-proxy  
-serving-proxy 是serving-server的代理，对外提供了grpc接口以及http的接口， 主要用于联邦预测请求的路由转发鉴权。在离线的联邦建模时， 每一个参与方都会分配一个唯一的partId。serving-proxy维护了一个各参与方partId的路由表， 并通过路由表中的信息来转发请求。
+如上图所示，整个集群需要有几个组件：  
+•	serving-server 
+
+>serving-server用于实时处理在线预测请求, 理论上serving-server需要从fate-flow加载模型成功之后才能对外提供服务。 在FATE中建好模型之后，通过fate-flow的推送模型脚本可以将模型推送至serving-server。 推送成功之后，serving-server会将该模型相关的预测接口注册进zookeeper， 外部系统可以通过服务发现获取接口地址并调用。 同时本地文件持久化该模型,以便在serving-server实例在集群中某些组件不可用的情况下，仍然能够从本地文件中恢复模型。支持多host的算法模型：纵向LR、纵向SBT。
+
+•	serving-proxy 
+
+>serving-proxy 是serving-server的代理，对外提供了grpc接口以及http的接口， 主要用于联邦预测请求的路由转发鉴权。在离线的联邦建模时， 每一个参与方都会分配一个唯一的partId。serving-proxy维护了一个各参与方partId的路由表， 并通过路由表中的信息来转发请求。
 
 •	serving-admin  
-serving-admin 提供在线集群的可视化操作界面， 可以查看管理集群中各节点的配置以及状态、查看模型列表、流量的调控、并能提供一定的监控的功能。[点击查看详情](./service/admin.md)    
+
+>serving-admin 提供在线集群的可视化操作界面， 可以查看管理集群中各节点的配置以及状态、查看模型列表、流量的调控、并能提供一定的监控的功能。[点击查看详情](./service/admin.md)    
 
 •	zookeeper  
-zookeeper 用户各组件的信息同步协调以及服务注册与发现
+>zookeeper 用于各组件的信息同步协调以及服务注册与发现
+
+### 工作时序图
+![工作时序图](img/sequence_diagram.jpg)
+
 
-### 架构简介  
-各组件的具体功能以及整个项目的功能如下图所示：  
-![架构1](img/Structure1.jpg)  
-![架构2](img/Structure2.jpg)
 
-### 源码结构
-•	fate-serving-register：主要为服务治理相关的逻辑  
-•	fate-serving-admin：serving-admin模块，提供集群服务的可视化管理/监控  
-•	fate-serving-admin-ui：serving-admin的前端代码，使用Vue.js开发  
-•	fate-serving-common：fate-serving的公共组件模块  
-•	fate-serving-core：fate-serving的核心代码包  
-•	fate-serving-extension：主要用于实现一些扩展逻辑，如host端的自定义Adaptor  
-•	fate-serving-federatedml：算法组件的实现逻辑  
-•	fate-serving-proxy：serving-proxy模块，主要提供路由转发及鉴权，对外开放http/grpc接口  
-•	fate-serving-sdk：提供sdk代码，用于代码接入serving-server服务  
-•	fate-serving-server：serving-server模块，主要处理在线联邦预测业务和模型算法逻辑  
-•	fate-serving-cli：golang实现，命令行工具的代码，提供serving-server的查询和预测  
+
diff --git a/document/docs/release/change_log.md b/document/docs/release/change_log.md
@@ -1,6 +1,16 @@
+## FATE-SERVING 2.1 新增特性： 
+```text
+1.支持多host的算法：纵向LR、纵向SBT
+2.支持查看模型pipeline 
+3.支持模型同步
+4.模型操作/展示优化
+5.增加cluster一键自检工具
+6.支持配置生成路由表
+7.服务拓扑图优化
+```
 
+## FATE-SERVING 2.0 支持的特性：
 
- ## FATE-SERVING 2.0 支持的特性：
 ```text
 1.单笔预测，2.0.*版本guest方与host方将并行计算，从而降低了耗时。    
 2.批量预测，2.0.*版本开始引入的新的特性，一次请求可以批量提交一批需要预测的数据，极大地提高了吞吐量。  
@@ -12,4 +22,11 @@
 8.支持多种缓存方式，FATE-SERVING在1.3.*版本强依赖redis，从2.0.*版本开始，不再强依赖redis。可以选择不使用缓存、使用本地内存缓存、使用redis。   
 9.更改内部预测流程，重构了核心代码，去除调了前后处理等组件，使用了统一的异常处理。算法组件不再跟rpc接口紧耦合。  
 10.提供命令行工具，能够查询配置、模型信息
-```
+```
+
+**兼容性** 
+- 2.0.* 版本的host方 fate-serving 兼容 1.3.* 版本的 guest 方fate-serving，反过来1.3.* 版本的host fate-serving 不兼容2.0.*版本的guest。 如果需要升级集群，则需要先升级host方。
+
+- 升级过程中， 建议不要在原有目录部署，原因是有可能因为原有版本的jar包没有替换干净导致jar包冲突 。可以新建另一个目录， 然后将新包部署。部署后并启动后，2.0.* 版本会读取当前用户根目录下.fate目录下的旧模型存储文件加载进内存，并且会生成新的模型文件放到另一目录，具体的目录可以通过配置model.cache.path配置，参见serving-server的配置详解，默认是当前部署目录下。（建议先备份用户目录下 .fate 目录 ，在1.3.* 版本中，所有模型的本地存储文件都放在了该目录下 ）。
+
+- 2.0.* 有部分配置项与1.3.* 不同，升级时参考各模块的配置 。
diff --git a/document/docs/service/client.md b/document/docs/service/client.md
@@ -1 +1,78 @@
 ## fate-serving-client命令行工具
+FATE-Serving提供了fate-serving-client工具进行 下载系统对应版本fate-serving-client：
+>linux版本：fate-serving-client-2.1.0-linux.tar.gz     
+>mac版本：fate-serving-client-2.1.0-darwin.tar.gz
+
+在终端中使用`./fate-serving-client`启动， 默认情况下，client连接localhost:8000，使用参数可以指定目标地址`./fate-serving-client [-h host] [-p port] `host为需要连接的serving-server的ip ， port 为serving-server对外暴露的端口。
+>./fate-serving-client -h 127.0.0.1 -p 8000
+![connect](../img/client_connect.jpg)
+
+提供了以下几种指令：
+
+* showconfig 查看服务配置
+![showconfig](../img/client_showconfig.jpg)
+
+
+* showmodel 查看已发布的模型信息
+![showmodel](../img/client_showmodel.jpg)
+
+
+* inference 在线单笔预测，参数为参数文件路径，如：
+>inference  /data/projects/request.json     
+
+ /data/projects/request.json文件的内容为：
+ ```json
+{
+    "serviceId": "lr-test",
+    "featureData": {
+        "x0": 0.100016,
+        "x1": 1.21,
+        "x2": 2.321,
+        "x3": 3.432,
+        "x4": 4.543,
+        "x5": 5.654,
+        "x6": 5.654,
+        "x7": 0.102345
+    },
+    "sendToRemoteFeatureData": {
+        "id": "8"
+    }
+}
+``` 
+
+
+* batchInference 在线批量预测，参数为参数文件路径，如：
+>batchInference /data/projects/request.json 
+
+/data/projects/request.json 的内容为： 
+```json
+{
+    "serviceId": "lr-test",
+    "batchDataList": [
+        {
+            "index": 0,
+            "featureData": {
+                "x0": 0.4853,
+                "x1": 1.1996,
+                "x2": -1.574,
+                "x3": -0.8811,
+                "x4": -0.6176,
+                "x5": 0.5997,
+                "x6": -0.5361,
+                "x7": -0.1189,
+                "x8": -1.5728
+            },
+            "sendToRemoteFeatureData": {
+                "device_id": "299",
+                "phone_num": 585
+            }
+        }
+    ]
+}
+```
+
+* help 查看帮助信息
+> help
+
+* quit 关闭连接
+> quit