# 替换服务槽位模型配置

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

完整替换一个功能槽位的模型列表及额外配置。空列表会清空槽位，不作为只读探测使用。

```text
PUT https://api.moi.matrixorigin.cn/v5/admin/aistudio/service-slots/{slot_id}
```

## 调用前准备

准备当前环境可用的Genesis管理员Bearer令牌；普通个人访问令牌、X-API-Key或工作区Owner不能替代。会话模式还需相应CSRF，详见[AI Studio](../../../../../developer/api/ai-studio/index.md)。这些是账户级管理操作，不需要工作区ID。

先由部署配置负责人确认目标槽位的完整配置，并做好配置源备份。列表响应不包含部署侧 endpoint，不能作为完整恢复备份；当前源码更新目标槽位时会重建该配置项，可能移除原有 endpoint。仅在获准的独立测试部署中验证写操作。

从候选中选择允许类型的真实模型ID，替换示例model-example。示例{}只表示额外JSON文本，不承诺特定扩展键的效果。清空、排序及失败后的回读见[写入与环境](write-recovery-environments.md)。

## 请求参数

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl -X PUT "https://api.moi.matrixorigin.cn/v5/admin/aistudio/service-slots/agent_chat" \
  -H "Authorization: Bearer $GENESIS_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"default_model_id":"model-example","model_ids":["model-example"],"extra_json":"{}"}'
```

:::::
:::::{tab-item} 参数说明

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `Authorization` | string | Bearer示例是 | Bearer加当前环境的管理员令牌；不要同时发送X-API-Key。 |
| `slot_id` | string | 是 | 路径字段，从槽位列表取得。 |
| 请求体 `slot_id` | string | 否 | 提供时须与路径选择一致。 |
| `default_model_id` | string | 否 | 非空模型列表中省略/空白时选首项；非空值必须在model_ids内。 |
| `model_ids` | string（字符串数组） | 按目标配置 | 完整列表；省略、null、[]或仅空白项均可能清空。 |
| `extra_json` | string | 否 | 合法JSON文本或空字符串；省略/空字符串不保留原值。 |
| `models` | object（对象数组） | 不作为写入依据 | 兼容解析字段，当前不进入写命令；不能替代model_ids。 |

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "slot_id": "agent_chat",
  "name": "Agent chat",
  "frontend_behavior": "selectable",
  "allowed_model_types": [
    "chat_text",
    "chat_multimodal"
  ],
  "configured": true,
  "default_model_id": "model-example",
  "models": [
    {
      "id": "model-example",
      "name": "model-example",
      "type": "",
      "position": 0
    }
  ],
  "default_model_name": "model-example",
  "extra_json": "{}"
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `slot_id` | string | 功能槽位标识。 |
| `name` | string | 当前注册定义的名称。 |
| `frontend_behavior` | string | hidden或selectable，描述前端是否让用户选模型。 |
| `allowed_model_types` | string（字符串数组） | 允许分配的目录模型类型。 |
| `configured` | boolean | 是否配置了非空模型列表；不等于模型健康或当前凭据可调用。 |
| `default_model_id` | string | 默认模型ID，未配置时为空字符串。 |
| `default_model_name` | string | 可选；当前按模型ID显示。 |
| `models` | object（对象数组） | 有序模型列表，未配置时为空。 |
| `models[].id` | string | 候选目录模型ID。 |
| `models[].name` | string | 当前投影名称。 |
| `models[].type` | string | 列表可由目录补充；写入响应当前可能为空字符串。 |
| `models[].position` | integer | 列表中的零基位置。 |
| `extra_json` | string | 可选额外JSON文本，不是JSON对象字段。 |

:::::
::::::
:::::::

## 错误响应

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": "ErrForbidden",
  "msg": "Forbidden"
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 当前错误代码。 |
| `msg` | string | 当前失败阶段的说明；该示例为HTTP Forbidden文本。 |

| HTTP / code | 条件与处理 |
| --- | --- |
| 400 / ErrParamInvalid | 槽位、模型、默认值、JSON文本或日志数量参数不合法。 |
| 401 / Unauthorized | 身份无效或使用X-API-Key等不适用认证方式。 |
| 403 / ErrForbidden | 无Genesis管理员事实。 |
| 503 / ErrServiceUnavailable | 已分类的必要身份/配置依赖不可用。 |
| 500 / ErrServer或InternalServerError | 内部或身份阶段失败；写入错误后先回读，不能推断回滚。 |

错误使用code/msg，成功却是原始对象。不同失败阶段可能使用不同字符串code；不虚构每个校验错误的独立机器reason。

:::::
::::::
:::::::
