# 创建计算实例

在当前工作区创建一个计算实例。

```text
POST https://moi.matrixorigin.cn/newmoi/compute-resources
```

## 调用前准备

先[列出计算规格](../compute-resource-specs/list-compute-resource-specs.md)，取得可用的 `spec_id`；需要指定镜像时，再[列出 Worker 镜像](list-worker-images.md)。准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：要创建计算实例的工作区 ID，通过 `X-Workspace-ID` Header 传递。
- `$SPEC_ID`：要使用的计算规格 ID，取自[列出计算规格](../compute-resource-specs/list-compute-resource-specs.md)的响应，在请求体中指定实例规格。

## 请求体

字段路径中的 `[]` 表示数组中的每一项。例如，`worker_images[].worker_type` 表示 `worker_images` 数组中每一项的 `worker_type` 字段。

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 是 | 计算实例名称。 |
| `spec_id` | string | 是 | 计算规格 ID。 |
| `kind` | string | 否 | 兼容性提示；实例类型以规格为准。 |
| `description` | string | 否 | 用途说明。 |
| `cpu` | integer | 否 | 兼容输入；实际容量由 `spec_id` 对应规格决定。 |
| `memory_gib` | integer | 否 | 兼容输入；实际容量由 `spec_id` 对应规格决定。 |
| `gpu` | integer | 否 | 兼容输入；实际容量由 `spec_id` 对应规格决定。 |
| `min_replicas` | integer | 否 | Serverless 实例仅接受 `0`，省略时为 `0`。 |
| `max_replicas` | integer | 否 | 副本上限，必须大于 `0`；省略时为 `1`。 |
| `auto_suspend_minutes` | integer | 否 | 自动暂停等待时间。 |
| `go_worker_image_id` | string | 否 | 兼容的 Go Worker 镜像 ID。 |
| `python_worker_image_id` | string | 否 | 兼容的 Python Worker 镜像 ID。 |
| `platform` | string | 否 | 兼容的运行平台。 |
| `worker_images` | object（对象数组） | 是 | Worker 镜像选择，必须覆盖镜像列表中当前所有活跃的 `worker_type`。 |
| `worker_images[].worker_type` | string | 是 | Worker 类型，取自镜像列表的 `worker_type`。 |
| `worker_images[].image_id` | string | 是 | 镜像 ID，取自镜像列表的 `id`。 |
| `worker_images[].platform` | string | 是 | 镜像运行平台，取自镜像列表的 `platform`。 |
| `worker_images[].kind` | string | 否 | 兼容别名；传入时应与 `worker_type` 一致。 |

`worker_images` 中的 `worker_type`、`image_id` 和 `platform` 应来自镜像列表。每次创建都要重新读取镜像列表，并为其中每个活跃 Worker 类型提交一项；不能只提交其中一项或依赖服务端自动补全。

## 请求示例

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/compute-resources" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "data-processing",
    "spec_id": "'"$SPEC_ID"'",
    "min_replicas": 0,
    "max_replicas": 1,
    "worker_images": [
      {
        "worker_type": "go-worker",
        "image_id": "$GO_WORKER_IMAGE_ID",
        "platform": "linux/amd64"
      },
      {
        "worker_type": "python-worker",
        "image_id": "$PYTHON_WORKER_IMAGE_ID",
        "platform": "linux/amd64"
      },
      {
        "worker_type": "java-worker",
        "image_id": "$JAVA_WORKER_IMAGE_ID",
        "platform": "linux/amd64"
      },
      {
        "worker_type": "custom-tool-worker",
        "image_id": "$CUSTOM_TOOL_WORKER_IMAGE_ID",
        "platform": "linux/amd64"
      }
    ]
  }'
```

## 成功响应

成功时返回 `200`。保存 `data.id`。新建 Serverless 实例初始为 `IDLE`，不会立即部署 Worker；后续工作负载需求会激活所需的 Worker 类型。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "resource-123",
    "name": "data-processing",
    "spec_id": "task-standard-small",
    "status": "IDLE",
    "status_message": "",
    "min_replicas": 0,
    "max_replicas": 1,
    "current_replicas": 0
  }
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.id` | string | 新建计算实例的 ID。 |
| `data.workspace_id` | string | 所属工作区 ID。 |
| `data.name` | string | 计算实例名称。 |
| `data.description` | string | 实例说明；有值时返回。 |
| `data.spec_id` | string | 使用的计算规格 ID。 |
| `data.kind` | string | 实例类型。 |
| `data.cpu` | integer | CPU 配置值。 |
| `data.memory_gib` | integer | 以内存 GiB 表示的配置值。 |
| `data.gpu` | integer | GPU 配置值。 |
| `data.cpu_milli` | integer | 以毫核表示的 CPU 配置值。 |
| `data.memory_mib` | integer | 以内存 MiB 表示的配置值。 |
| `data.gpu_count` | integer | GPU 数量。 |
| `data.gpu_memory_mib` | integer | 单个 GPU 的显存 MiB。 |
| `data.gpu_cores` | integer | GPU 核心数。 |
| `data.min_replicas` | integer | Serverless 实例固定为 `0`。 |
| `data.max_replicas` | integer | 最大副本数。 |
| `data.desired_replicas` | integer | 目标副本数。 |
| `data.current_replicas` | integer | 当前副本数。 |
| `data.go_worker_image_id` | string | Go Worker 镜像 ID；有值时返回。 |
| `data.python_worker_image_id` | string | Python Worker 镜像 ID；有值时返回。 |
| `data.worker_images` | object（对象数组） | Worker 镜像选择；有值时返回。 |
| `data.worker_images[].worker_type` | string | Worker 类型。 |
| `data.worker_images[].image_id` | string | 镜像 ID。 |
| `data.worker_images[].platform` | string | 运行平台。 |
| `data.platform` | string | 实例运行平台；有值时返回。 |
| `data.auto_suspend_minutes` | integer | 自动暂停等待时间。 |
| `data.is_default` | boolean | 是否为工作区默认计算实例。 |
| `data.status` | string | 当前生命周期状态。 |
| `data.status_message` | string | 状态补充信息；有值时返回。 |
| `data.scale_reason` | string | 服务端提供的缩放原因；有值时返回。 |
| `data.last_activation_at` | string | 最近一次激活时间；有值时返回。 |
| `data.last_active_at` | string | 最近一次活跃时间；有值时返回。 |
| `data.created_by` | string | 创建者标识；有值时返回。 |
| `data.created_at` | string | 创建时间；有值时返回。 |
| `data.updated_at` | string | 最后更新时间；有值时返回。 |

## 错误响应

```json
{
  "code": "INVALID_PARAMS",
  "msg": "请求参数无效",
  "data": null
}
```

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `INVALID_PARAMS`
  - 请求体无法解析，或必填的 `name`、`spec_id` 缺失。
  - 检查请求字段和计算规格。
* - `401`
  - —
  - 缺少或无效的访问凭据。
  - 检查 API Key 和工作区 Header。
* - `403`
  - `ErrForbidden`
  - 当前身份没有创建实例的权限。
  - 使用有权限的凭据，或联系管理员授权。
* - `409`
  - `COMPUTE_RESOURCE_NAME_EXISTS`
  - 工作区中已有同名实例。
  - 更换 `name` 后重试。
* - `500`
  - `CREATE_FAILED`
  - 服务端未能创建实例。
  - 记录请求时间和错误信息后重试。
```

## 后续操作

[查询计算实例详情](get-compute-resource.md)，直到状态满足任务要求。