跳到正文

用别名路由,实现回退、条件和分流

在 Kaeso 0.6.0 中,别名带有一条路由。模型失败时,回退到另一个模型;把企业流量或长提示词,发往别处;按调用方,对两个模型做 A/B 测试。这一切,应用代码一行都不用改。

发布日期
阅读时间
6 分钟
作者
Kaeso Team
明亮的橙色与黄色渐变,沿对角线向下折叠,一角透着暖光

应用在每个请求中都要指定一个模型,而这个名字往往会在代码里留很久,久到背后的模型早该换了。Kaeso 的别名一直在这方面有所帮助:应用发送 support,由项目决定哪个模型来回答。

在 0.6.0 中,别名带有一整条路由。它可以在某个模型失败时回退到另一个模型,把一部分请求发往一处、其余的发往另一处,还能按权重在模型之间分流。应用仍然只发送 "model": "support"。

三类步骤

路由是由步骤组成的树。只含一个模型的路由,就是别名一直以来的样子。

步骤作用
模型调用项目目录中的一个模型。模型因该步骤列出的原因失败时,由其回退步骤(任意类型)接手
条件规则对请求成立时走 then,否则走 else
分流按合计为 100 的权重,把每个请求送进 2 到 8 个分支之一

一条路由最多有 32 个步骤,最多嵌套 12 层,路由中的每个模型都必须在项目的目录中。

回退

模型步骤失败时,如果该步骤的 fall_back_on 列出了失败原因,Kaeso 会转到其回退步骤:

原因失败情形
unavailable无法连接服务商、服务商超时、过载或返回 5xx;服务商拒绝项目的密钥或不提供该模型
limited服务商的速率限制或配额,或该步骤模型的 Kaeso 限额或预算
unsupported模型无法接受请求用到的内容,例如图片、PDF、工具或 JSON schema。Kaeso 在发送任何内容之前就能从目录得知
rejected服务商拒绝请求本身,例如上下文过长

步骤若未列出其他原因,会在前三种原因时回退。只有当回退模型能接受第一个模型拒绝的内容时,才加上 rejected,例如上下文更长的模型。步骤的 timeout_seconds 设定 Kaeso 等待第一个字节的时长,超时后转到下一步。

服务商一旦开始应答,就不再回退:之后中断的流以错误事件结束,与没有路由时相同。

持续的失败会被跳过

密钥被拒、余额用尽或速率限制,不会在下一秒自己恢复。步骤因持续存在的原因失败后,后续请求会暂时跳过它,直接进入下一步:密钥被拒或余额用尽时跳过 5 分钟,速率限制按 Retry-After 所示的时长,超时或 5xx 跳过 30 秒。模型一旦应答,等待即结束。一个实例中的所有网关通过 Valkey 共享这些信息,所以一个网关看到某步骤失败,所有网关都会跳过它。

条件

条件读取请求的信息,有 1 到 10 条规则,用 all 或 any 组合:

  • 请求头等于某个值、包含某个值、存在或不存在。从应用发送 x-plan: enterprise,就能把付费客户路由到更大的模型。
  • 应用的格式,例如 anthropic_messages 或 gemini。
  • 请求用到的功能:图片、PDF、工具、推理、结构化输出或流式传输。
  • 输入 Token 至少达到或低于某个数,用于把长提示词发给上下文更长的模型。
  • 调用方:发送请求的 API 密钥、成员或服务账号。

路由从不读取携带凭据的请求头,例如 authorization 或 x-api-key。

分流

分流为每个请求抽取一个数,并走权重覆盖该数的分支。抽取的方式决定了分流的用途:

  • by: request 每次重新抽取,用于分散负载。
  • by: caller 让每个 API 密钥、成员或服务账号固定在一个分支上。可用于 A/B 测试,让一个应用始终看到同一个模型。之后调整权重,只会移动那些抽取值越过新边界的调用方。
  • by: header 让某个请求头的每个值固定在一个分支上,例如 x-user-id,这样同一个 API 密钥背后的每个用户都始终看到同一个模型。

一条路由,从上往下读

在线演示(在新标签页中打开)中有一个别名 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。

编辑器中别名 support 的路由:一个基于 x-plan 的条件把企业请求发给 Claude Sonnet 5.5,以 GPT-6 Sol 作为回退;按调用方分流把其余请求发给 Claude Haiku 5.5 或 GPT-5.4 mini编辑器中别名 support 的路由:一个基于 x-plan 的条件把企业请求发给 Claude Sonnet 5.5,以 GPT-6 Sol 作为回退;按调用方分流把其余请求发给 Claude Haiku 5.5 或 GPT-5.4 mini
图 01演示中的别名 support:一个条件、一次按调用方分流和几个回退。

在控制台中构建和测试

在项目中打开模型 › 别名,创建一个别名,或打开已有的别名。路由编辑器占满整页:可以从它的模板开始,也可以一步步构建这棵树。它的测试标签页会在保存之前让一个请求经过草稿,并按每一步的应答为其着色。试运行会显示每个条件及其中成立的规则、每个分流抽到的数字和所走的分支,以及请求会依次尝试的每个模型。

Platform API 也提供同样的试运行,因此脚本或 CI 任务可以在路由上线前检查它;智能体也能通过 MCP,以只读工具的形式获得它。

应用和日志看到的内容

  • 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} 统计回退和跳过的次数,供您的仪表板使用。

无权使用某步骤模型的密钥会跳过该步骤,而且不会得知模型的名字,所以受限的密钥无法了解路由的任何信息。

下一步

作者:Kaeso Team

本页内容

网关归您。记录也归您。

curl -fsSLhttps://kaeso.app/install.sh | sh