多上游模型接入

自有供应模型与第三方兼容接入的总览——双层接入结构、模型池准入门槛、上游到模型到分组的路由配置，以及接入探测与故障转移

灵渠平台聚合两类上游：自有供应模型（含自托管）与第三方兼容接入（OpenAI / Anthropic / Gemini 规范）。两类上游接入后统一进入同一个模型池，由路由中间件按分组、优先级与权重择优调度，对客户应用只暴露一套兼容主流大模型协议的统一查询入口与一组中性模型名。本节讲清这套接入体系的整体结构与配置方式，并按上游类型分子页给出各自的接入步骤与配置示例。

双层接入结构

无论上游来自哪一类供应方，灵渠都以同一套"上游 → 接入密钥 → 模型 → 分组路由"的层级把它纳入统一调度。两层接入的差别只在"如何把请求翻译成上游能理解的协议"，纳入模型池之后的路由、计量、护栏治理完全一致。

接入层	涵盖范围	协议处理	典型场景
自有供应模型	平台自有或自托管部署的模型实例	平台直接以原生协议对接	私有部署的模型、专用环境上的模型实例
第三方兼容接入	遵循 OpenAI / Anthropic / Gemini 规范的外部上游	平台按各规范做请求/响应格式转换，对外仍以统一入口呈现	复用既有第三方模型服务，按规范一键纳管

统一对外、分层对内。 客户应用始终只面对一套 OpenAI 兼容的 /v1/chat/completions 入口与中性模型名，感知不到背后接的是自有还是第三方上游。两层接入的差异被平台的协议适配层吸收，不向数据平面泄漏。

接入到调度的全流程

一个上游从登记到承接流量，经过六个环节。前四步是接入配置，后两步是平台在每次请求时自动施加的运行时治理。

① 登记上游        填写上游来源（自有/第三方）、协议类型、对外模型清单
   │
   ▼
② 接入探测        连通性自检，记录探测耗时，确认「已接入 · 可用」
   │
   ▼
③ 模型池准入      按智能水平指数判定模型是否进入可路由模型池
   │
   ▼
④ 路由配置        指派分组、设置优先级与权重，决定哪些查询可命中本上游
   │
   ▼
⑤ 加权择优        路由中间件在同分组、同优先级内按权重择优选定上游（运行时）
   │
   ▼
⑥ 重试与故障转移   选定上游不可用时按优先级降级到下一候选（运行时）

前四步在运营控制台「模型接入」页完成，对应控制平面 /api/v1/providers 与 /api/v1/model-pool 一组端点；后两步由路由中间件在数据平面每次请求时自动执行，可在「请求监控」页查看路由轨迹与故障转移记录。

模型池准入门槛

并非所有接入的模型都会立即承接流量。每个模型在接入时由平台按其智能水平指数自动判定是否进入可路由模型池——这是一道质量闸门，确保模型池整体保持在约定的能力水平之上，路由中间件才会把查询分流给它。

判定项	说明
智能水平指数	模型综合能力的量化指标，接入时自动测算并登记
池准入判定	指数达到模型池准入门槛的模型纳入可路由池；未达门槛的模型可接入但不参与路由
强档 / 中位约束	模型池对强档模型与池中位分别设独立门槛，保证池内高端与整体水位双线合规

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

路由配置：分组、优先级与权重

接入并通过准入后，上游通过三个配置项被编入路由：

配置项	作用	取值与行为
分组（`group`）	决定哪些查询可命中本上游	路由中间件先按分组缩小候选集，未指派分组的上游不参与该分组的路由
优先级（`priority`）	同分组内的候选排序	高优先级先被选用；仅当高优先级候选全部不可用时才降级到低优先级
权重（`weight`）	同优先级内的流量分配	在同一优先级的候选间按权重加权择优，权重越高承接流量比例越大

这三项共同构成一条可解释的路由决策链：分组筛选 → 优先级择层 → 权重择优 → 健康检查 → 必要时降级。配置变更即时生效，无需重启上游接入。

路由仅做调度，不改写内容。 路由中间件依据上述配置选定上游模型并转发请求，生成由所选定的上游模型完成；平台对路由决策与故障转移负责，对生成内容不做实质性加工。能力边界详见中间件管道与扩展点 SDK。

接入探测与故障转移

平台对每个上游维护"已接入 · 可用"的探测状态。接入或变更配置后可手动触发一次探测，记录探测耗时；运行时路由中间件也会在选用前做健康检查。

接入探测： POST /api/v1/providers/{providerId}/probe 对指定上游做一次连通性自检，返回可用状态与探测耗时，结果回填到「模型接入」页列表。
运行时健康检查： 每次路由选定候选后，对不健康的上游短路熔断，按优先级降级到下一候选。
故障转移轨迹： 一次请求若发生重试或降级，其逐次尝试链（选定模型、重试次数、故障转移序号）落入路由轨迹，可在「请求监控」页（GET /api/v1/monitor/route-trail）逐条查看。

上游列表端点速览

「模型接入」页与其配置动作由下列控制平面端点支撑，可见侧均为运营控制台（operator）。各端点的字段与按上游类型的差异，见下方子页。

方法	路径	用途
GET	`/api/v1/providers`	上游接入列表（自有 / 第三方分区，含状态、模型、分组、优先级·权重、探测耗时）
POST	`/api/v1/providers`	接入新上游
PUT	`/api/v1/providers/{providerId}`	变更上游接入配置（启停 / 优先级 / 权重 / 模型范围）
POST	`/api/v1/providers/{providerId}/probe`	接入探测（连通性 + 探测耗时）
GET	`/api/v1/model-pool`	模型池清单与准入门槛判定（智能水平指数）

本节子页

子页	内容
通用接入规则	接入字段、分组与权重、准入判定、探测与故障转移的统一规则，所有上游类型共用
自有供应模型	自有及自托管模型实例的接入步骤与配置示例
OpenAI 兼容接入	遵循 OpenAI 规范的第三方上游接入与映射要点
Anthropic 兼容接入	遵循 Anthropic 规范的第三方上游接入与映射要点
Gemini 兼容接入	遵循 Gemini 规范的第三方上游接入与映射要点

接入配置完成后，模型即以中性名出现在数据平面 GET /v1/models 与逐条调用记录中；上游的批发价等成本口径仅在运营控制台可见，不随数据平面返回给客户应用。完整端点契约见 API 参考。