---
title: 用别名路由，实现回退、条件和分流
description: 在 Kaeso 0.6.0 中，别名带有一条路由。模型失败时，回退到另一个模型；把企业流量或长提示词，发往别处；按调用方，对两个模型做 A/B 测试。这一切，应用代码一行都不用改。
url: https://kaeso.app/zh-CN/articles/alias-routes
markdown: https://kaeso.app/zh-CN/articles/alias-routes.md
language: zh-CN
alternates:
  en: https://kaeso.app/articles/alias-routes.md
  de: https://kaeso.app/de/articles/alias-routes.md
published: 2026-11-11
authors:
  - Kaeso Team
tags:
  - 网关
  - 路由
  - 别名
  - 指南
image: https://kaeso.app/articles/alias-routes/cover.jpg
index: https://kaeso.app/zh-CN/llms.txt
---

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

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

> Kaeso 的所有页面、文章和文档页面都列在 https://kaeso.app/zh-CN/llms.txt 中。

- 发布日期：2026年11月11日
- 阅读时间：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 密钥背后的每个用户都始终看到同一个模型。

## 一条路由，从上往下读

[在线演示](https://demo.kaeso.app)中有一个别名 `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](https://kaeso.app/articles/kaeso-demo/alias-route-light.png "演示中的别名 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}` 统计回退和跳过的次数，供您的仪表板使用。

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

## 下一步

- 文档中的[别名路由](https://docs.kaeso.app/zh-CN/concepts/alias-routes)列出了每条规则和每个字段。
- [模型和别名](https://docs.kaeso.app/zh-CN/console/models-and-aliases)逐步介绍编辑器。
- [Kaeso 0.6](https://kaeso.app/zh-CN/articles/kaeso-0-6) 介绍了这个版本新增的其他所有内容。

作者：Kaeso Team

## 更多文章

- [Gemini 应用经由 Kaeso，背后是 Claude 和 GPT](https://kaeso.app/zh-CN/articles/gemini-apps-through-kaeso.md)：Gemini API 应用，无论用 google-genai SDK，还是直接调用 REST，只需把基础 URL，换成 Kaeso 的地址，就能在 /v1beta 下，访问项目里的任何模型。本文介绍如何切换应用、哪些可用，以及途中的格式转换。
- [在哪里运行 Kaeso：从一台服务器到托管云](https://kaeso.app/zh-CN/articles/where-to-run-kaeso.md)：Kaeso 0.6.0：在您的服务器上，一条命令即可运行；借助仓库中的模板，也能运行在十个平台上。本文介绍四类路径、每条路径不变的部分，以及如何选择。

[查看所有文章](https://kaeso.app/zh-CN/articles.md)

## 网关归您。记录也归您

```bash
curl -fsSL https://kaeso.app/install.sh | sh
```

[安装 Kaeso](https://docs.kaeso.app/zh-CN/self-hosting/installation) · [打开在线演示](https://demo.kaeso.app)
