Ollama API：常見錯誤疑難排解

了解 100k 上下文視窗

每個章節的第一句話都會回答標題中的問題。

100,000 token 的上下文視窗聽起來很龐大，但它會平均分配給輸入提示詞和輸出補全。當您發送長系統提示詞並附上長對話歷史時，您消耗的預算可能比預期的更快。許多開發者誤以為限制僅適用於輸入，這會導致回應被截斷或當模型達到上限時出現無聲失敗。

考慮一個場景，您將一份 50,000 token 的文件作為上下文傳遞。您只剩下 50,000 個 token 用於實際生成。如果您不仔細管理這種平衡，模型將在中途截斷句子。請始終監控每次請求發送的總 token 數，以避免意外的截斷。

最大 Token 數與預設輸出長度

每個部分都必須回答標題中的問題。

除非您指定限制，否則大多數 API 預設的輸出長度較短，通常約為 2,048 個 token。這個預設值對於短查詢很有用，但對於程式碼生成或長篇寫作來說卻很糟糕。如果您需要模型生成完整的腳本或詳細的分析，您必須明確設定 max_tokens 參數。

將此值設定過高也會影響延遲與成本。您為每個生成的 token 付費，無論其是否有用。務實的做法是設定一個符合您使用情境的合理上限，而不是將其保留為預設值或無限大。

正確處理串流 SSE 區塊

串流需要仔細處理 Server-Sent Events 以避免資料遺失。

當您啟用串流傳輸時，API 會返回一系列小區塊，而非單一完整回應。每個區塊包含文本增量，但關鍵細節如 token 使用統計數據通常僅出現在最後一個區塊中。如果您過早停止解析，將會錯過用於計費或速率限制追蹤的用量數據。

此外，流式傳輸在錯誤處理方面引入了複雜性。網絡中斷可能會導致您只獲得部分文本。您需要一個強大的解析器，能夠從這些片段中重建完整消息。當與實時渲染文本的 UI 組件整合時，這一點尤為重要。

函式呼叫工具定義錯誤

當工具結構描述與模型的預期不符時，函式呼叫會失敗。

模型期望用於工具定義的特定 JSON 結構。如果您遺漏必要欄位或使用錯誤的類型，模型可能會完全忽略該工具或回傳格式錯誤的回應。這是開發人員建構需要與外部 API 互動的代理程式時常見的痛點。

始終根據 API 文件驗證您的工具架構，然後再發送請求。即使是微小的偏差，例如使用整數而不是字串作為參數，也可能破壞函數呼叫。調試此問題需要檢查原始 JSON 回應，以查看模型是否嘗試調用工具。

JSON 模式回應格式問題

JSON 模式強制模型輸出有效的 JSON，但它仍可能產生幻覺。

當您將 response_format 設定為 json_object 時，模型被限制僅輸出 JSON。然而，這並不保證內容在語義上是正確的。模型可能會產生有效的 JSON 語法，但包含錯誤的鍵或缺失的欄位。您仍需要使用解析器在將資料用於之前驗證結構。

此外，JSON 模式有時可能會降低模型的創意或靈活性。如果您的提示過於複雜，模型可能會難以將敘事適應到嚴格的 JSON 結構中。請主要在結構化資料提取或函式引數等需要一致性而非細微差別的場景下使用此模式。

速率限制與併發請求

速率限制是針對每組 API 金鑰執行，而非每個使用者或 IP 地址。

大多數 API 對每分鐘請求數和併發連接數設有限制。如果您超過這些限制，將收到 429 Too Many Requests 錯誤。這對於生成多個線程或進程來處理用戶請求的應用程式至關重要。單一金鑰只能處理有限數量的並行請求。

要管理此問題，請在客戶端程式碼中實作指數退避演算法。當收到 429 錯誤時，請等待一小段時間後再重試。這可防止伺服器超載，並確保更流暢的使用者體驗。請務必檢查回應標頭中的 retry-after 值，以最佳化您的等待時間。

API Key Replacement Behavior

重新產生 API 金鑰會立即使舊金鑰失效。

部分平台每個帳戶只允許一個活躍金鑰。如果您生成新金鑰，舊金鑰會立即失效。如果您有多個服務或腳本使用舊金鑰，這可能會導致中斷。在輪換金鑰之前，請始終更新所有金鑰實例。

此行為旨在確保安全，確保洩漏的金鑰無法無限期使用。然而，這需要分散式系統中的仔細管理。使用環境變數或金鑰管理員來儲存您的金鑰，使更新更容易且不易出錯。

請求體大小限制

大型有效載荷可能超過 8 MB 的請求主體限制。

當發送以 base64 編碼的長文件或圖片時，請求主體可能會迅速增長。如果您超過大小限制，伺服器將以 413 Payload Too Large 錯誤拒絕請求。這是一個硬性限制，在許多情況下無法通過升級您的方案來增加。

要避免此問題，請壓縮您的輸入內容或將大型文件拆分為較小的區塊。您也可以使用更高效的圖像編碼方法。始終監控請求的大小，特別是在處理富含媒體的內容時。