> ## 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/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/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/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/providers)。