本文基于fate1.6.1

一、fate flow client 命令行使用

1.1上传数据

1.1.1 上传数据配置文件

//upload_data.json
{
    "file": "examples/data/breast_hetero_guest.csv", //所上传的csv数据文件
    "table_name": "hetero_breast_guest",             //存储数据表的表名
    "namespace": "experiment",                       //存储数据表的命名空间
    "head": 1,         // 指定数据文件是否包含表头，1包含，0不包含
    "partition": 8,    // 指定用于存储数据的分区数    ？？？？
    "work_mode": 0,    //指定工作模式，0代表单机版，1代表集群版
    "backend": 0       //指定后端，0代表EGGROLL， 1代表SPARK加RabbitMQ，2代表SPARK加Pulsar
}

1.1.2 上传数据命令

//使用python方式上传数据   (FATE版本1.6.0单机部署，docker:fate)
 python /fate/python/fate_flow/fate_flow_client.py -f upload -c upload_data.json
 
 
//使用fateflow方式上传数据 
//使用fateflow的第一步是先对fateflow进行init
flow init -c /data/projects/fate/python/conf/service_conf.yaml 
或者flow init --ip 127.0.0.1 --port 9380
//上传数据
flow data upload -c upload_data.json --drop  //--drop代表覆盖已上传的同名文件

（不同版本fate_flow_client.py的位置可能不同）

1.2 任务配置和运行配置

版本1.5.0以前的FATE适用V1规则
版本1.5.0以后的FATE适用V2规则，可兼容V1

本章讲training job的配置
通过Flow Client提交conf & dsl来开始training job

1.2.1 DSL 配置文件

xxxx_dsl.json文件
components表示将会使用到的各个模块
每个独立的模块定义在在"components" 之下，使用模块名加 _num 作为对应模块的 key，如"dataio_0"
所有数据需要通过Reader模块从数据存储拿取数据 (Reader模块仅有输出output)

//xxxx_dsl.json
{
  "components" : { 
		  "reader_0": {          //V1不用reader，直接用dataio
		      "module": "Reader",
		      "output": {
		          "data": ["train"]
			  }
		  }
  		  "dataio_0": {
		      "module": "DataIO",
		      "input": {
		          "data": {
		              "data": [
		                  "reader_0.train_data" //通过Reader模块拿数据
		              ]
		          }
		      },
		      "output": {
		          "data": ["train"],
		          "model": ["dataio"]
		      }
		  }

		  ...
     }
}

参数说明

module
指定使用的模块，需要和 federatedml/conf/setting_conf 提供的各个模块的文件名保持一致
input
分为两种输入类型，分别是 data 和 model
data：有四种可能的输入类型：
* data（一般被用于data_io 模块、feature_engineering 模块或者 evaluation 模块）
* train_data（一般被用于 homo_lr, heero_lr 和 secure_boost 模块，出现train_data的任务将会被识别为一个fit任务）
* validate_data（如果存在 train_data 字段，则 eval_data 指向的数据将会作为 validation set。若不存在 train_data 字段，则这个任务将被视作为一个predict 或 transform 任务）
* test_data（用作预测数据，如提供，需同时提供model输入）
model：有两种可能的输入类型：
* model（用于同种类型组件的模型输入）
* isometric_model（用于指定继承上游组件的模型输入）
output
和 input一样，有 data 和 model 两种类型
data：有四种可能的输出类型：
* data（常规模块数据输出）
* train_data: 仅用于Data Split数据分割
* validate_data: 仅用于Data Split
* test_data：仅用于Data Split
model：只使用model

1.2.2 运行配置 Submit Runtime Conf

xxxxx_conf.json文件
设置各个参与方的信息, 作业的参数及各个组件的参数

内容包括如下：

dsl_version（V2）

"dsl_version": "2"

initiator（V1、V2）

任务发起方（一般都为guest）

"initiator": {
   "role": "guest",
   "party_id": 9999
}

role（V1、V2）

所有参与方的信息
每一个元素代表一种角色以及承担这个角色的 party_id。每个角色的 party_id 以列表形式存在，因为一个任务可能涉及到多个 party 担任同一种角色。

"role": {
    "guest": [9999],
    "host": [10000],
    "arbiter": [10000]
}

guest代表数据应用方。Guest是数据应用方，在纵向模型的建模中往往是有y的一方。通常整个建模任务通常是服务于y的业务逻辑的，因此也只有guest需要应用这一模型。同时，如果允许Host方任意发起建模流程，有可能会有Guest方的数据泄露风险。

host是数据提供方。

arbiter仲裁器/仲裁者是用来辅助多方完成联合建模的，它的主要作用是聚合梯度或者模型。比如纵向lr里面，各方将自己一半的梯度发送给arbiter，然后arbiter再联合优化等等。（集中式拓扑）

local是指本地任务, 该角色仅用于upload和download阶段中。

role_parameters （V1）

定义不同role各自使用的模块。
这一部分的参数对于不同的 party 都有所区别。party 名被作为每一项元素的 key，而 value 则是具体的参数内容。

"guest": {    //key
   "args": {
     "data": {       
       "train_data": [   //train_data，eval_data 都应该以列表形式存在
         {
           "name": "breast_hetero_guest",     //用来指定上传数据的表格位置
           "namespace": "experiment"         //同上
         }
       ]
     }
   },
   "dataio_0": {
     "with_label": [
       true
     ],
     ...
   }
 },
 "host": {
   "args": {
     "data": {
       "train_data": [
         {
           "name": "breast_hetero_guest",
           "namespace": "experiment"
         }
       ]
     }
   },
   "dataio_0": {
      ...
   }
   ...
 }

algorithm_parameters（V1)

定义一些所有 party 都共享的参数。常为特征处理模块、模型训练模块、模型评估模块等。

job_parameters & 2.2.7 component_parameters（V2）

job_parameters 和 component_parameters 部分在FATE文档中没有给出说明，我看了官方示例程序，以下是我自己的理解。因为都涉及到common和role，这两个放一起说。

job_parameters 配置了与任务相关的参数
component_parameters 配置各组件的参数

在 job_parameters 和 component_parameters下都需要添加 “common” 和 “role” 的关键字。
common表示这是该配置可供所有role通用，role下则单独列出每个角色不同的配置。

举例 ( 主要看注释进行理解 )：

  "job_parameters": {       //配置与任务相关的参数
    "common": {              //对所有role来说通用
      "job_type": "train",
      "backend": 0,
      "work_mode": 0
    }
  },
  "component_parameters": {         //配置与组件相关的参数
    "common": {                      //对所有role来说通用
      "dataio_0": { ... },
      "hetero_lr_0": { ... },
      "evaluation_0": { ... }
    },
    "role": {                   //对不同role来说，组件配置不同的，在“role”下列出
      "host": {
        "0": {
          "dataio_0": {
            "with_label": false      
          },
          "reader_0": {
            "table": {
              "name": "breast_hetero_host",  //host与guest数据来源不同
              "namespace": "experiment"      //namespace这个配置项，host与guest相同
              //可能是由于table的name和namespace一起控制数据来源，常常将两个写在一起
              //个人认为也可以只在common写一次，不写在role下
            }
          }
        }
      },
      "guest": {
        "0": {
          "dataio_0": {
            "with_label": true
          },
          "reader_0": {
            "table": {
              "name": "breast_hetero_guest",    //host与guest数据来源不同
              "namespace": "experiment"
            }
          }
        }
      }
    }
  }

job_parameters的一些配置项：

配置项	默认值	支持值	说明
job_type	train	train, predict	任务类型
work_mode	0	0，1	0代表单方单机版，1代表多方分布式版本
backend	0	0，1，2	0代表EGGROLL，1代表SPARK加RabbitMQ，2代表SPARK加Pulsar
…	…	…	…
更多配置项见：https://fate.readthedocs.io/en/latest/_build_temp/doc/dsl_conf_v2_setting_guide_zh.html

1.2.3 提交任务命令

//-d 代表 dsl.json ， -c 代表 conf.json

//python方式
python /fate/python/fate_flow/fate_flow_client.py -f submit_job  -c  xxx_conf.json  -d xxx_dsl.json

//fateflow方式
flow job submit  -c ./xxx_conf.json -d ./xxx_dsl.json

1.3 预测任务

提交训练任务后会得到一个包含model_id和model_version的返回信息，像下面这样：

>> flow job submit -c ./examples/dsl/v2/hetero_secureboost/test_secureboost_train_binary_conf.json -d ./examples/dsl/v2/hetero_secureboost/test_secureboost_train_dsl.json
>> {
        "data": {
            "board_url": "http://127.0.0.1:8080/index.html#/dashboard?job_id=2020103015490073208469&role=guest&party_id=10000",
            "job_dsl_path": "/fate/jobs/2020103015490073208469/job_dsl.json",
            "job_runtime_conf_path": "/fate/jobs/2020103015490073208469/job_runtime_conf.json",
            "logs_directory": "/fate/logs/2020103015490073208469",
            "model_info": {
                "model_id": "guest-10000#host-10000#model",
                "model_version": "2020103015490073208469"
            }
        },
        "jobId": "2020103015490073208469",
        "retcode": 0,
        "retmsg": "success"
    }

若是忘记了model_id和model_version可以通过job 输出到-o的目录下：

flow job config -j 2020103015490073208469 -r guest -p 9999 -o ./

预测任务同样需要一个predict conf，和一个predict dsl文件。
dsl V2的版本中预测任务需要同时定义预测的dsl和conf文件，而V1中只需要定义conf，dsl文件和训练的dsl文件相同。
可以通过训练的dsl来生成预测的dsl，指令如下：

flow job dsl --cpn-list "dataio_0, hetero_feature_binning_0, hetero_feature_selection_0, evaluation_0" --train-dsl-path fate_flow/examples/test_hetero_lr_job_dsl.json -o fate_flow/examples/
//--cpn-list 需要是train dsl中存在的组件
//-o 是生成的predict dsl输出路径

使用flow_client来部署配置模型预测DSL。

flow model deploy --model-id $MODEL_ID --model-version $MODEL_VERSION --dsl-path $DSL_PATH
//--dsl-path  参数  可选   用户指定预测DSL文件路径
//--cpn-list   参数  可选   预测任务需要用到的组件列表

我们可以通过替换model_id、model_version和数据集名称来修改现有的predict conf，从而形成一个新的predict conf。在这里，我们将 predict conf 中的 model_id 和 model_version 替换为训练工作返回的 model_id 和deploy指令返回的 model_version。

//predict_conf.json   V1
{
    "initiator": {
        "role": "guest",
        "party_id": 10000
    },
    "job_parameters": {
        "work_mode": 0,
        "job_type": "predict",
        "model_id": "guest-10000#host-10000#model",  <<-- to replace 
        "model_version": "2020103015490073208469"  <<-- to replace
    },
    "role": {
        "guest": [
            10000
        ],
        "host": [
            10000
        ]
    },
    "role_parameters": {
        "guest": {
            "args": {
                "data": {
                    "eval_data": [
                        {
                            "name": "breast_hetero_guest",   <<-- you can set predict dataset here
                            "namespace": "experiment"
                        }
                    ]
                }
            }
        },
        "host": {
            "args": {
                "data": {
                    "eval_data": [
                        {
                            "name": "breast_hetero_host",  <<-- you can set predict dataset here
                            "namespace": "experiment"
                        }
                    ]
                }
            }
        }
    }
}

//predict_conf.json   V2
{
    "dsl_version": 2,
    "initiator": {
        "role": "guest",
        "party_id": 10000
    },
    "role": {
        "host": [
            9999
        ],
        "guest": [
            10000
        ]
    },
    "job_parameters": {
        "common": {
            "work_mode": 0,
            "backend": 0,
            "job_type": "predict",
            "model_id": "guest-10000#host-9999#model", <<-- to replace
            "model_version": "20200928174750711017114"  <<-- to replace
        }
    },
    "component_parameters": {
        "role": {
            "guest": {
                "0": {
                    "reader_0": {
                        "table": {
                            "name": "breast_hetero_guest", <<-- you can set new dataset here
                            "namespace": "experiment"
                        }
                    }
                }
            },
            "host": {
                "0": {
                    "reader_0": {
                        "table": {
                            "name": "breast_hetero_host",  <<-- you can set new dataset here
                            "namespace": "experiment"
                        }
                    }
                }
            }
        }
    }
}

提交预测工作指令

flow job submit -c ./examples/dsl/v2/hetero_secureboost/test_predict_conf.json

二、Pipeline

Pipeline 是一个高级 Python API，允许用户以顺序方式设计、启动和查询 FATE 作业。FATE Pipeline 设计为用户友好且与 FATE 命令行工具的行为一致。用户可以通过向管道添加组件来自定义作业工作流，然后通过一次调用启动作业。此外，Pipeline 提供了在拟合管道后运行预测和查询信息的功能。

示例见：fate/examples/pipeline/demo/
pipeline-upload.py：数据上传
pipeline-quick-demo.py：hetero_secureboost的训练评估
pipeline-mini-demo.py：hetero_lr的训练评估、部署、预测
pipeline-deploy-demo.py：比pipeline-mini-demo.py多了个components_checkpoint

初始化运行时的作业参数，代码中未见，补充如下

from pipeline.runtime.entity import JobParameters
job_parameters = JobParameters(backend=Backend.EGGROLL, work_mode=WorkMode.STANDALONE)

三、补充

服务器上：first_test

位置：cd /data/projects/fate/
Python容器中：

docker exec -it confs-xxxx_python_1 bash  //进入容器
cd fate_flow  
python fate_flow_client.py -f upload -c examples/upload_host.json

Client容器中：

//进入容器
docker exec -it confs-9999_client_1 bash    
//上传数据
cd /data/projects/fate/examples/first_test/data/
flow data upload -c test_upload_train.json --drop   //guest和host都需执行此步
//提交任务
cd /data/projects/fate/examples/first_test/
flow job submit -c ./test_conf.json -d ./test_dsl.json

To Do List

predict试用
- 自己的predict跑通
每个module的作用和使用（机器学习深度学习）
pipeline学习
底层python实现
开发新的module
多方FML

参考资料

FATE官方API：https://fate.readthedocs.io/en/latest/?badge=latest
《联邦学习实践》相关文档：https://github.com/FederatedAI/Practicing-Federated-Learning

FATE使用笔记（草稿可更新）

FATE使用笔记