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

可靠的 AI API 路由不只是一個重試迴圈。它的意思是為每把 API 金鑰設定明確的主要群組、備援群組、模型能力與請求限制,並在請求變慢或失敗時,保留足夠且可提供給使用者查看的證據。
好的路由設計能讓結果說得清楚,並避免群組切換在不知不覺中改變所請求的模型或計費政策。
從明確的金鑰政策開始
Modelflare 支援兩種路由方式:
- 一般 API 金鑰使用一個明確的主要群組,以及一份有順序的備援群組清單。
- 智慧 API 金鑰(Smart API Key)會評估帳號目前可用的群組,並依其策略逐一嘗試符合條件的候選群組。
備援順序不是流量分配,而是優先順序。當主要群組無法使用時,請求會依序改由後面的群組處理。
請為不同的應用程式或環境建立各自的金鑰。相較於到處共用同一把金鑰,這樣更容易掌握群組存取權、額度、到期時間與用量記錄。
備援必須維持請求契約
將群組加入備援清單之前,請確認它:
- 提供所請求的模型;
- 支援相同的端點與串流行為;
- 允許任何必要的 Service Tier 或供應商專屬欄位;
- 具有可接受的用量倍率與請求速率限制;
- 確實已為該帳號解鎖。
備援群組不代表可以任意替換模型。所請求的模型與協定仍然定義了傳輸契約。
了解群組的請求限制
請求速率限制會依帳號以及實際處理請求的群組套用。分開使用多把 API 金鑰能讓用量更容易分析,但不會自動繞過帳號或群組的限制。
當目前的群組達到限制時,設有備援群組的 API 金鑰可以改用下一個可用群組。如果沒有可用的備援,請求會收到 429。用戶端重試時應採用有上限的退避,而不是立刻送出一波新請求。
使用請求層級的效能指標
使用日誌提供了解單一請求所需的產品層級指標:
| 指標 | 可協助說明的內容 |
|---|---|
| 總回應時間 | 從送出請求到完成所花的時間 |
| 首次回應 | 收到第一個有效文字、推理或工具事件前的時間 |
| 首段可見文字 | 對預期會產生文字的請求而言,文字出現前的時間 |
| 可見輸出速度 | 可見輸出開始後的生成速度 |
| 輸出 Token | 該請求產生的輸出量 |
首次回應較慢,通常表示請求在開始生成前等待了較久;首次回應正常、但輸出速度偏低,則較可能是生成階段的問題。將這些指標與狀態、模型、群組及時間範圍一起比對,就能分辨是偶發延遲還是持續性問題。
只包含工具呼叫的回應可能沒有可見文字,因此對 Responses 流量而言,「首次回應」是較可靠的首個有效輸出訊號。
使用可安全保留的證據
Modelflare 的時間中繼資料不包含提示詞、回應文字、原始請求本文、API 金鑰、電子郵件或明文 IP 位址。如此一來,營運記錄仍然有用,延遲診斷也不會變成第二個內容儲存庫。
發生事件時,請記錄:
- 請求 ID 與時間戳記;
- 所請求的模型與所選群組;
- 端點與串流模式;
- 下游狀態;
- 狀態、總回應時間與首次回應時間;
- 用戶端是否在請求完成前取消。
這些證據能讓客服團隊確認群組切換、模型生成緩慢與用戶端取消等情況,而不必在一般日誌中揭露內部服務拓撲。
正式環境可靠性檢查清單
- 為每個應用程式提供專屬的 API 金鑰。
- 審慎安排主要群組與備援順序。
- 確認每個候選群組都支援所需的模型與協定。
- 將用戶端逾時設定得足以涵蓋實際工作負載。
- 對可重試的失敗使用加上隨機抖動(jitter)且有上限的重試。
- 不要把驗證、額度或模型存取錯誤當成暫時性錯誤來重試。
- 同時測試非串流與串流請求。
- 監控 429、首次回應、輸出輸送量與取消情況。
- 將備援視為等效選項之前,先確認群組定價。
可靠性來自維持請求契約,並在請求失敗時保留足夠的證據。依序設定的備援群組能降低對單一群組的依賴,而效能與用量記錄則讓仍然發生的失敗有跡可循。
請參考 AI API 錯誤指南解讀驗證、存取、速率限制、取消與 5xx 失敗。擴大備援存取範圍之前,請先套用 AI API 金鑰安全中的控制措施。