模型后端管理对象与规则

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

调用前准备

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 不等于已获得真实推理、数据或付费资源访问权。

返回结构

项目

根式

工作区式

成功包装

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 写入使用更新已有记录而非创建;真实缺行场景须单独验证,不承诺读到默认就已完成初始化。写前备份,写后回读并用真实模型请求验证选路;恢复与清理只在同环境执行。

错误与结果确认

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

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

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

最后更新于