如何运行一个互联互通银联 BFIA 协议作业

打开链接即可点亮社区Star，照亮技术的前进之路。

Github 地址：https://github.com/secretflow/kuscia

Tips：由于内部 Kuscia P2P 协议升级，当前版本暂不支持银联 BFIA 协议，适配银联 BFIA 正在进行中。

若您使用第三方算法镜像提交互联互通作业，强烈建议您检查镜像安全性。

本教程以秘密分享-逻辑回归（SS-LR）算子为示例，介绍如何通过互联互通银联 BFIA（Beijing FinTech Industry Alliance 北京金融科技产业联盟）协议运行一个包含两方任务的作业。

在本教程中，通过两个 Kuscia Autonomy 节点来模拟不同框架底座的节点。在这两个节点之间，通过互联互通银联 BFIA 协议运行一个包含两方任务的作业。

准备环境

准备运行银联 BFIA 协议的节点

部署运行银联 BFIA 协议的节点，请参考快速入门点对点组网模式。

在执行启动集群命令时，需要新增一个命令行参数-p bfia，详细命令如下：

# Start the cluster, which will launch two docker containers, representing the Autonomy nodes alice and bob.
./kuscia.sh p2p -P bfia -a none

准备工具脚本

docker cp ${USER}-kuscia-autonomy-alice:/home/kuscia/scripts/user/bfia/ .

准备秘密分享-逻辑回归（SS-LR）算子镜像

准备 Alice 节点中算子镜像

./bfia/prepare_ss_lr_image.sh -k ${USER}-kuscia-autonomy-alice

准备 Bob 节点中算子镜像

./bfia/prepare_ss_lr_image.sh -k ${USER}-kuscia-autonomy-bob

工具帮助信息
```
./bfia/prepare_ss_lr_image.sh -h
```

部署 TTP Server 服务

因为秘密分享-逻辑回归（SS-LR）算子依赖一个可信第三方 TTP（Trusted Third Party）Server，所以本教程使用本地 Docker 容器的方式和运行银联 BFIA 协议的节点容器部署在同一套环境中，从而方便快速搭建运行互联互通银联 BFIA 协议作业的体验环境。

部署 TTP Server 服务
```
./bfia/deploy_ttp_server.sh
```
工具帮助信息
```
./bfia/deploy_ttp_server.sh -h
```

准备数据

您可以使用 Kuscia 中自带的数据文件，或者使用您自己的数据文件。

在 Kuscia 中，节点数据文件的存放路径为节点容器的 /home/kuscia/var/storage，您可以在容器中查看这个数据文件。

查看 Kuscia 示例数据

查看 Alice 节点示例数据

docker exec -it ${USER}-kuscia-autonomy-alice more /home/kuscia/var/storage/data/perfect_logit_a.csv

查看 Bob 节点示例数据

docker exec -it ${USER}-kuscia-autonomy-bob more /home/kuscia/var/storage/data/perfect_logit_b.csv

准备您自己的数据

您也可以使用您自己的数据文件，首先您要将数据文件复制到节点容器中，以 Alice 节点为例：

docker cp {your_alice_data} ${USER}-kuscia-autonomy-alice:/home/kuscia/var/storage/data/

接下来您可以像查看 Kuscia 示例数据一样查看您的数据文件，这里不再赘述。

提交一个银联 BFIA 协议的作业

目前在 Kuscia 中有两种方式提交银联 BFIA 协议的作业

通过配置 KusciaJob 提交作业
通过银联 BFIA 协议创建作业 API 接口提交作业

通过配置 KusciaJob 提交作业

数据准备好之后，我们将 alice 作为任务发起方，进入 alice 节点容器中，然后配置和运行作业。

docker exec -it ${USER}-kuscia-autonomy-alice bash

使用 Kuscia 示例数据配置 KusciaJob

下面的示例展示了一个 KusciaJob，该作业包含 1 个任务

算子通过读取 alice 和 bob 的数据文件，完成秘密分享逻辑回归任务。
KusciaJob 的名称为 job-ss-lr，在一个 Kuscia 集群中，这个名称必须是唯一的，由 .metadata.name 指定。

在 Alice 容器中，创建文件 job-ss-lr.yaml，内容如下：

apiVersion: kuscia.secretflow/v1alpha1
kind: KusciaJob
metadata:
  name: job-ss-lr
  namespace: cross-domain
spec:
  initiator: alice
  tasks:
  - alias: ss_lr_1
    appImage: ss-lr
    parties:
    - domainID: alice
      role: host
    - domainID: bob
      role: guest
    taskInputConfig: '{"name":"ss_lr_1","module_name":"ss_lr","output":[{"type":"dataset","key":"result"}],"role":{"host":["alice"],"guest":["bob"]},"initiator":{"role":"host","node_id":"alice"},"task_params":{"host":{"0":{"has_label":true,"name":"perfect_logit_a.csv","namespace":"data"}},"guest":{"0":{"has_label":false,"name":"perfect_logit_b.csv","namespace":"data"}},"common":{"skip_rows":1,"algo":"ss_lr","protocol_families":"ss","batch_size":21,"last_batch_policy":"discard","num_epoch":1,"l0_norm":0,"l1_norm":0,"l2_norm":0.5,"optimizer":"sgd","learning_rate":0.0001,"sigmoid_mode":"minimax_1","protocol":"semi2k","field":64,"fxp_bits":18,"trunc_mode":"probabilistic","shard_serialize_format":"raw","use_ttp":true,"ttp_server_host":"ttp-server:9449","ttp_session_id":"interconnection-root","ttp_adjust_rank":0}}}'
    tolerable: false

算子参数描述

KusciaJob 中算子参数由 taskInputConfig 字段定义，对于不同的算子，算子的参数不同

秘密分享-逻辑回归（SS-LR）算子相关信息可参考 SS-LR 参考实现
本教程秘密分享-逻辑回归（SS-LR）算子对应的 KusciaJob TaskInputConfig 结构可参考 TaskInputConfig 结构示例

提交 KusciaJob

现在已经配置好了一个 KusciaJob，接下来，让运行以下命令提交这个 KusciaJob。

kubectl apply -f job-ss-lr.yaml

通过银联 BFIA 协议 API 接口提交作业

数据准备好之后，将 Alice 作为任务发起方，进入 Alice 节点容器中。

docker exec -it ${USER}-kuscia-autonomy-alice bash

下面使用银联 BFIA 协议创建作业接口提交作业，该作业会提交给 Kuscia 互联互通 InterConn 控制器，该控制器将银联 BFIA 协议规定的创建作业请求参数转化为 Kuscia 中的 KusciaJob 作业定义。
最后，InterConn 控制器在 Kuscia 中创建 KusciaJob 资源。

curl -v -X POST 'http://127.0.0.1:8084/v1/interconn/schedule/job/create' \
--header 'Content-Type: application/json' \
-d '{"job_id":"job-ss-lr","dag":{"version":"2.0.0","components":[{"code":"ss-lr","name":"ss_lr_1","module_name":"ss_lr","version":"v1.0.0","input":[],"output":[{"type":"dataset","key":"result"}]}]},"config":{"role":{"host":["alice"],"guest":["bob"]},"initiator":{"role":"host","node_id":"alice"},"job_params":{"host":{"0":{}},"guest":{"0":{}}},"task_params":{"host":{"0":{"ss_lr_1":{"name":"perfect_logit_a.csv","namespace":"data","has_label":true}}},"arbiter":{},"guest":{"0":{"ss_lr_1":{"name":"perfect_logit_b.csv","namespace":"data","has_label":false}}},"common":{"ss_lr_1":{"skip_rows":1,"algo":"ss_lr","protocol_families":"ss","batch_size":21,"last_batch_policy":"discard","num_epoch":1,"l0_norm":0,"l1_norm":0,"l2_norm":0.5,"optimizer":"sgd","learning_rate":0.0001,"sigmoid_mode":"minimax_1","protocol":"semi2k","field":64,"fxp_bits":18,"trunc_mode":"probabilistic","shard_serialize_format":"raw","use_ttp":true,"ttp_server_host":"ttp-server:9449","ttp_session_id":"interconnection-root","ttp_adjust_rank":0}}},"version":"2.0.0"}}'

提交作业接口请求参数内容结构请参考提交 SS-LR 作业接口请求内容示例。

{#get-kuscia-job-phase}

查看 KusciaJob 运行状态

在提交完 KusciaJob 作业后，我们可以在 alice 容器中通过下面的命令查看 Alice 方的 KusciaJob 的运行情况。
同样，也可以登陆到 bob 容器中查看 Bob 方的 KusciaJob 的运行情况。下面以 Alice 节点容器为例。

查看所有的 KusciaJob

kubectl get kj -n cross-domain

您可以看到如下输出：

NAME            STARTTIME   COMPLETIONTIME   LASTRECONCILETIME   PHASE
job-ss-lr       3s                           3s                  Running

job-ss-lr 就是刚刚创建出来的 KusciaJob。

查看运行中的 KusciaJob 的详细状态

通过指定 -o yaml 参数，能够以 Yaml 的形式看到 KusciaJob 的详细状态。job-ss-lr 是提交的作业名称。

kubectl get kj job-ss-lr -n cross-domain -o yaml

如果任务成功了，您可以看到如下输出：

apiVersion: kuscia.secretflow/v1alpha1
kind: KusciaJob
metadata:
  creationTimestamp: "2023-07-01T02:21:04Z"
  generation: 3
  labels:
    kuscia.secretflow/interconn-protocol-type: bfia
    kuscia.secretflow/self-cluster-as-initiator: "true"
  name: job-ss-lr
  namespace: cross-domain
  resourceVersion: "50438"
  uid: 408a03ae-69c2-4fa8-a638-b47b6dbf530f
spec:
  initiator: alice
  maxParallelism: 2
  scheduleMode: Strict
  stage: Start
  tasks:
  - alias: ss_lr_1
    appImage: ss-lr
    parties:
    - domainID: alice
      role: host
    - domainID: bob
      role: guest
    taskID: job-ss-lr-26e3489ac66e
    taskInputConfig: '{"name":"ss_lr_1","module_name":"ss_lr","output":[{"type":"dataset","key":"result"}],"role":{"host":["alice"],"guest":["bob"]},"initiator":{"role":"host","node_id":"alice"},"task_params":{"host":{"0":{"has_label":true,"name":"perfect_logit_a.csv","namespace":"data"}},"guest":{"0":{"has_label":false,"name":"perfect_logit_b.csv","namespace":"data"}},"common":{"algo":"ss_lr","batch_size":21,"field":64,"fxp_bits":18,"l0_norm":0,"l1_norm":0,"l2_norm":0.5,"last_batch_policy":"discard","learning_rate":0.0001,"num_epoch":1,"optimizer":"sgd","protocol":"semi2k","protocol_families":"ss","shard_serialize_format":"raw","sigmoid_mode":"minimax_1","skip_rows":1,"trunc_mode":"probabilistic","ttp_adjust_rank":0,"ttp_server_host":"ttp-server:9449","ttp_session_id":"interconnection-root","use_ttp":true}}}'
    tolerable: false
status:
  completionTime: "2023-07-01T02:21:14Z"
  conditions:
  - lastTransitionTime: "2023-07-01T02:21:04Z"
    status: "True"
    type: JobValidated
  - lastTransitionTime: "2023-07-01T02:21:04Z"
    status: "True"
    type: JobCreateInitialized
  - lastTransitionTime: "2023-07-01T02:21:04Z"
    status: "True"
    type: JobCreateSucceeded
  - lastTransitionTime: "2023-07-01T02:21:04Z"
    status: "True"
    type: JobStartInitialized
  - lastTransitionTime: "2023-07-01T02:21:04Z"
    status: "True"
    type: JobStartSucceeded
  lastReconcileTime: "2023-07-01T02:21:14Z"
  phase: Succeeded
  startTime: "2023-07-01T02:21:04Z"
  taskStatus:
    job-ss-lr-26e3489ac66e: Succeeded

status 字段记录了 KusciaJob 的运行状态，.status.phase 字段描述了 KusciaJob 的整体状态，而 .status.taskStatus 则描述了包含的 KusciaTask 的状态。
详细信息请参考 KusciaJob。

查看 KusciaJob 中 KusciaTask 的详细状态

KusciaJob 中的每一个 KusciaTask 都有一个 taskID，通过 taskID 我们可以查看 KusciaTask 的详细状态。

kubectl get kt job-ss-lr-26e3489ac66e -n cross-domain -o yaml

KusciaTask 的介绍，请参考 KusciaTask。

查看 SS-LR 算子运行结果

可以通过查看 KusciaJob 运行状态查询作业的运行状态。当作业状态 PHASE 变成 Succeeded 时，可以查看算子输出结果。

进入节点 Alice 或 Bob 容器
若已经在容器中，跳过该步骤

# Enter the alice node container
docker exec -it ${USER}-kuscia-autonomy-alice bash

# Enter the bob node container
docker exec -it ${USER}-kuscia-autonomy-bob bash

查看 KusciaJob 作业状态

kubectl get kj job-ss-lr -n cross-domain
NAME        STARTTIME   COMPLETIONTIME   LASTRECONCILETIME   PHASE
job-ss-lr   13s         2s               2s                  Succeeded

查看 SS-LR 算子输出结果

输出内容表示 SS-LR 算子权重向量的密态分片

# View the output result in the alice container
more /home/kuscia/var/storage/job-ss-lr-host-0/job-ss-lr-{random-id}-result

# View the output result in the bob container
more /home/kuscia/var/storage/job-ss-lr-guest-0/job-ss-lr-{random-id}-result

删除 KusciaJob

当您想清理这个 KusciaJob 时，您可以通过下面的命令完成：

kubectl delete kj job-ss-lr -n cross-domain

当这个 KusciaJob 被清理时，这个 KusciaJob 创建的 KusciaTask 也会一起被清理。

参考

{#ss-lr-task-input-config}

SS-LR 算子对应的 TaskInputConfig 结构示例

{
  "name": "ss_lr_1",
  "module_name": "ss_lr",
  "input":[],
  "output": [{
    "type": "dataset",
    "key": "result"
  }],
  "role": {
    "host": ["alice"],
    "guest": ["bob"]
  },
  "initiator": {
    "role": "host",
    "node_id": "alice"
  },
  "task_params": {
    "host": {
      "0": {
        "has_label": true,
        "name": "perfect_logit_a.csv",
        "namespace": "data"
      }
    },
    "guest": {
      "0": {
        "has_label": false,
        "name": "perfect_logit_b.csv",
        "namespace": "data"
      }
    },
    "common": {
      "skip_rows": 1,
      "algo": "ss_lr",
      "protocol_families": "ss",
      "batch_size": 21,
      "last_batch_policy": "discard",
      "num_epoch": 1,
      "l0_norm": 0,
      "l1_norm": 0,
      "l2_norm": 0.5,
      "optimizer": "sgd",
      "learning_rate": 0.0001,
      "sigmoid_mode": "minimax_1",
      "protocol": "semi2k",
      "field": 64,
      "fxp_bits": 18,
      "trunc_mode": "probabilistic",
      "shard_serialize_format": "raw",
      "use_ttp": true,
      "ttp_server_host": "ttp-server:9449",
      "ttp_session_id": "interconnection-root",
      "ttp_adjust_rank": 0
    }
  }
}

字段说明

name 描述了任务算子的名称。
module_name 描述了任务算子所属模块名称。
input 描述了任务算子的输入，若任务不依赖其他任务的输出，则可以将该项置为空。
output 描述了任务算子的输出。
role 描述了任务的角色。
initiator 描述了任务发起方的信息。
task_params 描述了任务算子依赖的参数。

提交 SS-LR 作业接口请求内容示例

{
  "job_id": "job-ss-lr",
  "dag": {
    "version": "2.0.0",
    "components": [{
      "code": "ss-lr",
      "name": "ss_lr_1",
      "module_name": "ss_lr",
      "version": "v1.0.0",
      "input": [],
      "output": [{
        "type": "dataset",
        "key": "result"
      }]
    }]
  },
  "config": {
    "role": {
      "host": ["alice"],
      "guest": ["bob"]
    },
    "initiator": {
      "role": "host",
      "node_id": "alice"
    },
    "job_params": {
      "host": {
        "0": {}
      },
      "guest": {
        "0": {}
      }
    },
    "task_params": {
      "host": {
        "0": {
          "ss_lr_1": {
            "name": "perfect_logit_a.csv",
            "namespace": "data",
            "has_label": true
          }
        }
      },
      "arbiter": {},
      "guest": {
        "0": {
          "ss_lr_1": {
            "name": "perfect_logit_b.csv",
            "namespace": "data",
            "has_label": false
          }
        }
      },
      "common": {
        "ss_lr_1": {
          "skip_rows": 1,
          "algo": "ss_lr",
          "protocol_families": "ss",
          "batch_size": 21,
          "last_batch_policy": "discard",
          "num_epoch": 1,
          "l0_norm": 0,
          "l1_norm": 0,
          "l2_norm": 0.5,
          "optimizer": "sgd",
          "learning_rate": 0.0001,
          "sigmoid_mode": "minimax_1",
          "protocol": "semi2k",
          "field": 64,
          "fxp_bits": 18,
          "trunc_mode": "probabilistic",
          "shard_serialize_format": "raw",
          "use_ttp": true,
          "ttp_server_host": "ttp-server:9449",
          "ttp_session_id": "interconnection-root",
          "ttp_adjust_rank": 0
        }
      }
    },
    "version": "2.0.0"
  }
}

字段说明

job_id 描述了作业的标识。
dag 描述了作业的组件之间组合的配置。
config 描述了作业运行时的参数配置。

posted @ 2025-12-09 11:17 隐语开源社区阅读(8) 评论(0) 收藏举报

刷新页面返回顶部

如何运行一个互联互通银联 BFIA 协议作业

准备环境

准备运行银联 BFIA 协议的节点

准备工具脚本

准备秘密分享-逻辑回归（SS-LR）算子镜像

部署 TTP Server 服务

准备数据

查看 Kuscia 示例数据

查看 Alice 节点示例数据

查看 Bob 节点示例数据

准备您自己的数据

提交一个银联 BFIA 协议的作业

通过配置 KusciaJob 提交作业

使用 Kuscia 示例数据配置 KusciaJob

算子参数描述

提交 KusciaJob

通过银联 BFIA 协议 API 接口提交作业

查看 KusciaJob 运行状态

查看所有的 KusciaJob

查看运行中的 KusciaJob 的详细状态

查看 KusciaJob 中 KusciaTask 的详细状态

查看 SS-LR 算子运行结果

删除 KusciaJob

参考

SS-LR 算子对应的 TaskInputConfig 结构示例

提交 SS-LR 作业接口请求内容示例

字段说明

公告