多目标路由与故障转移

多目标模型使用一个面向调用方的别名承载多个目标模型。AISIX 为每个请求选择目标、重试符合条件的失败，并且可以在不要求应用更改模型名称的情况下执行故障转移。

该别名是面向调用方的模型名称，因此对于有权请求它的每个调用方 API Key，它都会显示在 GET /v1/models 中。将某个 Key 的作用域仅限定到该别名，即可把它作为调用方发现的唯一入口发布；此后可以更改别名的目标，而无需修改应用。

多目标模型包含 routing 块，而不是自身的服务提供方配置。每个目标都是一个已有的直接模型，具有自己的服务提供方密钥和上游模型名称。控制面通过模型 ID 引用这些目标，开源 AISIX 网关则在声明式资源文件中通过 display_name 引用它们。

路由模型选择一个直接目标，再由该目标使用自己的服务提供方密钥调用上游模型：

选择策略

请根据面向调用方的别名应如何分发流量来选择策略：

目标	策略	选择行为
保留一个主要目标和有序备用目标。	failover	按声明顺序尝试目标。
在相似目标之间轮转流量，可按比例分配。	round_robin	按目标 weight 做平滑加权轮询；权重相等或缺省时按声明顺序轮换。
将每个会话固定到同一目标。	consistent_hash	在加权哈希环上对每个请求的键做哈希，让相同键持续命中同一个健康目标。weight 改变的是哈希键的近似份额，而不是固定的请求百分比。适用于 A/B 测试和灰度发布以及会话亲和 + 池间故障转移。
优先选择预估价格最低的目标。	least_cost	按配置价格或控制面目录定价对符合条件的目标排序。
优先选择近期观测到的最快目标。	least_latency	按近期上游延迟排序。
优先选择加权并发数最低的目标。	least_busy	按 (1 + 当前进行中的请求数) / max(weight, 1) 对符合条件的目标排序，数值最低者优先。

failover 是省略 strategy 时的默认值。你也可以使用路由标签按请求缩小符合条件的目标范围。

每种策略都支持以下两个目标级属性：

• weight（默认 1）在使用它的策略下决定目标的份额：round_robin 的轮转份额、consistent_hash 的哈希环份额、least_busy 的并发折算系数。failover、least_cost 和 least_latency 接受该字段但不使用。
• priority（默认 0）将符合条件的目标划分为层级——数值越大越优先，因此给备用目标配置 -1。策略在每层内部对目标排序，只有当没有更高层目标可用时，较低层才会接收流量。请参阅会话绑定与池间故障转移。

AISIX 会先应用路由标签和 allowed_cidrs 过滤，再把剩余目标划分到各优先级层。因此，如果某个健康的高优先级目标因其中任一过滤条件而不适用于当前请求，较低优先级目标仍可为该请求提供服务。

AISIX 会在可重试的上游失败上执行重试和故障转移，例如 5xx 响应、请求超时和传输错误。AISIX 无法读取的 2xx 答复不属于此类：上游已经给出了答复，因此调用方收到 502，该答复不会被重试、不会故障转移，也不计入冷却。大多数上游 4xx 响应会直接返回调用方。启用 retry_on_429 可处理上游限流，配置 fallback_on_statuses 可处理其他服务提供方特定的临时状态码。

AISIX 也会跳过超过自身模型限流的目标。它会将被跳过的目标记录为一次失败的 429 路由尝试，并按策略顺序继续尝试其余目标，不会重试该目标。当所有目标都超过限额时，请求返回 429。

每次分发到目标的尝试（包括同一目标的重试）都会计入该目标自身的限制，而调用方 API Key 和路由模型自身的限制对每个请求只计一次。因自身限制被跳过的目标不消耗额度；因所有目标都超过限额、在任何尝试到达上游之前就返回 429 的请求，在任何一层都不消耗额度。参见请求如何计数。

如果目标自身的 allowed_cidrs 排除了调用方，该目标同样不会成为候选项。此检查在策略选择前执行，因此不会尝试该目标，也不会消耗 max_fallbacks 预算。当所有目标都排除调用方时，请求返回 403。

支持的端点

调用方可以在以下端点上请求多目标模型。每个端点都会按本页所述的策略、重试、故障转移和运行时过滤逐个尝试目标：

• /v1/chat/completions、/v1/messages、/v1/messages/count_tokens 和 /v1/responses。
• /v1/completions、/v1/embeddings、/v1/rerank、/v1/systemone、/v1/decisions、/v1/images/generations、/v1/images/edits、/v1/audio/transcriptions、/v1/audio/translations、/v1/audio/speech，以及 POST /v1/videos 提交。

/v1/realtime 以及 Files、Batches 和 Fine-tuning API 要求使用直接模型，会拒绝多目标模型，因为会话或服务提供方签发的 ID 必须始终留在同一个服务提供方上。

在第二组端点上，每个目标都必须能够处理该端点。端点无法处理的目标会像不可重试的失败一样结束请求，AISIX 不会转而尝试下一个目标；只有可重试的上游失败才会触发故障转移。/v1/rerank、/v1/images/generations、/v1/images/edits 和决策端点返回 400，错误信息会同时写出多目标模型和目标，例如 model `my-group` (target `claude-img`) is not an OpenAI provider。当目标的服务提供方缺少对应能力时，/v1/completions、/v1/embeddings、/v1/images/generations 和 /v1/videos 返回 501。这两种响应都应视为该组的配置错误。/v1/messages/count_tokens 是例外：它会跳过无法处理的目标，继续尝试下一个目标。

这些端点记录多目标请求的方式与 Chat Completions 相同：

• 每次上游尝试都会产生自己的用量事件，包括导致重试或故障转移的失败尝试。失败尝试的 Token 数为零，且不计费。给出响应的那次尝试的事件会写明实际提供服务的目标，计价也按该目标而不是按组进行。
• 部署与回退指标以及访问日志中的路由字段覆盖这些端点。
• least_latency 和 least_busy 会从这些端点的流量中学习。对于语音合成和流式转写，least_latency 测量的是到上游响应头的时间，而在中继的流结束之前，该目标在 least_busy 中一直计为忙碌。

通过多目标模型提交的视频会始终留在接受该任务的服务提供方上：返回的视频 ID 标识了该目标，因此 GET /v1/videos/{video_id} 及其 /content 路由会到达同一个服务提供方，状态响应中回显的是提交时使用的多目标模型名称。上游已经应答之后才失败的提交永远不会重放，无论是在同一目标还是下一个目标上，因为付费任务可能已经创建。

/v1/responses 对话会留在产出其上下文的目标上。AISIX 会在返回的推理 encrypted_content 和响应 id 上标记处理该请求的目标，并把携带它们的后续轮次优先发回该目标，或同一服务提供方密钥上的其他目标，不按策略顺序。参见在多目标模型上保持对话上下文。

配置并测试故障转移模型

以下示例会构建并测试一个双目标模型：优先使用 gpt-4o-primary，遇到符合条件的失败后改用 gpt-4o-secondary。本节同时提供 AISIX Enterprise、AISIX Cloud 和开源 AISIX 网关的操作说明。

准备工作

开始前，请准备以下资源：

• 两个或更多用作路由目标的直接模型。要执行故障测试，主要模型和备用模型必须使用不同的服务提供方密钥资源，但两个资源可以包含同一个上游凭据。
• 一个可以调用多目标模型的调用方 API Key，或创建该 Key 的权限。
• 用于执行 API 和验证命令的 cURL 和 jq。
• 对于 AISIX Enterprise 或 AISIX Cloud，需要一个已接入网关的环境，以及管理模型和调用方 API Key 的权限。
• 对于开源 AISIX 网关，需要有权访问声明式资源文件和网关进程。

创建模型

请先创建直接目标模型，再创建多目标模型。以下示例通过两种管理路径配置相同的故障转移行为：AISIX 先使用 gpt-4o-primary，在发生可重试失败后改用 gpt-4o-secondary。

AISIX Enterprise 或 AISIX Cloud

设置控制面 URL、Admin Token 和环境 ID：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且末尾不要带斜杠。
# 本地 AISIX Enterprise 快速入门使用 http://localhost:8080/api。
export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

导出直接目标模型的 ID：

export PRIMARY_MODEL_ID="YOUR_PRIMARY_MODEL_ID"
export SECONDARY_MODEL_ID="YOUR_SECONDARY_MODEL_ID"

创建一个故障转移模型：它会先从主要目标开始，再在失败时回退到备用目标。

ROUTING_MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "routing",
    "display_name": "chat-prod",
    "routing": {
      "strategy": "failover",
      "targets": [
        {"model_id": "'"$PRIMARY_MODEL_ID"'"},
        {"model_id": "'"$SECONDARY_MODEL_ID"'"}
      ],
      "retries": 1,
      "max_fallbacks": 1,
      "retry_on_429": true
    }
  }' | jq -r '.model.id')

使用该配置时，AISIX 会从 gpt-4o-primary 开始。如果该目标发生可重试失败，AISIX 可以先重试一次，然后故障转移一次到 gpt-4o-secondary。

使用获取的 ROUTING_MODEL_ID 授予调用方访问权限，并在以后更新、查看或删除该模型。如果已有调用方 API Key 需要使用 chat-prod，请把此 ID 添加到它的 allowed_models 列表。

为了快速验证，请创建一个只能调用 chat-prod 的调用方 API Key：

KEY_RESPONSE=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "routing-guide-caller",
    "allowed_models": ["'"$ROUTING_MODEL_ID"'"]
  }')

export AISIX_API_KEY=$(echo "$KEY_RESPONSE" | jq -r '.plaintext')
API_KEY_ID=$(echo "$KEY_RESPONSE" | jq -r '.api_key.id')

明文调用方密钥只返回一次。上述命令保存了它，供验证请求使用，并保存密钥 ID，供稍后更新允许列表。模型和调用方密钥配置会自动投射到已接入的网关。

开源 AISIX 网关

将两个模型服务提供方 Key、对应的直接模型以及 chat-prod 路由模型添加到完整资源文件。将两个 Key 分开可以只测试其中一个目标，而不影响另一个：

resources.yaml（路由模型服务提供方 Key 与模型）

provider_keys:
  - display_name: openai-primary
    provider: openai
    adapter: openai
    api_key: ${OPENAI_API_KEY}
  - display_name: openai-secondary
    provider: openai
    adapter: openai
    api_key: ${OPENAI_API_KEY}

models:
  - display_name: gpt-4o-primary
    provider: openai
    model_name: gpt-4o
    provider_key: openai-primary
  - display_name: gpt-4o-secondary
    provider: openai
    model_name: gpt-4o-mini
    provider_key: openai-secondary
  - display_name: chat-prod
    routing:
      strategy: failover
      targets:
        - model: gpt-4o-primary
        - model: gpt-4o-secondary
      retries: 1
      max_fallbacks: 1
      retry_on_429: true

将 chat-prod 添加到调用方 Key 的 allowed_models，然后验证并重新加载组装后的文件。

验证主要目标路由

导出所配置部署的网关 URL：

# 使用网关源地址，不要附加末尾斜杠或端点路径。
# 本地快速入门使用 http://127.0.0.1:3000。
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

对于 AISIX Enterprise 或 AISIX Cloud，请继续使用先前创建的 AISIX_API_KEY。对于开源网关，请导出调用方 API Key：

export AISIX_API_KEY="YOUR_CALLER_API_KEY"

向多目标别名发送请求：

curl -sSi -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chat-prod",
    "messages": [
      {"role": "user", "content": "Hello from AISIX routing."}
    ]
  }'

成功请求以 HTTP/1.1 200 OK 开头。响应体仍以 chat-prod 作为面向调用方的模型名称，因此默认情况下，响应不会告诉调用方由哪个目标处理了请求。要查看目标，请复制响应头 x-aisix-request-id 的值，在网关访问日志中找到该请求对应的行，其 served_by_model 字段为 gpt-4o-primary。使用开源快速入门容器时：

docker logs aisix-quickstart 2>&1 | grep "YOUR_REQUEST_ID"

在测试网关上，也可以在启动配置中将 proxy.expose_debug_headers 设为 true 并重启网关，此时响应还会包含 x-aisix-served-by: gpt-4o-primary。该响应头标识实际处理请求的直接模型；缓存命中、单目标模型响应、错误响应以及 /v1/chat/completions 以外的端点不会包含它。

流式请求可以解析多目标别名，但流已经开始后不会再执行故障转移。

模拟主要目标失败

正常请求到达 gpt-4o-primary 后，让该目标变得不可访问，再重复请求。在此测试中，主要直接模型和备用直接模型必须使用不同的服务提供方密钥，这样修改主要端点时不会同时影响故障转移目标。

警告

请为主要目标使用专用的非生产服务提供方密钥。在 AISIX Enterprise 和 AISIX Cloud 中，服务提供方密钥属于组织作用域，修改其端点会影响所有引用它的模型。

AISIX Enterprise 或 AISIX Cloud

导出仅由主要目标使用的服务提供方密钥 ID，再保存其当前端点：

export PRIMARY_PROVIDER_KEY_ID="YOUR_PRIMARY_PROVIDER_KEY_ID"

PRIMARY_API_BASE=$(curl -sS \
  "$AISIX_CP/provider_keys/$PRIMARY_PROVIDER_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  | jq -r '.provider_key.api_base // ""')

将该服务提供方密钥指向保留的、不可访问的域名：

curl -sS -X PATCH \
  "$AISIX_CP/provider_keys/$PRIMARY_PROVIDER_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"api_base":"https://api.openai.invalid/v1"}'

控制面会把更新投射到允许使用该服务提供方密钥的每个环境。发送测试请求前，请确认目标网关已经应用最新配置。有关控制面修订版本和网关状态检查，请参阅资源投射。

开源 AISIX 网关

在完整 resources.yaml 中，将现有 openai-primary 模型服务提供方 Key 条目替换为以下配置块，只更改其端点。保留其他条目和集合：

resources.yaml（主要服务提供方密钥条目）

provider_keys:
  - display_name: openai-primary
    provider: openai
    adapter: openai
    api_key: ${OPENAI_API_KEY}
    api_base: https://api.openai.invalid/v1

如果你按照开源快速入门完成部署，请使用现有容器验证并重新加载该文件：

docker exec aisix-quickstart \
  /usr/local/bin/aisix validate --resources /etc/aisix/resources.yaml

docker kill --signal=HUP aisix-quickstart

如果你的配置不同，请使用自己的网关容器名称和资源文件路径。如果重新加载失败，网关会继续使用上一个有效配置。发送测试请求前，请确认 GET /status/config 报告重新加载成功。

验证故障转移

通过任一管理路径模拟失败后，重复验证主要目标路由中的请求。成功响应仍以 HTTP/1.1 200 OK 开头，但该请求访问日志行中的 served_by_model 此时为 gpt-4o-secondary；当 proxy.expose_debug_headers 为 true 时，响应还会包含以下响应头：

x-aisix-served-by: gpt-4o-secondary

AISIX 会重试不可访问的主要目标，再将请求转发到备用目标。响应体仍以 chat-prod 作为面向调用方的模型名称。

如果可以访问网关的私有指标与状态监听器，请查看目标状态：

# 开源快速入门使用 http://127.0.0.1:9090
curl -sS "http://127.0.0.1:9090/status/models" \
  | jq '.[] | select(
      .display_name == "gpt-4o-primary" or
      .display_name == "gpt-4o-secondary" or
      .display_name == "chat-prod"
    )'

两个直接目标都报告 healthy，多目标模型本身报告 not_applicable，因为它的可用性来自直接目标。状态监听器的路由不需要认证，因此必须保持为私有。

不可访问的主要目标仍为 healthy，是因为这些目标模型没有配置 cooldown 块，而冷却需要显式开启。因此故障转移是逐请求发生的：每个请求都会先尝试 gpt-4o-primary——由于本示例设置了 retries: 1，实际会尝试两次——遇到同样的失败后才转到 gpt-4o-secondary。如果希望反复失败的目标在一段时间内退出候选列表，从而让后续请求省下这些尝试，请把主要目标的 cooldown.enabled 设为 true；此后该目标会报告 cooldown，并带上 transport_error 之类的 status_reason，直到冷却结束。

恢复主要目标路由

对于 AISIX Enterprise 或 AISIX Cloud，请恢复保存的端点：

jq -n --arg api_base "$PRIMARY_API_BASE" '{api_base: $api_base}' \
  | curl -sS -X PATCH \
      "$AISIX_CP/provider_keys/$PRIMARY_PROVIDER_KEY_ID" \
      -H "Authorization: Bearer $AISIX_TOKEN" \
      -H "Content-Type: application/json" \
      --data-binary @-

确认恢复后的配置已到达网关。对于开源网关，请恢复或移除测试用 api_base 覆盖项，再次验证并重新加载 resources.yaml。

再次发送请求，并确认 served_by_model（或已开启时的 x-aisix-served-by）重新标识 gpt-4o-primary。如果之前在主要目标上开启了冷却，它会保持退出轮转直到当前冷却周期结束，请先等待它重新报告 healthy。

自定义路由行为

使用以下选项调整 AISIX 如何为特定请求重试、排列目标、分配流量或筛选候选项。每个选项彼此独立，因此只需应用路由策略所需的行为。

调整重试与运行时行为

先前配置的 chat-prod 故障转移模型会重试 gpt-4o-primary 一次，并可故障转移一次到 gpt-4o-secondary。以下字段控制尝试和运行时故障转移行为：

字段	适用场景
retries	请求应在可重试失败后重复尝试同一目标，并在尝试之间逐步延长等待时间。它会为每个目标设置默认值；目标自己设置的 retries 会覆盖该值。
max_fallbacks	请求可以转移到另一个符合条件的目标。省略时，AISIX 可以尝试所有后续目标；设为 0 表示只选择目标，不跨目标故障转移。
retry_on_429	上游 429 响应应允许触发另一次尝试。默认禁用。
fallback_on_statuses	服务提供方使用其他状态码表示应允许再次尝试的临时情况。
when_all_unavailable	控制运行时过滤移除所有目标后的行为；当使用 "try_anyway" 尝试一个目标比返回 503 all_candidates_unavailable 更合适时启用。

retries 仅适用于重试预算中列出的推理路由，不适用于 Realtime、透传路由，也不适用于文件、批处理和微调 API。对于受支持路由上的流式请求，同目标重试和故障转移都发生在 AISIX 仍在建立上游流的阶段，因此对调用方不可见。一旦提交响应字节，后续故障会终止响应。

routing.retries 是此模型每个目标的默认值。目标自己设置的 retries 会优先使用，因此一个组可以混用允许重复尝试的目标和应立即放弃的目标。直接指向服务提供方的模型别名也有自己的重试预算——完整解析顺序和部署级默认值请参阅重试预算。

未设置 retries 时，AISIX 会优先转移到下一个符合条件的目标，而不是重复当前目标，并在最后一个目标上回退到部署默认值。如果目标应在故障转移前被重复尝试，请显式设置 retries。

选择额外的故障转移状态码

只有当服务提供方使用某个状态表示模型过载、队列饱和或配额耗尽等临时情况时，才应使用 fallback_on_statuses。在多目标模型的 routing 块中设置：

{
  "routing": {
    "fallback_on_statuses": [408, 409]
  }
}

条目必须位于 400 到 599 之间。5xx 响应本来就会故障转移，重复列出不会改变行为。除非已知服务提供方会用认证（401、403）或校验（400）状态表示临时失败，否则不要添加这些状态。重试调用方或凭据错误只会把相同的失败请求发送到更多目标。

fallback_on_statuses 只影响当前请求。如果某个目标对应的直接模型开启了冷却，该模型的 cooldown.trigger_statuses 会单独决定失败是否让该目标退出未来请求的轮转。两个列表互相独立：把 422 加入 fallback_on_statuses 可以把当前请求移到另一个目标，但不会让失败目标进入冷却。

处理流式失败

对于流式 Chat Completions，AISIX 只能在向调用方发送响应字节前重试或故障转移。当模型或路由模型设置 stream_timeout，或回退到自身的 timeout 时，AISIX 会等待第一个上游分片。此时的连接错误、空流或超时可以把请求移到另一个目标。流式传输开始后，超时只会结束当前流。

部署级 upstream.timeout_ms 和 upstream.stream_timeout_ms 默认值不会增加这项首分片等待。只使用这些默认值时，AISIX 会在上游响应开始时提交下游响应，之后的首分片停滞会表现为流内超时，而不是故障转移。

按成本、延迟或负载路由

least_cost、least_latency 和 least_busy 策略会根据运行时信号对每个目标排序。AISIX 会优先尝试排名最前的目标，再依次尝试其余目标。顺序来自信号，而不是目标声明顺序。

• least_cost 根据每个目标模型每 1,000 个 Token 的输入和输出合计价格排序；对于分档价格，使用第一档价格。没有已知价格的目标排在最后。在币种为人民币的 AISIX Cloud 组织中，目录价格不适用，因此组织未定价的目标排在最后。路由模型上的模型组价格或低峰折扣不影响排序。
• least_latency 根据近期上游延迟的移动平均值排序；对于流式响应，使用首 Token 时间。还没有样本的目标排在最前，以便每个目标先被探测再参与排序。
• least_busy 按 (1 + 当前进行中的请求数) / max(weight, 1) 排序，数值最低者优先。加上 1 可以让权重在多个空闲目标之间打破平局，也会按比例让权重更高的目标承载更多并发请求。

在路由块中设置策略。以下控制面示例会创建一个优先选择最便宜健康目标的别名：

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "routing",
    "display_name": "chat-cheapest",
    "routing": {
      "strategy": "least_cost",
      "targets": [
        {"model_id": "'"$PRIMARY_MODEL_ID"'"},
        {"model_id": "'"$SECONDARY_MODEL_ID"'"}
      ]
    }
  }'

对于开源网关，请将以下 chat-cheapest 条目添加到现有 models 集合。保留其他模型条目和顶层集合：

resources.yaml（模型条目）

- display_name: chat-cheapest
  routing:
    strategy: least_cost
    targets:
      - model: gpt-4o-primary
      - model: gpt-4o-secondary

价格来源取决于网关使用开源资源文件还是连接 AISIX Enterprise 或 AISIX Cloud：

• 连接控制面的网关会根据每个目标精确配置的服务提供方和上游 model_name 投射路由价格。模型定价中的组织覆盖价格优先于目录价格；价格变化会重新排序现有路由组，无需修改模型配置。控制面拒绝把通配符直接模型作为路由目标，因此控制面中的路由组必须指向显示名称和上游模型名称都明确的模型。
• 开源 AISIX 网关根据每个目标模型的 cost 块在 resources.yaml 中记录的值排序。请参阅模型别名。

为 A/B 测试和灰度发布拆分流量

使用 consistent_hash 可让每个会话固定在一个变体上，同时按目标权重近似分配不同的哈希键。只要哈希键、符合条件的目标集合和路由配置不变，会话就不会在请求之间切换变体。目标故障、配置变化或目标资格变化都可能重新映射会话。实际请求比例可能与权重不同，因为哈希键未必均匀分布，而且每个会话发送的请求数量也可能不同。

此示例复用本指南中的两个目标模型作为稳定版本和灰度版本，然后将新别名添加到调用方 API Key 允许列表。allowed_models 是替换列表，因此请包含该 Key 需要保留的所有模型：

CANARY_MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "routing",
    "display_name": "chat-canary",
    "routing": {
      "strategy": "consistent_hash",
      "targets": [
        {"model_id": "'"$PRIMARY_MODEL_ID"'", "weight": 95},
        {"model_id": "'"$SECONDARY_MODEL_ID"'", "weight": 5}
      ]
    }
  }' | jq -r '.model.id')

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/api_keys/$API_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_models": ["'"$ROUTING_MODEL_ID"'", "'"$CANARY_MODEL_ID"'"]
  }'

默认情况下，哈希键取 x-aisix-routing-key 请求头，缺失时回退到调用方 API Key——因此每个 API Key 会稳定落到同一个目标，调用方也可以通过该请求头按会话或最终用户绑定：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "x-aisix-routing-key: session-1a2b" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chat-canary",
    "messages": [
      {"role": "user", "content": "Hello."}
    ]
  }'

若要在不保持会话亲和的情况下按权重分配单个请求，请使用相同权重的 round_robin。当符合条件的目标集合保持稳定时，平滑加权轮询会在每个完整轮询周期内产生配置的比例。

hash_on 字段决定哈希键的来源：一条有序的来源链，取第一个非空值。可选来源为 header 和 cookie（都通过 name 指定名称）、调用方 api_key，以及解析后的 client_ip。例如按 Cookie 绑定会话：

"routing": {
  "strategy": "consistent_hash",
  "hash_on": [
    {"type": "cookie", "name": "session_id"},
    {"type": "api_key"}
  ],
  "targets": [...]
}

在开源资源文件中，将以下 chat-canary 条目添加到现有 models 集合。它使用两个现有模型名称配置 95/5 拆分：

resources.yaml（模型条目）

- display_name: chat-canary
  routing:
    strategy: consistent_hash
    targets:
      - model: gpt-4o-primary
        weight: 95
      - model: gpt-4o-secondary
        weight: 5

会话绑定与池间故障转移

将 consistent_hash 与 priority 层级组合，可以覆盖经典的主备池形态：主池中多个实例提供同一模型，备用池只在主池整体不可用时接管，两个池内部都保持缓存友好的会话亲和。这种形态适合自部署推理后端（vLLM、SGLang）——把会话固定到同一实例可以持续命中它的 KV 缓存。

对于 AISIX Enterprise 或 AISIX Cloud，请为两个池创建四个直连模型，并导出它们的模型 ID：

export VLLM_A1_ID="YOUR_ACTIVE_MODEL_1_ID"
export VLLM_A2_ID="YOUR_ACTIVE_MODEL_2_ID"
export VLLM_B1_ID="YOUR_BACKUP_MODEL_1_ID"
export VLLM_B2_ID="YOUR_BACKUP_MODEL_2_ID"

创建多目标模型：

POOLED_MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "routing",
    "display_name": "chat-pooled",
    "routing": {
      "strategy": "consistent_hash",
      "hash_on": [
        {"type": "header", "name": "x-session-id"},
        {"type": "api_key"}
      ],
      "targets": [
        {"model_id": "'"$VLLM_A1_ID"'"},
        {"model_id": "'"$VLLM_A2_ID"'"},
        {"model_id": "'"$VLLM_B1_ID"'", "priority": -1},
        {"model_id": "'"$VLLM_B2_ID"'", "priority": -1}
      ]
    }
  }' | jq -r '.model.id')

定义 vllm-a1、vllm-a2、vllm-b1 和 vllm-b2 后，将 chat-pooled 添加到 models。保持其他资源不变：

resources.yaml（模型条目）

- display_name: chat-pooled
  routing:
    strategy: consistent_hash
    hash_on:
      - type: header
        name: x-session-id
      - type: api_key
    targets:
      - model: vllm-a1          # priority 0 = 主池
      - model: vllm-a2
      - model: vllm-b1
        priority: -1            # 备用池
      - model: vllm-b2
        priority: -1

按故障升级顺序，行为如下：

• 主池健康时，备用池不接收任何流量。每个会话键哈希到主池中的一个实例并保持不变。
• 单个主池实例故障时，只有哈希到它的会话迁移——各自迁移到同一池内环上的后继实例。其他会话保持原实例不动，备用池仍然没有流量。
• 主池全部实例不可用时，流量整体切换到备用池——在备用池内部按同样方式哈希分配。第一个发现主池全灭的请求也会成功：候选遍历会在同一个请求内跨入备用层。
• 主池实例恢复后，它的会话会回归。失败只有在实例处于冷却中，或被后台健康检查标记为不健康时，才会把它从哈希环上摘掉，而这两项都需要在目标直接模型上显式开启。像上面的示例那样两者都没有配置时，它在成功处理第一个请求后会话就会回归。

max_fallbacks 限制一次请求在所有优先级层级之间最多可尝试的后续目标数，不包含首个目标；省略时可尝试所有其余目标，设为 0 时只选择首个目标，不进行跨目标故障转移。

按请求标签路由

为目标添加标签，可以按请求特定的信号路由，例如团队、套餐或环境。给每个目标添加 tags 后，在请求中通过 x-aisix-routing-tags 请求头发送逗号分隔的标签。

以下示例将主要目标标记为高级层，将备用目标标记为默认层，然后将新别名添加到调用方 API Key 允许列表：

TIERED_MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "routing",
    "display_name": "chat-tiered",
    "routing": {
      "strategy": "failover",
      "targets": [
        {"model_id": "'"$PRIMARY_MODEL_ID"'", "tags": ["premium"]},
        {"model_id": "'"$SECONDARY_MODEL_ID"'", "tags": ["default"]}
      ]
    }
  }' | jq -r '.model.id')

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/api_keys/$API_KEY_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_models": ["'"$ROUTING_MODEL_ID"'", "'"$TIERED_MODEL_ID"'"]
  }'

PATCH 请求会替换调用方密钥的允许列表。如果该密钥还应保留对 chat-canary 的访问权限，请把 CANARY_MODEL_ID 也加入列表。

携带 x-aisix-routing-tags: premium 的请求只会由标记为 premium 的目标处理，随后由配置的策略对剩余目标排序。请求未携带路由标签时，如果存在标记为 default 的目标，AISIX 会使用它们；否则所有目标都保持为候选项。如果请求提供了标签但没有匹配项，AISIX 会尝试 default 目标，只有不存在这类目标时才拒绝请求。

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "x-aisix-routing-tags: premium" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chat-tiered",
    "messages": [
      {"role": "user", "content": "Hello."}
    ]
  }'

路由请求头只会从请求头中读取，不会转发给上游服务提供方。

在开源资源文件中，将以下 chat-tiered 条目添加到现有 models 集合。它按模型名称为目标分配标签：

resources.yaml（模型条目）

- display_name: chat-tiered
  routing:
    strategy: failover
    targets:
      - model: gpt-4o-primary
        tags:
          - premium
      - model: gpt-4o-secondary
        tags:
          - default

若要筛查经由该模型到达某个目标的流量，请把安全护栏附加到多目标路由模型上，而不是附加到某个目标上：附加到目标上的安全护栏，不会在调用方寻址多目标路由模型的请求上运行。参见安全护栏作用范围由调用方寻址的模型决定。

下一步

如果目标选择应取决于请求语义，请继续阅读语义路由。使用代理错误与重试围绕网关和上游失败设计应用重试行为。