供应商

Cordy Gateway 如何抵达 100+ 上游——LiteLLM 与直连的兼容 OpenAI 路径，以及如何在 Admin 中添加供应商、通道与模型。

Cordy Gateway 本身不托管模型。它把你客户端的请求路由到你所配置的上游供应商。本页介绍两条集成路径、受支持的上游，以及如何在 Admin 中接线一个供应商、通道与模型。

两条集成路径

每个通道通过以下两条路径之一抵达其上游：

  1. LiteLLM——默认路径，通过单一集成即可访问 100+ 家供应商与模型。它把各供应商的 API 归一化为 OpenAI 形态。
  2. 直连的兼容 OpenAI 透传——对于已经使用 OpenAI Chat Completions API 的上游，网关通过池化的 httpx 客户端转发请求，不做翻译。在通道 config 中设置 openai_passthrough = true 即可按通道启用，覆盖对话（一元与流式）、嵌入与文本补全。

对 vLLM、火山引擎 Ark、Vercel AI Gateway 或任何自托管的兼容 OpenAI 服务器等兼容 OpenAI 端点，使用直连路径。其余一切使用 LiteLLM。

受支持的上游

以下供应商类型开箱即被识别。由于供应商类型是自由格式的大写标记，只要 LiteLLM 或直连路径支持该集成，运维人员无需改代码即可添加新上游。

  • OpenAI
  • Anthropic
  • Azure OpenAI
  • AWS Bedrock
  • Google Vertex / Gemini
  • Cohere
  • Groq
  • Together AI
  • DeepInfra
  • OpenRouter
  • Mistral
  • DeepSeek
  • Hugging Face
  • Replicate
  • Ollama（自托管）
  • 任何经直连路径接入的兼容 OpenAI 服务器（vLLM、火山引擎 Ark 等）

配置链

服务一个模型需要一小组记录，在 Admin 的 Gateway Configuration 下一次性创建：

Provider → Public model → Provider model → Channel → Channel-provider-model

它们在请求时如何解析见核心概念。以下步骤按序构建它们。

1. 添加供应商

为上游厂商创建一个 Provider：

  • name——唯一的内部名，例如 openai-main。
  • provider_type——大写标记，例如 OPENAI、ANTHROPIC、BEDROCK 或 CUSTOM。
  • base_url——可选；留空则使用供应商的默认端点。
  • status——ACTIVE。

供应商是全局系统资源。凭据不存放在供应商上——它们存放在其通道上。

2. 定义公开模型

创建一个 Public model——你客户端将在 model 字段中请求的 slug：

  • slug——公开标识，例如 gpt-4o-mini。唯一。
  • display_name、description——用于目录。
  • status——ACTIVE；若希望出现在列表中则 is_public。

这是客户端唯一能看到的模型名。它由你掌控，无需匹配任何厂商的命名。

3. 映射供应商模型

创建一个 Provider model，把 Provider 与 Public model 关联到具体上游模型：

  • provider_model_name——真实厂商模型字符串，例如 gpt-4o-mini。
  • input_price、output_price——用于成本计量与成本感知路由。
  • supports_chat、supports_embeddings、supports_streaming、context_window——能力标志。
  • status——ACTIVE。

4. 添加通道

在供应商上创建一个 Channel——一个带自有凭据的具体路由目标：

  • 上游凭据——供应商 API 密钥。它以 Fernet 静态加密存储；保存后 Admin 绝不返回明文。对 Bedrock，AWS secret 以同样方式存储。
  • base_url / endpoint_url——覆盖上游端点（直连到诸如 vLLM 的自托管服务器时必填）。
  • weight——加权路由的相对份额（默认 100）。
  • priority——优先级更高的通道被优先选择；加权挑选在最高优先级带内进行（默认 0）。
  • region——例如 us-east，用于区域感知路由。
  • cost_weight——成本感知路由的价格乘子（>1 偏离，<1 偏向）。
  • rate_limit、concurrent_limit、timeout_seconds——按通道的守卫。
  • 冷却设置——可选地在反复出错后将抖动通道移出轮转。
  • status——ACTIVE。

对直连的兼容 OpenAI 上游，还需在通道 config 中设置 openai_passthrough = true。

5. 在通道上启用该模型

创建一个 Channel-provider-model，把 Channel 与 Provider model 绑定。这才真正在该通道上启用该模型。该供应商模型必须属于该通道所属的供应商——你不能把供应商 B 的模型绑定到供应商 A 的通道上。

一旦至少有一个活跃通道绑定到该模型，公开模型即变为可路由，并在 GET /v1/models 中对被允许使用它的密钥显示。

跨通道路由

由于一个公开模型可由多个通道提供服务，你可以：

  • 用 weight 在同一供应商的多个密钥或账户间负载均衡。
  • 用 priority 优先某个主通道，并自动回退到其他通道。
  • 当某个供应商宕机时完全故障转移到另一供应商——把同一公开模型绑定到不同供应商上的通道。
  • 用 cost_weight 配合 cheapest 策略按成本偏置。
  • 用 region 配合 region_aware 策略按区域路由。

路由策略由 GATEWAY_DEFAULT_ROUTING_STRATEGY 全局设置（默认 weighted），并可用 X-Routing-Strategy 请求头按请求覆盖：

策略选择
weighted优先级带内加权随机。
cheapest有效价格最低（cost_weight × 供应商模型价格）。
fastest观测 P95 时延最低；无数据时回退 weighted。
region_aware先区域匹配，再加权。

故障转移、冷却与熔断器见核心概念。

完整示例

服务一个公开模型 gpt-4o-mini，在一个 OpenAI 账户与一个自托管 vLLM 服务器之间负载均衡：

  1. Providers： openai-main（provider_type: OPENAI）与 vllm-local（provider_type: CUSTOM）。
  2. Public model： slug gpt-4o-mini。
  3. Provider models： openai-main 下一个（provider_model_name: gpt-4o-mini），vllm-local 下一个（provider_model_name: 你所服务的模型名）。
  4. Channels： 带 OpenAI 密钥的 openai-main 通道；带指向 vLLM 服务器的 endpoint_url 且 config 中 openai_passthrough = true 的 vllm-local 通道。
  5. Channel-provider-models： 把每个通道绑定到其供应商模型。

客户端现在调用 model: "gpt-4o-mini"，网关便在 OpenAI 与 vLLM 之间均衡，若其一不可用则故障转移。

凭据安全

  • 客户端仅以 wnx_ 网关密钥鉴权。它们从不看到、发送或接收上游供应商密钥。
  • 上游凭据在通道记录中以 Fernet 加密存储，仅在派发请求时于内存中解密。见安全。
  • 轮换上游密钥是 Admin 中的一次通道编辑；无需任何客户端改动。

后续步骤

  • 核心概念——路由与故障转移如何工作。
  • 安全——凭据加密与信任模型。
  • 部署——规模化运行。