一、先理解穩(wěn)定性：不是不報錯，而是出錯可預期

把 Codex 接到 API中轉站 后，最容易出現(xiàn)的誤區(qū)是：把“能跑通”當成“穩(wěn)定”。短期看演示都正常，長期看會遇到各種預料之外的情況：網(wǎng)絡抖動導致請求超時、高峰期觸發(fā)頻率限制、模型側臨時不可用、自動化腳本在錯誤場景下瘋狂重試。如果沒有事先定義行為，這些情況的表現(xiàn)就是隨機的，排查起來毫無頭緒。

更合理的做法，是把穩(wěn)定性當成一組明確的行為契約。超時契約定義“等多久算失敗”；重試契約定義“失敗后怎么辦”；限流契約定義“被限流時怎么排隊”；降級契約定義“關鍵任務如何保住”。每一條契約都要能落到配置里，而不是停留在口頭約定。這樣故障發(fā)生時，系統(tǒng)的反應是可預測的，人介入時也有明確的抓手。

• 超時契約：連接超時、讀取超時、總超時分別設多少，寫清楚。
• 重試契約：哪些錯誤碼可重試、重試幾次、間隔多久，寫清楚。
• 限流契約：觸發(fā) 429 后是排隊、退避還是降級，寫清楚。
• 降級契約：關鍵任務失敗時切備用線路還是暫停，寫清楚。

二、從統(tǒng)一入口開始：先確認靈能API可用模型和接入信息

穩(wěn)定性策略的前提，是先有一個穩(wěn)定統(tǒng)一的接入入口。進入 靈能API 后，先確認三件事：*ase **L 是否清楚、API Key 是否獨立、當前賬號可用模型和限流口徑是否已經(jīng)列明。官網(wǎng)入口可以直接記錄為 https://www.lnsns.com/，團隊文檔里建議把它放在“接入信息”部分，而不是散落在聊天記錄里。

這里要注意，接入信息和穩(wěn)定性策略不是一回事。接入信息回答“請求從哪里走、用什么憑證”；穩(wěn)定性策略回答“請求失敗時系統(tǒng)怎么辦”。很多團隊前期只保存了 Key，卻沒有保存超時和重試配置，后面一出問題，連“當時的請求等了多久才放棄的”都查不到。

接入信息建議記錄：
- *ase **L：以當前控制臺說明為準
- API Key：按人員、項目或自動化任務分別創(chuàng)建
- 限流口徑：記錄賬號級、Key 級的頻率限制說明
- 負責人：寫清楚誰負責更新配置，誰負責處理故障

• 不要只把 Key 寫進工具里，至少要有一份團隊可讀的接入說明。
• 頻率限制口徑要記錄下來，它是設計重試和排隊策略的依據(jù)。
• 如果項目多人協(xié)作，建議把個人調(diào)試 Key 和團隊任務 Key 分開。

? 三、錯誤分類：401、403、404、429、5xx、超時要分開處理

所有失敗都走同一條處理路徑，是穩(wěn)定性問題最常見的根源。401 是憑證錯了，重試一百次也沒用；429 是觸發(fā)限流，馬上重試只會更糟；500 是服務端臨時問題，等一會兒重試可能就成功。不分類型統(tǒng)一處理，要么把能恢復的錯誤誤判成致命錯誤，要么把致命錯誤拖成無限重試。

建議先建立一張錯誤分類表，每一類寫清楚“是否可重試、重試間隔、是否告警、是否切換備用線路”。這張表是后面所有穩(wěn)定性配置的基礎，任何腳本和工具都應該按這張表實現(xiàn)，而不是各自即興處理。

錯誤分類表示例：
 
錯誤類型 | 含義       | 可重試 | 處理方式
401      | 憑證無效   | 否     | 立即停止，檢查 Key
403      | 權限不足   | 否     | 立即停止，檢查權限
404      | 模型不存在 | 否     | 停止，檢查模型 ID
429      | 觸發(fā)限流   | 是     | 指數(shù)退避，最長等待上限
5xx      | 服務端錯誤 | 是     | 固定間隔重試，超過次數(shù)告警
timeout  | 請求超時   | 是     | 按連接/讀取/總時長分層處理

• 不可重試的錯誤要立即失敗并告警，不要默默吞掉。
• 429 的處理核心是“慢下來”，不是“多試幾次”。
• 分類表要覆蓋團隊實際遇到的錯誤，不要只抄標準定義。

?? 四、超時設置：連接、讀取、總時長三層分開設

超時是穩(wěn)定性里最基礎也最容易設錯的參數(shù)。只設一個總超時，長任務可能被誤殺；完全不設超時，掛起的請求會無限占用連接。合理的做法是分三層：連接超時控制“能不能連上”，讀取超時控制“兩次數(shù)據(jù)之間最長等多久”，總超時控制“整個請求最長花多久”。

三層超時的取值要有依據(jù)。連接超時通常很短，幾秒就夠了；讀取超時要看模型的典型響應時間，留有余量但不無限寬容；總超時要結合任務類型，比如輕任務 30 秒、代碼任務 120 秒、長上下文任務 300 秒。所有取值寫進配置，不要散落在代碼里。

超時配置示例：
 
connect_timeout: 5s     # 建立連接最長等待
read_timeout: 60s       # 兩次數(shù)據(jù)包之間最長等待
total_timeout:          # 按任務類型設定
  light_task: 30s
  code_task: 120s
  long_context_task: 300s

• 讀取超時觸發(fā)頻繁時，先檢查任務是否本身就需要長響應。
• 總超時要比各層超時之和留有余量，避免邏輯沖突。
• 超時取值變更要記錄原因，方便回溯“為什么當時是 60 秒”。

五、重試策略：退避不是目的，防止雪崩才是

重試本身沒有錯，錯的是沒有節(jié)奏的重試。所有請求在同一秒失敗，又在同一秒重試，服務端壓力瞬間翻倍，這就是重試風暴。正確的重試策略是指數(shù)退避加隨機抖動：第一次等 1 秒，第二次等 2 秒，第三次等 4 秒，每次再加一點隨機偏移，讓重試請求在時間上散開。

重試必須有上限和兜底。上限一般是 3 到 5 次，超過后要么切換備用模型，要么把任務掛起等人處理。對于自動化批量任務，還要限制整體并發(fā)，避免單個腳本的失敗重試擠占其他任務的配額。

retry_policy:
  **x_attempts: 4
  *ackoff: exponential   # 1s, 2s, 4s, 8s
  jitter: random(0~30%)  # 每次疊加隨機抖動
  retry_on: [429, 500, 502, 503, timeout]
  no_retry_on: [401, 403, 404]
  on_exhausted: fall*ack_or_alert

• 429 觸發(fā)時的實際等待時間要以響應頭提示為準，沒有提示再按退避計算。
• 重試次數(shù)不是越多越好，超過上限說明問題不是抖動而是故障。
• 每次重試都要記錄日志，否則排查時無法還原時間線。

六、限流應對：429 之后的排隊與降級

頻率限制不是異常，而是 API中轉站 的正常保護機制。觸發(fā) 429 說明當前請求速率超過了配額，正確的響應是降低速率，而不是提高嘗試頻率。團隊層面要把 429 當成一個信號：要么是任務調(diào)度太激進，要么是配額需要調(diào)整，要么是某些腳本在無謂地刷請求。

應對 429 可以分三步：第一步，讀取響應中的限流提示，決定等待多久；第二步，把等待中的請求放入隊列，按優(yōu)先級依次發(fā)出，關鍵任務排在前面；第三步，如果隊列持續(xù)積壓，觸發(fā)降級，比如切到備用模型、改用輕量模型先出結果、或推遲非關鍵任務。

限流應對流程：
 
1. 識別：收到 429，記錄限流口徑和觸發(fā)時間點
2. 退避：按響應提示或指數(shù)退避等待
3. 排隊：請求進入隊列，關鍵任務優(yōu)先
4. 降級：隊列積壓超過閾值時切換備用線路
5. 復盤：統(tǒng)計觸發(fā)頻率，判斷是否需要調(diào)整配額或調(diào)度

• 不要把 429 當失敗直接丟棄，排隊往往比失敗重試更省資源。
• 隊列要有長度上限，避免無限積壓拖垮整個流程。
• 頻繁觸發(fā)限流時，先查是不是自動化腳本并發(fā)過高。

? 七、熔斷與降級：故障擴大之前先斷開

當錯誤率持續(xù)升高時，繼續(xù)放量只會把問題放大。熔斷機制的作用是：在一段時間內(nèi)錯誤超過閾值時，自動停止向故障線路發(fā)請求，給服務端恢復的時間，同時把流量切到備用線路或返回預設的降級結果。熔斷器通常有三個狀態(tài)：閉合（正常放行）、打開（拒絕請求）、半開（試探恢復）。

降級要和熔斷配套定義。比如代碼**線路熔斷后，輕量**任務可以切到默認模型先跑一版；文檔整理任務熔斷后，可以先返回“稍后重試”并把任務掛起；涉及發(fā)布決策的任務，熔斷后必須人工介入，不允許自動降級。降級的底線是：寧可不出結果，不能出錯誤結果。

circuit_*reaker:
  error_threshold: 50%      # 錯誤率閾值
  window: 60s               # 統(tǒng)計窗口
  open_duration: 30s        # 打開狀態(tài)持續(xù)時間
  half_open_pro*e: 2        # 半開狀態(tài)試探請求數(shù)
  on_open:
    - route_to: *ackup_model
    - notify: oncall_owner
  on_half_open_success: close
  on_half_open_failure: reopen

• 熔斷閾值要基于歷史錯誤率設定，不要照搬別人的數(shù)字。
• 半開試探失敗要重新計時，避免剛恢復又被打垮。
• 降級結果要明確標識，不能把降級輸出當成正常輸出。

八、故障演練：每類穩(wěn)定性規(guī)則都要經(jīng)過真實演練

穩(wěn)定性規(guī)則不能只看配置是否正確，要在受控環(huán)境里真的制造故障，看系統(tǒng)反應是否符合預期。演練的內(nèi)容包括：模擬 429 看退避是否生效、模擬 500 看重試是否按間隔執(zhí)行、模擬超時看分層設置是否生效、模擬連續(xù)失敗看熔斷是否按時打開。沒有經(jīng)過演練的規(guī)則，關鍵時刻大概率不工作。

演練要有記錄，每次演練寫清楚場景、預期行為、實際行為、差異原因。如果實際行為和預期不一致，先修規(guī)則再上線。對于自動化任務，建議每月跑一次常規(guī)演練，配置變更后額外加跑一次，確保新配置沒有破壞已有的穩(wěn)定性保障。

故障演練清單：
 
場景       | 注入方式         | 預期行為
429 限流   | 模擬限流響應     | 退避排隊，不立即重試
500 錯誤   | 模擬服務端錯誤   | 按間隔重試，超限熔斷
讀取超時   | 延遲響應數(shù)據(jù)     | 觸發(fā) read_timeout，不重試總超時
連續(xù)失敗   | 持續(xù)返回錯誤     | 熔斷打開，切備用線路
恢復探測   | 錯誤后恢復正常   | 半開試探成功后閉合

• 演練環(huán)境要和生產(chǎn)配置一致，否則演練結果沒有參考價值。
• 演練要覆蓋邊界情況，比如重試中再次觸發(fā) 429。
• 演練記錄要歸檔，作為后續(xù)調(diào)整閾值的依據(jù)。

九、團隊規(guī)范：告警、值班和故障響應寫在一起

穩(wěn)定性規(guī)則最終要落到人。建議給每類告警指定負責人和響應時限：401、403 這類憑證問題通知配置負責人，429 限流通知任務調(diào)度負責人，連續(xù) 5xx 和熔斷通知值班同學。告警發(fā)出后沒人響應，比沒有告警更糟，因為團隊會誤以為一切正常。

靈能API 的角色是提供統(tǒng)一入口和模型調(diào)用基礎，團隊自己的工作是把入口整理成可執(zhí)行規(guī)范。誰接收告警？多久算響應超時？熔斷期間關鍵任務誰決定降級？故障復盤誰主持？這些問題提前寫清楚，比故障發(fā)生時臨時拉群要穩(wěn)得多。

告警響應登記表：
 
告警類型       | 負責人       | 響應時限 | 升級路徑
401/403       | 配置負責人   | 15 分鐘  | 30 分鐘未響應升級技術負責人
429 持續(xù)觸發(fā)   | 調(diào)度負責人   | 30 分鐘  | 涉及關鍵任務時立即升級
5xx 連續(xù)錯誤   | 值班同學     | 10 分鐘  | 觸發(fā)熔斷時通知全體
熔斷打開       | 值班同學     | 立即     | 同時通知備用線路負責人

• 告警要分級，不要所有故障都打擾所有人。
• 響應時限要現(xiàn)實，定一個沒人能做到的時限等于沒定。
• 故障復盤只討論規(guī)則和流程，不追責個人，復盤結論要落回配置。

十、復盤優(yōu)化：每月看一次錯誤率、重試率和熔斷次數(shù)

穩(wěn)定性策略不是寫完就結束。建議每月***小復盤，重點看三類指標：錯誤率、重試成功率、熔斷觸發(fā)次數(shù)。錯誤率看哪類失敗最多；重試成功率看重試是否真的能救回請求；熔斷次數(shù)看故障是偶發(fā)還是持續(xù)。三類指標結合看，才能判斷當前策略是過松還是過緊。

復盤時不要只看平均值，而要看分布和趨勢。比如超時率整體不高，但集中在每天下午三點，說明是高峰期資源緊張；重試成功率整體不錯，但某類任務幾乎每次都要重試兩次才成功，說明初始配置可能有問題。把指標拆到任務類型和時間段上，才能找到真正的優(yōu)化點。

月度復盤建議：
 
1. 各類錯誤碼的觸發(fā)次數(shù)和占比是否變化
2. 重試成功率是否穩(wěn)定，哪類任務重試成本最高
3. 熔斷觸發(fā)次數(shù)和持續(xù)時間是否異常
4. 429 觸發(fā)是否集中在特定任務或時段
5. 告警響應是否及時，是否有告警無人處理

• 錯誤率下降不一定是變好，也可能是告警被靜默了。
• 重試率上升要警惕，它往往先于故障率上升出現(xiàn)。
• 復盤結論要落到具體配置變更，不要停留在“下個月注意”。

? 十一、結語：穩(wěn)定性讓 API中轉站 從能用變成可依賴

Codex 接入 API中轉站 只是第一步，真正決定團隊敢不敢把它放進關鍵流程的是穩(wěn)定性。錯誤分類讓失敗可理解，超時設置讓等待有邊界，重試退避讓恢復有節(jié)奏，熔斷降級讓故障不擴散。把這些契約按任務拆開，團隊才能在故障發(fā)生時從容應對，而不是手忙腳亂地改配置。

落地時可以從一個很小的動作開始：先給每類錯誤定義處理方式，再設三層超時和帶退避的重試，最后用故障演練驗證規(guī)則真的生效。等這套機制跑穩(wěn)以后，再逐步接入告警值班、熔斷降級、月度復盤。這樣，Codex 不只是偶爾能用的工具，而會變成項目里可預期、可恢復、可依賴的基礎設施。