模型发现与探测对象¶
调用前准备¶
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 独立授权;不推导为模型运行时权限。
返回字段¶
字段 |
类型 |
说明 |
|---|---|---|
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 会按已登记配置再过滤;工作区的两个模型列表不读取这个参数。绑定模型、调整路由、发起推理是后续独立任务。
状态与错误¶
旧式根入口使用字符串 code/msg:参数和工作区错误为 400、对象缺失 404、权限拒绝 403;探测失败为 502/ErrProbe,系统与授权依赖故障另外映射。工作区嵌入读取使用数值 code/message。根绑定只解码一个 JSON 值,未启用统一拒绝未知字段的严格模式;不要套用资源标签的绑定规则。