可靠的 AI API 路由:備援與請求診斷

以明確的備援順序、群組 RPM 限制與單筆請求的時間證據,設計可靠的 AI API 路由並診斷失敗原因。

可靠的 AI API 路由:備援與請求診斷

可靠的 AI API 路由不只是一個重試迴圈。它的意思是為每把 API 金鑰設定明確的主要群組、備援群組、模型能力與請求限制,並在請求變慢或失敗時,保留足夠且可提供給使用者查看的證據。

好的路由設計能讓結果說得清楚,並避免群組切換在不知不覺中改變所請求的模型或計費政策。

從明確的金鑰政策開始

Modelflare 支援兩種路由方式:

  • 一般 API 金鑰使用一個明確的主要群組,以及一份有順序的備援群組清單。
  • 智慧 API 金鑰(Smart API Key)會評估帳號目前可用的群組,並依其策略逐一嘗試符合條件的候選群組。

備援順序不是流量分配,而是優先順序。當主要群組無法使用時,請求會依序改由後面的群組處理。

請為不同的應用程式或環境建立各自的金鑰。相較於到處共用同一把金鑰,這樣更容易掌握群組存取權、額度、到期時間與用量記錄。

備援必須維持請求契約

將群組加入備援清單之前,請確認它:

  1. 提供所請求的模型;
  2. 支援相同的端點與串流行為;
  3. 允許任何必要的 Service Tier 或供應商專屬欄位;
  4. 具有可接受的用量倍率與請求速率限制;
  5. 確實已為該帳號解鎖。

備援群組不代表可以任意替換模型。所請求的模型與協定仍然定義了傳輸契約。

了解群組的請求限制

請求速率限制會依帳號以及實際處理請求的群組套用。分開使用多把 API 金鑰能讓用量更容易分析,但不會自動繞過帳號或群組的限制。

當目前的群組達到限制時,設有備援群組的 API 金鑰可以改用下一個可用群組。如果沒有可用的備援,請求會收到 429。用戶端重試時應採用有上限的退避,而不是立刻送出一波新請求。

使用請求層級的效能指標

使用日誌提供了解單一請求所需的產品層級指標:

指標 可協助說明的內容
總回應時間 從送出請求到完成所花的時間
首次回應 收到第一個有效文字、推理或工具事件前的時間
首段可見文字 對預期會產生文字的請求而言,文字出現前的時間
可見輸出速度 可見輸出開始後的生成速度
輸出 Token 該請求產生的輸出量

首次回應較慢,通常表示請求在開始生成前等待了較久;首次回應正常、但輸出速度偏低,則較可能是生成階段的問題。將這些指標與狀態、模型、群組及時間範圍一起比對,就能分辨是偶發延遲還是持續性問題。

只包含工具呼叫的回應可能沒有可見文字,因此對 Responses 流量而言,「首次回應」是較可靠的首個有效輸出訊號。

使用可安全保留的證據

Modelflare 的時間中繼資料不包含提示詞、回應文字、原始請求本文、API 金鑰、電子郵件或明文 IP 位址。如此一來,營運記錄仍然有用,延遲診斷也不會變成第二個內容儲存庫。

發生事件時,請記錄:

  • 請求 ID 與時間戳記;
  • 所請求的模型與所選群組;
  • 端點與串流模式;
  • 下游狀態;
  • 狀態、總回應時間與首次回應時間;
  • 用戶端是否在請求完成前取消。

這些證據能讓客服團隊確認群組切換、模型生成緩慢與用戶端取消等情況,而不必在一般日誌中揭露內部服務拓撲。

正式環境可靠性檢查清單

  • 為每個應用程式提供專屬的 API 金鑰。
  • 審慎安排主要群組與備援順序。
  • 確認每個候選群組都支援所需的模型與協定。
  • 將用戶端逾時設定得足以涵蓋實際工作負載。
  • 對可重試的失敗使用加上隨機抖動(jitter)且有上限的重試。
  • 不要把驗證、額度或模型存取錯誤當成暫時性錯誤來重試。
  • 同時測試非串流與串流請求。
  • 監控 429、首次回應、輸出輸送量與取消情況。
  • 將備援視為等效選項之前,先確認群組定價。

可靠性來自維持請求契約,並在請求失敗時保留足夠的證據。依序設定的備援群組能降低對單一群組的依賴,而效能與用量記錄則讓仍然發生的失敗有跡可循。

請參考 AI API 錯誤指南解讀驗證、存取、速率限制、取消與 5xx 失敗。擴大備援存取範圍之前,請先套用 AI API 金鑰安全中的控制措施。