Ollama API 疑難排解指南

了解 Ollama API 端點結構

The ollama endpoint 遵循嚴格的 RESTful 模式，並與 OpenAI API 結構保持一致。您可以透過發送 POST 請求與其互動， /v1/chat/completions 並透過 GET /v1/models. 此標準化允許您在無需重寫用戶端程式碼的情況下交換底層模型。

許多開發者認為端點預設支援嵌入或圖像生成。並非如此。我們的託管服務僅提供單一無審查模型的文本完成服務。始終檢查 GET /v1/models 回應，以查看具體暴露了哪些功能。如果您看到模型列表，請在發送請求前驗證它們的 ID。

使用本地實例時，端點通常運行於 http://localhost:11434. 對於雲端供應商，您將使用自訂基礎 URL。確保您的 HTTP 客戶端能正確處理標頭，特別是 Content-Type: application/json. 缺少標頭通常會導致看似模型錯誤的靜默失敗。

結構要素：

• model: 特定 LLM 的字串識別碼。
• messages: 基於角色的內容物件陣列。
• stream: 啟用伺服器發送事件（SSE）的布林旗標。

為何您的 ollama API 呼叫可能會失敗

API 調用通常因 base URL 不正確、密鑰過期或 JSON 負載格式錯誤而失敗。最常見的錯誤是 401 Unauthorized 響應，這意味著您的 API 密鑰缺失或無效。另一個常見問題是 404 Not Found，表示端點不支持請求的路徑或模型 ID。

仔細檢查您的請求主體。若您發送終端不支援的參數，例如 modalities for 純文字模型，伺服器可能會拒絕請求。我們的服務例如不支援影像輸入。傳送影像會導致立即錯誤。

網路超時也會導致失敗。如果您的本地 Ollama 執行個體處於閒置狀態，它可能會將模型從 VRAM 卸載。冷啟動後的第一個請求可能需要幾秒鐘。在您的 HTTP 客戶端中設定寬鬆的超時時間，以避免過早斷線。

常見錯誤代碼：

• 400: 錯誤請求（JSON 格式錯誤或參數無效）。
• 401: 未授權（API 金鑰無效或缺失）。
• 429: 請求過多（超過速率限制）。
• 500: 內部伺服器錯誤（模型載入失敗）。

正確配置無審查的 ollama 模型

無審查模型通常需要特定的參數才能按預期運作。主要的差異在於 system 提示。您必須明確指示模型繞過標準拒絕機制。若沒有強有力的系統提示，模型可能會恢復預設的安全行為。

我們的端點使用模型 ID uncensored. 您將請求發送至此 ID，伺服器會處理底層的模型選擇。這抽象化了管理模型版本的複雜性。您不需要知道底層架構是基於 Llama 還是 Mistral。

調整 temperature 參數以控制創意。值為 0.7 是獲得平衡回應的良好起點。較高的值會增加隨機性，這對於創意寫作很有用，但可能會降低事實準確性。較低的值會使輸出更具確定性。

設定技巧：

• 使用 top_p 並排 temperature 用於更好的控制。
• 設定 stop 序列以防止無限循環。
• 始終包含一個 system 角色定義的消息。

處理串流與 Token 限制

串流回應透過伺服器發送事件（SSE）以區塊形式回傳資料。每個區塊包含部分完成內容。您必須組裝這些區塊以取得完整回應。我們的服務在最後一個區塊中包含權杖使用統計數據，讓您可以即時追蹤成本。

Token 限制對於長對話至關重要。我們的端點支援 100,000 個 Token 的上下文視窗，結合了提示和完成內容。然而，每次請求的最大輸出為 16,000 個 Token。如果您未設定 max_tokens, 預設值為 2,048 個 token。這可能會意外截斷長回答。

串流處理時，請優雅地處理網路中斷。如果連接中斷，且伺服器支援，您可以從最後接收的區塊恢復。否則，您可能需要重試整個請求。始終監控 usage field in the final chunk to avoid billing surprises.

串流最佳實踐：

• 正確解析 SSE 事件，忽略空行。
• 在記憶體或緩衝區中累積區塊。
• 檢查 usage 最後一個區塊中的物件以取得 token 數量。

帳單錯誤與 Token 算術

計費錯誤通常源於對 Token 計數方式的不了解。Token 會針對輸入（提示詞）和輸出（補全）進行計費。我們的定價為每 1M 輸入 Token $0.15，每 1M 輸出 Token $0.50。錯誤和拒絕回應均免費，這有助於降低除錯成本。

Tokenizer 並不總是與字元 1:1 映射。一個單詞可能是多個 Token。如果您根據字元數估算成本，可能會低估帳單。在發送請求之前，請在客戶端中使用可靠的 Tokenizer 庫以獲得準確的計數。

餘額不會過期。若您使用加密貨幣充值，餘額將保留在您使用為止。這對於長期專案很有用。然而，請注意每次請求都會從您的餘額中消耗詞元。若您的餘額不足，後續請求可能會失敗。

計費技巧：

• 在每個回應中追蹤 token 用量。
• 設定低餘額閾值的警報。
• 使用 max_tokens 限制潛在成本。

安全性與埠掃描問題

本地 Ollama 端點通常預設暴露於網路。這使其容易受到尋找免費運算資源的端口掃描器攻擊。如果您在不進行身份驗證的情況下暴露端口 11434，任何人都可以使用您的 GPU 資源。這可能導致高昂的電費和性能下降。

透過更改預設埠或使用具有身份驗證的反向代理來保護您的端點。我們的託管服務為您處理安全性，因此您無需擔心埠暴露。您只需保持 API 金鑰私密即可。

對於本地設置，請使用防火牆限制對受信任 IP 地址的訪問。你也可以在 Ollama 的配置文件中啟用基於 token 的認證。這可以防止未經授權的用戶發送請求。

安全步驟：

• 若需暴露至網際網路，請變更預設連接埠。
• 使用帶有 HTTPS 和身份驗證的反向代理。
• 監控您的網路流量以發現異常活動。

本地與雲端 Ollama API 使用

本地使用讓您可以完全掌控資料隱私和模型選擇。您可以同時運行多個模型並即時切換。然而，您需負責硬體維護、更新和安全性。雲端使用將這些責任轉移給供應商。

我們的雲端服務提供針對無限制內容生成進行優化的 uncensored 模型。您無需下載大型模型檔案即可立即使用。代價是您的資料會經過我們的伺服器。對於敏感資料，本地部署可能是更好的選擇。

雲端服務通常因網路往返而具有較高延遲。若 GPU 足夠快，本機實例的延遲接近零。然而，本機實例需要大量 VRAM。若您的 GPU 記憶體耗盡，模型可能會交換至 CPU，導致回應速度大幅減慢。

比較：

• 本地： 隱私權、控制、硬體依賴。
• 雲端： 便利性、擴展性、數據傳輸。

常見客戶端錯誤

開發者常忽略處理速率限制。我們的服務允許每金鑰每分鐘 300 次請求。如果你超過此限制，將收到 429 錯誤。在客戶端實作指數退避以優雅地處理這些錯誤。

另一個錯誤是未設定 stream parameter correctly. If you expect streaming but do not set stream: true, 您必須等待整個回應完成後才能收到任何資料。這會使您的應用程式感覺變慢。

JSON 模式錯誤也很常見。如果您設定 response_format: {type: "json_object"}, 模型必須回傳有效的 JSON。如果無法做到，您的解析器將失敗。新增錯誤處理以捕獲並重試 JSON 解析錯誤。

檢查清單：

• 實作速率限制處理。
• 設定 stream: true 用於即時更新。
• 使用 JSON 模式時驗證 JSON 輸出。