FATE使用笔记

梁骞仕

2023-12-01

一、上传数据

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.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.5.0以前的FATE适用V1规则
版本1.5.0以后的FATE适用V2规则，可兼容V1

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

2.1 DSL 配置文件

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

//xxxx_dsl.json
{
  "components" : { 
		  "reader_0": {
		      "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

2.1.1 DataIO

"dataio_0": {
      "module": "DataIO",
      "input": {
          "data": {
              "data": [
                  "args.train_data"
              ]
          }
      },
      "output": {
          "data": ["train"],
          "model": ["dataio"]
      },
      "need_deploy": true
  }

2.2 运行配置 Submit Runtime Conf

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

内容包括如下：

2.2.1 dsl_version（V2）

"dsl_version": "2"

2.2.2 initiator（V1、V2）

任务发起方

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

2.2.3 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阶段中。

2.2.4 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": {
      ...
   }
   ...
 }

2.2.5 algorithm_parameters（V1)

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

2.2.6 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

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

三、预测任务

提交训练任务后会得到一个包含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"
    }

我们需要提供一个predict conf，和一个predict dsl文件
使用flow_client来部署预测任务中需要的组件

flow model deploy --model-id guest-10000#host-10000#model --model-version 2020103015490073208469 --cpn-list "dataio_0, intersection_0, hetero_secure_boost_0"
//--cpn-list =component list,预测任务需要用到的组件

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

//predict_conf.json
{
    "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

参考资料

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