多供應商路由與回退設定

provider 對象的欄位與作用域

`provider` 對象放在請求體內，只對這一次 Chat Completions 請求生效，不會持久化到帳戶或後續呼叫。它的作用是覆蓋預設的负載均衡逻辑，向路由層表達「這次請求希望怎樣挑選後端」。

欄位大致可分為四類。

第一類，候選集合的裁剪。`order` 給出按順序嘗試的供應商 slug 清單，例如 `["anthropic", "openai"]`，路由會按順序逐個嘗試，前面不可用時顺延到下一個。`only` 是白名單，只允許清單內的供應商響應本次請求。`ignore` 则是黑名單，跳過清單內的供應商。`quantizations` 用於按量化等級過濾，例如 `["int4", "int8"]`，不符合量化的端點會被排除。

第二類，回退與策略開關。`allow_fallbacks` 預設 `true`，當首選供應商不可用時，路由可切換到備份供應商；設為 `false` 则禁用回退。`require_parameters` 預設 `false`，設為 `true` 時，只選用支援請求中全部參數的供應商。`data_collection` 控制是否允許可能存储資料的供應商參與路由。`zdr` 用於把候選範圍限制在零資料保留端點。`enforce_distillable_text` 把候選限制在允許文字蒸馏的端點。

第三類，排序與阈值。`sort` 可以是字符串，也可以是帶 `by` 與 `partition` 欄位的對象。字符串形式下，`"price"` 按價格從低到高，`"throughput"` 按吞吐從高到低，`"latency"` 按延遲從低到高。`partition` 預設 `"model"`，即先按模型分組再排序；設為 `"none"` 時跨模型全局排序。一旦顯式設定 `sort` 或 `order`，預設的负載均衡會被關閉，路由改為按清單順序嘗試。`preferred_min_throughput` 是首選最低吞吐（tokens/s），可以是數位，也可以是帶 p50、p75、p90、p99 分位阈值的對象。`preferred_max_latency` 類似，針對延遲。低於阈值的端點不會被直接剔除，而是被排到清單末尾，仍可作為回退。

第四類，價格上限。`max_price` 用於限定本次請求愿意支付的最高價格，超出的端點不會被選中。

預設的價格负載均衡策略

在不传入 `provider` 對象，也不顯式設定 `sort` 或 `order` 的情況下，請求會走預設策略。其核心目標是「在保證可用性的前提下，按價格分配流量」。

策略分三步。第一步，剔除在最近 30 秒內出現過顯著故障的供應商，只在目前表現穩定的供應商集合內挑選，避免把請求投放到刚刚抖動的端點上。第二步，在穩定集合中，取候選裡價格最低的几個供應商做加權抽樣，權重與價格的反平方成正比。價格越低，被選中的概率越高，但低價供應商不會被獨占，其他低價端點也會分到一部分流量，從而把负載摊開。第三步，把集合中剩下的供應商作為回退，當首選與加權選中的供應商不可用時顺延兜底。

這個預設行為只針對單模型請求。如果同時指定了 `sort` 或 `order`，负載均衡自動關閉，路由改為按你指定的順序逐個嘗試，而不是按價格權重分配。

價格、吞吐量與延遲的顯式排序

預設的负載均衡策略已經按價格和近 30 秒內的穩定性做了加權選擇，但只要請求體裡出現了 `sort` 或 `order`，负載均衡就會立刻關閉，路由器改為按聲明的順序逐個嘗試供應商。`sort` 欄位接受三種字符串取值，分別是 `"price"`、`"throughput"`、`"latency"`，分別表示取價格最低、吞吐量最高、延遲最低的供應商。一旦顯式聲明 `sort`，路由器就會把候選供應商按該維度排序，然後順序嘗試，失敗再回退到下一位，這與預設的加權隨機分配是两套機制。

在多模型回退場景下，`sort` 還可以寫成帶有 `by` 與 `partition` 的對象。`by` 欄位的內容仍然是 `price`、`throughput`、`latency` 三個值之一，`partition` 控制候選端點是否按模型分組後再排序。預設 `partition` 為 `"model"`，意味着無論效能指標如何，路由器都會先把主模型的端點排到前面，直到它們全部失敗才考虑回退模型。把 `partition` 設為 `"none"` 後，分組規則被取消，所有候選端點會按全局 `by` 維度混合排序，路由器會直接從任意模型裡挑選目前吞吐量最高或延遲最低的那一個。該寫法適用於"多個模型都能接受、只關心當下速度"的場景。

在模型 slug 後追加 `:nitro` 或 `:floor` 是另一種簡寫形式。`:nitro` 在啟用吞吐量排序之外，還會放開優先級服務層端點的使用範圍，是 `provider.sort = "throughput"` 的超集；`:floor` 同理，在價格排序之外放開弹性服務層端點的資格，是 `sort = "price"` 的超集。两種簡寫都不需要手動改 `provider` 對象，但都屬於顯式排序的一種，會触發與設定 `sort` 相同的负載均衡關閉行為。

效能阈值的百分位設定

`preferred_min_throughput` 與 `preferred_max_latency` 這两個欄位用於在排序之外再加一層過濾門檻，前者表示可接受的最低吞吐量（單位為 token/秒），後者表示可接受的最高延遲（單位為秒）。它們既可以直接传入一個數位，也可以寫成對象形式。传入數位時，該數位會被自動绑定到 p50 分位數；寫入對象時，可以針對 p50、p75、p90、p99 各自指定一個阈值。路由器對每個模型與供應商的吞吐和延遲指標都維護着滚動 5 分鐘窗口的分位數統計，因此阈值的依據是最近 5 分鐘內的實測樣本，而不是即時單次測量。

當同時給出多個分位數阈值時，必須所有阈值都被满足，對應的模型與供應商才會進入"首選組"。例如同時設定 p50 與 p90 的延遲上限，意味着既要在中位數附近達標，也要在尾部延遲上達標。落在阈值之外的端點不會被剔除，只是被移到清單末尾，保留作為最終回退；只有當首選組中所有供應商都不可用時，這些降級端點才會被實際呼叫。

不同分位數反映不同的效能侧面。p50 是中位數，能體現典型水平；p90 與 p99 反映尾部情況，更接近最坏情形，可用於即時互動類場景。p50 阈值適合离線批次任務，這類場景更看重平均吞吐而非尾部抖動。把 `partition: "none"` 與 `preferred_min_throughput` 配合使用，可以讓路由器在多個候選模型之間挑出满足效能下限且價格最低的那一個，而不是先把某個模型的端點全部嘗試一遍後再回退到其他模型。

回退開關與禁用回退的場景

`provider` 對象裡的 `allow_fallbacks` 欄位是控制回退行為的總開關，預設值為 `true`。在預設负載均衡策略下，OpenRouter 會先排除最近 30 秒內出現顯著故障的供應商，然後在剩余的低價候選裡按價格的反平方加權選擇主供應商，其余供應商作為回退備份。當這一欄位被顯式設為 `false` 時，路由器只會嘗試被選中的那一個供應商或 `order` 清單裡指定的那批供應商，不再向清單外的供應商轉移請求。

`order` 欄位接收一個供應商 slug 數組，路由器按數組順序依次嘗試，一旦某個供應商不可用就會移到下一個。`order` 與 `allow_fallbacks=false` 配合使用時，行為收敛到「只信任這几個供應商」，其余一概不碰，適合強一致性場景。例如一個應用要求必須走 OpenAI 的某條企業專線，不允許請求落到任何第三方聚合端，就把 `order` 與 `allow_fallbacks` 一起配死。

禁用回退的代價是可用性轉嫁給所選供應商本身的健康度。當被锁定的供應商出現短暂抖動時，沒有備用端可以吸收流量，請求會直接失敗或回傳錯誤。所以關閉回退通常出現在三類需求裡：合規與審計要求請求只走特定供應商；呼叫方已經知道某個供應商在目前時刻是穩定的，回退反而會引入不可控延遲；或把回退交給上層的自動重試逻辑統一處理，避免在閘道層重複切換。

需要指出的是，回退與负載均衡在設定層面是互斥的。當使用者在 `provider` 偏好裡設定了 `sort` 或 `order`，預設的價格负載均衡會自動關閉，路由器改為按指定順序逐個探測供應商，此時 `allow_fallbacks` 控制的是這份順序清單之外的兜底是否啟用。

模型回退與分區排序的進階用法

模型回退指在同一次 `chat completions` 呼叫裡提供多個候選模型，路由器按一定順序逐個嘗試，主模型不可用時落到下一個。這個機制在 `models` 欄位層面起作用，與 `provider` 層面的供應商回退是正交的：前者切換模型身份，後者在同一模型下切換承載方。

`sort` 欄位除了接受字符串形式的 `"price"`、`"throughput"`、`"latency"` 之外，還可以寫成對象 `{ by, partition }`。其中 `partition` 決定端點如何分組後再排，取值預設是 `"model"`。預設行為是先按模型分組，再在每個模型內部按 `by` 指定的方式排序，這保證主模型的所有端點會被穷尽之後才會嘗試下一個模型，即便後者的效能指標更好。

把 `partition` 顯式設為 `"none"` 時，分組被移除，排序作用於所有模型的所有端點，形成一個全局候選池。這讓路由器可以無視模型邊界，直接挑出目前吞吐最高或延遲最低的那條端點。典型場景是同時列出多個可接受的模型，讓 OpenRouter 選當下表現最好的那一條，而不是死守使用者寫的第一個模型名。

`partition: "none"` 與效能阈值可以叠加使用。`preferred_min_throughput` 與 `preferred_max_latency` 只能把不達標的端點排到末尾，不能完全剔除，所以 `partition: "none"` 的全局排序在效能過濾之後仍然能挑出性價比最高的候選，淘汰的端點作為最後一層兜底。

另一個落地場景是 BYOK（Bring Your Own Key）。當使用者給某個供應商配了自有密钥，但首選模型恰好沒有覆蓋這個供應商的 BYOK 端點時，啟用 `partition: "none"` 可以讓路由器跨模型挑選出真正能用使用者自有密钥的端點，避免因為模型順序寫死而錯失本應命中的 BYOK 通道。

多供應商路由與回退設定的落地取舍

把 `order`、`sort`、`allow_fallbacks`、`max_price`、`preferred_min_throughput`、`preferred_max_latency` 單獨看都容易理解，但放進同一次請求就會互相牵制。文件對相互覆蓋的規則其實寫得很硬，先把這些規則理順清楚，再談取舍才不至於猜。

第一條規則是 `sort` 與預設负載均衡互斥。預設情況下請求按價格做加權负載均衡，候選池來自過去 30 秒內沒有顯著故障的供應商。一旦在 `provider` 對象裡顯式寫入 `sort` 或 `order`，负載均衡就立刻關閉，路由退化為按指定鍵值依次嘗試。`:nitro` 與 `:floor` 這两條模型名後缀同樣會強制 `sort`，並附帶額外的服務層級資格，等價於在 `sort` 之外再叠加一層篩選。

第二條規則是 `order` 與 `allow_fallbacks` 共同決定候選池邊界。`order` 只是一種偏好順序，真正的邊界由 `allow_fallbacks` 劃定。預設 `allow_fallbacks: true` 時，`order` 之外的供應商仍可作為回退；置為 `false` 後，回退被關閉，候選池就被收紧到 `order` 列出的供應商之內，必要時還需要配合 `only` 做白名單兜底。`ignore` 與 `only` 的覆蓋關系则是後者優先，寫在 `only` 之外的供應商即便出現在 `order` 中也不會被選中。

第三條規則是效能阈值不直接淘汰，而是降級。不满足 `preferred_min_throughput` 或 `preferred_max_latency` 的端點不會被剔除候選集，只會被排到隊尾，仍保留作為回退的資格。百分位欄位支援同時給出 p50 到 p99 中的多項，全部命中才算進入「preferred」組。這意味着阈值實際扮演的是分層過濾的角色：達標的端點集中排序，未達標的端點作為兜底，避免單次抖動把整條鏈路掐斷。

基於以上規則，几類典型取舍可以這樣落地。

成本敏感的批次任務倾向於不顯式設定 `sort`，讓預設價格负載均衡接管；只在遇到持續故障時再用 `max_price` 收口，避免在價格與可用性之間反複横跳。對延遲敏感的使用者面介面则常用 `sort: "latency"`，必要時叠 `preferred_max_latency` 的 p99 阈值，把最差情況压住，同時保留 `allow_fallbacks: true` 以防雪崩。BYOK 場景下 `sort.partition: "none"` 才有意義，它允許在多個回退模型之間按統一鍵值排序，從而在主模型沒有自帶密钥時也能命中其他模型的 BYOK 端點；若不開啟這一開關，路由器會先把主模型的全部端點跑完才考虑其他模型，BYOK 利用率會被顯著拉低。