> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arouter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 模型路由

> ARouter 如何使用 provider/model 格式、`auto` 以及有序候选模型列表将请求路由到正确的提供商。

## `provider/model` 格式

使用与 OpenAI 兼容的端点（`/v1/chat/completions`、`/v1/embeddings`）时，
请使用 `provider/model` 格式指定模型：

```json theme={null}
{
  "model": "anthropic/claude-sonnet-4.6",
  "messages": [{"role": "user", "content": "Hello!"}]
}
```

ARouter 解析提供商前缀，将请求路由到正确的上游，
并在转发前将 `model` 字段改写为提供商的原生格式。

## 示例

| 您发送                            | 提供商        | 上游模型                 |
| ------------------------------ | ---------- | -------------------- |
| `openai/gpt-5.4`               | OpenAI     | `gpt-5.4`            |
| `anthropic/claude-sonnet-4.6`  | Anthropic  | `claude-sonnet-4.6`  |
| `google/gemini-2.5-flash`      | Google     | `gemini-2.5-flash`   |
| `deepseek/deepseek-v3.2`       | DeepSeek   | `deepseek-v3.2`      |
| `x-ai/grok-4.20`               | xAI        | `grok-4.20`          |
| `mistralai/mistral-large-2512` | Mistral    | `mistral-large-2512` |
| `meta-llama/llama-4-maverick`  | Meta       | `llama-4-maverick`   |
| `gpt-5.4`                      | OpenAI（默认） | `gpt-5.4`            |

<Tip>
  如果省略提供商前缀，ARouter 默认使用 **OpenAI**。
  因此 `"model": "gpt-5.4"` 等同于 `"model": "openai/gpt-5.4"`。
</Tip>

## 原生 SDK 端点

对于拥有自己 SDK 格式的提供商，请直接使用原生端点。
提供商由端点路径决定，而非 model 字段：

| SDK       | 端点                                            | 模型格式                   |
| --------- | --------------------------------------------- | ---------------------- |
| Anthropic | `POST /v1/messages`                           | 原生：`claude-sonnet-4.6` |
| Gemini    | `POST /v1beta/models/{model}:generateContent` | 原生：`gemini-2.5-flash`  |
| MiniMax   | `POST /v1/text/chatcompletion_v2`             | 原生：`minimax-m2.7`      |

<Note>
  原生端点**不**使用 `provider/model` 前缀——它们使用提供商的
  原始模型名称，因为提供商已由端点路径隐含确定。
</Note>

## 通用提供商代理

对于任何提供商，您也可以使用通用代理格式：

```
POST /{provider}/v1/chat/completions
```

例如：

* `POST /openai/v1/chat/completions` → 代理至 OpenAI
* `POST /deepseek/v1/chat/completions` → 代理至 DeepSeek
* `POST /anthropic/v1/messages` → 代理至 Anthropic

当您想绕过 model 字段解析并明确控制哪个提供商接收请求时，此方式非常有用。

## 自动路由

将 `model` 设置为 `"auto"`，ARouter 将自动为您的提示选择最佳可用模型。无需任何模型配置。

```json theme={null}
{
  "model": "auto",
  "messages": [{ "role": "user", "content": "Explain quantum entanglement in simple terms" }]
}
```

### 工作原理

1. ARouter 的路由服务分析您的请求（提示复杂度、任务类型、所需模态等）
2. 根据成本效率和质量，从健康的可用提供商中选出最优模型
3. 将您的请求转发至所选模型
4. 响应中包含 `model` 字段，显示实际使用的模型

### 限制可选模型

使用 `auto-router` 插件通过通配符模式限制 `auto` 可选择的模型范围：

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const response = await client.chat.completions.create({
      model: "auto",
      messages: [{ role: "user", content: "Explain quantum entanglement" }],
      // @ts-ignore
      plugins: [
        {
          id: "auto-router",
          allowed_models: ["anthropic/*", "openai/gpt-5.4"],
        },
      ],
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = client.chat.completions.create(
        model="auto",
        messages=[{"role": "user", "content": "Explain quantum entanglement"}],
        extra_body={
            "plugins": [
                {
                    "id": "auto-router",
                    "allowed_models": ["anthropic/*", "openai/gpt-5.4"],
                }
            ]
        },
    )
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.arouter.ai/v1/chat/completions \
      -H "Authorization: Bearer lr_live_xxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "auto",
        "messages": [{"role": "user", "content": "Explain quantum entanglement"}],
        "plugins": [
          {
            "id": "auto-router",
            "allowed_models": ["anthropic/*", "openai/gpt-5.4"]
          }
        ]
      }'
    ```
  </Tab>
</Tabs>

**模式语法：**

| 模式               | 匹配                      |
| ---------------- | ----------------------- |
| `anthropic/*`    | 所有 Anthropic 模型         |
| `openai/gpt-5*`  | 所有 GPT-5 变体             |
| `google/*`       | 所有 Google 模型            |
| `openai/gpt-5.4` | 仅精确匹配                   |
| `*/claude-*`     | 任何提供商中模型名含 "claude" 的模型 |

```json theme={null}
{
  "id": "chatcmpl-xxx",
  "model": "anthropic/claude-sonnet-4.6",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 120,
    "total_tokens": 135
  }
}
```

请始终检查 `response.model` 以确认实际使用的模型。

### 代码示例

<Tabs>
  <Tab title="Python (OpenAI)">
    ```python theme={null}
    from openai import OpenAI

    client = OpenAI(
        base_url="https://api.arouter.ai/v1",
        api_key="lr_live_xxxx",
    )

    response = client.chat.completions.create(
        model="auto",
        messages=[{"role": "user", "content": "Explain quantum entanglement in simple terms"}],
    )

    print(response.choices[0].message.content)
    print("Model used:", response.model)
    ```
  </Tab>

  <Tab title="Node.js (OpenAI)">
    ```typescript theme={null}
    import OpenAI from "openai";

    const client = new OpenAI({
      baseURL: "https://api.arouter.ai/v1",
      apiKey: "lr_live_xxxx",
    });

    const response = await client.chat.completions.create({
      model: "auto",
      messages: [{ role: "user", content: "Explain quantum entanglement in simple terms" }],
    });

    console.log(response.choices[0].message.content);
    console.log("Model used:", response.model);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    resp, err := client.CreateChatCompletion(ctx, arouter.ChatCompletionRequest{
        Model: "auto",
        Messages: []arouter.Message{
            {Role: "user", Content: "Explain quantum entanglement in simple terms"},
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(resp.Choices[0].Message.Content)
    fmt.Println("Model used:", resp.Model)
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.arouter.ai/v1/chat/completions \
      -H "Authorization: Bearer lr_live_xxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "auto",
        "messages": [{"role": "user", "content": "Explain quantum entanglement in simple terms"}]
      }'
    ```
  </Tab>
</Tabs>

### 使用场景

* **通用应用** — 当您不确定用户会发送哪类提示时
* **成本优化** — 让 ARouter 自动将简单任务路由到高效模型
* **零配置原型** — 无需选择特定模型即可快速上手
* **自适应路由** — 先让 ARouter 自动选择，仅在需要精确控制时再切换为有序候选列表

### 限制说明

* 自动路由使用标准 `messages` 请求格式
* 自动路由从您账户可用的模型中选择
* 流式传输完全支持 `"model": "auto"`
* 您按 ARouter 所选模型的正常费率付费，不收取额外路由费
* 所选模型始终体现在响应的 `model` 字段中

***

## 候选模型列表

将 `models` 数组与 `route` 结合使用，让 ARouter 按顺序遍历候选模型列表。

```json theme={null}
{
  "models": [
    "anthropic/claude-opus-4.5",
    "openai/gpt-5.4",
    "google/gemini-2.5-flash"
  ],
  "route": "fallback",
  "messages": [{ "role": "user", "content": "Hello!" }]
}
```

### 工作原理

1. ARouter 尝试列表中的第一个模型
2. 如果该模型无法处理请求（提供商错误、速率限制、密钥不可用），则切换到下一个
3. 如果所有模型均失败，ARouter 返回含最后一次失败原因的错误

### 路由行为

| 触发条件      | 行为        |
| --------- | --------- |
| 提供商不可用    | 切换到下一个模型  |
| 速率限制（429） | 切换到下一个模型  |
| 模型未找到     | 切换到下一个模型  |
| 错误请求（400） | 停止并返回请求错误 |

### 控制分区行为

默认情况下，使用候选列表时，端点按模型分组——第一个模型的端点始终在第二个模型之前尝试。您可以通过 `provider.sort.partition` 更改此行为：

```json theme={null}
{
  "models": [
    "anthropic/claude-sonnet-4.6",
    "openai/gpt-5.4",
    "google/gemini-2.5-flash"
  ],
  "route": "fallback",
  "messages": [{ "role": "user", "content": "Hello!" }],
  "provider": {
    "sort": {
      "by": "throughput",
      "partition": "none"
    }
  }
}
```

设置 `partition: "none"` 可在所有候选模型间全局排序端点——当您希望使用当前最快的模型而不关心列表顺序时非常有用。完整参考请参阅[提供商路由](/zh/provider-routing#advanced-sorting-with-partition)。

### 在 OpenAI SDK 中使用候选列表

OpenAI SDK 原生不支持 `models` 参数。请使用 `extra_body` 传入：

<Tabs>
  <Tab title="Python (OpenAI)">
    ```python theme={null}
    from openai import OpenAI

    client = OpenAI(
        base_url="https://api.arouter.ai/v1",
        api_key="lr_live_xxxx",
    )

    response = client.chat.completions.create(
        model="anthropic/claude-opus-4.5",  # 第一候选
        messages=[{"role": "user", "content": "Hello!"}],
        extra_body={
            "models": [
                "anthropic/claude-opus-4.5",
                "openai/gpt-5.4",
                "google/gemini-2.5-flash",
            ],
            "route": "fallback",
        },
    )
    print(response.choices[0].message.content)
    ```
  </Tab>

  <Tab title="Node.js (OpenAI)">
    ```typescript theme={null}
    import OpenAI from "openai";

    const client = new OpenAI({
      baseURL: "https://api.arouter.ai/v1",
      apiKey: "lr_live_xxxx",
    });

    const response = await client.chat.completions.create({
      model: "anthropic/claude-opus-4.5", // 第一候选
      messages: [{ role: "user", content: "Hello!" }],
      // @ts-ignore — extra_body 不在类型定义中
      models: [
        "anthropic/claude-opus-4.5",
        "openai/gpt-5.4",
        "google/gemini-2.5-flash",
      ],
      route: "fallback",
    });
    console.log(response.choices[0].message.content);
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.arouter.ai/v1/chat/completions \
      -H "Authorization: Bearer lr_live_xxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "models": [
          "anthropic/claude-opus-4.5",
          "openai/gpt-5.4",
          "google/gemini-2.5-flash"
        ],
        "route": "fallback",
        "messages": [{"role": "user", "content": "Hello!"}]
      }'
    ```
  </Tab>
</Tabs>

## 助手预填充

ARouter 支持让模型补全部分响应。在 `messages` 数组末尾添加一条 `role: "assistant"` 的消息，即可从您留下的位置继续：

```json theme={null}
{
  "model": "anthropic/claude-sonnet-4.6",
  "messages": [
    { "role": "user", "content": "Name 3 popular programming languages." },
    { "role": "assistant", "content": "1." }
  ]
}
```

模型将从预填充的助手消息继续。此技术适用于：

* 强制特定输出格式
* 恢复多轮补全
* 引导模型生成特定响应结构

<Note>
  并非所有模型都支持助手预填充。Anthropic Claude 和大多数开源模型支持此功能。OpenAI 模型支持有限。
</Note>

## 路由底层原理

```
1. 解析 model 字段 → 提取提供商 ID
2. 检查 API key 权限 → 该提供商是否被允许？
3. 调用路由服务 → 选择区域，从池中挑选健康密钥
4. 改写 model 字段 → 去除提供商前缀
5. 反向代理 → 使用提供商 API key 转发至上游
6. 流式返回响应 → 异步记录用量
```

ARouter 完全透明地处理提供商 API key 注入、健康检查和故障转移。
您的应用程序永远不会看到上游提供商的凭据。