原廠 SDK 移轉
將現有 OpenAI、Anthropic 或 Gemini SDK 應用程式串接 AGTCloud，並系統檢查相容邊界。
如果應用程式已經使用 OpenAI、Anthropic 或 Gemini SDK，通常可以保留原有 SDK 和業務框架，將用戶端連線到 AGTCloud 的同類相容協議。移轉不只是替換地址：身分驗證、模型 ID、自動串接路徑、請求欄位和回應解析都需要一起檢查。
保持協議一致
OpenAI、Anthropic Messages 和 Gemini Generate Content 是三套不同協議。請在同一協議內替換服務地址；如果同時更換協議，請按照一次完整的介面重構進行設計和測試。
移轉前盤點
先記錄目前應用程式真實使用的能力，避免只驗證最簡單的文字請求。
| 檢查項 | 需要記錄的內容 |
|---|---|
| SDK | 套件名稱、語言、版本和同步或非同步 Client |
| 協議 | Chat Completions、Responses、Messages 或 Generate Content |
| 模型 | 目前模型 ID，以及程式碼中是否存在模型允許清單 |
| 輸入 | 文字、圖片、檔案、系統指令和歷史訊息 |
| 輸出 | 文字便利屬性、完整回應物件和自訂解析邏輯 |
| Streaming | 事件類型、增量串接和結束條件 |
| 工具 | 工具定義、呼叫 ID、參數解析和結果回傳 |
| 可靠性 | 逾時、重試、限流、記錄和回退策略 |
最小變更
三種 SDK 都需要確認以下設定，但填寫方式由 SDK 決定。
| 設定 | 移轉動作 |
|---|---|
| API 地址 | 使用本頁對應教學給出的 Origin 或 Base URL，確認 SDK 是否自動追加版本路徑 |
| API Key | 從環境變數讀取 AGTCloud API Key，不寫入原始碼或倉庫 |
| 模型 ID | 使用目前 API Key 可見且支援目標協議的模型 |
| 請求方法 | 保持原協議的 Client 方法，例如 chat.completions.create 或 messages.create |
| 回應讀取 | 對照 AGTCloud Reference 檢查文字、工具、Usage 和錯誤結構 |
依 SDK 移轉
OpenAI SDK 可以呼叫 Chat Completions 和 Responses。AGTCloud Base URL 包含 /v1。
| 移轉前 | 移轉後 |
|---|---|
| 原服務的 API Key | AGTCLOUD_API_KEY 環境變數 |
| 原服務的 Base URL 或 SDK 預設地址 | https://api.agtcloud.cn/v1 |
| 原模型名稱 | 目前 API Key 可見的 MODEL_ID |
| 原有 Chat 或 Responses 方法 | 保持同一個 Client 方法 |
不要重複追加 /v1
https://api.agtcloud.cn/v1 已經包含版本路徑。不要再設定成 https://api.agtcloud.cn/v1/v1，也不要填寫完整的 /chat/completions 或 /responses 端點。
完整安裝、Client 初始化和 Python、TypeScript 範例請參閱 OpenAI SDK。
不能只改三個設定的情況
以下場景需要調整業務程式碼，而不是只替換 Base URL、Key 和模型：
- 應用程式從 Chat Completions 改為 Responses；
- 應用程式跨 OpenAI、Anthropic 或 Gemini 協議移轉；
- 程式碼直接依賴某個 SDK 的回應類、便利屬性或串流事件；
- 工具呼叫使用了協議專屬的定義和結果回傳結構；
- 多模態內容區塊、系統指令或角色名稱發生變化；
- SDK 自動串接路徑，而原專案傳入的是完整端點 URL；
- 應用程式依賴原服務專屬的模型發現、檔案上傳或託管工具。
驗證移轉結果
驗證最小文字請求
先傳送一個不使用 Streaming、工具或多模態內容的請求。確認請求傳送到預期 API 地址，並能夠讀取文字回應。
恢復正式環境所需能力
按照 Streaming、工具呼叫、結構化輸出、多模態和多輪狀態的順序逐項恢復。每次只增加一種能力，便於定位差異。
檢查非成功路徑
至少驗證無效 API Key、錯誤模型 ID、逾時、限流和連線中斷。確認應用程式能夠讀取狀態碼和錯誤資訊，不會無限重試。
對比業務結果
不要只檢查 HTTP 200。同步比較文字內容、工具參數、結束原因、Usage、串流結束條件和記錄中的 Request ID。
分階段切換與復原
- 為新舊 Provider 保留獨立設定，不在業務程式碼中散落地址和模型名稱。
- 先讓開發或測試流量使用 AGTCloud，再逐步擴大範圍。
- 記錄每個階段的成功率、延遲、錯誤類型和功能差異。
- 保留原 Provider 設定和可控的回退切換開關，確認穩定後再清理舊設定。
不要依賴靜默忽略
某些相容實現可能接受未知欄位但不執行對應能力。驗證時需要觀察真實結果和回應結構，不能只根據狀態碼判斷欄位已經生效。
下一步
- 檢視 SDK 概覽 選擇對應教學；
- 檢視 API Key、Base URL 與驗證；
- 如果準備從 Chat 移轉到 Responses，請繼續閱讀 Chat Completions → Responses；
- 遇到狀態碼或請求失敗時，參考 錯誤與疑難排解。