博客 / 詳情

返回

如何使用 Kuscia API 運行一個 SecretFlow 作業

打開鏈接點亮社區項目羣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 個任務：

  1. job-psi 讀取 Alice 和 Bob 的數據文件，進行隱私求交，求交的結果分別保存為兩個參與方的 psi-output.csv。
  2. 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 配置的信息，請查看 KusciaJob 和算子參數描述 。
前者描述了 KusciaJob 的定義和相關説明，後者描述了支持的算子和參數。

查看 KusciaJob 運行狀態

{#job-query}

查看運行中的 KusciaJob 的詳細狀態

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

我們請求批量查詢 Job 狀態接口來批量查詢 KusciaJob
的狀態。

請求參數 job_ids 是一個 Array[String] ，需要列出所有待查詢的 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 詢問。

調度器 , 隱私 , 數據 , 開源
user avatar footprint_analytics 頭像 lvxingzhongdemaojin_clive7 頭像
2 位用戶收藏了這個故事！

發佈 評論

Some HTML is okay.