> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 路由与回退

> 了解 Gateway 如何选择提供商并确保请求可靠完成。

Phaseo Gateway 会将每个请求路由到能够提供所选模型的提供商。如果提供商响应缓慢、触发速率限制或返回错误，Gateway 可以尝试回退，以确保请求仍能完成。

## 选择路由模式

除非某项生产需求明显比其他需求更重要，否则请从 `balanced` 开始。

| 模式 | 适用场景 |
| - | - |
| `balanced` | 需要兼顾价格、延迟、吞吐量和可用性。 |
| `price` | 降低提供商成本比缩短响应时间更重要。 |
| `latency` | 尽快开始响应是首要需求。 |
| `throughput` | 持续提高 Token 生成速度最重要。 |

请在**控制台 -> 设置 -> 路由**中配置工作区默认值。如果某个工作流需要比工作区默认值更严格的提供商或模型策略，请使用预设。

### 模型路由后缀

如果希望模型 ID 本身决定此次请求的优化模式，请添加路由后缀：

| 后缀 | 路由模式 |
| - | - |
| `:nitro` | `throughput` |
| `:cheap` | `price` |
| `:fast` | `latency` |

例如，`openai/gpt-5-mini:nitro` 会优先考虑吞吐量。识别到的路由后缀优先于请求中的 `routing.mode` 或 `provider.sort`，也优先于预设和工作区路由模式。提供商允许列表、区域要求、护栏和价格上限等其他约束仍然有效。

## 路由的基本流程

* 你发送一个包含模型 ID 的请求。
* Gateway 评估提供商的健康状态、延迟和能力覆盖情况。
* Gateway 选择提供商并执行请求。

调试路由行为时，请查看活动日志和响应元数据中的请求结果。

## 使用自动路由器选择模型

自动路由目前处于 Alpha 阶段，仅对部分工作区开放。

当模型需要根据工作负载变化时，请使用 `phaseo/auto`。Phaseo 会从所有符合生产条件的文本模型开始，应用工作区约束，并构建适合当前工作负载的候选列表：

1. 打开**控制台 -> 设置 -> 路由 -> 自动路由**。
2. 选择优化均衡性能、质量、成本还是延迟。
3. 选择经济、标准、高级或不受限支出配置。这些配置会在评分前对输入和输出价格应用固定上限。
4. 可选：使用 `anthropic/*`、`openai/gpt-5.*` 等模式或精确模型 ID 缩小候选范围。
5. 选择在可重试错误发生后，Phaseo 是否可以尝试排名靠后的模型。
6. 保存配置。

这样，应用就可以选择使用自动路由器，而无需在每个请求中复制工作区路由策略：

```json theme={null}
{
  "model": "phaseo/auto",
  "input": "Review this TypeScript function for correctness."
}
```

请求不能更改工作区目标、支出配置或模型模式。指定固定模型的请求仍会绕过自动路由器。

优化目标会改变模型质量、提供商可靠性、延迟和价格的相对权重：

| 目标 | 适用场景 |
| - | - |
| `balanced` | 需要综合四项指标的实用默认值。 |
| `quality` | 相关基准测试的表现最重要。 |
| `cost` | 最低的预估输入和输出 Token 价格最重要。 |
| `latency` | 提供商近期延迟更低最重要。 |

支出配置会对标准层级设置硬性价格上限，单位为每百万文本 Token 的美元价格：

| 支出配置 | 输入价格上限 | 输出价格上限 |
| - | -: | -: |
| 经济 | \$0.10 | \$0.50 |
| 标准 | \$0.30 | \$1.50 |
| 高级 | \$1 | \$5 |
| 任意价格 | 无上限 | 无上限 |

自定义限制可直接设置输入和输出上限。没有已知标准文本价格的模型不会进入受管理的候选范围。

对于每个 `phaseo/auto` 请求，Phaseo 都会向固定的低成本分类模型发出一个普通的 Gateway 子请求。子请求使用相同的工作区和计费身份，会单独显示在请求日志中，并标记 `purpose=auto_routing_classifier` 和父请求 ID。分类器会返回结构化的工作负载组合、复杂度分数和置信度，但不会直接选择模型。

工具和结构化输出等确定的请求事实会作为可信元数据提供。如果分类器请求失败、超时或返回无效数据，Phaseo 会回退到本地确定性分类器，判断请求属于代码、推理、工具使用、结构化输出、翻译、摘要还是通用任务，而不会让生成请求失败。

分类器复杂度代表可能足以生成可靠且可接受答案的最低模型能力。Phaseo 会增加能力余量，然后结合基准适配度、工作区目标、价格、延迟、提供商健康状况和可靠性进行评分。分类器请求与选定的生成请求会通过常规 Gateway 流程分别计量。

评分前，每个允许的模型都必须通过常规的端点、工作区模型、提供商、隐私、护栏和熔断器检查。随后，路由器会将 Phaseo 目录中相关且非提供商自报的基准数据与 Phaseo 当前的提供商健康状况、延迟和价格结合起来。缺少基准或运行数据时按中性处理；这不会扩大允许列表。

响应中的 `model` 字段标识所选模型。请求详情会显示工作负载、目标、选定模型、回退顺序、候选和因素评分、基准 ID、排除项以及算法版本。路由跟踪不包含请求或响应内容。

如果工作区启用了模型回退，Phaseo 会在收到 `429`、`500`、`502`、`503` 或 `504` 后，按排名顺序重试其余模型。每次回退都会重新执行完整的策略和提供商选择流程。客户端错误不会切换模型。

已附加的动态路由若选择了固定模型，则该模型优先。在这种情况下，请求详情会记录该覆盖，且自动路由器对该请求禁用模型回退。

<Warning>
  支出配置和模型模式用于控制候选资格，不保证质量。请结合自己的工作负载验证最终的模型组合。
</Warning>

## 解释路由决策

打开**控制台 -> 设置 -> 使用情况 -> 请求日志**，选择一个请求，然后在**提供商响应**下展开**路由可观测性**。

请求日志会显示：

* 所有已排名的提供商及其最终得分
* Phaseo 选择的提供商以及尝试过的提供商
* 排名之前被排除的提供商及记录的原因
* 因发布或路由状态而被降级的提供商
* 为每个已排名提供商评分时使用的输入、权重、贡献和乘数

评分因素与记录的上下文分开显示。评分因素会改变当前路由模式的最终得分。记录的上下文有助于解释决策，但不一定会影响评分。

在 `balanced` 路由中，Phaseo 根据可靠性、延迟、尾部延迟、吞吐量、价格和 Token 适配度为合格提供商评分。显示的计算会说明每项因素如何影响最终得分，而不会把所有记录指标都视为同等重要。

### 可靠性与提供商运行时间

可靠性样本是评分所用的值，根据提供商的结果计算；成功率会作为补充上下文显示。

以下结果会降低提供商运行时间：

* 身份验证失败（`401`）
* 付款失败（`402`）
* 找不到模型的响应（`404`）
* 服务器错误（`500` 及以上）
* 响应流开始后的错误
* HTTP 响应成功但最终以错误原因结束

以下结果不会降低提供商运行时间：

* 错误请求（`400`）
* 地理位置限制（`403`）
* 载荷过大（`413`）
* 速率限制（`429`）

地理位置限制和速率限制会单独跟踪，因为它们并不表示提供商本身不可用。

### 跟踪数据的可用性与隐私

启用路由可观测性后发出的请求可以查看完整路由跟踪。较早的请求可能只有部分跟踪数据，也可能没有路由详情。

路由跟踪有明确边界，且不包含内容。它只包含解释提供商选择所需的数字和状态，不会将提示、消息或生成内容复制到跟踪记录中。

## 在模型 ID 中指定确切的提供商

如果请求必须使用某个特定的提供商和模型组合，请使用 `<provider-id>:<canonical-model-id>`：

```json theme={null}
{
  "model": "baseten:thinking-machines/inkling-small",
  "input": "Hello"
}
```

添加限定符会禁止该请求跨提供商回退。后缀仍是规范模型 ID 的一部分，例如 `baseten:google/gemma-4-26b-a4b:free`。

有关完整语法、免费路由验证、路由优先级、别名、错误代码和请求示例，请参阅[提供商限定的模型 ID](./provider-qualified-models.mdx)。

## 控制路由和回退

当前公开的路由和回退控制项是明确设置的：

### 预设限制回退范围

在**控制台 -> 设置 -> 预设**中，你可以定义：

* 允许使用的模型
* 提供商允许列表
* 提供商忽略列表
* 提示和参数的默认行为

这些约束会在选择提供商之前应用，因此预设可以有意缩小适用于重试和故障转移的提供商范围。

### 路由模式会更改提供商排名

在**控制台 -> 设置 -> 路由**中，工作区可以调整 Gateway 对兼容提供商的排序方式：

* `balanced`
* `price`
* `latency`
* `throughput`

同一页面还提供 Beta 和 Alpha 通道切换，以便有意引入预览流量，而不是让它作为未跟踪的路由副作用出现。

### BYOK 回退由你明确控制

在**控制台 -> 设置 -> BYOK**中，团队可以选择 BYOK 请求失败后是否允许改用 Phaseo 积分。这是当前面向常见问题“我自己的密钥失败了，请求是否仍应完成？”的公开控制项。

### 动态路由将策略绑定到 API 密钥

如果不同 API 密钥或请求类别需要不同的提供商行为，请在**控制台 -> 设置 -> 路由**中创建动态路由。路由可以：

* 根据嵌套请求正文字段、请求标头、自定义元数据、端点、模型或会话 ID 进行分支
* 按百分比分配流量，用于 A/B 测试和逐步发布
* 使用已验证密钥的使用量分桶来执行每日、每周或每月请求数和费用上限
* 调用其他模型，并选择该模型的路由模式、提供商偏好和回退策略
* 启用感知缓存和会话的提供商亲和性
* 附加到一个或多个推理 API 密钥

条件节点会提供 true 和 false 输出。速率和预算节点会提供未超限和已超限输出。对于会话或提示缓存密钥，百分比选择是确定性的，因此同一缓存对话在逐步发布期间不会随机切换分支。

保存后会创建不可变的草稿版本。部署选定版本会将该快照复制到 Gateway，并使已附加密钥的策略缓存失效。之前的版本仍可用于回滚。提供商健康状况的运行建议显示在**洞察**中，与流程编辑器分开。

OpenAI 兼容的文本推理接口支持自定义元数据：

```json theme={null}
{
  "model": "openai/gpt-5-mini",
  "metadata": {
	    "customer_plan": "pro",
	    "workspace": "acme"
  }
}
```

## 回退行为

如果提供商返回错误或速率限制，Gateway 可以重试，也可以将请求路由到支持同一模型的其他提供商。你仍应使用指数退避处理 `429` 和 `5xx` 响应。

动态路由中的模型节点还可以设置按顺序排列的回退模型列表。Phaseo 会先用完所选模型的所有合格提供商尝试。如果返回的响应可以重试（`429`、`500`、`502`、`503` 或 `504`），Gateway 会按顺序对每个回退模型重新执行完整的策略和提供商选择流程。客户端错误会立即返回，不会切换模型。

每个回退模型都会单独检查工作区模型限制、护栏、提供商策略、价格和能力支持情况。一条路由最多可以保存八个回退模型。

了解更多：

* [速率限制](../api-reference/limits.mdx)
* [错误处理](../api-reference/errors.mdx)

## 感知缓存和会话的亲和性

文本生成端点默认启用感知缓存的路由。提供商报告实际发生提示缓存读取后，如果该提供商仍然健康，且符合活动路由、预设、护栏和请求策略，Phaseo 会将匹配的上下文固定到该提供商 15 分钟。

如果请求包含 `session_id`，缓存亲和性会绑定到会话，而不只绑定到最初的上下文。Phaseo 观察到另一次缓存读取时会刷新亲和性，并在会话活动期间最多保留 24 小时。熔断器和策略过滤器始终优先于亲和性。

如需对单个请求关闭此功能，同时保留工作区和动态路由默认值：

```json theme={null}
{
  "model": "openai/gpt-5",
  "session_id": "support-session-42",
  "provider": {
    "cache_aware_routing": false
  }
}
```

如需保留上下文缓存亲和性，但让单个请求忽略会话标识符，请使用：

```json theme={null}
{
  "model": "openai/gpt-5",
  "session_id": "support-session-42",
  "routing": {
    "session_affinity": false
  }
}
```

## BYOK 注意事项

如果你希望使用 Phaseo 的路由和可观测性，同时让所选提供商将模型用量计费到你自己的账户，请使用 BYOK。

* 每个 UTC 日历月内，前 250,000 个已完成的 BYOK 请求不收取 Phaseo 服务费。
* 超出该额度后，Phaseo 会收取相当于提供商成本 2.5% 的费用。
* 请至少保留价值 1 美元的 Phaseo 积分，以支持托管回退和额度用尽后的费用收取；提供商费用仍会直接计入你的提供商账户。
* 提供商的配额、数据政策、模型访问权限和账户限制仍然适用。

存储前，提供商凭证会使用 AES-256-GCM 加密，并绑定到对应的工作区和提供商。请将每个密钥限制为确实需要它的模型和 Phaseo API 密钥。如果某个请求绝不能使用 Phaseo 积分，请关闭托管回退。

## 应记录的内容

对于生产工作负载，请记录请求 ID、响应状态代码和模型 ID，以便调试时关联故障并确认路由行为。

## 相关指南

* [预设](./presets.mdx)
* [功能对等矩阵](../migration-guides/feature-parity-matrix.mdx)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.