> ## 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-Hant/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 注入、健康檢查和故障轉移。
您的應用程式永遠不會看到上游提供商的憑證。