管理计算实例

计算实例为 SQL、工作流和数据处理任务提供运行容量。本页说明如何选择规格、创建实例、观察运行状态，以及在确认依赖后暂停、启动或删除实例。

前提条件

• 已准备 Product API Base URL、个人访问令牌和工作区 ID。

• 当前身份具有计算实例的读取或管理权限。

• 已了解将要运行的任务类型和容量需求。

计算规格由平台统一提供。普通开发者应从规格列表选择 spec_id，不应自行创建或修改规格。

计算实例生命周期

读取可用规格和 Worker 镜像
→ 创建计算实例并保存 resource_id
→ 查询详情、运行时或指标
→ 按需暂停、恢复或重试
→ 删除预检
→ 删除计算实例

创建、暂停、启动、重试和删除可能需要后台完成。HTTP 请求成功表示操作已经受理，不表示计算实例已经达到目标状态；继续读取实例详情中的 status 和 status_message。

相关接口

方法与路径	用途
GET /compute-resource-specs	列出当前工作区可选择的计算规格。
GET /compute-resources/worker-images	列出可选 Worker 镜像。
POST /compute-resources	创建计算实例。
GET /compute-resources	列出计算实例。
GET /compute-resources/{resource_id}	读取实例详情和状态。
PUT /compute-resources/{resource_id}	更新实例配置。
GET /compute-resources/{resource_id}/runtime	读取各 Worker 的运行时状态。
GET /compute-resources/{resource_id}/metrics	读取实例用量指标。
POST /compute-resources/{resource_id}/suspend	暂停实例。
POST /compute-resources/{resource_id}/resume	启动实例。
POST /compute-resources/{resource_id}/retry	重试失败的生命周期操作。
GET /compute-resources/{resource_id}/preflight-delete	检查删除依赖。
DELETE /compute-resources/{resource_id}	删除实例。

选择规格

先读取当前可用的规格：

curl "$PRODUCT_API_BASE_URL/compute-resource-specs" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

从响应中选择已启用并满足任务需求的规格，保存其 id。规格可能包含 kind、CPU、内存、GPU 和每小时 Credit 等信息；可选值以本次响应为准。

如果需要指定 Worker 镜像，再读取镜像列表：

curl "$PRODUCT_API_BASE_URL/compute-resources/worker-images" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

不要把镜像地址直接写入创建请求。需要自定义镜像时，使用列表返回的镜像 ID、Worker 类型和平台信息。

创建计算实例

下面的请求创建一个最小计算实例。cpu 和 memory_gib 应与所选规格的容量保持一致：

curl -X POST "$PRODUCT_API_BASE_URL/compute-resources" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-processing",
    "description": "用于数据处理任务",
    "spec_id": "<SPEC_ID>",
    "cpu": 2,
    "memory_gib": 4,
    "min_replicas": 1,
    "max_replicas": 2
  }'

字段	类型	必需	说明
name	string	是	工作区内便于识别的实例名称。
spec_id	string	是	从规格列表取得的规格 ID。实例类型和标准容量以该规格为准。
cpu	integer	是	CPU 数量。使用所选规格对应的值。
memory_gib	integer	是	内存容量，单位为 GiB。使用所选规格对应的值。
description	string	否	实例用途说明。
min_replicas	integer	否	最小副本数。不得大于 max_replicas。
max_replicas	integer	否	最大副本数。
auto_suspend_minutes	integer	否	无活动后自动暂停的等待时间。
worker_images	object[]	否	Worker 镜像选择。使用镜像列表返回的标识和类型。

成功响应返回计算实例对象：

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "<RESOURCE_ID>",
    "workspace_id": "<WORKSPACE_ID>",
    "name": "data-processing",
    "spec_id": "<SPEC_ID>",
    "status": "DEPLOYING",
    "status_message": "",
    "current_replicas": 0,
    "desired_replicas": 1
  }
}

保存 data.id。随后读取 GET /compute-resources/{resource_id}，而不是根据创建请求耗时推断实例是否可用。

读取运行状态和指标

实例详情给出整体状态；运行时接口进一步按 Worker 类型返回目标副本数、当前副本数和运行状态：

curl "$PRODUCT_API_BASE_URL/compute-resources/$RESOURCE_ID/runtime" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

指标接口返回计算实例 ID、累计 Credit 和分类明细：

curl "$PRODUCT_API_BASE_URL/compute-resources/$RESOURCE_ID/metrics" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

breakdown 的维度可能随实例类型不同而变化。读取前应允许未知字段，不要依赖固定的明细键集合。

暂停、启动和重试

以下操作不需要请求体：

curl -X POST "$PRODUCT_API_BASE_URL/compute-resources/$RESOURCE_ID/suspend" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

将路径末尾改为 resume 可启动实例；只有实例处于可重试的失败状态时才使用 retry。每次操作后重新读取详情，直到 status 达到预期状态或进入失败终态。

暂停会影响依赖该计算实例的新任务和正在运行的任务。操作前先确认关联工作负载，并让调用方能够处理实例启动带来的等待时间。

删除前检查依赖

删除前先调用预检：

curl "$PRODUCT_API_BASE_URL/compute-resources/$RESOURCE_ID/preflight-delete" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "active_tasks": 1,
    "active_task_ids": ["<TASK_ID>"],
    "bound_workflows": 1,
    "bound_workflow_details": []
  }
}

当 active_tasks 或 bound_workflows 大于 0 时，先停止任务或把工作流迁移到其他计算实例。依赖处理完成后重新预检，再发送删除请求。删除不可恢复，也可能被默认计算实例或权限规则阻止。

常见问题

现象	先检查	下一步
创建请求被拒绝	spec_id 是否存在并启用，CPU 和内存是否匹配规格	重新读取规格，不沿用其他环境保存的 ID。
长时间处于部署中或扩缩容中	status_message、运行时副本和 Worker 镜像	保留计算实例 ID，查询详情；不要重复创建同名实例。
暂停后任务调用变慢	实例是否正在启动	延长调用等待时间，并在实例可用后再判断任务是否失败。
无法删除	删除预检、默认计算实例限制和权限	先解除任务及工作流依赖，再重新预检。
指标明细为空	实例是否刚创建或尚未产生工作负载	结合实例状态和任务记录判断，不把空明细直接当作接口失败。

下一步

• 运行 SQL 并读取结果

• 运行并查询工作流

• 查看状态码和错误码

最后更新于 2026 年 8 月 14 日