任务#

简介#

NVCF 现在支持一次性工作负载，例如微调模型或构建 TensorRT 引擎，这些工作负载可以长时间运行，且对延迟不敏感。这些工作负载需要在 GPU 驱动的工作节点上执行具有适当输入和配置的容器。执行此类容器的输出或结果可以是一组结果，例如检查点。此功能通过任务支持。将在任务中包装并在工作节点上执行的容器称为任务容器。

与函数不同，任务不是交互式的，也不会多次调用。启动任务类似于部署函数，主要区别在于任务容器在 GPU 驱动的工作节点上运行直至完成。完成后，工作节点将关闭。

任务可用于

  • 使用训练和验证数据微调现有模型，以生成具有权重的检查点。

  • 生成 TensorRT 引擎构建。

  • 需要在 GPU 驱动的工作节点上执行的其他操作。

任务管理和执行#

任务属于特定的 NVIDIA 云账户 (NCA)。以下章节详细介绍了可用于任务管理和执行的 REST 端点。

任务生命周期#

随着任务在其生命周期中推进，其状态会相应更新

  • 已排队：任务已创建并等待调度。

  • 已启动：任务已调度运行。

  • 运行中：任务当前正在执行。

  • 已完成：任务已成功完成。

  • 已取消：任务已被用户取消。

  • 出错：任务执行期间发生错误。

  • 超出最大运行时长：任务超出指定的最大运行时长。

  • 超出最大排队时长：任务无法启动，并且已超出指定的最大排队时长。

REST API 端点#

创建任务#

端点

POST /v1/nvct/tasks
Authorization: Bearer <SSA-JWT> with 'launch_task' scope

请求负载

{
  "name": "gpt-3.5-turbo-fine-tuning-task",
  "containerImage": "nvcr.io/zq9tgr/gpt-3.5-turbo-fine-tune:1.0.0",
  "models": [  # Optional model
    {
        "name": "gpt-3.5-turbo",     # Input model
        "uri": "nvcr.io/zq9tgr/model/gpt-3.5-turbo/versions/1/files",
        "version": "2.0.0"
    }
  ],
  "gpuSpecification": {
    "gpu": "T10",
    "instanceType": "g6.full",
    "backend": "GFN"
  },
  "secrets": [
    {
      "name": "NGC_API_KEY",    # Well-known secret name for uploading results to NGC
      "value": "<personal api-key with PRIVATE_REGISTRY scope to upload results to NGC org zq9tgr >"
    }
  ],
  "maxRuntimeDuration": "PT7H",
  "maxQueuedDuration": "PT6H",
  "terminationGracePeriodDuration": "PT15M",
  "resultHandlingStrategy": "UPLOAD",
  "resultsLocation": "zq9tgr/finetuned-gpt-3.5-turbo"
}

响应

状态 200

{
  "id": "579ad430-34b9-4a6e-9537-a060db4a9e6c",
  "ncaId": "test-nca-id",
  "name": "gpt-3.5-turbo-fine-tuning-task",
  …
}

注意

  • 有关更多详细信息，OpenAPI 规范包含响应详细信息。

  • 如果 resultHandlingStrategy 为 UPLOAD，则必须包含 NGC_API_KEY 作为密钥，以允许将结果上传到您的 NGC 私有注册表。

  • 如果未指定 maxRuntimeDuration 且 GFN 是后端，则请求将被状态 400 拒绝。此外，如果 GFN 后端任务的 maxRuntimeDuration 超过 8 小时，则请求将被拒绝。

  • 当调用此端点时，将创建/排队新任务，并将相应的条目添加到任务数据库以管理任务的生命周期。

列出任务#

端点

GET /v1/nvct/tasks?limit=N&cursor=<cursor-id>  # Default N to 10
Authorization: Bearer <SSA-JWT> with 'list_tasks' scope

响应

状态 200

{
  "tasks": [
    {
      "id": "579ad430-34b9-4a6e-9537-a060db4a9e6c",
      "ncaId": "test-nca-id",
      "name": "gpt-3.5-turbo-fine-tuning-task",
      "tags": ["gpt", "llm", "3.5"],
      "description": "GPT 3.5 Fine-Tuning Task",
      "status": "COMPLETED",
      "containerImage": "nvcr.io/zq9tgr/gpt-3.5-turbo-fine-tune:1.0.0",
      "secretNames": ["secret-t1"],
      "createdAt": "2024-04-15T17:57:39.716Z",
      "lastUpdatedAt": "2024-04-15T18:50:01.716Z",
      "lastHeartbeatAt": "2024-04-15T18:50:01.716Z"
    },
    {
      "id": "679ad430-34b9-4a6e-9537-a060db4a9e6c",
      "ncaId": "test-nca-id",
      "name": "trt-engine-build-task",
      "tags": ["gpt", "llm", "4.0"],
      "description": "TRT Engine Build Task",
      "status": "RUNNING",
      "containerImage": "nvcr.io/zq9tgr/trt-engine-build:1.0.0",
      "secretNames": ["secret-t2"],
      "createdAt": "2024-04-15T18:57:39.716Z",
      "lastUpdatedAt": "2024-04-15T18:50:01.716Z",
      "lastHeartbeatAt": "2024-04-15T18:50:01.716Z"
    }
  ],
  "cursor": "<UUID>"  # To be passed in as query param with the next pagination request
}

注意

响应不包括实例详细信息以及响应中每个任务的任何密钥名称。

检索任务详细信息#

端点

GET /v1/nvct/tasks/{taskId}
Authorization: Bearer <SSA-JWT> with 'task_details' scope

响应

状态 200

{
  "id": "579ad430-34b9-4a6e-9537-a060db4a9e6c",
  "ncaId": "test-nca-id",
  "name": "gpt-3.5-fine-tuning-task",
  "tags": ["gpt", "llm", "3.5"],
  "description": "GPT 3.5 Fine-Tuning Task",
  "status": "QUEUED | LAUNCHED | RUNNING | ERRORED | COMPLETED | CANCELED | EXCEEDED_MAX_RUNTIME_DURATION | EXCEEDED_MAX_QUEUED_DURATION",
  "containerImage": "nvcr.io/zq9tgr/gpt-3.5-turbo-fine-tune:1.0.0",
  "createdAt": "2024-04-15T17:57:39.716Z",
  "lastUpdatedAt": "2024-04-15T18:01:21.650Z",
  "lastHeartbeatAt": "2024-04-15T18:01:21.650Z",
  "percentComplete": 50,
  "secretNames": ["secret-t1"],
  "healthInfo": {
      "instanceType": "g6.full",
      "gpu": "T10",
      "backend": "GFN",
      "error": "Failed to start the container"
    },
  "gpuSpecification": {
    "gpu": "T10",
    "instanceType": "g6.full",
    "backend": "GFN"
  },
  "maxRuntimeDuration": "PT1H",
  "activeInstances": [  # Optional - Typically only one worker
    {
      "instanceId": "bbe8690a-9cc1-4973-bfcb-d5ff64221bb3",
      "taskId": "579ad430-34b9-4a6e-9537-a060db4a9e6c",
      "instanceType": "g6.full",
      "instanceStatus": "ACTIVE",
      "ncaId": "test-nca-id",
      "gpu": "T10",
      "backend": "GFN",
      "location": "ND-SJC6M-03",
      "instanceCreatedAt": "2024-04-15T17:57:50.245Z",
      "instanceUpdatedAt": "2024-04-15T18:01:21.650Z"
    }
  ]
}

删除任务#

端点

DELETE /v1/nvct/tasks/{taskId}
Authorization: Bearer <SSA-JWT> with 'delete_task' scope

响应

状态 204

注意

  • 删除任务还会删除关联的密钥并终止 GPU 驱动的实例。

  • 如果任务当前正在执行，它将优雅地终止，允许任务容器在指定的“terminationGracePeriodDuration”内保存结果。

取消任务#

端点

POST /v1/nvct/tasks/{taskId}/cancel
Authorization: Bearer <SSA-JWT> with 'cancel_task' scope

响应

状态 200

{
  "id": "579ad430-34b9-4a6e-9537-a060db4a9e6c",
  "ncaId": "test-nca-id",
  "name": "example-task",
  "tags": ["gpt", "llm", "3.5"],
  "description": "GPT 3.5 Fine-Tuning Task",
  "status": "CANCELED",
  "containerImage": "nvcr.io/zq9tgr/gpt-3.5-turbo-fine-tune:1.0.0",
  "createdAt": "2024-04-15T17:57:39.716Z",
  "lastUpdatedAt": "2024-04-15T18:01:21.650Z",
  "lastHeartbeatAt": "2024-04-15T18:01:21.650Z"
}

注意

  • 取消任务还会终止关联的 GPU 驱动的实例。

  • 取消任务会优雅地停止其执行，允许其在指定的“terminationGracePeriodDuration”内保存任何结果。

列出任务事件#

端点

GET /v1/nvct/tasks/{taskId}/events?limit=N&cursor=<cursor-pos-from-prev-response>
Authorization: Bearer <SSA-JWT> with 'list_task_events' scope

响应

状态 200

{
  "id": "579ad430-34b9-4a6e-9537-a060db4a9e6c",
  "cursor": "cursor-position-for-next-set-of-events",
  "limit": N,
  "ncaId": "test-nca-id",
  "name": "example-task",
  "events": [
    {
      "id": "679ad430-44b9-5a6e-0537-b060db4a9e6c",
      "message": "Status changed from QUEUED to LAUNCHED",
      "createdAt": "2024-04-15T17:57:50.245Z"
    },
    {
      "id": "779ad430-54b9-6a6e-1537-c060db4a9e6c",
      "message": "Status changed from LAUNCHED to RUNNING",
      "createdAt": "2024-04-15T17:58:50.245Z"
    },
    {
      "id": "879ad430-64b9-7a6e-2537-d060db4a9e6c",
      "message": "Status changed from RUNNING to COMPLETED",
      "createdAt": "2024-04-16T17:57:50.245Z"
    }
  ]
}

列出任务结果#

端点

GET /v1/nvct/tasks/{taskId}/results?limit=N&cursor=<result-id>
Authorization: Bearer <SSA-JWT> with 'list_task_results' scope

响应

{
  "taskId": "579ad430-34b9-4a6e-9537-a060db4a9e6c",
  "ncaId": "test-nca-id",
  "taskName": "fine-tune-gpt-3.5",
  "results": [
    {
      "id": "679ad430-44b9-5a6e-0537-b060db4a9e6c",
      "createdAt": "2024-04-15T17:57:50.245Z",
      "name": "ckpt-step-2000",
      "uri": "nvcr.io/zq9tgr/model/gpt-3.5-ckpt-step-2000/versions/1/files"
    },
    {
      "id": "779ad430-54b9-6a6e-1537-c060db4a9e6c",
      "createdAt": "2024-04-15T16:57:50.245Z",
      "name": "ckpt-step-1000",
      "uri": "nvcr.io/zq9tgr/model/gpt-3.5-ckpt-step-1000/versions/1/files"
    }
  ],
  "cursor": "<cursor-position-for-next-set-of-results>"
}

更新任务密钥#

端点

PUT /v1/nvct/secrets/tasks/{taskId}
Authorization: Bearer <SSA-JWT> with 'update_secrets' scope

请求负载

{
    "secrets": [
        {
            "name": "AWS_ACCESS_KEY_ID",
            "value": "shhh!"
        },
        {
            "name": "AWS_SECRET_ACCESS_KEY",
            "value": "shhh!shhh!"
        }
    ]
}

响应

状态 204

任务容器中可用的环境变量#

除了在任务创建期间指定的环境变量外，以下环境变量也将提供给任务容器

环境变量

描述

NVCT_TASK_ID

唯一的任务 ID。它可以包含在日志中。

NVCT_TASK_NAME

任务名称

NVCT_NCA_ID

拥有该任务的 NVIDIA 云账户。

NVCT_PROGRESS_FILE_PATH

进度文件的路径。

NVCT_RESULTS_DIR

应在其中创建结果子目录的位置。

模型和资源#

如果模型与任务关联，则任务容器可以在 /config/models/{modelName} 文件夹下找到从 NGC 私有注册表下载的模型。

同样，如果资源与任务关联，则任务容器可以在 /config/resources/{resourceName} 文件夹下找到从 NGC 私有注册表下载的资源。

任务密钥#

如果使用密钥创建任务，则密钥将在工作节点上的固定路径 /var/secrets/secrets.json 中提供给任务容器。任务作者可以使用 REST 端点更新/轮换密钥。这将导致 /var/secrets/secrets.json 自动更新。任务容器可以监视此文件的更新，并在密钥轮换时使用最新的密钥。

{
  "AWS_ACCESS_KEY_ID": "key-id",
  "AWS_SECRET_ACCESS_KEY": "access-key",
  ..
}

任务结果#

处理任务结果#

任务在执行期间可以生成多个结果。例如，在微调模型时，可能会创建多个检查点。每个任务都有在创建时指定的结果处理策略

  • 上传：系统将结果上传到指定位置。

  • 无：任务容器处理结果管理。

结果处理策略：上传#

在上传策略下

  • 任务容器必须在磁盘上 NVCT_RESULTS_DIR 下的结果特定子文件夹中创建结果文件。

  • 任务容器或 Helm Chart 必须每 3 分钟更新进度文件中的 lastUpdatedAt 字段作为心跳信号。lastUpdatedAt 字段的值应基于 RFC3339Nano 格式。如果 lastUpdatedAt 与当前时间戳之间的差异大于 5 分钟，并且 percentComplete 不是 100，则任务将 ERRORED。

  • 任务容器必须使用 percentComplete（介于 1 到 100 之间）、name 和可选的结果元数据更新进度文件。

  • 进度文件中的 name 属性必须与 NVCT_RESULTS_DIR 文件夹下的结果特定子文件夹的名称匹配。

  • 系统使用 NGC_API_KEY 密钥将新生成的结果上传到您的 NGC 私有注册表。

  • 结果将上传到 resultsLocation 属性中指定的路径。

  • 任务容器必须使用 NVCT_PROGRESS_FILE_PATH 环境变量在工作节点上创建/更新进度文件。同样，任务容器必须使用 NVCT_RESULTS_DIR 环境变量创建结果特定子文件夹。

结果处理策略：无#

在无策略下

  • 任务容器负责创建和上传结果。

  • 任务容器或 Helm Chart 必须每 3 分钟更新进度文件中的 lastUpdatedAt 字段作为心跳信号。lastUpdatedAt 字段的值应基于 RFC3339Nano 格式。如果 lastUpdatedAt 与当前时间戳之间的差异大于 5 分钟，并且 percentComplete 不是 100，则任务将 ERRORED。

  • 任务容器必须在最后创建/更新进度文件，并将 percentComplete 设置为 100，以指示其正常退出，以便系统将任务标记为 COMPLETED。

  • 外部存储的凭据可以作为任务密钥提供。

  • 系统根据进度文件更新任务的进度，但不处理结果上传。

  • 任务容器必须使用 NVCT_PROGRESS_FILE_PATH 环境变量在工作节点上创建/更新进度文件。同样，任务容器应该使用 NVCT_RESULTS_DIR 环境变量创建一个结果特定子文件夹以存储结果。

进度文件格式#

{
  "taskId": "579ad430-34b9-4a6e-9537-a060db4a9e6c",
  "percentComplete": 20,
  "name": "ckpt-step-2000",
  "metadata": {
    "step-number": 2000,
    "token_accuracy": 0.874
  },
  "lastUpdatedAt": "20025-01-02T15:04:05.999999999Z07:00"
}

  • taskId：任务 ID。

  • percentComplete：整数，表示 1-100 之间的完成百分比。

  • metadata：任务容器用于添加有关上传的元数据的可选字段。所需格式：键值对。

  • name：要上传到 NGC 私有注册表的结果的目录/文件夹名称。命名 UPLOAD 策略的目录有一些限制。该字段长度应为 1-190 个字符。允许的字符：[0-9a-zA-Z!-_.*’()]。不允许使用前缀 ./ 和 ../。

  • lastUpdatedAt：ISO 8061 时间戳，指示上次更新进度文件的时间。必须至少每 3 分钟更新一次，以向 NVCF 发出任务正在进行中的信号。

任务容器必须使用 NVCT_PROGRESS_FILE_PATH 环境变量在工作节点上创建/更新进度文件。同样，任务容器必须使用 NVCT_RESULTS_DIR 环境变量创建结果特定子文件夹。

中间结果和最终结果#

  • 中间结果：当生成新结果时，任务容器应使用 percentComplete（介于 1 和 <100 之间）、name 以及可选的结果元数据更新进度文件。系统会监视此文件并相应地更新任务的状态和进度。任何连续的具有重复 percentComplete 和 name 字段的中间结果都将被忽略。

  • 最终结果：当任务完成时，任务容器必须最后一次更新进度文件，并将 percentComplete 设置为 100、name 以及可选的结果元数据。系统将任务标记为已完成。

任务运行时长#

默认情况下，任务无限期运行。但是，您可以在创建任务时指定 maxRuntimeDuration 属性来控制其执行时长。如果指定了 maxRuntimeDuration，则任务将在持续时间结束后优雅地终止，从而允许其保存任何最终结果。如果选择 GFN 作为后端，则 maxRuntimeDuration 必须少于 8 小时。

本页内容