# 模型后端管理对象与规则

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

管理当前工作区的 LLM/Embedding 后端、接入端点与路由配置。根式和工作区式协议访问同类 owner，但字段、默认值、包装与 HTTP 成功码不同。

<span id="prepare"></span>

## 调用前准备

BASE_URL、MOI_KEY、WORKSPACE_ID 来自同一环境。BACKEND_ID/ENDPOINT_ID 从同环境和同 kind 的读取结果取得。示例提供商凭据 provider-key-example 与地址是占位值，实际调用前替换。生产部署支持需独立确认。

根式 /llm 和 /embedding 通过 X-Workspace-ID 选择租户，不是管理员全局配置。工作区式 /workspaces/{id}/llm、/embeddings 在路径选择工作区。普通产品认证与经验证的任务身份分别处理；这组示例使用普通身份，不证明完整任务调用已验收。

后端 canonical 身份含 kind 与数值 ID；同一个整数可属于不同 kind，不能跨用。管理路径只接受规范正十进制 ID，0、负数、前导零和加号不接受。模型列表中的系统合成负数身份不能直接用于这些管理动作。

| 操作 | 权限 |
| --- | --- |
| 后端集合/详情、端点集合 | model_backend.read；集合按当前有效角色过滤。 |
| 创建后端 | 工作区 model_backend.create，创建结果与 Ownership 生命周期关联。 |
| 更新后端、创建端点、状态写入 | 指定后端 model_backend.update。 |
| 删除后端 | 指定后端 model_backend.delete，进入删除生命周期。 |
| 读取/写入 Router | 工作区 model_router.read / model_router.update。 |

运行模型没有独立 model_backend.use 权限；实际 Agent/任务/数据访问按各自正式准入。能读取配置或修改 Router 不等于已获得真实推理、数据或付费资源访问权。

<span id="responses"></span>

## 返回结构

| 项目 | 根式 | 工作区式 |
| --- | --- | --- |
| 成功包装 | code="OK", msg="OK", data | code=0, data；204 无响应体。 |
| 后端列表 | data.backends，可为 null；无 total | data.backends 与 total；空时字段可省略。 |
| 后端对象 | data 直接是后端，可能附 endpoints | data 直接是后端，省略零值字段；不附 endpoints。 |
| 端点列表 | data.endpoints，可为 null | data 直接为数组，空时 []。 |
| Router | data 直接是配置 | data.config 是配置。 |
| 创建后端/端点 | HTTP 200 | HTTP 201。 |
| 删除后端 | HTTP 200，data.success=true | LLM 204；Embedding 200，data.deleted=true。 |
| 设置端点状态 | HTTP 200，data.success=true | LLM 204；Embedding 200，data.updated=true。 |

### 后端字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | integer | 当前 kind 的后端 ID。 |
| name | string | 后端名称。 |
| type | string 或 integer | 根式字符串；工作区式数值。 |
| timeout_seconds | integer | 配置超时秒数。 |
| models | array（字符串数组） | 已声明模型名；根式可为 null，工作区式空时可省略。 |
| reasoning_control_protocol | string 或 integer | LLM 推理控制协议；Embedding 固定 NONE/0。 |
| created_at | integer | Unix 秒。工作区式零时间可省略。 |
| updated_at | integer | Unix 秒。工作区式零时间可省略。 |
| endpoints | array（对象数组） | 根式读取可带；LLM 只附在线项，Embedding 保留两种状态，更新结果不附。 |
| api_key_encrypted | string | 工作区式写入结果可能返回保存值；列表/详情主动移除。 |
| provider_origin | string | 工作区式来源；LLM 可写 external_provider，Embedding 返回 unknown。 |
| origin_ref | string | 工作区式 LLM 来源引用，空时省略。 |
| origin_version | string | 工作区式 LLM 来源版本，空时省略。 |

根式不返回凭据字段。工作区式创建/更新使用非脱敏转换，保存值非空时可能出现在 api_key_encrypted；列表/详情使用脱敏转换并省略它。字段名称不能证明加密状态或由客户端自动加密，示例和记录只用占位值。

工作区式 backend type 对应 0 OPENAI、1 OLLAMA、2 VLLM、3 QIANWEN、4 DOUBAO、5 DEV_LLM、6 HTTP。Embedding 创建拒绝 DEV_LLM。配置接受某类型不证明当前生产路由支持；通用 LoadLLMWorkspaceConfig 拒绝 DEV_LLM/HTTP；聊天实际使用 LoadChatCompletionWorkspaceConfig，后者允许 DEV_LLM、拒绝 HTTP。两种加载器不能合并推断，开发适配器也不证明生产支持。

工作区式 LLM 推理控制 0～5 依次为 NONE、OPENAI_REASONING_EFFORT、CHAT_TEMPLATE_KWARGS_ENABLE_THINKING、CHAT_TEMPLATE_KWARGS_THINKING、OLLAMA_THINK、QIANWEN_ENABLE_THINKING。根式接受对应名称及 REASONING_CONTROL_* 正式字符串。实际模型是否支持该控制另测。

### 端点字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | integer | 端点 ID。 |
| backend_id | integer | 所属后端 ID。 |
| address | string | 接入地址。 |
| status | string 或 integer | 根式 ONLINE/OFFLINE；工作区式 0/1。 |
| created_at | integer | Unix 秒。 |
| updated_at | integer | Unix 秒。 |

LLM 的端点列表、后端列表和后端详情都过滤离线项，Embedding 保留两种状态。设置离线前保留创建时的端点 ID；当前这些读取入口不能补查离线 LLM 端点 ID。工作区式 status=0 在 HTTP 中可省略；SDK 默认仍是在线，不能把省略识别为未知。设置在线/离线是配置，不测试健康，不删除端点。

### Router 字段

| 根式字段 | 工作区式字段 | 类型/含义 |
| --- | --- | --- |
| strategy | strategy | ROUND_ROBIN/LEAST_CONNECTIONS/MODEL_BASED 字符串，或对应整数0/1/2。 |
| health_check_interval | health_check_interval_seconds | 正数秒。 |
| max_retries | max_retries | 重试配置值，协议默认差异见比较页。 |
| session_affinity | enable_session_affinity | boolean；省略/null 按 false 写入。 |
| 无 | id | 配置记录 ID，零时省略。 |
| 无 | created_at | Unix 秒，零时省略。 |
| 无 | updated_at | Unix 秒，零时省略。 |

Router PUT 按完整配置写入，不能把未给字段理解为保留旧值。owner 读取缺失配置行时返回默认值，DAO 写入使用更新已有记录而非创建；真实缺行场景须单独验证，不承诺读到默认就已完成初始化。写前备份，写后回读并用真实模型请求验证选路；恢复与清理只在同环境执行。

<span id="errors"></span>

## 错误与结果确认

根式使用 string code/msg；工作区式使用 integer code/message。参数/枚举和缺失对象分别可能为 400/404，授权拒绝为 403、依赖失败为 503，其余按入口具体映射。根式非法 reasoning 协议可走 500/ErrServer，工作区式非法数值在绑定映射阶段拒绝；不要复用同一张错误表。

Embedding DAO 对删除或设置端点的零匹配处理与 LLM 不同；正式 IAM/对象生命周期还可能在进入 DAO 前拒绝。不能由存储分支推导整条公开 API 幂等或任意缺失 ID 必成功。规范要求引用冲突有稳定错误，完整引用准入仍需补核，不假设删除无影响。

请求绑定未统一严格拒绝未知键或尾随 JSON。字段被接收、HTTP 成功、SDK 解包成功与目标值真的改变分别确认。
