# 模型发现与探测对象

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

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

## 调用前准备

BASE_URL、MOI_KEY 和 WORKSPACE_ID 使用同一目标环境；BACKEND_ID 来自同环境的后端列表。生产支持范围须另核部署。提供商地址与密钥示例均为占位值，实际调用前替换。此组产品接口管理模型供给，与 Genesis 推理/管理 API 分开。

根路径 /llm、/embedding、/parser 仍通过 X-Workspace-ID 选择租户；路径没有 workspace 段不代表管理员全局配置。根入口使用普通产品身份；带工作区路径的所列入口另接受经验证的任务身份。

模型列表按 model_backend.read 集合过滤；探测已保存后端要求该对象 read；临时地址探测使用 regular 访问级别，不能借它读取未授权保存配置。配置写入还有 create/update/delete 与 router 独立授权；不推导为模型运行时权限。

(response)=
## 返回字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data.models | array（对象数组或字符串数组） | 列表为对象；探测为模型名称字符串。 |
| models[].model | string | 模型名。 |
| models[].backend_id | integer | 路由模型所属后端 ID，可含系统合成 ID，不能拿负数直接操作只接受正数的管理接口。 |
| models[].backend_name | string | 后端名称。 |
| models[].model_type | string | 根模型列表中的类型标记。 |
| models[].reasoning_efforts | array（字符串数组） | 提供的推理级别，空时省略；普通工作区声明不保证带此字段。 |
| models[].source | string | 根列表的 workspace/system 来源。 |
| models[].system_default | boolean | 根列表的系统默认标记。 |
| models[].type | string | 可选嵌入子类型，非后端的 OPENAI 等协议类型。 |
| models[].dim | integer | 可选嵌入维度，零时省略。 |
| data.backend | object | 设置操作保存的后端。 |
| data.endpoint | object | 同一设置操作保存的端点。 |

工作区 embeddings/models 仅投影 model/backend_id/backend_name 及非空 type/非零 dim，返回 code=0；根列表为字符串 OK/msg=OK。工作区 llm/models 又只投影名称、后端与请求类型标记，没有系统列表合并；不能把三种协议归并成别名。所有列表均无分页。

| 后端/端点字段 | 类型 | 说明 |
| --- | --- | --- |
| backend.id | integer | 后端 ID。 |
| backend.name | string | 名称。 |
| backend.type | string | 后端协议类型。 |
| backend.reasoning_control_protocol | string | 推理控制协议。 |
| backend.timeout_seconds | integer | 配置超时秒数。 |
| backend.models | array（字符串数组） | 已声明模型名。 |
| backend.endpoints | array（对象数组） | 非空时可附端点；设置结果另给 data.endpoint。 |
| backend.created_at | integer | 创建时间，Unix 秒。 |
| backend.updated_at | integer | 更新时间，Unix 秒。 |
| endpoint.id | integer | 端点 ID。 |
| endpoint.backend_id | integer | 所属后端 ID。 |
| endpoint.address | string | 接入地址。 |
| endpoint.status | string | ONLINE/OFFLINE；与工作区 Core 端点的数值 0/1 分开。 |
| endpoint.created_at | integer | 创建时间，Unix 秒。 |
| endpoint.updated_at | integer | 更新时间，Unix 秒。 |

凭据不在上述响应中。推理控制支持 NONE、OPENAI_REASONING_EFFORT、CHAT_TEMPLATE_KWARGS_ENABLE_THINKING、CHAT_TEMPLATE_KWARGS_THINKING、OLLAMA_THINK、QIANWEN_ENABLE_THINKING 及对应 REASONING_CONTROL_* 正式值；实际模型须支持所选协议，保存不做能力测试。

## 探测结果与副作用

探测向指定根地址追加 /models，读取提供商返回的 data[].id，去除空名称后按名称模式划分 LLM/Embedding，不测视觉、OCR、推理或实际嵌入能力。已保存后端探测需要显式 api_key。LLM 的 DAO 先过滤离线端点，再取首个在线候选；Embedding 保留两种状态，直接取首地址，不自动轮换。候选不会写回配置。探测最多读取 1 MiB 响应；超过上限会失败。提供商网络、超时、限流与鉴权规则须真实验证。

模型列表 source/type/dim 等声明也不能替代实际调用。根列表的 service_slot 会按已登记配置再过滤；工作区的两个模型列表不读取这个参数。绑定模型、调整路由、发起推理是后续独立任务。

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

## 状态与错误

旧式根入口使用字符串 code/msg：参数和工作区错误为 400、对象缺失 404、权限拒绝 403；探测失败为 502/ErrProbe，系统与授权依赖故障另外映射。工作区嵌入读取使用数值 code/message。根绑定只解码一个 JSON 值，未启用统一拒绝未知字段的严格模式；不要套用资源标签的绑定规则。
