多供應商路由與回退設定

provider 對象欄位详解

在多供應商路由設定中，provider 對象是控制請求分發的核心結構。它通過一系列欄位精確指定哪些供應商參與處理、以何種順序嘗試、是否允許回退以及如何篩選符合條件的端點。這些欄位共同構成一個靈活的路由策略層，允許開發者根據成本、效能、資料合規性或可用性等維度客製請求路径。

order 欄位接受一個字符串數組，其中每個元素是供應商的標識符（slug），例如 "anthropic" 或 "openai"。路由器將严格按照數組中列出的順序嘗試這些供應商。如果第一個供應商不可用或響應逾時，系統會立即轉向清單中的下一個供應商，直到成功響應或清單耗尽。該欄位的優先級高於預設负載均衡策略，一旦設定，负載均衡機制將被禁用，轉而採用严格的順序嘗試模式。

allow_fallbacks 欄位是一個布爾值，預設為 true。當設定為 true 時，如果主供應商（由 order 或預設策略選出）無法提供服務，系統會自動啟用備用供應商。備用供應商的選擇基於系統內部維護的可用性狀態，通常包含最近無故障紀錄的供應商。若設定為 false，则僅嘗試主供應商，若失敗则直接回傳錯誤，不進行任何回退操作。

require_parameters 欄位預設為 false。當設定為 true 時，路由器會過濾掉所有不支援請求中全部參數的供應商。這意味着如果請求中包含某些供應商模型不支援的參數（如特定的温度值、上下文長度或自定義欄位），該供應商將被排除在候選清單之外。該欄位有助於避免因參數不兼容導致的請求失敗，但可能缩小可選供應商範圍。

data_collection 欄位控制是否使用可能存储資料的供應商。其值可為 "allow" 或 "deny"。"allow" 表示允許使用任何供應商，包含那些可能紀錄請求資料的供應商；"deny" 则排除已知會存储資料的供應商，適用於對資料隱私有严格要求的場景。該欄位與 zdr 欄位配合使用時，可進一步细化資料處理策略。

zdr 欄位是一個布爾值，用於強制僅路由到支援零資料保留（Zero Data Retention）的端點。啟用後，所有不满足 ZDR 標準的供應商將被排除。ZDR 端點保證不會持久化請求或響應資料，適用於處理敏感資訊的場景。該欄位與 data_collection 欄位協同工作，形成多層資料保護機制。

enforce_distillable_text 欄位預設為 false。啟用後，僅允許使用支援文字蒸馏（text distillation）的模型。文字蒸馏是指從模型輸出中提取結構化資訊或摘要的能力，某些供應商的模型可能不支援此功能。該欄位適用於需要後續處理模型輸出的流程，確保輸出格式符合預期。

only 欄位是一個字符串數組，用於顯式指定本次請求允許使用的供應商清單。任何未列入該清單的供應商將被完全忽略，即使其效能或價格更佳。該欄位與 ignore 欄位互補，only 用於白名單控制，ignore 用於黑名單排除。

ignore 欄位是一個字符串數組，用於排除特定供應商。被列入該清單的供應商將不會被考虑，即使其在預設策略中表現優異。該欄位適用於已知某些供應商不穩定或不符合特定需求的情況。

quantizations 欄位接受一個字符串數組，如 ["int4", "int8"]，用於篩選符合特定量化精度的供應商端點。量化級別影響模型的計算精度與推理速度，int4 表示 4 位整數精度，int8 表示 8 位整數精度。該欄位允許使用者在精度與效能之間做出權衡，適用於對延遲或資源消耗有严格要求的場景。

sort 欄位可以是字符串或對象，用於指定供應商的排序依據。字符串形式可為 "price"、"throughput" 或 "latency"，分別表示按價格、吞吐量或延遲排序。對象形式包含 by 和 partition 两個子欄位，by 指定排序策略，partition 控制排序範圍。一旦設定 sort，负載均衡將被禁用，路由器將严格按照排序結果嘗試供應商。

preferred_min_throughput 和 preferred_max_latency 欄位用於設定效能阈值。前者指定最小吞吐量（tokens/sec），後者指定最大延遲（秒）。這些欄位可以是數值或對象，數值形式適用於 p50 百分位，對象形式可指定 p50、p75、p90、p99 等多個百分位。未達標的供應商將被降級處理，排在候選清單末尾，但仍可能作為回退選項。

max_price 欄位是一個對象，用於設定本次請求的最高可接受價格。路由器將排除任何超出該價格的供應商端點。該欄位與 sort: "price" 結合使用時，可實現成本最優的路由策略，確保在满足效能要求的前提下選擇最經济的供應商。

預設负載均衡機制

OpenRouter 的預設负載均衡策略以價格為核心最佳化目標，同時兼顾供應商的近期可用性。該策略在不顯式指定 order 或 sort 欄位時自動啟用，旨在最大化請求成功率的同時降低平均成本。

策略的第一步是過濾掉最近 30 秒內發生過顯著故障的供應商。這裡的“顯著故障”通常指連續多個請求失敗、響應逾時或回傳 5xx 狀態碼。系統通過滑動窗口機制監控每個供應商的健康狀態，確保僅考虑目前穩定的端點。

在穩定供應商中，系統評估每個供應商的最低價格候選，並根據價格的反平方根進行加權選擇。具體而言，價格越低的供應商權重越高，但權重递减速度隨價格上升而放緩，避免過度集中於單一低價供應商。這種加權機制在成本與分布均衡之間取得平衡，防止因低價供應商過載而導致新的故障。

剩余的供應商被列為回退選項，按價格升序排列。當主選供應商失敗時，系統按順序嘗試這些回退供應商，直到成功響應或清單耗尽。回退機制不依赖顯式設定，是預設策略的一部分，確保在主供應商不可用時仍有備用路径。

若在 provider 對象中設定了 order 或 sort 欄位，负載均衡將被完全禁用。此時路由器不再進行加權選擇或動態調整，而是严格按照指定順序或排序結果嘗試供應商。這種顯式控制適用於需要確定性路由路径的場景，例如強制使用特定供應商或按效能優先級排序。

负載均衡策略的設計兼顾了自動化與靈活性。預設行為適合大多數通用場景，而顯式欄位则允許開發者根據具體需求進行精细控制。通過組合不同欄位，可實現從簡單故障回退到複雜多維路由策略的多種設定。

排序策略與快捷方式

在多供應商路由設定中，排序策略決定了請求在多個候選供應商之間的嘗試順序。預設情況下，系統採用基於價格的负載均衡機制，優先選擇成本較低且近期無顯著故障的供應商。若需明確指定優先級，可啟用排序欄位，此時负載均衡將被禁用，系統將严格按照排序結果依次嘗試供應商。排序策略支援三種模式：按價格優先、按吞吐量優先、或按延遲優先。選擇價格優先時，系統始終嘗試最低單價的供應商；選擇吞吐量優先時，则優先符合目前吞吐表現最優的節點；選擇延遲優先時，则優先路由至響應延遲最低的供應商。

為提升設定效率，系統提供两種快捷方式。其一為模型標識後缀 `:nitro`，該後缀自動啟用吞吐量排序，並額外激活優先服務層級端點，使請求可存取高效能通道。該後缀屬於路由變體，不改變模型元資料，僅影響路由行為。其二為模型標識後缀 `:floor`，該後缀啟用價格排序，並激活弹性服務層級端點，使請求可存取成本最佳化通道。同樣屬於路由變體，不新增模型條目，僅調整路由策略。两種快捷方式均覆蓋預設负載均衡行為，適用於對效能或成本有明確偏好的場景。

分區排序與多模型回退

當設定多模型回退策略時，排序欄位可擴充為對象形式，以支援更精细的控制。預設情況下，系統在排序前將端點按模型分組，確保主模型的所有端點優先於備用模型的端點被嘗試，無論其效能表現如何。此行為由 `partition` 欄位控制，其預設值為 `"model"`。若需打破模型分組限制，實現跨模型全局排序，可將 `partition` 設定為 `"none"`。此時系統將所有模型的端點視為統一候選池，按指定排序策略（價格、吞吐量或延遲）全局擇優。

該機制適用於多種典型場景。在效能優先場景中，若使用者關注目前最優效能而非特定模型，可啟用全局吞吐量或延遲排序，系統將自動選擇所有模型中表現最佳的端點，而非固守主模型。在成本最佳化場景中，結合全局排序與效能阈值，系統可在满足最低吞吐或最高延遲要求的前提下，跨模型尋找成本最低的選項，未達標端點仍可作為回退候選。在密钥重複使用場景中，若使用者設定了特定供應商的自帶密钥（BYOK），全局排序可確保系統在主模型無可用密钥時，自動路由至支援該密钥的備用模型，提升密钥利用率。所有排序與分區設定均作用於回退鏈路，不影響單模型場景下的路由行為。

效能阈值與百分位控制

在多供應商路由場景中，效能阈值是篩選候選節點的關鍵手段。系統通過 `preferred_min_throughput` 和 `preferred_max_latency` 两個欄位，對候選供應商的即時表現進行量化過濾。這两個欄位均支援數值與對象两種形式，數值形式直接作用於中位數（p50）指標，而對象形式则允許 finer-grained 的百分位控制，可分別指定 p50、p75、p90、p99 四個檔位的阈值。所有指定的百分位條件必須同時满足，供應商才能進入優先級佇列；未達標者不會被剔除，而是被降級至回退清單末尾，僅在主路径全部失敗時才被呼叫。

百分位資料基於過去五分鐘內的滚動窗口統計，反映的是供應商在近期窗口內的穩定表現。p50 代表中位延遲或吞吐，體現典型工況；p90 與 p99 则更關注尾部延遲，適合對響應一致性要求高的即時互動場景。例如，若某供應商的 p90 延遲為 2 秒，意味着其 90% 的請求能在 2 秒內完成，剩余 10% 可能更慢。通過組合多個百分位，使用者可同時約束典型效能與极端情況，實現 SLA 級別的保障。在批處理任務中，優先使用 p50 吞吐阈值可有效過濾掉偶發波動的節點，保留穩定輸出的供應商；而在面向使用者的前端服務中，p90 或 p99 延遲阈值更能防止卡顿體驗。

結合 `sort` 欄位使用時，效能阈值可作為成本最佳化的前置過濾器。例如設定 `sort: "price"` 並附加 `preferred_min_throughput: { p90: 50 }`，系統將僅在满足每秒 50 tokens 且 90% 請求達標的基礎上，選擇價格最低的供應商。這種組合避免了為追求低價而引入效能波動節點的風險，確保成本節約不以穩定性為代價。效能阈值不改變路由順序，僅影響供應商的優先級分組，因此仍可與 `order`、`allow_fallbacks` 等欄位協同工作。

BYOK 與密钥優先級設定

BYOK（Bring Your Own Key）機制允許使用者注入自有 API 密钥，繞過平台預設的密钥池，實現資料隔离與合規控制。在多供應商回退場景中，BYOK 的可用性並非全局一致，而是绑定於具體供應商與模型的組合。例如，使用者可能為 OpenAI 設定了自有密钥，但未在 Anthropic 端完成相同設定。此時，若請求預設優先路由至 Anthropic，即使 OpenAI 節點具備 BYOK 能力，也無法被優先呼叫，導致密钥資源閒置。

為解決此類錯配，系統引入 `partition: "none"` 排序策略，打破預設的模型分組限制。在預設模式下，路由按模型分組排序，主模型的所有供應商優先於回退模型的供應商，即使後者具備更佳的密钥符合或效能表現。啟用 `partition: "none"` 後，所有模型的供應商被置於同一排序池中，系統依據 `sort`、`order`、效能阈值等條件全局擇優，不再受模型邊界約束。這意味着，當主模型無 BYOK 節點可用時，系統可直接跳轉至具備 BYOK 能力的回退模型供應商，無需等待主模型全部失敗後再触發回退。

密钥優先級在路由決策中隱式體現：BYOK 密钥的注入使對應供應商在合規性與資料控制維度上獲得隱性優勢，尤其在 `data_collection` 設為 `"deny"` 或 `zdr` 啟用的場景下，BYOK 節點成為唯一可選路径。此時，結合 `partition: "none"` 可確保系統在多模型間自動識別並優先調度具備密钥符合的節點，避免因模型分組導致的密钥浪費或合規風險。該設定尤其適用於多模型回退策略中，使用者希望最大化利用自有密钥、同時保持路由靈活性的場景。