通用接入规则

所有上游类型共用的接入规则——上游登记字段、模型清单与中性名、分组与优先级权重、模型池准入判定、接入探测与运行时故障转移

本页给出所有上游类型共用的接入规则。无论上游来自自有供应还是第三方兼容接入，登记字段、模型池准入、路由配置与故障转移的规则都一致；各类型的差异（协议类型取值、模型映射要点）见对应的类型子页。

1. 上游登记字段

接入一个上游通过 POST /api/v1/providers 完成。登记体的字段在所有上游类型间通用，只是部分取值随类型而定。

curl https://your-platform/api/v1/providers \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{
    "name": "<上游显示名>",
    "source": "self",
    "type": "openai-compatible",
    "models": ["<模型中性名>"],
    "group": "default",
    "priority": 1,
    "weight": 1
  }'

字段	含义	取值
`name`	上游显示名，用于「模型接入」页识别	任意可读名称
`source`	上游来源	`self`（自有供应）/ `third_party`（第三方兼容）
`type`	协议类型，决定平台如何翻译请求与响应	`native` / `openai-compatible` / `anthropic-compatible` / `gemini-compatible`
`models`	该上游对外提供的模型清单	统一中性名数组（见第 2 节）
`group`	路由分组	决定哪些查询可命中本上游
`priority`	路由优先级	整数，越小越优先
`weight`	同优先级内加权权重	整数，越大承接流量比例越高

接入成功返回上游摘要，其中 provider_id 是后续变更、探测、查询所用的标识：

{
  "provider_id": "<上游标识>",
  "name": "<上游显示名>",
  "source": "self",
  "type": "openai-compatible",
  "status": "active",
  "models": ["<模型中性名>"]
}

2. 模型清单与中性名

models 中登记的是模型的中性名——平台对外统一暴露的模型标识，客户应用按中性名调用，感知不到背后的上游归属。同一个中性名可由多个上游供给，路由中间件据此在多个候选间择优与故障转移。

规则	说明
一名多源	一个中性名可挂在多个上游下；这是同名模型可做加权择优与故障转移的前提
对外只见中性名	数据平面 `GET /v1/models` 与逐条调用记录中只出现中性名，不出现上游内部型号或批发口径
范围授权	子账户密钥可限定可调用的模型范围（`model_scope`），限定后仅能调用授权范围内的中性名

成本口径不外泄。 上游的批发价、折扣等成本信息仅在运营控制台可见，不随数据平面返回；客户侧的计量与计费一律以统一计价词元口径折算，与上游批发口径无关。

3. 分组、优先级与权重

三个路由配置项共同决定一次查询如何在多个候选上游间落地：

查询（带分组归属）
   │
   ▼
按 group 筛选候选上游 ──► 候选集
   │
   ▼
按 priority 取最高优先级层 ──► 同级候选
   │
   ▼
按 weight 加权择优 ──► 选定上游
   │
   ▼
健康检查 ──► 通过则转发；不通过则降级到下一优先级

分组（group）： 路由的第一道筛选。未指派分组的上游不参与该分组路由。
优先级（priority）： 同分组内分层。高优先级先用，低优先级仅在高优先级全部不可用时承接。
权重（weight）： 同优先级内的流量比例。多个同级候选按权重加权择优，承接相应比例的查询。

配置可随时通过 PUT /api/v1/providers/{providerId} 调整，即时生效：

curl https://your-platform/api/v1/providers/<上游标识> \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{
    "priority": 2,
    "weight": 3,
    "status": "active"
  }'

4. 模型池准入判定

接入的模型须通过模型池准入才会承接流量。准入依据每个模型的智能水平指数，由平台在接入时自动测算并登记。

curl https://your-platform/api/v1/model-pool \
  -H "Cookie: <控制台会话凭证>"

{
  "items": [
    {
      "model": "<模型中性名>",
      "source": "self",
      "intelligence_index": 0,
      "admitted": true,
      "tier": "strong"
    }
  ]
}

字段	含义
`intelligence_index`	模型综合智能水平指数（接入时自动测算）
`admitted`	是否通过模型池准入门槛、纳入可路由池
`tier`	池内分档（强档 / 中位），强档与中位分设独立门槛

门槛口径以协议与控制台为准。 智能水平指数的具体门槛、强档与中位的分界属于服务质量约定，不在文档中固化。当期门槛与各模型实测指数以「模型接入」页模型池面板显示为准；该指数与「模型评测」页的模型池能力维度同源。

5. 接入探测与故障转移

平台对每个上游维护"已接入 · 可用"的探测状态，并在运行时对每次路由做健康检查。

接入或变更后做一次探测：

curl https://your-platform/api/v1/providers/<上游标识>/probe \
  -X POST \
  -H "Cookie: <控制台会话凭证>"

{
  "provider_id": "<上游标识>",
  "status": "available",
  "probe_latency_ms": 0,
  "probed_at": "<探测时间>"
}

运行时，路由中间件在选用候选后做健康检查；不健康的上游被短路熔断，按优先级降级到下一候选。一次请求若发生重试或降级，其逐次尝试链落入路由轨迹：

curl "https://your-platform/api/v1/monitor/route-trail?start=<起>&end=<止>" \
  -H "Cookie: <控制台会话凭证>"

路由轨迹记录"选定模型 / 重试次数 / 故障转移序号"等尝试信息，是多上游路由可追溯的依据。监控数据与逐条调用记录取自同一份用量底座，跨页面核对时两处数字一致。

6. 启停与变更

操作	端点	行为
启停	`PUT /api/v1/providers/{providerId}`（`status` 字段）	停用后该上游不再参与路由，已配置不丢失
改优先级 / 权重	`PUT /api/v1/providers/{providerId}`	即时生效，不影响在途请求
改模型范围	`PUT /api/v1/providers/{providerId}`（`models` 字段）	调整该上游对外供给的中性名清单

变更上游配置不影响其承接过的历史用量记录——逐条调用记录为只增不改，路由变更只影响后续请求的调度。

各上游类型在上述通用规则之上的差异（协议类型取值、模型映射要点），见自有供应模型、OpenAI 兼容接入、Anthropic 兼容接入、Gemini 兼容接入。