提供商路由

ARouter 根据模型可用性、提供商健康状况和成本效率，自动将每个请求路由到最优上游提供商。对于大多数使用场景，这是自动发生的，无需任何配置。如需高级控制，可在请求体中传入 provider 对象，自定义路由决策方式。

`provider` 对象

在任何 /v1/chat/completions 请求中加入 provider 对象，可覆盖路由默认值：

{
  "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 在健康的提供商之间负载均衡请求，优先考虑成本。算法如下：

排除过去30秒内有严重中断的提供商
在稳定的提供商中，按价格倒数的平方加权选择
将其余提供商作为自动回退

示例：若提供商 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 延迟

TypeScript
Python
cURL

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" },
});

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"}},
)

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"}
  }'

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

在模型 slug 后附加后缀作为排序的简写：

后缀	等同于
`:nitro`	`provider.sort = "throughput"`
`:floor`	`provider.sort = "price"`

{"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" 可取消此分组，允许跨所有候选模型全局排序。

用例一：跨多个模型路由到最高吞吐量

当您有多个可接受的模型并希望使用当前最快的那个时：

TypeScript
Python
cURL

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" },
  },
});

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"},
        },
    },
)

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"}
    }
  }'

用例二：满足性能要求的最廉价模型

将 partition: "none" 与性能阈值结合使用，找到仍满足 SLA 的最低成本选项：

TypeScript
Python
cURL

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 },
  },
});

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},
        },
    },
)

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}
    }
  }'

性能阈值

设置最低吞吐量或最大延迟偏好以过滤提供商。不满足阈值的提供商会被降低优先级（移至末尾），而非完全排除。

字段	描述
`preferred_min_throughput`	最低 tokens/秒。可以是数字（适用于 p50）或带百分位键的对象
`preferred_max_latency`	最大首 token 延迟（秒）。可以是数字或带百分位键的对象

百分位数工作原理

ARouter 在滚动5分钟窗口内跟踪提供商性能：

百分位	含义
`p50`	50% 的请求性能优于此值（中位数）
`p75`	75% 的请求性能优于此值
`p90`	90% 的请求性能优于此值
`p99`	99% 的请求性能优于此值

更高的百分位（p90/p99）可对最差情况性能提供更高置信度。所有指定的百分位截止值都必须满足，提供商才能进入优选组。

{
  "provider": {
    "preferred_min_throughput": {
      "p50": 100,
      "p90": 50
    },
    "preferred_max_latency": {
      "p99": 3.0
    }
  }
}

preferred_min_throughput 和 preferred_max_latency 是软偏好——它们不会阻止请求被处理。这与 max_price 不同，后者是硬限制。

指定提供商顺序

使用 order 指定要尝试的提供商及其顺序。设置 order 后负载均衡将被禁用。

TypeScript
Python
cURL

const response = await client.chat.completions.create({
  model: "openai/gpt-5.4",
  messages: [{ role: "user", content: "Hello" }],
  // @ts-ignore
  provider: {
    order: ["openai", "azure"],
  },
});

response = client.chat.completions.create(
    model="openai/gpt-5.4",
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={
        "provider": {
            "order": ["openai", "azure"],
        }
    },
)

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"]}
  }'

仅允许特定提供商

使用 only 将路由限制为特定提供商集合：

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

忽略提供商

使用 ignore 跳过此请求的特定提供商：

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

禁用回退

默认情况下，若主要提供商不可用，ARouter 会回退到备用提供商。设置 allow_fallbacks: false 可要求使用精确的提供商：

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

若指定的提供商不可用，ARouter 将返回 503 错误，而非路由到其他地方。

要求参数支持

设置 require_parameters: true，只路由到支持请求中所有参数的提供商。默认情况下，ARouter 可能会路由到忽略不支持参数的提供商。

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

量化过滤

按提供商提供的模型量化级别过滤。当您需要特定精度/性能权衡时非常有用：

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

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

数据收集策略

控制 ARouter 是否路由到可能存储您请求数据的提供商：

值	行为
`"allow"`（默认）	路由到任何提供商，包括可能存储数据的提供商
`"deny"`	只路由到不存储请求/响应数据的提供商

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

零数据保留（ZDR）

为最大程度保护隐私，将路由限制为具有零数据保留保证的提供商：

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

ZDR 提供商不会记录、存储或将请求数据用于训练。详情请参阅数据收集。

最高价格

设置每 token 愿意支付的硬性上限。若没有提供商满足价格要求，请求将失败而非路由到更贵的提供商：

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

与性能阈值不同，max_price 是硬性限制。若没有提供商满足价格要求，请求将返回错误。

提供商健康状态与可用性

ARouter 使用熔断机制持续跟踪提供商健康状态：

状态	行为
健康	提供商正常接受请求
降级	检测到近期故障；请求可能使用不同密钥重试
不可用	所有密钥已熔断；ARouter 返回 `503`

这是完全透明的——您的应用程序无需实现提供商级别的重试逻辑。

通过模型前缀指定提供商

控制哪个提供商处理请求的主要方式是通过 provider/model 格式：

{
  "model": "openai/gpt-5.4",
  "messages": [{ "role": "user", "content": "Hello!" }]
}

支持的完整格式列表请参阅模型路由。

原生提供商代理

如需完全控制，使用提供商代理端点 /{provider}/{path} 完全绕过 ARouter 的模型路由层：

# 直连 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": [...]}'

完整参考请参阅提供商代理。

支持的提供商

提供商	前缀	示例模型
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`

完整功能列表请参阅提供商。

快速开始

核心概念

路由

功能特性

使用指南

隐私

管理

最佳实践

框架与集成

供应商接入

帮助

`provider` 对象

完整字段参考

默认策略：基于成本的负载均衡

提供商排序

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

高级排序与 Partition

用例一：跨多个模型路由到最高吞吐量

用例二：满足性能要求的最廉价模型

性能阈值

百分位数工作原理

指定提供商顺序

仅允许特定提供商

忽略提供商

禁用回退

要求参数支持

量化过滤

数据收集策略

零数据保留（ZDR）

最高价格

提供商健康状态与可用性

通过模型前缀指定提供商

原生提供商代理

支持的提供商

快速开始

核心概念

路由

功能特性

使用指南

隐私

管理

最佳实践

框架与集成

供应商接入

帮助

​provider 对象

​完整字段参考

​默认策略：基于成本的负载均衡

​提供商排序

​:nitro 和 :floor 快捷方式

​高级排序与 Partition

​用例一：跨多个模型路由到最高吞吐量

​用例二：满足性能要求的最廉价模型

​性能阈值

​百分位数工作原理

​指定提供商顺序

​仅允许特定提供商

​忽略提供商

​禁用回退

​要求参数支持

​量化过滤

​数据收集策略

​零数据保留（ZDR）

​最高价格

​提供商健康状态与可用性

​通过模型前缀指定提供商

​原生提供商代理

​支持的提供商

`provider` 对象

完整字段参考

默认策略：基于成本的负载均衡

提供商排序

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

高级排序与 Partition

用例一：跨多个模型路由到最高吞吐量

用例二：满足性能要求的最廉价模型

性能阈值

百分位数工作原理

指定提供商顺序

仅允许特定提供商

忽略提供商

禁用回退

要求参数支持

量化过滤

数据收集策略

零数据保留（ZDR）

最高价格

提供商健康状态与可用性

通过模型前缀指定提供商

原生提供商代理

支持的提供商