构建您自己的瘦客户端

概述

瘦客户端和 cli 提供了访问 cuOpt 服务的便利性，但这些仅是如何与 cuOpt 服务通信的参考示例。如果您希望创建自己的瘦客户端，下面将讨论 API 的底层细节。

注意

请不要使用 cuopt_thin_client.py 或 cuopt_service_client.py 作为您的瘦客户端名称，只是为了避免在您从 pypi 安装了 cuopt 瘦客户端时造成混淆。

API 授权

一旦您拥有 NVIDIA 身份联合 API 密钥，您可以在后续对 cuOpt 服务的请求中将其在 Authorization 标头中传递。

列出 cuOpt 版本

cuOpt 管理员代表客户端创建函数，可以列出这些版本，以便可以选择最新/合适的版本。

示例

curl --request GET https://api.nvcf.nvidia.com/v2/nvcf/functions
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <NVIDIA Identity Federation API Key>'

这将获取可用的 cuOpt 版本列表，客户端可以根据创建日期选择 cuOpt 版本。

响应将如下所示

{
 "functions": [
     {
         "id": "649b46a7-f65d-4943-873f-920bfe37ae66",
         "versionId": "b9957f66-4e1d-4957-8ab8-cf472e3a0f5b",
         ...
         ...
         ...
         "createdAt": "2023-08-14T12:16:32.116Z"
     }
   ]
 }

id 和 versionId 将用于调用 cuOpt 函数。

调用 cuOpt 服务

当有效负载 <= 250KB 时发送 cuOpt 请求

此方法用于执行 cuOpt 函数。requestBody 包含一个 JSON 对象，该对象将由 cuOpt 处理。

您必须在 URL 中包含函数 ID 和版本 ID，如下所示；这标识要调用的特定函数。

带有函数版本 ID 的示例

curl --location 'https://api.nvcf.nvidia.com/v2/nvcf/pexec/functions/{id}/versions/{versionId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <NVIDIA Identity Federation API Key>' \
--data '{
        "data": {
          "cost_matrix_data": {"data": {"0": [[0, 1], [1, 0]]}},
          "task_data": {"task_locations": [1], "demand": [[1]], "task_time_windows": [[0, 10]], "service_times": [1]},
          "fleet_data": {"vehicle_locations":[[0, 0]], "capacities": [[2]], "vehicle_time_windows":[[0, 20]] },
          "solver_config": {"time_limit": 2}
        },
        "client_version": "custom"
    }
}'

JSON_DATA 应遵循为 cuOpt 输入描述的 Open-API 规范。

当有效负载 > 250KB 时发送 cuOpt 请求

requestBody 的最大大小为 250KB。如果 JSON_DATA 的大小大于 250KB，则需要先单独上传，并在请求中引用返回的资产 ID。cuOpt 将根据 ID 获取资产并进行处理。

示例

curl -X 'POST' \
'https://api.nvcf.nvidia.com/v2/nvcf/assets' \
-H 'Authorization: Bearer <NVIDIA Identity Federation API Key>' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"contentType": "application/octet-stream",
"description": "Optimization-data"
}'

这将导致如下所示的响应，其中包含 assetId 和用于将数据推送到 uploadUrl 的地址

{
    "assetId":"b5b841c3-11c2-4c34-b057-9475e82c5369",
    "uploadUrl":"<pre-signed-upload-url>",
    "contentType":"application/octet-stream",
    "description":"Optimization-data"
}

压缩 JSON 数据。

import msgpack

pickled_cuopt_data = msgpack.dump(cuopt_problem_json_data, open('problem_data.mpk', 'wb'))

将压缩后的资产上传到云端。

curl -X PUT -T problem_data.mpk "<pre-signed-URL>" -H "Content-Type: application/octet-stream" -H "x-amz-meta-nvcf-asset-description: Optimization-data"

列出资产

curl -X GET https://api.nvcf.nvidia.com/v2/nvcf/assets -H "Authorization: Bearer <NVIDIA Identity Federation API Key>"

在调用函数时引用资产

要在函数调用中使用资产，请添加一个 requestHeader 字段，如下所示。请注意，inputAssetReferences 的值在技术上可以是列表，但 cuOpt 仅期望单个 assetId。由于 cuOpt 数据已作为资产上传，请将 requestBody 设置为 {}。

curl --location 'https://api.nvcf.nvidia.com/v2/nvcf/pexec/functions/{id}/versions/{versionId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <NVIDIA Identity Federation API Key>' \
--header 'NVCF-INPUT-ASSET-REFERENCES: <assetID>' \
--data '{
    "data": null,
    "client_version": "custom"
}'

删除资产

资产应在您完成处理后删除；但是，它们将被自动垃圾回收。

curl -X DELETE https://api.nvcf.nvidia.com/v2/nvcf/assets/{assetId} -H "Authorization: Bearer <NVIDIA Identity Federation API Key>"

cuOpt 结果检索

cuOpt 服务采用 长轮询 进行调用和结果检索。

当您发出调用请求时，系统将保持您的请求打开一段时间，然后返回以下内容之一

• HTTP 状态 200 已完成结果

• HTTP 状态 202 轮询响应

收到轮询响应后，您的客户端应立即轮询 cuOpt 服务以检索您的结果。建议每秒轮询一次。

轮询场景将具有以下调用响应

{
 "reqId": "ef4c1967-d543-467c-af7e-8c7899d75be8",
 "status": "pending-evaluation"
}

轮询响应

curl --location 'https://api.nvcf.nvidia.com/v2/nvcf/pexec/status/{request-id}' \
--header 'Authorization: Bearer <JWT>'

为了获得最佳性能，预计客户端在确定不再需要与服务器进行通信之前不会关闭连接。

cuOpt 大型响应检索

在某些情况下，调用的结果可能会返回一个 URL，用于下载大型响应。您将在结果中收到对下载有效负载的引用。对 URL 的 GET 请求将返回一个包含结果的 zip 文件。URL 的 TTL 为 24 小时。

{
 "reqId":"abc123",
 "status":"fulfilled",
 "responseReference": "<pre-signed download url for large result>",
 "percentComplete":100,
 "errorCode":0
}