Mistral API 整合指南

了解基礎 URL 的變更

您的程式碼會將請求傳送至基礎 URL 並附加金鑰。若要切換至其他 OpenAI 相容的端點，只需更改這兩個值，其餘無需變動。路徑 /v1/chat/completions 保持不變，因此請求主體與回應主體的結構保持不變。

將舊的基礎 URL 保存在配置值中，而不是程式碼中。這樣如果生產環境出現問題，您可以一步切換回去。

SDK 相容性：OpenAI 與 Mistral 客戶端

大多數客戶端程式庫接受自訂 base URL。官方 OpenAI SDK、LangChain 和 LlamaIndex 都支援此功能，純 HTTP 客戶端也可以。將 base URL 設定為 https://mistralapibaseurl.com/v1 並傳遞新金鑰。

• 檢查 SDK 版本，因為非常舊的版本會忽略基礎 URL 設定。
• 檢查客戶端是否將金鑰傳遞至 Authorization header 作為 bearer token。

配置模型 ID

傳送模型 id uncensored. 該服務僅提供一種模型，因此 id 在請求之間不會變化，您無需編寫模型選擇邏輯。

運行一次請求，使用短提示詞。收到回覆和使用區塊，即表示基礎 URL、密鑰和模型 id 均正確。

實作串流回應

設定 stream: true 以伺服器發送事件（server-sent events）接收答案。每個事件攜帶一小段文字，最後一個事件則包含用量數據。

即時顯示隨流式傳輸到達的區塊，並將完整文字保留在緩衝區中，以便在串流結束時儲存訊息。測量第一個 token 的到達時間；該數值可反映聊天對使用者的回應速度。

啟用函式呼叫和工具

以您已使用的相同格式傳遞 tools 陣列。模型會回傳包含函式名稱和 JSON 參數的工具呼叫。在您的程式碼中執行該函式，將結果作為 tool message 送回，並讀取最終答案。

1. 定義一個包含兩個必要參數的工具並單獨測試它。
2. 測試需要連續進行兩次工具呼叫的案例。
3. 在執行任何更改資料的操作之前驗證參數。

管理上下文視窗與令牌

上下文視窗為 100,000 個 token。長對話會填滿視窗，因此在達到限制前請修剪舊的對話輪次或將其摘要。每次請求最多可返回 16,000 個輸出 token，預設為 2,048，因此請設定 max_tokens 用於您期望的答案。

從每個回應的 usage 欄位計算 token。從字數估算通常對程式碼和非英文文本的誤差很大。

處理速率限制與重試

每個金鑰允許每分鐘 300 次請求與 8 個同時請求。超出限制時，您將收到 429 回應。僅對 429 和 5xx 響應進行重試，採用指數退避並設定總等待時間上限。

Never retry a 400 or a 401, because the same request fails the same way again. Fix the request or the key first.

除錯常見 API 錯誤

狀態	常見原因	該做什麼
400	JSON 格式錯誤或未知欄位	檢查請求主體是否符合您發送的格式
401	缺少或錯誤的金鑰	再次複製金鑰並檢查 Authorization 標頭
402	餘額已用完	充值餘額；最低充值金額為 $20。
429	達到速率限制	退避並稍後重試

記錄每次失敗的狀態碼和請求 ID，以便快速追蹤問題。

從競爭對手的 API 遷移

分三個階段進行遷移：測試環境、小部分線上流量，然後完全切換。在中期階段，配置中同時保留兩個 base URL，並在相同的提示下比較答案和延遲。

根據您的實際使用情況比較成本，而非列表價格。將使用欄位中的輸入和輸出 Token 數量乘以每百萬 Token $0.15 和 $0.50，並與您当前的帳單進行對比。