提供商路由

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）

最高價格

提供商健康狀態與可用性

透過模型前綴指定提供商

原生提供商代理

支援的提供商