用别名路由,实现回退、条件和分流
在 Kaeso 0.6.0 中,别名带有一条路由。模型失败时,回退到另一个模型;把企业流量或长提示词,发往别处;按调用方,对两个模型做 A/B 测试。这一切,应用代码一行都不用改。
- 发布日期
- 阅读时间
- 6 分钟
- 作者
- Kaeso Team

应用在每个请求中都要指定一个模型,而这个名字往往会在代码里留很久,久到背后的模型早该换了。Kaeso 的别名一直在这方面有所帮助:应用发送 support,由项目决定哪个模型来回答。
在 0.6.0 中,别名带有一整条路由。它可以在某个模型失败时回退到另一个模型,把一部分请求发往一处、其余的发往另一处,还能按权重在模型之间分流。应用仍然只发送 "model": "support"。
三类步骤01
路由是由步骤组成的树。只含一个模型的路由,就是别名一直以来的样子。
| 步骤 | 作用 |
|---|---|
| 模型 | 调用项目目录中的一个模型。模型因该步骤列出的原因失败时,由其回退步骤(任意类型)接手 |
| 条件 | 规则对请求成立时走 then,否则走 else |
| 分流 | 按合计为 100 的权重,把每个请求送进 2 到 8 个分支之一 |
一条路由最多有 32 个步骤,最多嵌套 12 层,路由中的每个模型都必须在项目的目录中。
回退02
模型步骤失败时,如果该步骤的 fall_back_on 列出了失败原因,Kaeso 会转到其回退步骤:
| 原因 | 失败情形 |
|---|---|
unavailable | 无法连接服务商、服务商超时、过载或返回 5xx;服务商拒绝项目的密钥或不提供该模型 |
limited | 服务商的速率限制或配额,或该步骤模型的 Kaeso 限额或预算 |
unsupported | 模型无法接受请求用到的内容,例如图片、PDF、工具或 JSON schema。Kaeso 在发送任何内容之前就能从目录得知 |
rejected | 服务商拒绝请求本身,例如上下文过长 |
步骤若未列出其他原因,会在前三种原因时回退。只有当回退模型能接受第一个模型拒绝的内容时,才加上 rejected,例如上下文更长的模型。步骤的 timeout_seconds 设定 Kaeso 等待第一个字节的时长,超时后转到下一步。
服务商一旦开始应答,就不再回退:之后中断的流以错误事件结束,与没有路由时相同。
持续的失败会被跳过
密钥被拒、余额用尽或速率限制,不会在下一秒自己恢复。步骤因持续存在的原因失败后,后续请求会暂时跳过它,直接进入下一步:密钥被拒或余额用尽时跳过 5 分钟,速率限制按 Retry-After 所示的时长,超时或 5xx 跳过 30 秒。模型一旦应答,等待即结束。一个实例中的所有网关通过 Valkey 共享这些信息,所以一个网关看到某步骤失败,所有网关都会跳过它。
条件03
条件读取请求的信息,有 1 到 10 条规则,用 all 或 any 组合:
- 请求头等于某个值、包含某个值、存在或不存在。从应用发送
x-plan: enterprise,就能把付费客户路由到更大的模型。 - 应用的格式,例如
anthropic_messages或gemini。 - 请求用到的功能:图片、PDF、工具、推理、结构化输出或流式传输。
- 输入 Token 至少达到或低于某个数,用于把长提示词发给上下文更长的模型。
- 调用方:发送请求的 API 密钥、成员或服务账号。
路由从不读取携带凭据的请求头,例如 authorization 或 x-api-key。
分流04
分流为每个请求抽取一个数,并走权重覆盖该数的分支。抽取的方式决定了分流的用途:
by: request每次重新抽取,用于分散负载。by: caller让每个 API 密钥、成员或服务账号固定在一个分支上。可用于 A/B 测试,让一个应用始终看到同一个模型。之后调整权重,只会移动那些抽取值越过新边界的调用方。by: header让某个请求头的每个值固定在一个分支上,例如x-user-id,这样同一个 API 密钥背后的每个用户都始终看到同一个模型。
一条路由,从上往下读05
在线演示(在新标签页中打开)中有一个别名 support,在一条路由中展示了全部三类步骤。带有 x-plan: enterprise 的请求,或输入至少 100,000 个 Token 的请求,会发给 Claude Sonnet 5.5,以 GPT-6 Sol 作为回退。其他请求按调用方分流:大约五分之四使用 Claude Haiku 5.5,以 GPT-5.4 mini 作为回退,其余的使用 GPT-5.4 mini。


在控制台中构建和测试06
在项目中打开模型 › 别名,创建一个别名,或打开已有的别名。路由编辑器占满整页:可以从它的模板开始,也可以一步步构建这棵树。它的测试标签页会在保存之前让一个请求经过草稿,并按每一步的应答为其着色。试运行会显示每个条件及其中成立的规则、每个分流抽到的数字和所走的分支,以及请求会依次尝试的每个模型。
Platform API 也提供同样的试运行,因此脚本或 CI 任务可以在路由上线前检查它;智能体也能通过 MCP,以只读工具的形式获得它。
应用和日志看到的内容07
kaeso-model和kaeso-provider给出应答的步骤。kaeso-route按顺序列出请求到达的每个步骤,以及它的模型、状态和耗时:"route";model="anthropic/claude-sonnet-5-5";status=529;dur=1204, "route.fallback";model="openai/gpt-6-sol";status=200。- 请求日志把别名记为请求的模型,并列出尝试过或跳过的每个步骤,以及它的状态和错误。
- 用量和费用以应答步骤为准。失败的步骤在 Kaeso 中不产生费用,失败的步骤还会在下一步申请之前,归还它占用的预算额度。
kaeso_alias_fallbacks_total{provider, reason}统计回退和跳过的次数,供您的仪表板使用。
无权使用某步骤模型的密钥会跳过该步骤,而且不会得知模型的名字,所以受限的密钥无法了解路由的任何信息。
下一步08
- 文档中的别名路由(在新标签页中打开)列出了每条规则和每个字段。
- 模型和别名(在新标签页中打开)逐步介绍编辑器。
- Kaeso 0.6 介绍了这个版本新增的其他所有内容。
作者:Kaeso Team


