---
title: "模型回退"
description: "请求的模型不可用时，pirouter 的模型回退会自动改用另一个模型。本页说明备用模型怎么写、什么时候切换、怎么计费。"
canonical: "https://pirouter.ai/zh/docs/fallbacks"
last-updated: "2026-10-13"
lang: "zh"
source: "content/docs/zh/(start)/fallbacks.mdx"
---

# 模型回退

请求的模型不可用时，pirouter 的模型回退会自动改用另一个模型。本页说明备用模型怎么写、什么时候切换、怎么计费。

[Provider 路由](https://pirouter.ai/zh/docs/routing.md)在同一个模型的多家 provider 之间切换。模型回退更进一步：一个模型的所有 provider 都用不了时，pirouter 改用你指定的下一个模型。

## 在请求里写备用模型

在请求体里加一个 `models` 数组。pirouter 先试 `model`，不行再按数组顺序试。

```bash
curl https://api.pirouter.ai/v1/chat/completions \
  -H "Authorization: Bearer $PIROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5.5",
    "models": ["anthropic/claude-haiku-5.5", "openai/gpt-6-sol"],
    "messages": [{ "role": "user", "content": "Hello!" }]
  }'
```

- `models` 最多 3 个，超过返回 `422`。
- 和 `model` 相同的、重复的条目会被去掉。
- 不写 `model` 时，`models` 的第一个就是主模型。
- 三种协议的请求都可以带 `models`。Gemini 协议的主模型在路径里，`models` 只是备用。

所有备用模型在请求一开始就会被核对。其中任何一个不存在，整个请求返回 `404 model_not_found`，`message` 指出是哪一个，此时还没有转发任何请求。

`route` 字段只接受 `"fallback"`，写不写效果相同。

## 在工作区里设备用模型

在控制台 **路由** 页的 **备用模型** 里添加，最多 3 个，只能选对话类的文本模型。只有工作区所有者能改。

工作区的备用模型只在请求自己没有写 `models` 时生效。请求写了 `models`，就只用请求里的，不会再追加工作区的。

工作区列表里已经下线的模型会被跳过，不报错。

## 什么时候会切换

两种情况会换到下一个模型：

1. 当前模型没有可用的 provider：被[路由设置](https://pirouter.ai/zh/docs/routing.md#一家都不剩时)排空了，或者都处于不可用状态。
2. 当前模型的 provider 在返回第一个字节之前失败，并且这个模型已经没有别的 provider 可以重试。

pirouter 只在响应开始之前切换模型。响应一旦开始，不管后面出什么错，都不会再换模型。

一个请求在所有模型上合计最多尝试 5 次。

`provider` 里的 `"allow_fallbacks": false` 只限制 provider，不限制 `models`：换到下一个模型时，会重新在那个模型的 provider 里选。

## 计费

只为实际给出回答的那一次付费，按它自己的模型和 provider 的价格算。中途失败、被下一次接手的尝试不计费。

## 怎么知道用了哪个模型

响应体的 `model` 是实际给出回答的那个模型的 ID。它和你请求里写的 `model` 不同，就说明发生了回退。`X-Pi-Model` 响应头是同一个值，`X-Pi-Provider` 是处理它的 provider。

## 目前没有的能力

- **预设（preset）。** 请求里带 `preset` 会返回 `422`。
- **专门标明发生过回退的字段。** 比较响应的 `model` 和请求的 `model` 来判断。

## 下一步

- [Provider 路由](https://pirouter.ai/zh/docs/routing.md): 在同一个模型的多家 provider 之间怎么选。
- [模型与协议](https://pirouter.ai/zh/docs/models.md): 模型 ID 怎么写，每个模型接受哪些协议。