打开链接点亮社区项目群 Star，照亮技术的前进之路。每一个点赞，都是社区技术大佬前进的动力
Github 地址： https://github.com/secretflow
准备节点
准备节点请参考快速入门。
本示例在中心化组网模式下完成。在点对点组网模式下，证书的配置会有所不同。
{#cert-and-token}
确认证书和 Token
Kuscia API 使用双向 HTTPS，所以需要配置您的客户端库的双向 HTTPS 配置。
中心化组网模式
证书文件在 ${USER}-kuscia-master 节点的 /home/kuscia/var/certs/ 目录下：
点对点组网模式
证书的配置参考配置授权
这里以 Alice 节点为例，接口需要的证书文件在 ${USER}-kuscia-autonomy-alice 节点的 /home/kuscia/var/certs/ 目录下：
同时，还要保证节点间的授权证书配置正确，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 配置的信息，请查看 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 询问。
评论