集群间模型迁移¶

模型迁移功能使得模型文件复制拷贝到不同party_id的集群依然可用，以下两种场景需要做模型迁移：

模型生成参与方任何一方的集群, 重新部署且部署后集群的party_id变更, 例如源参与方为arbiter-10000#guest-9999#host-10000, 改为arbiter-10000#guest-99#host-10000
其中任意一个或多个参与方将模型文件从源集群复制到目标集群，需要在目标集群使用

基本原理： 1. 上述两种场景下，模型的参与方party_id会发生改变，如arbiter-10000#guest-9999#host-10000 -> arbiter-10000#guest-99#host-10000，或者arbiter-10000#guest-9999#host-10000 -> arbiter-100#guest-99#host-100 2. 模型的参与方party_id发生改变，因此model_id以及模型文件里面涉及party_id需要改变 3. 整体流程下来，有三个步骤：复制转移原有模型文件、对原有模型文件执行模型迁移任务、导入模型迁移任务生成的新模型 4. 其中*原有模型文件执行模型迁移任务*其实就是在执行处临时复制一份原模型文件，然后按照配置，修改model_id及模型文件里面涉及party_id的内容，以适配新的参与方party_id 5. 上述步骤都需要在所有新的参与方执行，即使其中某个目标参与方的party_id没有改变，也需要执行 6. 新的参与方集群版本需大于等于1.5.1

迁移流程如下：

转移模型文件¶

请将源参与方fate flow服务所在机器生成的模型文件（包括以model id为命名的目录）进行打包并转移到目标参与方fate flow所在机器中，请将模型文件转移至固定目录中：

$FATE_PROJECT_BASE/model_local_cache

说明: 1. 文件夹转移即可，如果是通过压缩打包进行的转移，请在转移后将模型文件解压到模型所在目录中。 2. 模型文件请按源目参与方一一对应转移

迁移前的准备工作¶

说明¶

参考fate flow client安装支持模型迁移的客户端fate-client，只有fate 1.5.1及其以上版本支持

执行迁移任务¶

说明¶

执行迁移任务是将源模型文件根据迁移任务配置文件修改model_id、model_version以及模型内涉及role和party_id的内容进行替换
提交任务的集群必须完成上述迁移准备

1. 修改配置文件¶

在新参与方（机器）中根据实际情况对迁移任务的配置文件进行修改，如下为迁移任务示例配置文件 migrate_model.json

{
  "job_parameters": {
    "federated_mode": "SINGLE"
  },
  "role": {
    "guest": [9999],
    "arbiter": [10000],
    "host": [10000]
  },
  "migrate_initiator": {
    "role": "guest",
    "party_id": 99
  },
  "migrate_role": {
    "guest": [99],
    "arbiter": [100],
    "host": [100]
  },
  "execute_party": {
    "guest": [9999],
    "arbiter": [10000],
    "host": [10000]
  },
  "model_id": "arbiter-10000#guest-9999#host-10000#model",
  "model_version": "202006171904247702041",
  "unify_model_version": "20200901_0001"
}

请将上述配置内容保存到服务器中的某一位置进行修改。

以下为对该配置中的参数的解释说明：

job_parameters：该参数中的federated_mode有两个可选参数，分别为MULTIPLE 及SINGLE。如果设置为SINGLE，则该迁移任务只会在提交迁移任务的本方执行，那么需要分别在所有新参与方提交任务;如果设置为MULTIPLE，则将任务分发到execute_party中指定的参与方执行任务，只需要在作为migrate_initiator的新参与方提交。
role：该参数填写生成原始模型的参与方role及其对应的party_id信息。
migrate_initiator：该参数用于指定迁移后的模型的任务发起方信息，分别需指定发起方的role与party_id。
migrate_role：该参数用于指定迁移后的模型的参与方role及party_id信息。
execute_party：该参数用于指定需要执行迁移的role及party_id信息, 该party_id为源集群party_id。
model_id：该参数用于指定需要被迁移的原始模型的model_id。
model_version：该参数用于指定需要被迁移的原始模型的model_version。
unify_model_version：此参数为非必填参数，该参数用于指定新模型的model_version。若未提供该参数，新模型将以迁移任务的job_id作为其新model_version。

上述配置文件举例说明： 1. 源模型的参与方为guest: 9999, host: 10000, arbiter: 10000, 将模型迁移成参与方为guest: 99, host: 100, arbiter: 100, 且新发起方为guest: 99 2. federated_mode: SINGLE 表示每个迁移任务只在提交任务的集群执行任务，那么需要在99、100分别提交任务 3. 例如在99执行，则execute_party配置为"guest": [9999] 4. 例如在100执行，则execute_party配置为"arbiter": [10000], "host": [10000]

2. 提交迁移任务(在所有目标集群分别操作)¶

迁移任务需使用fate-client进行提交，示例执行命令如下：

flow model migrate -c $FATE_FLOW_BASE/examples/model/migrate_model.json

3. 任务执行结果¶

如下为实际迁移任务的配置文件内容：

{
  "job_parameters": {
    "federated_mode": "SINGLE"
  },
  "role": {
    "guest": [9999],
    "host": [10000]
  },
  "migrate_initiator": {
    "role": "guest",
    "party_id": 99
  },
  "migrate_role": {
    "guest": [99],
    "host": [100]
  },
  "execute_party": {
    "guest": [9999],
    "host": [10000]
  },
  "model_id": "guest-9999#host-10000#model",
  "model_version": "202010291539339602784",
  "unify_model_version": "fate_migration"
}

该任务实现的是，将party_id为9999 (guest)，10000 (host)的集群生成的model_id为guest-9999#host-10000#model，model_version为202010291539339602784的模型修改迁移生成适配party_id为99 (guest)，100 (host)集群的新模型

如下为迁移成功的后得到的返回结果：

{
    "data": {
        "detail": {
            "guest": {
                "9999": {
                    "retcode": 0,
                    "retmsg": "Migrating model successfully. The configuration of model has been modified automatically. New model id is: guest-99#host-100#model, model version is: fate_migration. Model files can be found at '/data/projects/fate/temp/fate_flow/guest#99#guest-99#host-100#model_fate_migration.zip'."
                }
            },
            "host": {
                "10000": {
                    "retcode": 0,
                    "retmsg": "Migrating model successfully. The configuration of model has been modified automatically. New model id is: guest-99#host-100#model, model version is: fate_migration. Model files can be found at '/data/projects/fate/temp/fate_flow/host#100#guest-99#host-100#model_fate_migration.zip'."
                }
            }
        },
        "guest": {
            "9999": 0
        },
        "host": {
            "10000": 0
        }
    },
    "jobId": "202010292152299793981",
    "retcode": 0,
    "retmsg": "success"
}

任务成功执行后，执行方的机器中都会生成一份迁移后模型压缩文件，该文件路径可以在返回结果中得到。如上，9999 (guest)的迁移后模型文件路径为：/data/projects/fate/temp/fate_flow/guest#99#guest-99#host-100#model_fate_migration.zip，10000 (host)的迁移后模型文件路径为：/data/projects/fate/temp/fate_flow/host#100#guest-99#host-100#model_fate_migration.zip。新的model_id与model_version同样可以从返回中获得。

4. 转移文件并导入(在所有目标集群分别操作)¶

迁移任务成功之后，请手动将新生成的模型压缩文件转移到目标集群的fate flow机器上。例如：第三点中9999 (guest)生成的新模型压缩文件需要被转移到99 (guest) 机器上。压缩文件可以放在对应机器上的任意位置，接下来需要配置模型的导入任务，配置文件请见import_model.json（压缩文件内包含此配置文件，请根据实际情况修改，切勿直接使用）。

下面举例介绍在guest (99)中导入迁移后模型的配置文件：

{
  "role": "guest",
  "party_id": 99,
  "model_id": "guest-99#host-100#model",
  "model_version": "202010292152299793981",
  "file": "/data/projects/fate/python/temp/guest#99#guest-99#host-100#202010292152299793981.zip"
}

请根据实际情况对应填写角色role，当前本方party_id，迁移模型的新model_id及model_version，以及迁移模型的压缩文件所在路径。

如下为使用fate-client提交导入模型的示例命令：

flow model import -c $FATE_FLOW_BASE/examples/model/import_model.json

得到如下返回视为导入成功：

{
  "data": {
    "job_id": "202208261102212849780",
    "model_id": "arbiter-10000#guest-9999#host-10000#model",
    "model_version": "foobar",
    "party_id": "9999",
    "role": "guest"
  },
  "retcode": 0,
  "retmsg": "success"
}

迁移任务至此完成，用户可使用新的model_id及model_version进行任务提交，以利用迁移后的模型执行预测任务。