模型后端管理对象与规则¶
管理当前工作区的 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 解包成功与目标值真的改变分别确认。