常見 AI 聊天 API 錯誤排除

理解上下文視窗

API 失敗最常見的原因之一是超出上下文視窗。上下文視窗定義了單一請求中允許的 token 總數，包括輸入提示詞和生成的補全。當達到此限制時，API 將拒絕請求並顯示錯誤，通常表示序列過長。

開發人員經常將字元計數誤認為 token 計數。一個單字可能代表多個 token，具體取決於 tokenizer。例如，100,000 token 的上下文視窗（如我們的 推理 API 所提供的）允許大量的對話歷史或大型文件處理，但它並非無限。

• 監控 token 用量： 使用模型的官方 tokenizer 在發送請求之前準確計算 token。
• 智慧截斷： 如果超出限制，請從對話歷史中移除最舊的訊息，而不是最近的訊息。
• 考慮開銷： 為模型的回應保留一些 token。如果您的提示詞使用了 63,000 個 token，則剩餘的 token 僅有 1,000 個用於補全。

未能管理此限制將導致連線丟失或不完整的回應。在部署到生產環境之前，始終根據模型的文件驗證您的 token 計數。

處理串流錯誤

透過伺服器發送事件 (SSE) 進行串流回應對於良好的使用者體驗至關重要，但它會增加錯誤處理的複雜性。與標準 JSON 回應不同，串流可能在中途中斷。如果發生網路錯誤，您的客戶端可能會收到部分資料，使串流處於未定義狀態。

在實現串流消費者時，您必須仔細處理串流的生命週期。在嘗試解析串流之前檢查 HTTP 狀態碼。如果連線中斷，您應該記錄錯誤並決定是重試還是向使用者顯示訊息。

此外，確保您的客戶端正確處理串流結束標記。某些程式庫期望特定的關閉事件，而其他則依賴連線關閉。誤解這一點可能會導致程序掛起或記憶體洩漏。

始終為串流請求實施超時。如果 API 在合理時間內未發送回應，請中止請求以釋放資源。這對於在高併發環境中保持穩定至關重要。

Token 計數與限制

Token 計數不僅是為了保持在上下文視窗內；它還涉及成本管理。每個 token 都有特定的價格，計算錯誤的用量可能會導致意外的帳單。雖然我們的定價是透明的，具有輸入和輸出的每 token 費率，但仍需準確追蹤用量。

大多數開發人員使用程式庫來計算 token，但使用您所使用模型的正確 tokenizer 至關重要。不同的模型使用不同的 tokenizer，使用錯誤的 tokenizer 可能會導致計數 token 的顯著差異。例如，針對英文文本訓練的 tokenizer 處理標點符號的方式可能與針對程式碼訓練的不同。

密切關注您的用量限制。我們的 API 允許每個金鑰每分鐘 300 次請求。如果您超出此限制，您將收到 429 Too Many Requests 錯誤。在您的應用程式中實施簡單的計數器可以幫助您保持在這些限制內，避免服務中斷。

最後，請記住 token 計數在不同 tokenizer 的實現之間可能會略有不同。始終使用一些已知輸入測試您的 token 計數邏輯，以確保一致性。

標頭配置陷阱

標頭是 API 請求的配置層。配置錯誤是 400 Bad Request 或 401 Unauthorized 錯誤的常見來源。兩個最關鍵的標頭是 Content-Type 和 Authorization。

Content-Type 標頭必須設為 application/json。若遺漏或設定錯誤，API 可能無法正確解析您的請求主體。Authorization 標頭必須包含您的 API 金鑰，格式為 Bearer YOUR_API_KEY。一個常見的錯誤是遺漏了 Bearer 前綴，這會導致驗證錯誤。

• 檢查拼寫錯誤： 確保正確複製您的 API 金鑰，包括任何尾隨空格或換行符。
• 驗證標頭： 使用 curl 或 Postman 等工具檢查正在發送的標頭。
• 處理大小寫敏感性： 某些 API 對標頭名稱大小寫敏感，儘管大多數現代 API 並非如此。

在發送請求之前始終驗證您的標頭。標頭中的小錯誤可能會導致整個請求失敗，導致混淆和浪費除錯時間。

速率限制管理

實施速率限制是為了確保公平使用並防止濫用。我們的 API 允許每個金鑰每分鐘 300 次請求。如果您超出此限制，您將收到 429 Too Many Requests 錯誤。此錯誤包含 Retry-After 標頭，指示您應等待多久後再發送請求。

要有效管理速率限制，請實施退避策略。不要立即重試，而是等待一段隨著每次重試呈指數增長的時間。這可以防止您的應用程式在高峰時段壓垮 API。

監控您的用量指標。大多數 API 提供儀表板或 API 端點來追蹤您的請求量。使用這些數據來優化應用程式的請求模式。如果您發送了太多小請求，請考慮將它們分批處理。

請記住，速率限制是按金鑰計算，而非按帳戶計算。如果您有多個金鑰，每個金鑰都有自己的限制。相應地規劃金鑰分發，以避免意外達到限制。

錯誤碼解讀

了解錯誤碼對於除錯至關重要。您將遇到的最常見錯誤是 400 Bad Request、401 Unauthorized、429 Too Many Requests 和 500 Internal Server Error。

• 400 Bad Request： 這通常表示請求主體有問題，例如缺少欄位或無效的 JSON。請查看錯誤訊息以取得哪個欄位不正確的詳細資訊。
• 401 Unauthorized： 這表示您的 API 金鑰有問題。請驗證金鑰是否正確且未被撤銷。
• 429 Too Many Requests： 這表示您已超出速率限制。實施退避策略以優雅地處理此情況。
• 500 Internal Server Error： 這表示伺服器端有問題。稍作延遲後重試請求。

始終記錄錯誤回應主體。它通常包含有關出錯原因的寶貴資訊，例如導致錯誤的特定欄位。這可以為您節省數小時的除錯時間。

最佳化請求主體

請求主體是 API 互動的核心。最佳化它可以提升效能並降低成本。一個常見的錯誤是在單一請求中傳送過多資料。如果你的提示詞太大，可能會超出上下文視窗或產生更高的費用。

仔細建構你的 JSON。確保所有必要欄位都存在，且選擇性欄位僅在需要時才包含。例如，如果你不需要串流輸出，就不要包含 stream 參數。這可以減少有效負載大小並簡化回應。

使用 curl 或 Postman 等工具來測試你的請求主體。這可以讓你驗證 JSON 是否有效，以及 API 是否正確解析它。這也有助於你識別是否有不必要的資料被傳送。

最後，考慮為相同的請求快取回應。如果你多次傳送相同的提示詞，你可以將回應儲存在本地端，避免再次進行 API 呼叫。這可以顯著降低重複性任務的延遲和成本。

除錯函式呼叫

函式呼叫允許模型根據使用者輸入執行函式。除錯函式呼叫可能具有挑戰性，因為它涉及多個步驟：傳送請求、接收函式呼叫、執行函式，並將結果傳回模型。

確保您的函式定義準確無誤。Schema 必須與實際的函式簽章相符。如果 Schema 不正確，模型可能會產生無效的參數，導致您在嘗試執行函式時發生錯誤。

記錄函式呼叫參數和函式輸出。這可以讓你驗證模型是否產生正確的參數，以及你的函式是否按預期執行。如果有錯誤，記錄檔將有助於你識別問題。

妥善處理錯誤。如果函式執行失敗，將錯誤訊息傳回模型，讓它可以調整回應。這提供更好的使用者體驗，並讓模型能夠從錯誤中恢復。