选择路由模式
除非某项生产需求明显比其他需求更重要，否则请从balanced 开始。
请在控制台 -> 设置 -> 路由中配置工作区默认值。如果某个工作流需要比工作区默认值更严格的提供商或模型策略，请使用预设。
模型路由后缀
如果希望模型 ID 本身决定此次请求的优化模式，请添加路由后缀：
例如，
openai/gpt-5-mini:nitro 会优先考虑吞吐量。识别到的路由后缀优先于请求中的 routing.mode 或 provider.sort，也优先于预设和工作区路由模式。提供商允许列表、区域要求、护栏和价格上限等其他约束仍然有效。
路由的基本流程
- 你发送一个包含模型 ID 的请求。
- Gateway 评估提供商的健康状态、延迟和能力覆盖情况。
- Gateway 选择提供商并执行请求。
使用自动路由器选择模型
自动路由目前处于 Alpha 阶段，仅对部分工作区开放。 当模型需要根据工作负载变化时，请使用phaseo/auto。Phaseo 会从所有符合生产条件的文本模型开始，应用工作区约束，并构建适合当前工作负载的候选列表：
- 打开控制台 -> 设置 -> 路由 -> 自动路由。
- 选择优化均衡性能、质量、成本还是延迟。
- 选择经济、标准、高级或不受限支出配置。这些配置会在评分前对输入和输出价格应用固定上限。
- 可选：使用
anthropic/*、openai/gpt-5.*等模式或精确模型 ID 缩小候选范围。 - 选择在可重试错误发生后，Phaseo 是否可以尝试排名靠后的模型。
- 保存配置。
支出配置会对标准层级设置硬性价格上限，单位为每百万文本 Token 的美元价格：
自定义限制可直接设置输入和输出上限。没有已知标准文本价格的模型不会进入受管理的候选范围。
对于每个
phaseo/auto 请求，Phaseo 都会向固定的低成本分类模型发出一个普通的 Gateway 子请求。子请求使用相同的工作区和计费身份，会单独显示在请求日志中，并标记 purpose=auto_routing_classifier 和父请求 ID。分类器会返回结构化的工作负载组合、复杂度分数和置信度，但不会直接选择模型。
工具和结构化输出等确定的请求事实会作为可信元数据提供。如果分类器请求失败、超时或返回无效数据，Phaseo 会回退到本地确定性分类器，判断请求属于代码、推理、工具使用、结构化输出、翻译、摘要还是通用任务，而不会让生成请求失败。
分类器复杂度代表可能足以生成可靠且可接受答案的最低模型能力。Phaseo 会增加能力余量，然后结合基准适配度、工作区目标、价格、延迟、提供商健康状况和可靠性进行评分。分类器请求与选定的生成请求会通过常规 Gateway 流程分别计量。
评分前，每个允许的模型都必须通过常规的端点、工作区模型、提供商、隐私、护栏和熔断器检查。随后，路由器会将 Phaseo 目录中相关且非提供商自报的基准数据与 Phaseo 当前的提供商健康状况、延迟和价格结合起来。缺少基准或运行数据时按中性处理；这不会扩大允许列表。
响应中的 model 字段标识所选模型。请求详情会显示工作负载、目标、选定模型、回退顺序、候选和因素评分、基准 ID、排除项以及算法版本。路由跟踪不包含请求或响应内容。
如果工作区启用了模型回退，Phaseo 会在收到 429、500、502、503 或 504 后，按排名顺序重试其余模型。每次回退都会重新执行完整的策略和提供商选择流程。客户端错误不会切换模型。
已附加的动态路由若选择了固定模型，则该模型优先。在这种情况下，请求详情会记录该覆盖，且自动路由器对该请求禁用模型回退。
解释路由决策
打开控制台 -> 设置 -> 使用情况 -> 请求日志，选择一个请求，然后在提供商响应下展开路由可观测性。 请求日志会显示：- 所有已排名的提供商及其最终得分
- Phaseo 选择的提供商以及尝试过的提供商
- 排名之前被排除的提供商及记录的原因
- 因发布或路由状态而被降级的提供商
- 为每个已排名提供商评分时使用的输入、权重、贡献和乘数
balanced 路由中，Phaseo 根据可靠性、延迟、尾部延迟、吞吐量、价格和 Token 适配度为合格提供商评分。显示的计算会说明每项因素如何影响最终得分，而不会把所有记录指标都视为同等重要。
可靠性与提供商运行时间
可靠性样本是评分所用的值，根据提供商的结果计算；成功率会作为补充上下文显示。 以下结果会降低提供商运行时间：- 身份验证失败（
401） - 付款失败（
402） - 找不到模型的响应（
404） - 服务器错误（
500及以上） - 响应流开始后的错误
- HTTP 响应成功但最终以错误原因结束
- 错误请求（
400） - 地理位置限制（
403） - 载荷过大（
413） - 速率限制（
429）
跟踪数据的可用性与隐私
启用路由可观测性后发出的请求可以查看完整路由跟踪。较早的请求可能只有部分跟踪数据，也可能没有路由详情。 路由跟踪有明确边界，且不包含内容。它只包含解释提供商选择所需的数字和状态，不会将提示、消息或生成内容复制到跟踪记录中。在模型 ID 中指定确切的提供商
如果请求必须使用某个特定的提供商和模型组合，请使用<provider-id>:<canonical-model-id>：
baseten:google/gemma-4-26b-a4b:free。
有关完整语法、免费路由验证、路由优先级、别名、错误代码和请求示例，请参阅提供商限定的模型 ID。
控制路由和回退
当前公开的路由和回退控制项是明确设置的：预设限制回退范围
在控制台 -> 设置 -> 预设中，你可以定义：- 允许使用的模型
- 提供商允许列表
- 提供商忽略列表
- 提示和参数的默认行为
路由模式会更改提供商排名
在控制台 -> 设置 -> 路由中，工作区可以调整 Gateway 对兼容提供商的排序方式：balancedpricelatencythroughput
BYOK 回退由你明确控制
在控制台 -> 设置 -> BYOK中，团队可以选择 BYOK 请求失败后是否允许改用 Phaseo 积分。这是当前面向常见问题“我自己的密钥失败了，请求是否仍应完成？”的公开控制项。动态路由将策略绑定到 API 密钥
如果不同 API 密钥或请求类别需要不同的提供商行为，请在控制台 -> 设置 -> 路由中创建动态路由。路由可以：- 根据嵌套请求正文字段、请求标头、自定义元数据、端点、模型或会话 ID 进行分支
- 按百分比分配流量，用于 A/B 测试和逐步发布
- 使用已验证密钥的使用量分桶来执行每日、每周或每月请求数和费用上限
- 调用其他模型，并选择该模型的路由模式、提供商偏好和回退策略
- 启用感知缓存和会话的提供商亲和性
- 附加到一个或多个推理 API 密钥
回退行为
如果提供商返回错误或速率限制，Gateway 可以重试，也可以将请求路由到支持同一模型的其他提供商。你仍应使用指数退避处理429 和 5xx 响应。
动态路由中的模型节点还可以设置按顺序排列的回退模型列表。Phaseo 会先用完所选模型的所有合格提供商尝试。如果返回的响应可以重试（429、500、502、503 或 504），Gateway 会按顺序对每个回退模型重新执行完整的策略和提供商选择流程。客户端错误会立即返回，不会切换模型。
每个回退模型都会单独检查工作区模型限制、护栏、提供商策略、价格和能力支持情况。一条路由最多可以保存八个回退模型。
了解更多：
感知缓存和会话的亲和性
文本生成端点默认启用感知缓存的路由。提供商报告实际发生提示缓存读取后，如果该提供商仍然健康，且符合活动路由、预设、护栏和请求策略，Phaseo 会将匹配的上下文固定到该提供商 15 分钟。 如果请求包含session_id，缓存亲和性会绑定到会话，而不只绑定到最初的上下文。Phaseo 观察到另一次缓存读取时会刷新亲和性，并在会话活动期间最多保留 24 小时。熔断器和策略过滤器始终优先于亲和性。
如需对单个请求关闭此功能，同时保留工作区和动态路由默认值：
BYOK 注意事项
如果你希望使用 Phaseo 的路由和可观测性，同时让所选提供商将模型用量计费到你自己的账户，请使用 BYOK。- 每个 UTC 日历月内，前 250,000 个已完成的 BYOK 请求不收取 Phaseo 服务费。
- 超出该额度后，Phaseo 会收取相当于提供商成本 2.5% 的费用。
- 请至少保留价值 1 美元的 Phaseo 积分，以支持托管回退和额度用尽后的费用收取；提供商费用仍会直接计入你的提供商账户。
- 提供商的配额、数据政策、模型访问权限和账户限制仍然适用。