受健康檢查驅動的路由

在使用者遇到錯誤之前，將流量路由遠離不健康的部署。背景健康檢查會以可設定的間隔執行，任何失敗的部署都會主動從路由池中移除，而不是等到使用者請求已經失敗之後才處理。

架構

這個問題解決了什麼？

預設情況下，LiteLLM 會將流量路由到所有部署，且只有在某個部署已經讓使用者請求失敗之後，才會停止把流量送往該部署。冷卻系統是反應式的。

健康檢查驅動的路由讓這件事變成主動式：背景迴圈會依可設定的間隔輪詢每個部署。如果某個部署的健康檢查失敗，它會在使用者請求打到之前，立即從路由池中移除。

當您也設定 allowed_fails_policy 時，您可以精確控制每種錯誤類型（驗證錯誤、速率限制、逾時）需要累積多少次健康檢查失敗，才會讓部署進入冷卻。這能避免短暫雜訊造成誤判。

設定

步驟 1：啟用背景健康檢查

背景健康檢查預設為關閉。請在 general_settings 中啟用：

general_settings:
  background_health_checks: true
  health_check_interval: 60    # seconds between each full check cycle

步驟 2：啟用健康檢查路由

general_settings:
  background_health_checks: true
  health_check_interval: 60
  enable_health_check_routing: true  # ← route away from unhealthy deployments

此時，任何健康檢查失敗的部署都會立即從路由中排除，直到下一個檢查週期將其清除。

步驟 3：新增政策以控制多少次失敗會觸發冷卻

如果沒有政策，第一次健康檢查失敗就會將部署標記為不健康。如果您希望更有容錯空間（例如，只有連續 2 次驗證失敗後才採取動作），請使用 allowed_fails_policy：

model_list:
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY

  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY_SECONDARY

general_settings:
  background_health_checks: true
  health_check_interval: 30
  enable_health_check_routing: true

router_settings:
  cooldown_time: 60              # how long a deployment stays in cooldown
  allowed_fails_policy:
    AuthenticationErrorAllowedFails: 1   # cooldown after 2nd auth failure
    TimeoutErrorAllowedFails: 3          # cooldown after 4th timeout

當 allowed_fails_policy 已設定時，二元健康檢查篩選器會被略過。只有冷卻系統會控制路由排除，且僅在超過您設定的閾值後才會生效。例外情況是當 background_health_check_model_groups 也已設定時（請參閱步驟 5）：此時已列出的群組即使已設定原則，仍會保留二元篩選器。

步驟 4（選用）：忽略暫時性錯誤

健康檢查回傳的 429（速率限制）和 408（逾時）通常表示部署暫時過載，而不是故障。若要完全避免這些情況影響路由：

general_settings:
  background_health_checks: true
  health_check_interval: 30
  enable_health_check_routing: true
  health_check_ignore_transient_errors: true  # 429 and 408 never affect routing

啟用此設定後，只有健康檢查中的硬性失敗（401、404、5xx）會納入冷卻計算。

步驟 5（選用）：將健康檢查範圍限定於特定模型群組

預設情況下，背景迴圈會探測每個模型群組。若只想讓您要管理的群組啟用，請將它們列在 background_health_check_model_groups 中：

general_settings:
  background_health_checks: true
  health_check_interval: 30
  enable_health_check_routing: true
  background_health_check_model_groups: ["prod-openai"]

設定允許清單後：

只有已列出群組中的部署會被探測，因此未列出的群組不會產生背景探測流量或成本
GET /health 會提供背景結果，因此只會回報已列出的群組
健康檢查路由只會在已列出群組內導流；未列出的群組會保留其設定的路由策略與一般請求時重試行為
後續新增的模型群組會被排除，直到您將它們加入清單
即使 allowed_fails_policy 已設定，已列出的群組仍會保留二元健康篩選器
非字串清單的值會在閘道啟動時失敗，而不是被靜默忽略

完整範例

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEY

  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEY_SECONDARY

  - model_name: gpt-5.6-terra
    litellm_params:
      model: azure/gpt-5.6-terra
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY

general_settings:
  background_health_checks: true
  health_check_interval: 30
  enable_health_check_routing: true
  health_check_ignore_transient_errors: true

router_settings:
  cooldown_time: 60
  allowed_fails_policy:
    AuthenticationErrorAllowedFails: 0   # cooldown immediately on auth failure
    TimeoutErrorAllowedFails: 2          # cooldown after 3 timeouts
    RateLimitErrorAllowedFails: 5        # cooldown after 6 rate limits (if not ignoring transients)

設定參考

設定	位置	預設值	說明
`enable_health_check_routing`	`general_settings`	`false`	將流量導離健康檢查失敗的部署
`background_health_checks`	`general_settings`	`false`	健康檢查路由運作時必須為 `true`
`health_check_interval`	`general_settings`	`300`	兩次完整健康檢查週期之間的秒數
`health_check_staleness_threshold`	`general_settings`	`600`	忽略快取健康狀態前的秒數。預設值固定為預設 300 秒間隔的 2 倍，且不會跟隨 `health_check_interval`，因此當您變更間隔時，請明確設定它（例如 `2 x health_check_interval`）
`health_check_ignore_transient_errors`	`general_settings`	`false`	忽略健康檢查中的 429 與 408；這些永遠不會影響路由
`background_health_check_model_groups`	`general_settings`	`null`	僅探測並對已列出的模型群組進行健康路由；未列出的群組維持正常路由
`cooldown_time`	`router_settings`	`5`	超過閾值後，部署會進入冷卻狀態的秒數
`allowed_fails_policy`	`router_settings`	`null`	進入冷卻前，各錯誤類型的失敗閾值（見下方）

`allowed_fails_policy` 欄位

欄位	錯誤類型	HTTP 狀態碼
`AuthenticationErrorAllowedFails`	API 金鑰錯誤	401
`TimeoutErrorAllowedFails`	請求逾時	408
`RateLimitErrorAllowedFails`	超出速率限制	429
`BadRequestErrorAllowedFails`	請求格式錯誤	400
`ContentPolicyViolationErrorAllowedFails`	內容被過濾	400

其值是指在進入冷卻前可容忍的失敗次數。0 表示第一次失敗就進入冷卻。2 表示第三次才進入冷卻。

需要注意的事項

計數器 TTL 必須長於健康檢查間隔。 allowed_fails_policy 會透過對每個部署遞增一個 failed_calls 計數器來運作。該計數器會在 cooldown_time 秒後過期。如果 cooldown_time 比 health_check_interval 短，則計數器會在每個檢查週期之間重設，失敗次數永遠無法累積。使用 cooldown_time 時，請將 health_check_interval 設為大於 allowed_fails_policy。
```
router_settings:
  cooldown_time: 60       # must be > health_check_interval (30s here)

general_settings:
  health_check_interval: 30
```
AllowedFails: N 表示在第 (N+1) 次失敗時進入冷卻。 計數器檢查是 updated_fails > allowed_fails，因此 0 會在第 1 次失敗時觸發，1 會在第 2 次，2 會在第 3 次。

AllowedFails 冷卻觸發於
0 第 1 次失敗
1 第 2 次失敗
2 第 3 次失敗
如果沒有 allowed_fails_policy，第一次失敗就足夠。 第一次健康檢查失敗會立即將該部署排除在路由之外。當您希望容忍不穩定的檢查時，請使用 allowed_fails_policy。
如果所有部署都不健康，過濾器會被繞過。 流量會持續通過，而不是完全沒有任何部署可用。請求仍會失敗，但路由器會持續嘗試。
健康檢查失敗與請求失敗共用相同的計數器。 當設定 allowed_fails_policy 時，這兩種來源都會遞增同一個 failed_calls 計數器。某個部署若已有 1 次健康檢查失敗，接著又收到 1 次失敗請求，便會達到 AllowedFails: 1 的門檻並進入冷卻。

`AllowedFails`	冷卻觸發於
`0`	第 1 次失敗
`1`	第 2 次失敗
`2`	第 3 次失敗

疑難排解

以 --detailed_debug 啟動 proxy，並尋找以下記錄行：

每次健康檢查週期後（以 DEBUG 等級寫入）：

health_check_routing_state_updated healthy=2 unhealthy=1

當健康檢查失敗遞增計數器並觸發冷卻時（DEBUG 等級）：

checks 'should_run_cooldown_logic'
Attempting to add <deployment_id> to cooldown list

當安全機制因為所有部署都在冷卻中而觸發時：

All deployments in cooldown via health-check routing, bypassing cooldown filter

當安全機制因為所有部署都不健康而觸發時（二元過濾器，沒有 allowed_fails_policy）：

All deployments marked unhealthy by health checks, bypassing health filter

架構​

這個問題解決了什麼？​

設定​

步驟 1：啟用背景健康檢查​

步驟 2：啟用健康檢查路由​

步驟 3：新增政策以控制多少次失敗會觸發冷卻​

步驟 4（選用）：忽略暫時性錯誤​

步驟 5（選用）：將健康檢查範圍限定於特定模型群組​

完整範例​

設定參考​

allowed_fails_policy 欄位​

需要注意的事項​

疑難排解​

架構