如何使用 Kuscia API 运行一个 SecretFlow 作业

原创

隐语社区小迷弟

发布于 2025-11-10 16:42:23

940

打开链接点亮社区项目群Star，照亮技术的前进之路。每一个点赞，都是社区技术大佬前进的动力

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

准备节点

准备节点请参考快速入门。

本示例在中心化组网模式下完成。在点对点组网模式下，证书的配置会有所不同。

{#cert-and-token}

确认证书和 Token

Kuscia API 使用双向 HTTPS，所以需要配置您的客户端库的双向 HTTPS 配置。

中心化组网模式

证书文件在 ${USER}-kuscia-master 节点的 /home/kuscia/var/certs/ 目录下：

文件名	文件功能
kusciaapi-server.key	服务端私钥文件
kusciaapi-server.crt	服务端证书文件
ca.crt	CA 证书文件
token	认证 Token ，在 headers 中添加 Token: { token 文件内容}

点对点组网模式

证书的配置参考配置授权

这里以 Alice 节点为例，接口需要的证书文件在 ${USER}-kuscia-autonomy-alice 节点的 /home/kuscia/var/certs/ 目录下：

文件名	文件功能
kusciaapi-server.key	服务端私钥文件
kusciaapi-server.crt	服务端证书文件
ca.crt	CA 证书文件
token	认证 Token ，在 headers 中添加 Token: { token 文件内容}

同时，还要保证节点间的授权证书配置正确，Alice 节点和 Bob 节点要完成授权的建立，否则双方无法共同参与计算任务。

准备数据

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

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

{#kuscia}

查看 Kuscia 示例数据

这里以 Alice 节点为例，首先进入节点容器：

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

在 Alice 节点容器中查看节点示例数据：

cat /home/kuscia/var/storage/data/alice.csv

Bob 节点同理。

{#prepare-your-own-data}

准备您自己的数据

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

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

然后，您还需要参考Kuscia API给新的数据文件创建 domaindata。

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

{#configure-kuscia-job}

配置 KusciaJob

我们需要在 kuscia-master 节点容器中配置和运行 Job，首先，让我们先进入 kuscia-master 节点容器：

docker exec -it ${USER}-kuscia-master bash

如果是点对点组网模式，则需要进入任务发起方节点容器，以 Alice 节点为例：

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

注意，您只能向已和 Alice 节点建立了授权的节点发布计算任务。

使用 Kuscia 示例数据配置 KusciaJob

此处以KusciaJob 示例作为任务示例展示，该任务流完成 2 个任务：

job-psi 读取 Alice 和 Bob 的数据文件，进行隐私求交，求交的结果分别保存为两个参与方的 psi-output.csv。
job-split 读取 Alice 和 Bob 上一步中求交的结果文件，并拆分成训练集和测试集，分别保存为两个参与方的 train-dataset.csv、test-dataset.csv。

这个 KusciaJob 的名称为 job-best-effort-linear，在一个 Kuscia 集群中，这个名称必须是唯一的，由 job_id 指定。

我们请求创建 Job 接口来创建并运行这个 KusciaJob。

具体字段数据格式和含义请参考创建 Job ，本文不再赘述。

如果您成功了，您将得到如下返回：

{ "status": { "code": 0, "message": "success", "details": [] }, "data": { "job_id": "job-best-effort-linear" } }

恭喜，这说明 KusciaJob 已经成功创建并运行。

如果遇到 HTTP 错误（即 HTTP Code 不为 200），请参考 HTTP Error Code 处理。

使用您自己的数据配置 KusciaJob

如果您要使用您自己的数据，可以将两个算子中的 taskInputConfig.sf_input_ids 的数据文件 id 修改为您在准备您自己的数据中的 domaindata_id 即可。

查看 KusciaJob 运行状态

{#job-query}

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

job-best-effort-linear 是您在配置 Job 中指定的 KusciaJob 的名称。

我们请求批量查询 Job 状态接口来批量查询 KusciaJob

的状态。

请求参数 job_ids 是一个 ArrayString ，需要列出所有待查询的 KusciaJob 名称。

curl -k -X POST 'https://localhost:8082/api/v1/job/status/batchQuery' \
--header "Token: $(cat /home/kuscia/var/certs/token)" \
--header 'Content-Type: application/json' \
--cert '/home/kuscia/var/certs/kusciaapi-server.crt' \
--key '/home/kuscia/var/certs/kusciaapi-server.key' \
--cacert '/home/kuscia/var/certs/ca.crt' \
-d '{
    "job_ids": ["job-best-effort-linear"]
}'

如果任务成功了，您可以得到如下返回：

{
  "status": {
    "code": 0,
    "message": "success",
    "details": []
  },
  "data": {
    "jobs": [
      {
        "job_id": "job-best-effort-linear",
        "status": {
          "state": "Succeeded",
          "err_msg": "",
          "create_time": "2023-07-27T01:55:46Z",
          "start_time": "2023-07-27T01:55:46Z",
          "end_time": "2023-07-27T01:56:19Z",
          "tasks": [
            {
              "task_id": "job-psi",
              "state": "Succeeded",
              "err_msg": "",
              "create_time": "2023-07-27T01:55:46Z",
              "start_time": "2023-07-27T01:55:46Z",
              "end_time": "2023-07-27T01:56:05Z",
              "parties": [
                {
                  "domain_id": "alice",
                  "state": "Succeeded",
                  "err_msg": "",
                  "endpoints": [
                    {
                      "port_name": "spu",
                      "scope": "Cluster",
                      "endpoint": "job-psi-0-spu.alice.svc"
                    },
                    {
                      "port_name": "fed",
                      "scope": "Cluster",
                      "endpoint": "job-psi-0-fed.alice.svc"
                    },
                    {
                      "port_name": "global",
                      "scope": "Domain",
                      "endpoint": "job-psi-0-global.alice.svc:8081"
                    }
                  ]
                },
                {
                  "domain_id": "bob",
                  "state": "Succeeded",
                  "err_msg": "",
                  "endpoints": [
                    {
                      "port_name": "fed",
                      "scope": "Cluster",
                      "endpoint": "job-psi-0-fed.bob.svc"
                    },
                    {
                      "port_name": "global",
                      "scope": "Domain",
                      "endpoint": "job-psi-0-global.bob.svc:8081"
                    },
                    {
                      "port_name": "spu",
                      "scope": "Cluster",
                      "endpoint": "job-psi-0-spu.bob.svc"
                    }
                  ]
                }
              ]
            },
            {
              "task_id": "job-split",
              "state": "Succeeded",
              "err_msg": "",
              "create_time": "2023-07-27T01:56:05Z",
              "start_time": "2023-07-27T01:56:05Z",
              "end_time": "2023-07-27T01:56:19Z",
              "parties": [
                {
                  "domain_id": "alice",
                  "state": "Succeeded",
                  "err_msg": "",
                  "endpoints": [
                    {
                      "port_name": "spu",
                      "scope": "Cluster",
                      "endpoint": "job-split-0-spu.alice.svc"
                    },
                    {
                      "port_name": "fed",
                      "scope": "Cluster",
                      "endpoint": "job-split-0-fed.alice.svc"
                    },
                    {
                      "port_name": "global",
                      "scope": "Domain",
                      "endpoint": "job-split-0-global.alice.svc:8081"
                    }
                  ]
                },
                {
                  "domain_id": "bob",
                  "state": "Succeeded",
                  "err_msg": "",
                  "endpoints": [
                    {
                      "port_name": "fed",
                      "scope": "Cluster",
                      "endpoint": "job-psi-0-fed.bob.svc"
                    },
                    {
                      "port_name": "global",
                      "scope": "Domain",
                      "endpoint": "job-psi-0-global.bob.svc:8081"
                    },
                    {
                      "port_name": "spu",
                      "scope": "Cluster",
                      "endpoint": "job-psi-0-spu.bob.svc"
                    }
                  ]
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

data.jobs.status.state 字段记录了 KusciaJob 的运行状态，data.jobs.status.tasks.state 则记录了每个 KusciaTask 的运行状态。

详细信息请参考 KusciaJob

和批量查询 Job 状态

删除 KusciaJob

当您想清理这个 KusciaJob 时，我们请求删除 Job 接口来删除这个

KusciaJob.

curl -k -X POST 'https://localhost:8082/api/v1/job/delete' \
--header "Token: $(cat /home/kuscia/var/certs/token)" \
--header 'Content-Type: application/json' \
--cert '/home/kuscia/var/certs/kusciaapi-server.crt' \
--key '/home/kuscia/var/certs/kusciaapi-server.key' \
--cacert '/home/kuscia/var/certs/ca.crt' \
-d '{
    "job_id": "job-best-effort-linear"
}'

如果任务成功了，您可以得到如下返回：

{ "status": { "code": 0, "message": "success", "details": [] }, "data": { "job_id": "job-best-effort-linear" } }

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

{#input-config}

算子参数描述

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

对于 secretflow ，请参考：Secretflow 官网。

{#http-client-error}

HTTP 客户端错误处理

curl: (56)

curl: (56) OpenSSL SSL_read: error:14094412:SSL routines:ssl3_read_bytes:sslv3 alert bad certificate, errno 0

未配置 SSL 证书和私钥。请确认证书和 Token.

curl: (58)

curl: (58) unable to set XXX file

SSL 私钥、 SSL 证书或 CA 证书文件路径错误。请确认证书和 Token.

{#http-error-code}

HTTP Error Code 处理

401 Unauthorized

身份认证失败。请检查是否在 Headers 中配置了正确的 Token 。 Token 内容详见确认证书和 Token.

404 Page Not Found

接口 path 错误。请检查请求的 path 是否和文档中的一致。必要时可以提 issue 询问。

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

云开发

任务调度

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

云开发

任务调度

登录后参与评论

0 条评论

热度