> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# 提供商路由

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

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

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

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

## **提供商路由为何重要**

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

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

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

## **路由接口**

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

| **接口**                     | **用例**                              |
| -------------------------- | ----------------------------------- |
| /v1/\*                     | 为现有 OpenAI SDK 和智能体客户端提供网关访问        |
| model="provider/model\_id" | 从 OpenAI 风格请求中明确选择提供商和模型            |
| model="model\_id"          | 当裸模型 ID 映射到一个已知提供商时，由 Alephant 进行解析 |
| /router/\{id}/\*           | 通过已配置的策略路由器进行路由                     |
| /\{provider}/\*            | 为明确的上游控制直接透传至提供商                    |

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

```typescript
curl https://ai.alephant.io/v1/chat/completions \

  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      { "role": "user", "content": "Write a short product summary." }
    ]
  }'
```

## **模型命名**

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

### **带提供商前缀的模型 ID**

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

```typescript
{
  "model": "openai/gpt-4o-mini"
}
```

示例：

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。

```typescript
{
  "model": "gpt-4o-mini"
}
```

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

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

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

```typescript
{
  "error": {
    "message": "Ambiguous model 'gpt-4o': matches multiple providers. Please specify one of: openai/gpt-4o, azure/gpt-4o",
    "type": "invalid_request_error",
    "code": "ambiguous_model"
  }
}
```

## **请求生命周期**

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

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`

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

有关成本感知路由、回退链和路由指标，请参见 [路由优化](/ai-gateway/routing-optimization)。

## **路由与成本归因**

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

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

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

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

## **示例**

### **OpenAI SDK 请求**

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://ai.alephant.io/v1",
  apiKey: process.env.ALEPHANT_VIRTUAL_KEY,
  defaultHeaders: {
    "Alephant-Agent-Id": "agt_support_bot_8f3a",
    "Alephant-Run-Id": "run_support_summary_001",
  },
});

const response = await client.chat.completions.create({
  model: "openai/gpt-4o-mini",
  messages: [
    { role: "user", content: "Summarize this support conversation." },
  ],
});
```

### **裸模型自动解析**

```typescript
{
  "model": "gpt-4o-mini",
  "messages": [
    { "role": "user", "content": "Explain gateway routing." }
  ]
}
```

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

### **显式提供商路由**

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

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

## **推荐用法**

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

`provider/model_id`

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

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

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

## **常见问题**

### **Alephant 只是一个模型代理吗？**

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

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

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

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

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

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

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

### **路由会影响可观测性吗？**

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