提供商路由

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）

最高价格

提供商健康状态与可用性

通过模型前缀指定提供商

原生提供商代理

支持的提供商