為 AI API 設計斷路器
為 AI API 設計斷路器：包含明確決策、可重用工件、失敗驗證、運行指標與來源邊界的生產實作指南。
為 AI API 設計斷路器：包含明確決策、可重用工件、失敗驗證、運行指標與來源邊界的生產實作指南。
直接結論
應把為 AI API 設計斷路器視為可靠性控制契約，而非一次性設定。移動流量前先固定協定、職責、證據與回復條件。核心控制點為 closed, open, half_open, failure_window。
核心結論由下方契約表與確定性範例共同固定。只要 ai-api-circuit-breaker 任一硬性控制缺少線路證據、持久回讀或明確 owner，就不可放量。
範圍與職責
區分使用者任務與控制面職責：用戶端設定負責本機檔案或環境變數；閘道負責認證、路由、限制、計量與嘗試記錄；供應商負責原生協定與會變動的能力契約。一次文字請求成功只證明單一路徑。
本文負責解釋決策、風險與驗證路徑；即時接入文件繼續負責會變動的安裝命令與介面步驟。這樣可形成能力樹，也避免同一搜尋意圖出現兩個 owner。
本頁的內容 owner 記錄為 ai-api-circuit-breaker，固定控制點為 closed, open, half_open, failure_window。每個值都在線路或持久狀態邊界核驗，不從行銷標籤推論。
可重用技術工件: 為 AI API 設計斷路器
下列審查記錄就是可交付工件。技術值保持明確，審查者能直接比對設定、線路證據與持久狀態。
| 控制點 | 固定決策 | 保留證據 |
|---|---|---|
breaker_key |
provider_route_plus_protocol_plus_failure_class |
route_id + endpoint + normalized_error_class |
closed_state |
rolling_window_with_minimum_sample |
eligible_attempts + failures + window_bounds |
open_state |
fail_fast_without_upstream_attempt |
decision_timestamp + reopen_at + returned_error |
half_open_state |
bounded_probe_concurrency |
probe_count + outcomes + state_transition |
fallback |
same_contract_eligible_route_only |
eligibility_reason + route_choice + terminal_state |
operator_override |
time_bounded_and_audited |
actor + reason + expiry + restored_policy |
確定性範例
範例只使用佔位符與確定性輸入。請替換成已審查識別，不可加入密鑰或客戶內容，並保存精確設定快照。
state = CLOSED
if eligible_failures(window) >= threshold and samples >= minimum:
state = OPEN
reopen_at = now + cool_down
if state == OPEN and now < reopen_at:
return fail_fast
if state == OPEN and now >= reopen_at:
state = HALF_OPEN
if bounded_probe_succeeds():
state = CLOSED
else:
state = OPEN
分層驗證
依序執行驗證；後續成功不能補足前段缺失的邊界，每次嘗試都必須連結同一邏輯請求。
- 固定目前用戶端、閘道策略、模型別名、路由集合與可觀測基線。 證據記錄：對
breaker_key強制provider_route_plus_protocol_plus_failure_class，並保留route_id + endpoint + normalized_error_class。 - 執行確定性正向探測，保留回應、請求 ID、路由、終態與用量。 證據記錄：對
closed_state強制rolling_window_with_minimum_sample，並保留eligible_attempts + failures + window_bounds。 - 執行配對的負向、上限或斷線案例，確認在預期層失敗。 證據記錄：對
open_state強制fail_fast_without_upstream_attempt，並保留decision_timestamp + reopen_at + returned_error。 - 透過真實協定入口重複探測，不可從相鄰端點推論原生支援。 證據記錄：對
half_open_state強制bounded_probe_concurrency，並保留probe_count + outcomes + state_transition。 - 只對有界群組放量，記錄 owner、期限、停止閾值與回復方案。 證據記錄：對
fallback強制same_contract_eligible_route_only，並保留eligibility_reason + route_choice + terminal_state。 - 測試後回讀持久設定與帳務，移除暫時權限和資料。 證據記錄：對
operator_override強制time_bounded_and_audited，並保留actor + reason + expiry + restored_policy。
必須避免的失敗模式
以下每項都是發佈阻斷條件。HTTP 200、儀表板或一次成功展示都不能覆蓋失敗。
global_breaker— 若發生global_breaker，立即停止放量並依 owner、證據與回復路徑處理，不可用一次成功結果覆蓋。mixed_denominator— 若發生mixed_denominator，立即停止放量並依 owner、證據與回復路徑處理，不可用一次成功結果覆蓋。half_open_stampede— 若發生half_open_stampede，立即停止放量並依 owner、證據與回復路徑處理，不可用一次成功結果覆蓋。fallback_cascade— 若發生fallback_cascade，立即停止放量並依 owner、證據與回復路徑處理，不可用一次成功結果覆蓋。
觀測訊號與停止條件
同時觀測成功與傷害。閾值是工作負載策略輸入；開始時窗前先固定 SLO 與分母。
| 訊號 | 決策閾值 | 動作 |
|---|---|---|
eligible_failure_ratio |
reviewed_window_and_minimum_sample |
open_route_breaker |
open_fail_fast_latency |
<_caller_remaining_deadline |
repair_local_decision_path |
half_open_probe_concurrency |
<=_configured_probe_limit |
reject_extra_probes |
fallback_headroom |
>=_required_reserved_capacity |
shed_load_instead_of_failover |
Modelflare 邊界與限制
Modelflare 可集中處理相容與原生協定路由、限權密鑰、群組、用量與失敗，但已設定渠道不代表所有欄位、別名、保留承諾、區域或回退均受支援。用原生協定驗證具體路由，保留明確零值，最終持久結算才是帳務真相。
本文是實作方法，不是供應商認證、法律結論、歷史可用性證明或通用效能基準。T-1 日重查契約、模型、價格、資料保留與區域可用性；核心事實變更時移動日期。
繼續閱讀同一主題群
父文章提供較寬決策，兄弟文章提供下一步，文件頁提供目前設定。正文連結必須保留，因為託管 CMS 尚無獨立 related-slug 欄位。
常見問題
為 AI API 設計斷路器：一次成功請求能批准上線嗎？
不能；負向案例、有界放量、持久回讀與停止條件是獨立閘門。
為 AI API 設計斷路器：能提前數月固定模型與價格嗎？
不能；使用佔位符或核驗快照，並在 T-1 日重查。
為 AI API 設計斷路器：應保留哪些證據？
保留去敏請求與嘗試 ID、設定版本、時間戳、終態、用量、最終扣費與審查結論。
來源與核驗日期
來源核驗日期：2026-08-07。來源只建立外部契約與工程原則，不證明未測試路由或未來狀態。