OpenAI 相容 API：開發者遷移檢查清單
作者：Nicho
OpenAI 相容的 API 可以讓你保留現有的用戶端函式庫，同時更換背後的服務。這對於評估模型、控管成本或整併供應商很有用。但這並不代表每個端點、參數或應用程式功能都會有一致的行為。
安全的遷移要從你的應用程式實際發出的請求開始。把相容性視為針對特定模型與路由的檢查清單，而不是貼在整個平台上的標籤。
本指南以 cheapaimodel 的設定作為具體範例。範例依循 2026 年 10 月 26 日檢視的公開文件；它們不是經過驗證的 API 測試結果。
1. 區分四種相容性
| 層級 | 要回答的問題 | 要蒐集的證據 |
|---|---|---|
| 用戶端 | SDK 能否將請求傳送到這個服務？ | 有文件記載的自訂 Base URL 與驗證方式 |
| 通訊協定 | 伺服器是否看得懂請求的格式？ | 端點與參數文件 |
| 模型 | 所選模型是否實作該功能？ | 模型專屬的能力清單與針對性的測試 |
| 應用程式 | 結果是否符合你的工作流程？ | 回歸案例、已驗證的輸出與營運指標 |
一次成功的文字補全，只回答了這份檢查清單的一小部分。它無法證明圖片輸入、工具呼叫、結構化輸出或對話狀態能夠運作。
在選擇替代方案之前，先寫下你的應用程式所需的能力。把必要功能與便利功能分開。否則，一個便宜、只測文字的煙霧測試，可能掩蓋掉代價高昂的串接落差。
2. 一起設定 Key、Base URL 與模型
cheapaimodel 將 https://api.cheapaimodel.ai/v1 記載為其 OpenAI SDK 的 Base URL。請提供閘道自己的 API Key，而不是其他無關供應商的 Key。避免在 Base URL 中放入 /chat/completions，因為 SDK 會自行加上資源路徑。網站網域不是 API 主機。請參閱 Base URL 指南。
最小設定看起來像這樣：
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["CHEAPAIMODEL_API_KEY"],
base_url="https://api.cheapaimodel.ai/v1",
)
result = client.chat.completions.create(
model="deepseek-v4-1-flash",
messages=[{"role": "user", "content": "Reply with one short greeting."}],
)
print(result.choices[0].message.content)
模型識別碼請依循閘道 SDK 指南；每個模型頁面都會列出其識別碼與價格，例如 DeepSeek V4.1 Flash。不要假設其他供應商對同一個模型系列會使用相同的識別碼。請把這三個設定值一起放在你的部署設定中，這樣部分變更就不會不小心把新的 Key 送到舊的端點。
請讓 Key 遠離前端打包檔、已提交的檔案與除錯日誌。為遷移環境使用獨立的 Key，這樣你就能單獨撤銷它。
3. 分辨 Chat Completions 與 Responses
檢查你的應用程式所呼叫的 SDK 方法。client.chat.completions.create(...) 與 client.responses.create(...) 是不同的介面。應用程式中標示為「OpenAI 相容」的設定，可能使用其中任一種。
cheapaimodel 同時列出這兩種路由，但其文件表示支援的端點取決於模型。請驗證路由與模型的組合，而不是假設其中一個可用就代表另一個也可用。請參閱 API 參考與 FAQ。
針對每個路由，請記錄：
- 應用程式送出的請求欄位。
- 應用程式讀取的回應欄位。
- 它如何傳遞對話歷史或狀態。
- 它需要哪些工具或格式選項。
- 它的串流解析器如何辨識完成。
不要獨立變更端點與回應解析器。如果生成成功，但應用程式讀取了錯誤的欄位並顯示空白答案，那麼遷移就不算完成。
4. 稽核參數，而不是全部轉送
從具代表性的請求建立一份小型清單，並移除憑證與個人內容。納入框架新增的選填欄位，而不只是你自己程式碼中可見的欄位。
分別測試 token 限制、推理控制、取樣選項、工具與輸出格式。被接受的參數不一定就是有效的參數。DeepSeek 目前的 Chat Completions 參考文件記載了行為取決於思考模式的設定，同時也列出已不再生效的棄用欄位。
結構化輸出值得單獨測試。OpenAI 區分 JSON 模式與受結構描述約束的 Structured Outputs。OpenAI 形式的請求不會把這些保證轉移到每個相容的伺服器上。請確認所選供應商文件記載的格式支援，然後在你的應用程式中驗證結果。請參閱 OpenAI 的結構化輸出指南。
5. 測試失敗路徑與串流行為
使用精簡的迴歸測試套件，而不是單一令人驚豔的提示：
| 案例 | 必要觀察結果 |
|---|---|
| 短文字請求 | 可用的內容送達應用程式 |
| 多輪對話 | 相關的較早上下文獲得保留 |
| 串流回應 | 差異片段正確組裝，且中斷情況可見 |
| 工具工作流程（如有需要） | 引數在執行前通過驗證 |
| 結構化回應（如有需要） | 無效或不完整的輸出遭到拒絕 |
| 無效的模型或 Key | 可讀的錯誤送達操作人員 |
| 緩慢或中斷的請求 | 逾時與重試行為有界限 |
在非生產環境中執行這些測試，並設定明確的支出上限。在可取得時記錄請求 ID、HTTP 狀態、延遲、完成狀態與驗證結果。絕不記錄憑證。除非你的日誌政策明確允許，否則請遮蔽客戶內容。
6. 讓其他協定與服務保持獨立
Anthropic Messages 相容性是另一份獨立的串接契約。它無法從 OpenAI 相容性推斷而來。cheapaimodel 為 Anthropic SDK 記載了不同的 Base URL 慣例，這些 SDK 會附加自己的 /v1/messages 路徑。請遵循文件記載的設定，而不是盲目重用某個 URL。
同時也要獨立稽核 embeddings、儲存、批次處理，以及任何託管工具。全域的 Base URL 覆寫可能會將超出預期的用戶端重新導向。當你的應用程式使用多項服務時，請優先採用明確的個別用戶端設定。
7. 以可回復的決策進行推行
先從內部流量或範圍狹窄的工作負載開始。比較任務成功率與每個可接受結果的成本，而不只是 token 價格。我們的 LLM API 定價比較 提供了定價方面的起點；你的回歸測試套件則提供品質證據。
保留先前的設定，定義回復門檻，並在重複執行受到控管之前，避免對有副作用的流程自動切換供應商。
當必要功能通過、失敗仍可理解，且應用程式能安全回到先前的設定時，遷移就準備就緒了。重複使用 SDK 是這個過程的開始，而不是它的驗收標準。