提供商路由

Alephant Provider Routing 是智能体财务网关中的模型路由层。它让智能体、工作流和应用使用一套熟悉的 API 接口，同时由 Alephant 在 AI 提供商、模型和自定义后端之间路由请求。

Alephant 中的路由不只是提供商转发。它是连接模型选择、提供商访问、Agent ID、Run ID、预算策略、回退行为、Token 记账、请求可观测性和成本归因的决策层。

每个经路由的请求都可以：

• 解析到正确的提供商和模型
• 根据工作区、密钥、用户、智能体、会话和模型策略进行检查
• 通过正确的提供商适配器进行分发
• 按配置进行重试或故障转移
• 标准化为 OpenAI 风格响应
• 记录提供商、模型、Token、成本、延迟、缓存、重试和追踪元数据

提供商路由为何重要

生产级 AI 系统很少只使用一个模型或一家提供商。

团队可能使用 OpenAI 处理通用聊天、Anthropic 处理推理、Gemini 处理长上下文、Bedrock 用于企业部署、Ollama 用于本地模型，并使用自定义端点进行私有推理。没有网关时，每个智能体和应用都必须管理提供商特有的 SDK、模型名称、凭证、错误格式、用量字段、重试行为和成本报告。

Alephant 为团队提供统一的模型流量路由层，并带有足够的智能体上下文，可回答哪次运行产生了成本、应用了哪项策略，以及接下来应如何处理。

路由接口

Alephant 支持多种路由接口，取决于你希望在请求时拥有多大的控制权。

对大多数应用而言，请从 /v1/* 和带提供商前缀的模型名称开始。

1
curl https://ai.alephant.io/v1/chat/completions \
2
3
  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
4
  -H "Content-Type: application/json" \
5
  -d '{
6
    "model": "openai/gpt-4o-mini",
7
    "messages": [
8
      { "role": "user", "content": "Write a short product summary." }
9
    ]
10
  }'

模型命名

Alephant 使用模型名称来解析目标提供商。

带提供商前缀的模型 ID

当希望请求发送到特定提供商时，请使用 provider/model_id。

1
{
2
  "model": "openai/gpt-4o-mini"
3
}

示例：

openai/gpt-4o-mini
anthropic/claude-3-5-sonnet
google/gemini-1.5-pro
bedrock/anthropic.claude-3-5-sonnet
ollama/llama3.1

带提供商前缀的模型 ID 是生产流量最清晰的选择，因为它明确表达了路由意图。

裸模型 ID

当模型恰好映射到一个已知提供商时，Alephant 也可以解析裸模型 ID。

1
{
2
  "model": "gpt-4o-mini"
3
}

如果裸模型是唯一的，Alephant 会在内部将其扩展为规范的 provider/model 形式。

gpt-4o-mini -> openai/gpt-4o-mini

如果同一模型 ID 存在于多个提供商下，Alephant 会返回 400 Bad Request 并要求指定提供商。

1
{
2
  "error": {
3
    "message": "Ambiguous model 'gpt-4o': matches multiple providers. Please specify one of: openai/gpt-4o, azure/gpt-4o",
4
    "type": "invalid_request_error",
5
    "code": "ambiguous_model"
6
  }
7
}

请求生命周期

经路由的请求会经过相同的网关生命周期：

1. 接收请求
   你的应用、智能体或工作流向 Alephant 发送模型请求。
2. 验证密钥
   Alephant 验证 Virtual Key，并加载工作区、用户、智能体、会话和密钥元数据。
3. 解析提供商和模型
   Alephant 从请求路径、路由器 ID、带提供商前缀的模型、裸模型 ID 或密钥绑定的提供商配置中解析提供商。
4. 在分发前检查策略
   在产生任何上游提供商成本前，Alephant 会评估模型允许列表、提供商访问权限、速率限制、预算规则、并发限制和路由级策略。
5. 适配并分发
   Alephant 将 OpenAI 风格请求映射为所选提供商的格式，调用上游提供商，并在配置后应用重试或回退行为。
6. 标准化响应
   提供商特有的响应、用量字段、错误、流式事件和结束原因会被标准化为一致的网关响应。
7. 记录成本和追踪元数据
   Alephant 记录提供商、模型、Token、成本、延迟、状态码、缓存状态、重试次数、回退路径、Agent ID、Run ID、会话、用户和工作区元数据。

策略感知路由

提供商路由与 Alephant 的策略和预算控制相连。

在向提供商分发前，Alephant 可以实施：

• 工作区级提供商访问权限
• Virtual Key 范围内的提供商访问权限
• 模型允许列表和拒绝列表
• 智能体级模型规则
• 成员或团队级预算
• 每个会话的预算上限
• 速率限制和并发控制
• 路由特定的回退或降级规则

这意味着路由可以回答技术和财务两类问题：

• 此密钥能否使用该提供商？
• 此智能体能否调用该模型？
• 工作区是否仍在预算范围内？
• 此请求应被阻止、限流、降级还是正常路由？
• 哪一项提供商/模型决策产生了最终成本？

回退与可靠性

提供商路由还可支持可靠性行为。

配置后，Alephant 可以重试失败的上游调用，或回退至另一个模型或提供商。这在提供商不可用、被限流、过载或返回瞬态错误时很有用。

回退链示例：

openai/gpt-4o-mini -> anthropic/claude-3-5-haiku -> groq/llama-3.1-70b

系统会记录回退决策，以便仪表板展示实际为请求提供服务的模型，以及回退如何影响延迟、成本和可靠性。

有关成本感知路由、回退链和路由指标，请参见 路由优化。

路由与成本归因

每项路由决策都会成为 Alephant 成本台账的一部分。

针对每个请求，Alephant 可以展示：

• 请求的模型
• 解析后的提供商
• 解析后的模型
• 重试或回退后最终使用的提供商
• 输入 Token
• 输出 Token
• Token 总成本
• 缓存命中或未命中
• 延迟
• 状态码
• 工作区
• Virtual Key
• 用户或团队成员
• 智能体
• 会话
• 提示词或工具调用元数据

这让工程和财务团队都能看到提供商路由。

示例

OpenAI SDK 请求

1
import OpenAI from "openai";
2
3
const client = new OpenAI({
4
  baseURL: "https://ai.alephant.io/v1",
5
  apiKey: process.env.ALEPHANT_VIRTUAL_KEY,
6
  defaultHeaders: {
7
    "Alephant-Agent-Id": "agt_support_bot_8f3a",
8
    "Alephant-Run-Id": "run_support_summary_001",
9
  },
10
});
11
12
const response = await client.chat.completions.create({
13
  model: "openai/gpt-4o-mini",
14
  messages: [
15
    { role: "user", content: "Summarize this support conversation." },
16
  ],
17
});

裸模型自动解析

1
{
2
  "model": "gpt-4o-mini",
3
  "messages": [
4
    { "role": "user", "content": "Explain gateway routing." }
5
  ]
6
}

如果 gpt-4o-mini 在模型目录中是唯一的，Alephant 会自动解析它。

显式提供商路由

1
{
2
  "model": "anthropic/claude-3-5-sonnet",
3
  "messages": [
4
    { "role": "user", "content": "Review this architecture decision." }
5
  ]
6
}

当需要确定性的提供商选择时，请使用显式提供商路由。

推荐用法

生产工作负载请使用带提供商前缀的模型 ID。

provider/model_id

当希望获得更简单的开发者体验且模型名称不存在歧义时，请使用裸模型 ID。

当路由应由工作区策略集中控制，而非硬编码在应用代码中时，请使用已配置的路由器。

仅当有意需要明确的上游行为时，才使用直接提供商透传。

常见问题

Alephant 只是一个模型代理吗？

不是。Alephant 会路由请求，但也会在网关路径中应用策略、预算控制、提供商适配、重试和回退行为、成本归因与可观测性。

一个应用可以使用多个提供商吗？

可以。单个智能体、工作流或应用可通过 Alephant 发送请求，并通过更改模型值或使用已配置的路由器选择不同提供商。当包含 Agent ID 和 Run ID 上下文时，同一项路由决策也会关联到成本、策略和追踪元数据。

如果模型不被允许，会怎样？

Alephant 会在将请求分发给提供商前拒绝它。这会阻止不允许的提供商使用，并避免产生上游成本。

如果模型名称有歧义，会怎样？

Alephant 会返回 400 Bad Request 并要求指定提供商，例如 openai/gpt-4o 或 azure/gpt-4o。

路由会影响可观测性吗？

会。Alephant 会同时记录请求的模型和解析后的提供商/模型，使团队能准确了解每个请求如何被路由以及花费了多少成本。