# 更新计算规格

更新一个计算规格的定义。

```text
PUT https://moi.matrixorigin.cn/newmoi/compute-resource-specs/{spec_id}
```

## 调用前准备

先[列出计算规格](list-compute-resource-specs.md)，确认要更新的规格。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID 和规格 ID。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：目标工作区 ID，通过 `X-Workspace-ID` Header 传递。
- `$SPEC_ID`：要更新的计算规格 ID，取自[列出计算规格](list-compute-resource-specs.md)的响应。

先[查询计算规格管理权限](get-compute-resource-spec-management-permission.md)。只有结果为 `true` 时才能更新规格。请求体使用完整规格定义，且 `family_name_en` 不能为空。

## 路径参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `spec_id` | string | 是 | 要更新的计算规格 ID。 |

## 请求体

请求体是完整规格定义。除 `id` 可省略外，必填字段必须全部提交；省略 `enabled` 会将规格设为禁用。

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 否 | 规格 ID；提供时必须与路径中的 `spec_id` 一致。 |
| `kind` | string | 是 | 资源类型，只能为 `task` 或 `query`。 |
| `family` | string | 是 | 规格族标识。 |
| `family_name` | string | 是 | 规格族名称。 |
| `family_name_en` | string | 是 | 规格族英文名称；不能为空。 |
| `cpu_milli` | integer | 是 | CPU 容量，单位为毫核，必须大于 `0`。 |
| `memory_mib` | integer | 是 | 内存容量，单位为 MiB，必须大于 `0`。 |
| `gpu_count` | integer | 否 | GPU 数量，不能小于 `0`。 |
| `gpu_memory_mib` | integer | 否 | GPU 显存，单位为 MiB，不能小于 `0`。 |
| `gpu_cores` | integer | 否 | GPU 核数，不能小于 `0`。 |
| `credit_per_hour` | number | 否 | 每小时 Credit 用量，不能小于 `0`。 |
| `description` | string | 否 | 规格说明。 |
| `node_placement` | object | 否 | 节点调度配置。 |
| `enabled` | boolean | 否 | 是否允许使用该规格；省略时为 `false`。 |

## 请求示例

```bash
curl -X PUT "https://moi.matrixorigin.cn/newmoi/compute-resource-specs/$SPEC_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "task-standard-small",
    "kind": "task",
    "family": "standard",
    "family_name": "标准",
    "family_name_en": "Standard",
    "cpu_milli": 2000,
    "memory_mib": 4096,
    "gpu_count": 0,
    "gpu_memory_mib": 0,
    "gpu_cores": 0,
    "credit_per_hour": 1,
    "enabled": true
  }'
```

## 成功响应

成功时返回 `200`。`data` 返回更新后的规格对象。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "task-standard-small",
    "kind": "task",
    "family": "standard",
    "family_name": "标准",
    "family_name_en": "Standard",
    "cpu_milli": 2000,
    "memory_mib": 4096,
    "gpu_count": 0,
    "gpu_memory_mib": 0,
    "gpu_cores": 0,
    "credit_per_hour": 1,
    "description": "用于常规任务",
    "node_placement": {},
    "enabled": true
  }
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.id` | string | 更新后的规格 ID。 |
| `data.kind` | string | 资源类型。 |
| `data.family` | string | 规格族标识。 |
| `data.family_name` | string | 规格族名称。 |
| `data.family_name_en` | string | 规格族英文名称。 |
| `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.credit_per_hour` | number | 每小时 Credit 用量。 |
| `data.description` | string | 规格说明。 |
| `data.description_en` | string | 英文规格说明；系统规格可返回。 |
| `data.node_placement` | object | 节点调度配置。 |
| `data.enabled` | boolean | 更新后的启用状态。 |
| `data.is_system` | boolean | 是否为系统内置规格。 |
| `data.created_by` | string | 创建者标识。 |
| `data.updated_by` | string | 最后更新者标识。 |
| `data.created_at` | string | 创建时间。 |
| `data.updated_at` | string | 最后更新时间。 |

## 错误响应

```json
{
  "code": "INVALID_PARAMS",
  "msg": "family_name_en is required",
  "data": null
}
```

### 常见 HTTP 错误

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

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `INVALID_PARAMS`
  - 请求体无法解析，或未提供 `family_name_en`。
  - 检查 JSON 格式，并提供非空的 `family_name_en`。
* - `401`
  - —
  - 缺少、无效或已失效的访问凭据。
  - 检查 API Key。
* - `403`
  - `COMPUTE_RESOURCE_SPEC_FORBIDDEN`
  - 当前身份没有规格管理权限。
  - 使用具有相应权限的身份重试。
* - `404`
  - `NOT_FOUND`
  - `spec_id` 对应的规格不存在。
  - 先[列出计算规格](list-compute-resource-specs.md)，并确认路径参数。
* - `409`
  - —
  - 更新后的定义与已有规格冲突。
  - 修改冲突字段后重试。
* - `500`
  - `UPDATE_SPEC_FAILED`
  - 服务端未能更新规格。
  - 保留错误信息并稍后重试；持续失败时联系支持人员。
```

## 后续操作

如只需切换可用性，使用[启用或禁用计算规格](set-compute-resource-spec-enabled.md)。