提供商路由

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）

最高價格

提供商健康狀態與可用性

透過模型前綴指定提供商

原生提供商代理

支援的提供商