模型供应商接入与多通道凭证池

模型供应商管理（Provider Management）是 OmniCortex 的全球主流商用大模型与企业私有算力引擎的统一接入底座。它将公有商业云（OpenAI、Anthropic、Gemini、阿里云百炼、智谱等）与企业自建算力（vLLM、Ollama、SGL）纳管在同一套调度框架下，建立企业级多通道物理凭证池，通过加权随机算法、通道并发排队削峰、周期用量硬熔断与内网防 SSRF 保护，构建高韧性的大模型算力供给管道。

---

核心机制与调度原理

1. 多通道加权随机调度 (Weighted Random Selection)

在企业高并发生产场景下，单一物理 API Key 极易触发供应商账号级速率限制（429 Too Many Requests）或账号风控封禁。OmniCortex 支持为单一供应商绑定多张物理凭证并组建通道池，通过加权随机算法无偏分发流量：

⚖️

多通道加权随机选路 (Weighted Random Key Pool)

单一供应商聚合多张物理凭证，动态打散并发请求，突破单账号 429 速率瓶颈

并发削峰 · 账号级高可用

通道 A · 企业专线主凭证权重 3.0 (约 60% 流量)

Key-Corp-Primary (高配额)

• 白名单约束：专供 gpt-4o 等旗舰模型
• 调度策略：高并发优先倾斜，保障关键业务响应

通道 B · 弹性补充凭证权重 1.5 (约 30% 流量)

Key-Elastic-Sub (标准配额)

• 承接范围：全模型通用通行
• 调度策略：平滑分摊主通道压力，消除脉冲峰值

通道 C · 应急低频凭证权重 0.5 (约 10% 流量)

Key-Backup-Standby (保底)

• 故障自愈：遇到 401 封禁或 429 熔断时秒级顶上
• 动态探测：异常通道自动剔除，恢复后自动入列

2. 公私异构算力融合与实体多模自适应

网关对公有商业 API 与企业自建私有化引擎进行了统一抽象，前端控制台与后端接入层对凭证实体进行多模自适应：

• 商业公有云：抽象为 密钥通道 (Key)，支持配置物理 API Key 与账号标签；
• 企业私有 vLLM：自适应为 模型引擎 (Engine)，承接本地显卡集群部署的推理服务；
• 本地 Ollama / SGL：自适应为 节点服务 (Server)，提供免 Key 模式的物理端点代理。

对外统一暴露标准 OpenAI 兼容协议，业务端无需关注底层是第三方商业 API 还是私有 GPU 节点。

3. 并发队列隔离与缓冲削峰 (Peaking & Concurrency Isolation)

为防止突发营销活动或批量离线分析产生的脉冲式流量冲垮上游通道，网关在通信层实现分层隔离与缓冲保护：

• 独立协程池与管道隔离：每个 Provider 拥有独立的 Worker 协程池与通信 Channel，某一供应商的链路超时或服务雪崩完全物理隔离在专属管道内，绝不阻塞其他供应商；
• 并发排队缓冲削峰：支持设定供应商的最大并发连接数上限。超出并发承载能力的突发流量在网关内部队列有序等待吐纳，通过平滑削峰消除 429 拒收。

4. 周期用量硬熔断与流控门控 (Usage Circuit Breaker)

为彻底杜绝客户端递归 Bug、死循环调用或恶意刷量对企业算力造成的异常冲击，系统提供底层硬熔断机制：

• 周期用量硬熔断：支持为指定供应商设置重置周期（1 小时、1 天、1 周、1 个月、1 年）内的用量上限阈值（Budget Limit）。一旦累积达到上限，网关在毫秒内触发硬熔断，立即拦截后续请求；
• 供应商级速率门控 (RPM/TPM)：支持直接在供应商维度配置每分钟请求数（RPM）与每分钟 Token 数（TPM）上限，确保网关出向流量严格收敛在上游合同许可阈值内。

5. 主动健康心跳探测与自愈 (Active Health Probes)

网关后台运行独立的健康监控协程，提供全自动化的链路探测与亚健康故障隔离：

• 定时连通性探测：定期向上游发送轻量级探活包，验证物理端点与物理 Key 的实时可用性；
• 亚健康动态摘除与自动恢复：当某张 Key 或私有节点发生网络超时、证书失效或连续返回 5xx 达到阈值时，网关自动将其从活跃调度池中临时摘除；当后台探活确认节点自愈后，自动将其重新拉回轮询池，实现全流程无人值守自愈。

6. 内网边界防 SSRF 保护与企业正向代理

针对金融与政企等高度隔离的私有化网络拓扑，网关提供出向边界安全管控：

• 默认防 SSRF 私网阻断：网关出向默认严禁访问 10.0.0.0/8、172.16.0.0/12、192.168.0.0/16 及 127.0.0.1 等私有网段。仅当管理员在供应商网络配置中显式开启 allow_private_network 时，才允许向自建 vLLM/Ollama 私网地址建立连接，从源头封堵内网横向穿透风险；
• 企业前置代理拓扑：支持配置 HTTP、HTTPS 及 SOCKS5 正向代理服务器，支持配置代理认证凭证及加载企业私有 CA 根证书完成双向 TLS 验签。

7. 离线批处理专道分流 (Batch API Dedicated Route)

针对知识库嵌入向量化、离线质检评估等非实时、高耗时的大批量请求，网关支持将其分流至专用的离线批处理通道（Batch Channel），保障前台用户的实时交互式会话享有绝对优先的带宽与并发配额。

---

控制台配置

管理入口：模型与治理 ➔ 供应商管理 (/model/provider)。

1. 供应商管理全景与网络概览

左侧导航展示全量纳管的供应商清单（支持搜索与状态统计），右侧展示选中供应商的基础信息、在线状态、协议格式、Base URL 与默认超时设定。

📸 截图替换指引（图 1：供应商管理全景与网络概览）

• 需截图内容：登录控制台，进入「模型与治理」→「供应商管理」（/model/provider），在左侧选中具体供应商（如 OpenAI），右侧呈现默认全景视图。
• 关键画面要素：
  1. 左侧供应商导航栏：展示配置总数统计徽标（如 20+）、关键词搜索输入框、各厂商图标及 ONLINE 状态标签；
  2. 右侧顶部概览 Header：供应商大图标、在线状态、协议格式、Base URL 地址、默认超时标签及右侧「配置」「删除」操作按钮；
  3. 三大选项卡导航条：高亮「凭证与密钥通道 (Keys)」、旁侧「管控与用量 (Governance)」、「网络与代理拓扑 (Network & Proxy)」。
• 推荐保存路径：
  • 中文版：Documentation/docs/public/images/providers/zh/provider-overview.png
  • 英文版：Documentation/docs/public/images/providers/en/provider-overview.png

2. 多凭证加权通道池与探活维护

在「凭证与密钥通道 (Keys)」选项卡中，维护物理 Key 资源池、调度权重与模型映射。

📸 截图替换指引（图 2：多凭证加权通道池与探活列表）

• 需截图内容：在供应商详情中停留在「凭证与密钥通道 (Keys)」Tab，展示该供应商下配置的多张物理 Key。
• 关键画面要素：
  1. 顶部操作条：包含「+ 添加凭证」按钮及「全量模型探活」操作按钮；
  2. 密钥表格主体：包含凭据名称（Key Name）、脱敏物理密钥、调度权重（Weight，如 1.0、2.0）、适用模型标签组（Models）、状态切换开关（Active/Disabled）；
  3. 操作列按钮：单 Key 探活、编辑与删除图标。
• 推荐保存路径：
  • 中文版：Documentation/docs/public/images/providers/zh/keys-table.png
  • 英文版：Documentation/docs/public/images/providers/en/keys-table.png

点击「添加凭证」或已有通道的「编辑」按钮，可在抽屉中设定通道名称、安全凭据、调度权重及模型绑定范围。

📸 截图替换指引（图 3：凭证添加与加权模型绑定抽屉）

• 需截图内容：点击「+ 添加凭证」或某张 Key 的「编辑」按钮，右侧滑出的密钥配置抽屉。
• 关键画面要素：
  1. 抽屉顶部标题：显示「添加凭证通道」或「编辑凭证通道」；
  2. 核心表单项：凭据名称输入框（name）、物理密钥/连接地址输入框（key）、调度权重数字滑块/输入框（weight）、模型绑定多选选择器（models）；
  3. 底部操作按钮：「取消」与「确认保存」。
• 推荐保存路径：
  • 中文版：Documentation/docs/public/images/providers/zh/key-drawer.png
  • 英文版：Documentation/docs/public/images/providers/en/key-drawer.png

3. 网络连接、代理拓扑与防 SSRF 配置

点击供应商详情右上角的「配置」按钮，可调整通信网络参数、代理服务及内网安全开关。

📸 截图替换指引（图 4：网络连接、代理拓扑与防 SSRF 配置抽屉）

• 需截图内容：点击供应商详情右上角的「配置」按钮，右侧滑出 720px 高级网络配置抽屉（展示 Network Tab 或 Proxy Tab）。
• 关键画面要素：
  1. 抽屉顶部与导航 Tab：包含 Network、Proxy、Performance、Governance 等标签；
  2. 网络核心表单输入区：Base URL 输入框、默认请求超时滑块（如 60s）、最大重试次数与退避基数（retry_backoff_initial / retry_backoff_max）、私有网络访问开关（allow_private_network 防 SSRF）；
  3. 代理配置表单区：代理协议类型选择器（HTTP/HTTPS/SOCKS5）、代理服务器 URL 与 CA 证书上传。
• 推荐保存路径：
  • 中文版：Documentation/docs/public/images/providers/zh/network-drawer.png
  • 英文版：Documentation/docs/public/images/providers/en/network-drawer.png

4. 周期用量硬熔断与流控看板

在「管控与用量 (Governance)」选项卡中，查看当前周期内该供应商的调用量消耗态势，并设定硬熔断阈值与速率限制。

📸 截图替换指引（图 5：供应商周期用量熔断与流控看板）

• 需截图内容：在供应商详情中切换至「管控与用量 (Governance)」Tab。
• 关键画面要素：
  1. 用量与限流指标卡片：展示当前周期已消耗额度与调用统计卡片；
  2. 周期重置设置看板：展示每小时/每天/每月重置周期与用量硬熔断上限（Budget Limit）；
  3. 速率限制规则：展示供应商级 RPM（每分钟请求数）与 TPM（每分钟 Token 数）阈值。
• 推荐保存路径：
  • 中文版：Documentation/docs/public/images/providers/zh/governance-panel.png
  • 英文版：Documentation/docs/public/images/providers/en/governance-panel.png

---

核心配置项规格参数表

配置参数 / 字段	数据类型	默认值 / 约束	语义作用与工程建议
name	字符串	必填	凭证通道标识（如 openai-prod-key-01），便于链路排错与审计追溯。
key	字符串	必填	上游物理 API Key、vLLM Engine 地址或 Ollama Server 节点地址。
weight	浮点数	默认 1.0 (0.1 ~ 100.0)	加权调度权重，数值越大承接的流量比例越高。
models	字符串数组	默认空 (全量支持)	限制此凭证仅服务于白名单模型，实现物理 Key 的专线专享。
default_request_timeout_in_seconds	整数 (秒)	默认 60	端到端单次请求最大超时时间，防挂死连接。
max_retries	整数	默认 0 (推荐 2~3)	网络抖动或 429 瞬态错误时的自动重试次数。
allow_private_network	布尔值	默认 false	防 SSRF 保护核心开关。对接本地私有引擎时必须显式开启。
proxy_config.type	枚举	none / http / https / socks5	企业出向代理类型，支持受限内网环境通过专用通道出网。
budget.limit	浮点数	可选	周期用量硬熔断阈值，达到上限后毫秒级阻断，防死循环刷量。

---

常见异常排查与故障处理

聚焦于凭证调度、上游连通性与网络边界防御相关的深度异常。

现象 / 错误码	根因排查方向	推荐处理方案
429 Rate Limit (单 Key 瞬时超限)	当前被挑中的物理 Key 触发了上游供应商的单账号并发或速率限制。	1. 网关将自动退避并尝试挑选同 Provider 下其他可用 Key； 2. 在密钥通道列表中调小该 Key 的权重，或追加新的 Key 凭证打散流量； 3. 在高级网络配置抽屉中配置 max_retries 与 retry_backoff_max。
502 Upstream Credentials Exhausted	供应商下的所有物理 Key 均不可用（全部处于停用状态、配额冻结或处于亚健康摘除态）。	1. 检查密钥列表中各通道的 Active 开关状态； 2. 点击「全量模型探活」验证上游连接状态； 3. 检查是否存在模型绑定限制导致当前请求无匹配 Key。
SSRF Blocked: Private IP Access Denied	对接内网私有模型引擎（如 http://192.168.1.100:8000）时请求被网关安全防御拦截。	1. 网关默认策略阻断所有私有网段的出向请求，防止内网横向探测； 2. 打开该供应商的高级网络配置抽屉，显式勾选「允许访问私有网络 (allow_private_network)」。
504 Gateway Timeout (私有引擎不可达)	vLLM 或 Ollama 引擎负载过载、GPU 显存溢出或物理网络不可达。	1. 检查自建模型引擎服务容器存活状态与显存占用； 2. 在网络配置中适当增加 default_request_timeout_in_seconds 阈值； 3. 若启用了企业前置代理，核对正向代理认证凭证及 SOCKS5 代理连通性。