> ## 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 物件自訂路由——按價格、吞吐量或延遲排序；按量化級別過濾；執行資料策略。

ARouter 根據模型可用性、提供商健康狀況和成本效率，自動將每個請求路由到最優上游提供商。對於大多數使用場景，這是自動發生的，無需任何設定。

如需進階控制，可在請求體中傳入 `provider` 物件，自訂路由決策方式。

## `provider` 物件

在任何 `/v1/chat/completions` 請求中加入 `provider` 物件，可覆蓋路由預設值：

```json theme={null}
{
  "model": "openai/gpt-5.4",
  "messages": [{ "role": "user", "content": "Hello!" }],
  "provider": {
    "sort": "throughput",
    "allow_fallbacks": true
  }
}
```

### 完整欄位參考

| 欄位                         | 類型                  | 預設值       | 描述                                             |
| -------------------------- | ------------------- | --------- | ---------------------------------------------- |
| `order`                    | `string[]`          | —         | 按順序嘗試的提供商 slug 清單，例如 `["openai", "azure"]`     |
| `allow_fallbacks`          | `boolean`           | `true`    | 當主要提供商不可用時，是否允許備用提供商                           |
| `require_parameters`       | `boolean`           | `false`   | 只使用支援請求中所有參數的提供商                               |
| `data_collection`          | `"allow" \| "deny"` | `"allow"` | 控制是否使用可能儲存請求資料的提供商                             |
| `zdr`                      | `boolean`           | —         | 僅限路由到零資料保留端點                                   |
| `only`                     | `string[]`          | —         | 此請求允許的提供商 slug 清單                              |
| `ignore`                   | `string[]`          | —         | 此請求跳過的提供商 slug 清單                              |
| `quantizations`            | `string[]`          | —         | 按量化級別過濾，例如 `["int4", "int8"]`                  |
| `sort`                     | `string \| object`  | —         | 按 `"price"`、`"throughput"` 或 `"latency"` 排序提供商 |
| `preferred_min_throughput` | `number \| object`  | —         | 首選最低吞吐量（tokens/秒）                              |
| `preferred_max_latency`    | `number \| object`  | —         | 首選最大延遲（秒）                                      |
| `max_price`                | `object`            | —         | 每 token 願意支付的最高價格                              |

***

## 預設策略：基於成本的負載均衡

預設情況下，ARouter 在健康的提供商之間負載均衡請求，優先考慮成本。演算法如下：

1. 排除過去30秒內有嚴重中斷的提供商
2. 在穩定的提供商中，按價格倒數的平方加權選擇
3. 將其餘提供商作為自動回退

**範例**：若提供商 A 花費 $1/M tokens，提供商 B 花費 $2/M，提供商 C 花費 \$3/M：

* 提供商 A 被選中的可能性是提供商 C 的9倍（倒數平方加權）
* 若提供商 A 失敗，則嘗試提供商 C
* 提供商 B（近期降級）最後嘗試

如果設定了 `sort` 或 `order`，負載均衡將被停用，提供商按嚴格順序嘗試。

***

## 提供商排序

使用 `sort` 欄位明確優先選擇某個提供商屬性。負載均衡將被停用，提供商按順序嘗試。

可用排序值：

* `"price"` — 優先最低 token 成本
* `"throughput"` — 優先最高 tokens/秒
* `"latency"` — 優先最低首 token 延遲

<Tabs>
  <Tab title="TypeScript">
    ```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: "openai/gpt-5.4",
      messages: [{ role: "user", content: "Hello" }],
      // @ts-ignore
      provider: { sort: "throughput" },
    });
    ```
  </Tab>

  <Tab title="Python">
    ```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="openai/gpt-5.4",
        messages=[{"role": "user", "content": "Hello"}],
        extra_body={"provider": {"sort": "throughput"}},
    )
    ```
  </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": "openai/gpt-5.4",
        "messages": [{"role": "user", "content": "Hello"}],
        "provider": {"sort": "throughput"}
      }'
    ```
  </Tab>
</Tabs>

### `:nitro` 和 `:floor` 快捷方式

在模型 slug 後附加後綴作為排序的簡寫：

| 後綴       | 等同於                            |
| -------- | ------------------------------ |
| `:nitro` | `provider.sort = "throughput"` |
| `:floor` | `provider.sort = "price"`      |

```json theme={null}
{"model": "openai/gpt-5.4:nitro"}  // 按吞吐量排序
{"model": "openai/gpt-5.4:floor"}  // 按價格排序
```

***

## 進階排序與 Partition

使用候選模型清單（`models[]`）時，`sort` 欄位可以是帶有 `partition` 選項的物件，以控制端點如何跨模型排序。

| 欄位               | 類型       | 預設值       | 描述                                     |
| ---------------- | -------- | --------- | -------------------------------------- |
| `sort.by`        | `string` | —         | `"price"`、`"throughput"` 或 `"latency"` |
| `sort.partition` | `string` | `"model"` | `"model"`（先嘗試主模型）或 `"none"`（全域排序）      |

預設情況下（`partition: "model"`），端點按模型分組——第一個模型的端點始終在第二個模型之前嘗試。設定 `partition: "none"` 可取消此分組，允許跨所有候選模型全域排序。

### 使用案例一：跨多個模型路由到最高吞吐量

當您有多個可接受的模型並希望使用當前最快的那個時：

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const response = await client.chat.completions.create({
      // @ts-ignore
      models: [
        "anthropic/claude-sonnet-4.6",
        "openai/gpt-5.4",
        "google/gemini-2.5-flash",
      ],
      messages: [{ role: "user", content: "Hello" }],
      provider: {
        sort: { by: "throughput", partition: "none" },
      },
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = client.chat.completions.create(
        model="anthropic/claude-sonnet-4.6",
        messages=[{"role": "user", "content": "Hello"}],
        extra_body={
            "models": [
                "anthropic/claude-sonnet-4.6",
                "openai/gpt-5.4",
                "google/gemini-2.5-flash",
            ],
            "provider": {
                "sort": {"by": "throughput", "partition": "none"},
            },
        },
    )
    ```
  </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-sonnet-4.6",
          "openai/gpt-5.4",
          "google/gemini-2.5-flash"
        ],
        "messages": [{"role": "user", "content": "Hello"}],
        "provider": {
          "sort": {"by": "throughput", "partition": "none"}
        }
      }'
    ```
  </Tab>
</Tabs>

### 使用案例二：滿足效能要求的最廉價模型

將 `partition: "none"` 與效能閾值結合使用，找到仍滿足 SLA 的最低成本選項：

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const response = await client.chat.completions.create({
      // @ts-ignore
      models: [
        "anthropic/claude-sonnet-4.6",
        "openai/gpt-5.4",
        "google/gemini-2.5-flash",
      ],
      messages: [{ role: "user", content: "Hello" }],
      provider: {
        sort: { by: "price", partition: "none" },
        preferred_min_throughput: { p90: 50 },
      },
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = client.chat.completions.create(
        model="anthropic/claude-sonnet-4.6",
        messages=[{"role": "user", "content": "Hello"}],
        extra_body={
            "models": [
                "anthropic/claude-sonnet-4.6",
                "openai/gpt-5.4",
                "google/gemini-2.5-flash",
            ],
            "provider": {
                "sort": {"by": "price", "partition": "none"},
                "preferred_min_throughput": {"p90": 50},
            },
        },
    )
    ```
  </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-sonnet-4.6",
          "openai/gpt-5.4",
          "google/gemini-2.5-flash"
        ],
        "messages": [{"role": "user", "content": "Hello"}],
        "provider": {
          "sort": {"by": "price", "partition": "none"},
          "preferred_min_throughput": {"p90": 50}
        }
      }'
    ```
  </Tab>
</Tabs>

***

## 效能閾值

設定最低吞吐量或最大延遲偏好以過濾提供商。不滿足閾值的提供商會被降低優先級（移至末尾），而非完全排除。

| 欄位                         | 描述                                  |
| -------------------------- | ----------------------------------- |
| `preferred_min_throughput` | 最低 tokens/秒。可以是數字（適用於 p50）或帶百分位鍵的物件 |
| `preferred_max_latency`    | 最大首 token 延遲（秒）。可以是數字或帶百分位鍵的物件      |

### 百分位數工作原理

ARouter 在滾動5分鐘視窗內追蹤提供商效能：

| 百分位   | 含義                 |
| ----- | ------------------ |
| `p50` | 50% 的請求效能優於此值（中位數） |
| `p75` | 75% 的請求效能優於此值      |
| `p90` | 90% 的請求效能優於此值      |
| `p99` | 99% 的請求效能優於此值      |

更高的百分位（p90/p99）可對最差情況效能提供更高置信度。所有指定的百分位截止值都必須滿足，提供商才能進入優選組。

```json theme={null}
{
  "provider": {
    "preferred_min_throughput": {
      "p50": 100,
      "p90": 50
    },
    "preferred_max_latency": {
      "p99": 3.0
    }
  }
}
```

<Note>
  `preferred_min_throughput` 和 `preferred_max_latency` 是軟偏好——它們不會阻止請求被處理。這與 `max_price` 不同，後者是硬限制。
</Note>

***

## 指定提供商順序

使用 `order` 指定要嘗試的提供商及其順序。設定 `order` 後負載均衡將被停用。

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const response = await client.chat.completions.create({
      model: "openai/gpt-5.4",
      messages: [{ role: "user", content: "Hello" }],
      // @ts-ignore
      provider: {
        order: ["openai", "azure"],
      },
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = client.chat.completions.create(
        model="openai/gpt-5.4",
        messages=[{"role": "user", "content": "Hello"}],
        extra_body={
            "provider": {
                "order": ["openai", "azure"],
            }
        },
    )
    ```
  </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": "openai/gpt-5.4",
        "messages": [{"role": "user", "content": "Hello"}],
        "provider": {"order": ["openai", "azure"]}
      }'
    ```
  </Tab>
</Tabs>

## 僅允許特定提供商

使用 `only` 將路由限制為特定提供商集合：

```json theme={null}
{
  "model": "meta-llama/llama-4-maverick",
  "messages": [{ "role": "user", "content": "Hello" }],
  "provider": {
    "only": ["groq", "together"]
  }
}
```

## 忽略提供商

使用 `ignore` 跳過此請求的特定提供商：

```json theme={null}
{
  "model": "openai/gpt-5.4",
  "messages": [{ "role": "user", "content": "Hello" }],
  "provider": {
    "ignore": ["azure"]
  }
}
```

## 停用回退

預設情況下，若主要提供商不可用，ARouter 會回退到備用提供商。設定 `allow_fallbacks: false` 可要求使用精確的提供商：

```json theme={null}
{
  "model": "openai/gpt-5.4",
  "messages": [{ "role": "user", "content": "Hello" }],
  "provider": {
    "order": ["openai"],
    "allow_fallbacks": false
  }
}
```

若指定的提供商不可用，ARouter 將返回 `503` 錯誤，而非路由到其他地方。

***

## 要求參數支援

設定 `require_parameters: true`，只路由到支援請求中所有參數的提供商。預設情況下，ARouter 可能會路由到忽略不支援參數的提供商。

```json theme={null}
{
  "model": "openai/gpt-5.4",
  "messages": [{ "role": "user", "content": "Hello" }],
  "tools": [...],
  "provider": {
    "require_parameters": true
  }
}
```

***

## 量化過濾

按提供商提供的模型量化級別過濾。當您需要特定精度/效能權衡時非常有用：

```json theme={null}
{
  "model": "meta-llama/llama-4-maverick",
  "messages": [{ "role": "user", "content": "Hello" }],
  "provider": {
    "quantizations": ["fp16", "bf16"]
  }
}
```

常見量化值：`"fp32"`、`"fp16"`、`"bf16"`、`"int8"`、`"int4"`。

***

## 資料收集策略

控制 ARouter 是否路由到可能儲存您請求資料的提供商：

| 值             | 行為                    |
| ------------- | --------------------- |
| `"allow"`（預設） | 路由到任何提供商，包括可能儲存資料的提供商 |
| `"deny"`      | 只路由到不儲存請求/回應資料的提供商    |

```json theme={null}
{
  "model": "anthropic/claude-sonnet-4.6",
  "messages": [{ "role": "user", "content": "Sensitive content" }],
  "provider": {
    "data_collection": "deny"
  }
}
```

## 零資料保留（ZDR）

為最大程度保護隱私，將路由限制為具有零資料保留保證的提供商：

```json theme={null}
{
  "model": "openai/gpt-5.4",
  "messages": [{ "role": "user", "content": "Hello" }],
  "provider": {
    "zdr": true
  }
}
```

ZDR 提供商不會記錄、儲存或將請求資料用於訓練。詳情請參閱[資料收集](/zh-Hant/guides/privacy/data-collection)。

***

## 最高價格

設定每 token 願意支付的硬性上限。若沒有提供商滿足價格要求，請求將失敗而非路由到更貴的提供商：

```json theme={null}
{
  "model": "openai/gpt-5.4",
  "messages": [{ "role": "user", "content": "Hello" }],
  "provider": {
    "max_price": {
      "prompt": "0.000010",
      "completion": "0.000030"
    }
  }
}
```

<Note>
  與效能閾值不同，`max_price` 是硬性限制。若沒有提供商滿足價格要求，請求將返回錯誤。
</Note>

***

## 提供商健康狀態與可用性

ARouter 使用熔斷機制持續追蹤提供商健康狀態：

| 狀態      | 行為                       |
| ------- | ------------------------ |
| **健康**  | 提供商正常接受請求                |
| **降級**  | 偵測到近期故障；請求可能使用不同金鑰重試     |
| **不可用** | 所有金鑰已熔斷；ARouter 返回 `503` |

這是完全透明的——您的應用程式無需實作提供商級別的重試邏輯。

***

## 透過模型前綴指定提供商

控制哪個提供商處理請求的主要方式是透過 `provider/model` 格式：

```json theme={null}
{
  "model": "openai/gpt-5.4",
  "messages": [{ "role": "user", "content": "Hello!" }]
}
```

支援的完整格式清單請參閱[模型路由](/zh-Hant/model-routing)。

## 原生提供商代理

如需完全控制，使用提供商代理端點 `/{provider}/{path}` 完全繞過 ARouter 的模型路由層：

```bash theme={null}
# 直連 OpenAI
curl https://api.arouter.ai/openai/v1/chat/completions \
  -H "Authorization: Bearer lr_live_xxxx" \
  -d '{"model": "gpt-5.4", "messages": [...]}'

# 直連 Anthropic
curl https://api.arouter.ai/anthropic/v1/messages \
  -H "Authorization: Bearer lr_live_xxxx" \
  -d '{"model": "claude-sonnet-4.6", "messages": [...]}'
```

完整參考請參閱[提供商代理](/zh-Hant/guides/provider-proxy)。

***

## 支援的提供商

| 提供商       | 前綴           | 範例模型                           |
| --------- | ------------ | ------------------------------ |
| OpenAI    | `openai`     | `openai/gpt-5.4`               |
| Anthropic | `anthropic`  | `anthropic/claude-sonnet-4.6`  |
| Google    | `google`     | `google/gemini-2.5-flash`      |
| DeepSeek  | `deepseek`   | `deepseek/deepseek-v3.2`       |
| xAI       | `x-ai`       | `x-ai/grok-4.20`               |
| Mistral   | `mistralai`  | `mistralai/mistral-large-2512` |
| Meta      | `meta-llama` | `meta-llama/llama-4-maverick`  |
| Qwen      | `qwen`       | `qwen/qwen3-235b`              |
| MiniMax   | `minimax`    | `minimax/minimax-m2.7`         |
| Groq      | `groq`       | `groq/llama-3.3-70b-versatile` |
| Kimi      | `moonshotai` | `moonshotai/kimi-k2.5`         |
| Dashscope | `dashscope`  | `dashscope/qwen-max`           |

完整功能清單請參閱[提供商](/zh-Hant/providers)。