模型组¶

模型组（Model Group）是调用方看到的稳定模型名，也是入站协议、Endpoint Model 映射和故障转移策略的边界。

主要字段¶

字段	当前语义
`name`	请求体中的 `model`；只允许字母、数字、点、下划线和连字符
`kind`	`text`、`image` 或 `video`；当前可调用实现为文本与图片
`status`	`normal` 接受请求，`disabled` 拒绝
`inboundProtocolContracts`	这个公开模型名允许从哪些精确 API Contract 调用
`routingMode`	当前固定为 `tiered_failover`
`sidecarConfigMode`	`full` 或 `reference`
`mappings`	Endpoint、上游模型、tier、weight 与 sort order

名称解析¶

普通入口从 JSON 或 multipart 的 model 字段解析模型组：

{"model":"chat-default"}

请求中的公开模型名在 Driver Attempt 中与选中的上游模型 ID 分开传递，Driver 必须使用后者构造上游请求。

对外协议契约¶

文本模型组可以选择：

OpenAI Chat Completions；
OpenAI Responses；
Anthropic Messages。

图片模型组可以选择 OpenAI Image Generation 和 Image Edit。至少选择一个 Contract。

模型组只接受已选择的 Contract。每条映射还必须满足：Endpoint kind 一致、Driver 存在、Driver 声明该 Contract；图片模型本身也必须声明对应图片 Contract。Console 会禁用不兼容选项，后端保存时再次校验。

文本 Contract 同时包含 buffered 与 SSE 生命周期，是否流式由请求中的 stream 决定，不再由模型组单独配置 exposed mode。

映射、Tier 与 Weight¶

每条映射指向一个精确 Endpoint Model：

chat-default
├── tier 0 · weight 80 → endpoint-a / gpt-5
├── tier 0 · weight 20 → endpoint-b / glm-5
└── tier 1 · weight 100 → endpoint-c / claude-sonnet

数字更小的 tier 优先；0 是 Console 中的主用池，1+ 是备选池。
同 tier 候选按 weight 做确定性加权选择；weight 必须大于 0。
同一个 Endpoint 在一次请求中最多尝试一次，即使模型组包含它的多个模型映射。
只有当前 tier 没有可用候选或尝试产生可故障转移结果时，才进入下一 tier。

详细错误分类见路由与故障转移。

Sidecar 下发模式¶

full 把本地执行所需 Endpoint、凭据、Driver Binding、模型和映射投影到 Sidecar。Sidecar 成功下载/验证所需 WASM 并完整 Bind 后才原子激活新快照。

reference 只下发 API Key hash、模型组稳定 ID 与授权关系。Sidecar 本地鉴权并解析模型组，然后使用签名内部身份转发 Central，由 Central 执行真实路由。

设计建议¶

按业务语义命名，例如 chat-default、reasoning、image-production。
把不同故障域放在不同 Endpoint，按 tier 表达主备。
只有调用方确实需要的 Contract 才对外暴露。
变更协议或映射前先确认所有候选兼容；配置写入会触发 runtime generation 和 Sidecar revision。