作者注:多模型應用應通過統一消息格式、廠商適配層和能力註冊表,處理工具調用、推理狀態、流式輸出、結構化數據與緩存差異。
GPT、Claude 和 Gemini 都能完成普通文本調用,Claude 和 Gemini 也提供官方的 OpenAI SDK 兼容入口。生產級應用在切換模型時,需要解決 6 類兼容問題:消息角色與系統指令、工具調用協議、推理參數與思考狀態、流式事件、結構化輸出與多模態、緩存計費與錯誤處理。只替換 Model ID 能跑通簡單問答,多輪工具調用、斷流恢復和成本覈算則需要單獨處理。比較穩妥的工程方案是“統一業務接口 + 廠商適配層(Provider Adapter)+ 模型能力註冊表”。這樣,模型切換可以作爲一項可維護的產品功能來管理。
下文先對照三家原生 API 的結構差異,並說明 OpenAI 兼容接口能覆蓋哪些場景。隨後逐一拆解 6 類兼容問題會引發哪些真實故障,再給出六層接入架構和可運行的統一調用代碼。最後列出上線前的六項兼容性測試,並說明統一 API 網關與原生能力適配之間如何分工。

To Know:多模型 API 兼容術語表
| 術語 | 解釋 |
|---|---|
| API | 應用向模型服務發送請求並取回結果的接口。 |
| SDK | 封裝好接口調用細節的軟件開發工具包。 |
| 原生 API | 廠商自己設計的主力接口,例如 OpenAI Responses、Claude Messages、Gemini Interactions。 |
| 兼容接口 | 沿用另一套請求格式(通常是 OpenAI 格式)的適配入口,便於用同一個 SDK 調用。 |
| 函數調用(Function Calling) | 模型用結構化參數請求應用執行某個外部函數。 |
| 調用 ID | 把模型發起的工具請求與應用回傳的執行結果對應起來的標識。 |
| 思考簽名(Thought / Thinking Signature) | 部分模型用來保存推理和工具調用上下文的加密狀態數據,需要原樣回傳。 |
| 流式輸出(Streaming) | 服務端按事件逐段返回結果,前端可以邊收邊顯示。 |
| JSON Schema | 描述 JSON 數據結構和校驗規則的規範。 |
| 提示詞緩存(Prompt Caching) | 對重複出現的輸入前綴複用計算結果,以降低延遲和費用。 |
| TTL | 緩存的存活時長,過期後需要重新寫入。 |
| 適配器(Provider Adapter) | 把統一請求轉換成某家廠商的原生格式,再把返回結果轉換回統一格式的組件。 |
| 能力註冊表 | 記錄每個模型、每個接入端點實際支持哪些參數和功能的配置清單。 |
| 冪等 | 同一操作執行一次和執行多次的效果相同,用來防止重試造成重複扣款、重複發信。 |
1 多模型 API 兼容:爲什麼換模型不能只換 Model ID
三家都能通過一個 model 字段指定模型,但請求體、響應對象和上下文狀態的組織方式各不相同。普通問答的差異集中在字段名上,適配成本較低。Agent 類應用會依賴工具調用、推理狀態和流式事件,差異就會直接變成線上故障。
1.1 GPT、Claude、Gemini 三家原生 API 對照
下表只描述原生 API,不涉及任何兼容層或網關端點。
| 維度 | OpenAI(原生) | Claude(原生) | Gemini(原生) |
|---|---|---|---|
| 主力接口 | Responses API,/v1/responses |
Messages API,/v1/messages |
Interactions API(2026 年 6 月 GA,官方推薦新項目使用);generateContent 仍受支持 |
| 輸入組織 | model + input |
model + messages + max_tokens,system 獨立於消息數組 |
原生 Interactions 結構,另有 system_instruction 規則 |
| 輸出結構 | 多類型輸出項:文字、reasoning 項、function_call 等 |
content blocks:text、thinking、tool_use 等 |
steps:模型輸出、工具調用、推理等步驟 |
| 結束判斷 | 響應完成事件 / 輸出項類型 | stop_reason(正常結束、需要執行工具等) |
步驟類型與交互狀態 |
| 上下文延續 | previous_response_id |
應用自行回傳完整消息歷史 | previous_interaction_id,可選服務端會話狀態 |
| 內置工具 | 平臺工具 + 自定義函數 | 自定義工具爲主 | Google Search、URL Context、代碼執行等內置工具;第三方工具由應用執行 |
從上表可以看到,三家在“誰來保存上下文”這一點上就分成了兩條路線。OpenAI 和 Gemini 支持服務端延續上下文,Claude Messages 由應用自行回傳歷史。如果應用的會話存儲只按其中一種方式設計,切換到另一家時就會出現上下文丟失或重複發送。
1.2 OpenAI 兼容接口能解決多少問題
Claude 和 Gemini 都提供 OpenAI SDK 兼容入口。Gemini 的官方兼容端點是 generativelanguage.googleapis.com/v1beta/openai/,使用 OpenAI 客戶端時修改 base_url、API Key 和 model 即可。Claude 的兼容文檔則明確限定了支持範圍,截至 2026-11-13 的已知限制如下:
- 工具定義中的
strict參數會被忽略,工具參數的嚴格約束因此失效。 - 不支持 Prompt Caching。
- 不支持 audio、file 類型的輸入。
system與developer消息會被提到最前面合併處理。thinking相關字段與原生 API 存在差異。
兼容接口適合三類場景:普通聊天、單輪生成,以及快速對比不同模型的回答質量。複雜 Agent 遷移涉及嚴格工具參數、緩存、文件輸入和多輪推理狀態,這些能力需要回到原生 API,或者經過逐項驗證後再上線。一個實用的判斷標準是:應用依賴的功能如果只在原生文檔中出現,就把它記入能力註冊表,交給專門的適配器處理。
2 GPT、Claude、Gemini 模型切換最容易遇到的六類兼容問題

2.1 消息角色與系統指令的兼容處理
OpenAI 區分 developer 和 system 等角色。Claude 的 system 指令位於消息數組之外。Gemini 使用 system_instruction,用戶與模型內容也有自己的結構規則。三者表達的都是“指令優先級 + 多輪歷史”,承載的字段位置卻各不相同。
常見故障來自偷懶的拼接:把系統指令、歷史消息和工具結果拼成一整段字符串,交給模型當作用戶輸入。這樣做能跑通,但指令優先級會被削弱,模型可能把歷史中的工具輸出當作用戶的新要求。正確做法是在應用內部保留角色語義,由適配器負責映射到各家的字段。另外要注意,Claude 兼容層會把 system 和 developer 合併,依賴兩者分層的提示詞設計需要實測效果。
2.2 工具調用協議與調用 ID 的兼容處理
三家都支持 Function Calling,調用鏈路的形態如下:
| 環節 | OpenAI | Claude | Gemini |
|---|---|---|---|
| 模型發起調用 | function_call 輸出項 |
tool_use 內容塊 |
functionCall / 原生工具步驟 |
| 關聯標識 | call_id |
tool_use 的 ID |
對應調用標識 |
| 應用回傳 | function_call_output |
tool_result 內容塊 |
對應結果回傳結構 |
| 是否需繼續 | 根據輸出項判斷 | stop_reason 指示需要執行工具 |
根據步驟狀態判斷 |
| 推理狀態 | reasoning 項可能需隨歷史傳遞 | thinking 塊可能需原樣回傳 | stateless 模式需保留 thought 塊和簽名 |
工具層需要完整保存六項信息:調用 ID、函數名、參數 JSON、並行調用關係、執行結果,以及模型是否要求繼續推理。並行調用是最容易出錯的地方。模型一次發起多個工具請求,應用只回傳了其中一個結果,或者結果與 ID 對錯了,下一輪請求就會報參數錯誤,或者模型基於錯誤數據繼續回答。
建議統一工具層先用 JSON Schema 校驗參數,校驗通過後再執行真實的外部操作。模型生成的參數並不總是合法,提前校驗可以把錯誤攔截在“調用外部系統”之前。
2.3 思考模式及上下文狀態的兼容處理
推理參數的名稱和含義在三家之間並不對等:
- OpenAI:使用
reasoning.effort等參數。GPT-6 Astra 和 GPT-6.1 Sol 不接受reasoning.effort=none,這兩款模型的工具調用也要求使用 Responses API。 - Claude:新一代模型主要採用 Adaptive Thinking,配合 effort 等思考配置。部分新模型已不再支持舊式固定
budget_tokens的手動思考模式。 - Gemini:不同模型使用 thinking level 或 budget,能否關閉推理、有哪些檔位都因模型而異。原生 API 與 OpenAI 兼容入口的參數映射規則也不同。
產品界面上設計“快速、標準、深入”三檔推理強度時,檔位名稱表達的是產品意圖。適配器需要把它轉換成每個模型實際支持的參數,三家在同一檔位下獲得的計算資源也不相同。另外,用戶看到的思考摘要與實際計費的思考 Token 數可能對不上,成本統計要以接口返回的用量字段爲準。
多輪工具調用中的加密狀態,是長程 Agent 最容易忽略的問題:
- OpenAI Responses 的 reasoning 項和工具調用可能需要隨歷史繼續傳遞。
- Claude 的
thinking/redacted_thinking塊可能包含加密狀態,工具執行後回傳時要保持原始結構。 - Gemini Interactions 的 stateless 模式要求原樣保留 thought 塊和簽名;使用 stateful 模式時,部分狀態可由服務端維護。
只保存聊天窗口裏顯示的文字,無法完整恢復模型的推理歷史。典型故障是:Agent 在第三輪工具調用後突然報錯,或者開始重複已經完成的步驟。原因通常是中間某一輪丟掉了簽名塊。
2.4 Streaming 流式事件的統一
三家的流式事件類型、順序和結束信號各不相同。OpenAI Responses 可能輸出 response.output_text.delta、工具調用增量以及 response 完成事件。Claude Messages 流使用 message_start、content_block_delta、message_delta 等事件。Gemini 的原生 API 則使用自己的輸出與步驟結構。
前端如果直接解析廠商的原始事件,每接入一個模型就要改一次前端代碼。建議後端統一轉換成內部事件協議:
| 內部事件 | 含義 | 處理要點 |
|---|---|---|
text_delta |
文本增量 | 直接追加顯示 |
reasoning_summary |
思考摘要 | 可摺疊展示,計費以 usage 爲準 |
tool_call_start |
工具調用開始 | 記錄調用 ID 與函數名 |
tool_call_args |
參數分片 | 按調用 ID 或索引拼接,全部收齊後才能解析 |
tool_result |
工具執行結果 | 與調用 ID 一一對應 |
usage |
用量統計 | 區分輸入、緩存、思考、輸出 Token |
completed |
正常結束 | 必須收到明確的結束信號 |
error |
錯誤或斷流 | 區分可重試與不可重試 |
流式處理有三個高頻故障點。第一,多個工具調用的參數分片交替到達,按到達順序拼接會串號。第二,JSON 參數被切在任意字符處,收到一半就解析會拋異常。第三,連接半途斷開卻沒有收到完成事件,界面會一直停在“生成中”。轉換層需要顯式處理這三種情況。
2.5 JSON Schema 結構化輸出與多模態能力差異
三家都提供結構化輸出能力,但支持的 JSON Schema 特性、嚴格模式以及與工具調用的組合方式存在差異。Claude 官方區分了兩種機制:JSON outputs 約束最終回答的結構,Strict tool use 約束工具調用參數的結構。部分模型使用嚴格格式時,還會產生額外的 Schema 編譯或緩存開銷。
工程上的建議是:應用維護一份自己的標準 JSON Schema,在能力註冊表裏記錄每個模型支持哪些 Schema 特性。對於不支持的特性,由適配器做降級轉換。無論模型聲稱多嚴格,應用側都要再做一次校驗,校驗失敗時進入可控的重試或報錯流程。
多模態同理。“支持圖片輸入”只說明了能力類別,具體還要比較以下幾點:可接受的文件類型、大小和圖片數量,視頻與音頻能力,文件上傳方式,長上下文上限與實際可用範圍,最大輸出 Token,以及工具調用能否與多模態輸入組合使用。Claude 兼容層不支持 audio、file 輸入,就是一個需要寫進註冊表的具體限制。
2.6 緩存、計費與錯誤處理的跨模型差異
三家的提示詞緩存機制差別明顯:
- OpenAI:GPT-5.6 及後續模型支持隱式緩存和顯式緩存斷點,TTL 有 30 分鐘和 12 小時兩種。
- Claude:通過
cache_control指定自動或顯式緩存,支持 5 分鐘與 1 小時兩種模式;該能力在其 OpenAI 兼容層中不受支持。 - Gemini:新模型提供自動隱式緩存,部分 API 和模型支持顯式創建緩存對象。
模型切換後,原廠商的緩存通常無法複用。會話中途從 Claude 切到 Gemini,第一輪請求會按完整輸入計費。成本預估如果默認“緩存一直命中”,切換策略越頻繁,賬單偏差就越大。
各家標準單價也有明顯差距。截至 2026-11-13 的官方標準價格如下(USD / 百萬 Token):
| 模型 | 輸入 | 輸出 | 備註 |
|---|---|---|---|
| GPT-6 Astra | $10 | $50 | 工具調用需使用 Responses API |
| GPT-6.1 Sol | $1 | $5 | 工具調用需使用 Responses API |
| Claude Sonnet 5.5 | $2 | $10 | — |
| Gemini 3.8 Flash | $0.75 | $3.75 | 促銷價至 2026-12-31;2027-01-01 起計劃調整爲 $1.50 / $7.50 |
這張表用來說明計費差異,各模型的能力和使用條件不同,價格高低不能直接換算成性能比較。表中也沒有包含緩存寫入、工具調用、服務檔位和第三方加價等費用。
💰 成本覈算建議:多模型應用的賬單需要按“普通輸入、緩存寫入、緩存命中、思考與輸出、工具費用、長上下文附加”分項記錄。通過 API易 apiyi.com 統一調用多個模型時,可以在同一處查看各模型用量,便於把路由策略和實際成本對應起來。
錯誤處理方面,三家的請求速率、Token 速率、配額、超時和錯誤格式都不同。應用應建立統一的錯誤分類:鑑權失敗、模型不支持、參數不合法、請求過大或超出上下文、429 限流、服務端錯誤、網絡斷線、響應流中斷、工具調用失敗。
模型回退還要考慮任務是否有副作用。主模型在工具執行之後才超時,系統自動切換到備用模型重跑整個任務,付款、發郵件、改文件這類操作就可能執行兩次。解決方法是給有副作用的工具加冪等鍵,回退時只從“尚未執行的步驟”繼續。
3 多模型 API 兼容架構應該怎樣設計

推薦的六層結構如下:
- 業務界面:用戶提問、上傳材料、選擇模型和任務。
- 統一請求格式:用統一結構表示消息歷史、附件、工具列表、結構化輸出要求、推理強度和任務 ID。
- 模型路由:根據價格、能力、延遲、可用性和業務規則選擇 GPT、Claude 或 Gemini。
- Provider Adapter:把標準請求轉成各家原生格式,再把返回結果映射回內部格式。
- 工具執行與狀態管理:維護調用 ID、執行記錄、對話上下文、廠商推理狀態、緩存和失敗恢復。
- 日誌與成本覈算:記錄每次請求的模型、Token、實際費用、延遲、緩存、錯誤和工具調用。
3.1 建立統一消息及工具格式
統一格式的核心原則是把歷史分成兩層存儲。第一層是可通用的標準歷史,包括用戶消息、模型最終回答、工具請求和工具結果,任何廠商都能讀懂。第二層是廠商專屬狀態,例如 reasoning 項、thinking 簽名、thought 塊,按廠商隔離存放,只在請求同一家時原樣帶回。
from dataclasses import dataclass, field
from typing import Any, Literal
@dataclass
class ToolCall:
call_id: str # 統一調用 ID,適配器負責與廠商 ID 互相映射
name: str
arguments: dict[str, Any]
result: Any = None
idempotency_key: str = "" # 有副作用的工具必須設置
@dataclass
class Message:
role: Literal["system", "developer", "user", "assistant", "tool"]
content: list[dict] # 文本、圖片等多模態塊
tool_calls: list[ToolCall] = field(default_factory=list)
# 廠商專屬狀態:鍵爲廠商名,值爲原樣保存的簽名 / reasoning 塊
vendor_state: dict[str, Any] = field(default_factory=dict)
切換模型時,適配器讀取標準字段生成新請求。vendor_state 中屬於其他廠商的部分不發送,屬於目標廠商的部分原樣回傳。
3.2 通過 Provider Adapter 適配原生 API
每個適配器承擔三項職責:
- 輸入轉換:角色映射(例如把 system 移到 Claude 的獨立字段)、工具定義轉換、Schema 降級、推理檔位映射。
- 輸出轉換:把原生響應和流式事件轉成第 2.4 節的內部事件,把工具調用 ID 映射成統一 ID。
- 狀態處理:提取並保存簽名、reasoning 項等廠商狀態,決定使用服務端延續(
previous_response_id、previous_interaction_id)還是完整回傳歷史。
普通問答可以走 OpenAI 兼容格式的公共適配器。需要嚴格工具參數、緩存控制、加密思考狀態的場景,再分別實現原生適配器。這樣既保留了統一入口的便利,又讓高級能力有明確的落點。
3.3 用能力註冊表決定可用功能
能力註冊表以“模型 + 接入端點”爲單位記錄實際支持情況,同一個模型走原生 API 和走兼容層,可能對應兩條記錄。下面是一個結構示例,具體取值必須以官方文檔和你自己的測試結果爲準:
gpt-6.1-sol@responses:
tools: true
tool_api: responses # 工具調用要求使用 Responses API
reasoning_effort: [low, medium, high] # 不接受 none
vendor_state: reasoning_items
claude-sonnet@openai-compat:
tools: true
strict_tools: false # 兼容層忽略 strict
prompt_caching: false
file_input: false
merges_system_developer: true
gemini-flash@interactions:
tools: true
builtin_tools: [google_search, url_context, code_execution]
vendor_state: thought_signatures
路由層在選模型前查詢註冊表。請求帶了文件,就排除 file_input: false 的條目;需要嚴格工具參數,就只選擇 strict_tools: true 的條目。產品界面也可以據此隱藏當前模型不支持的選項,減少用戶觸發報錯。
4 多模型 API 兼容上線前的測試與觀測
4.1 從簡單問答到多輪工具鏈的六項兼容測試
按複雜度遞增,依次完成以下六項測試:
- 普通問答:同一段提示詞發給三個模型,檢查回答內容和 Token 統計是否正常。
- 流式輸出:確認輸出持續到達,並且收到正確的結束信號。
- 工具調用:模型調用天氣查詢或數據查詢工具,應用執行後回傳結果。
- 多工具循環:連續兩輪以上調用工具,確認歷史記錄和調用 ID 完整。
- 結構化 JSON:按同一份 Schema 輸出,並用應用側校驗器驗證結構。
- 模型切換:同一業務會話在 GPT、Claude、Gemini 之間切換,確認上下文、工具記錄和最終回答都正常。
第 4、6 項最能暴露推理狀態的問題,建議放進持續集成流程。每當升級模型版本或更換接入端點,都重新跑一遍。
4.2 建立統一的成本及穩定性觀測
每次請求至少記錄以下字段:模型與端點、請求成功率、異常類型(按第 2.6 節的分類)、首字延遲與總任務耗時、分項 Token(輸入、緩存寫入、緩存命中、思考、輸出)、工具調用次數與失敗次數、重試與回退次數。
評估模型時要看完整任務的總耗時和總成本,單次請求的數據參考價值有限。一個單價便宜的模型如果工具參數出錯率高,需要多輪重試,整體成本可能反而更高。
5 統一 API 網關在多模型 API 兼容中的作用
5.1 接入與維護成本
同時使用三家模型,意味着三套賬號、三套密鑰、三套計費和三套 SDK 配置。統一 API 網關把這些工作收斂到一個入口:集中管理模型接入和憑據,減少各服務商的配置維護,支持在配置層選擇和切換模型,並統一觀察用量與成本。對於需要頻繁對比模型效果的團隊,試用新模型的門檻也隨之降低。
5.2 API易 的定位:統一入口與原生能力適配的分工
API易 是 AI 大模型 API 聚合平臺,用一個 API Key 即可通過 OpenAI 兼容接口調用 OpenAI、Claude、Gemini 等主流模型,按量計費。它適合承擔架構中的“統一調用入口”這一層:普通問答、流式輸出、模型對比和多模型路由都可以直接接入。
統一調用入口與廠商原生能力完全一致,是兩項不同的技術要求。接入具體模型時,仍需在能力註冊表中逐項覈實工具調用、思考狀態、多模態、緩存和結構化輸出的支持範圍。依賴 Responses API、cache_control、加密簽名等原生能力的鏈路,要確認對應端點確實可用後再上線,或者爲其保留專門的原生適配器。
多模型 API 兼容快速上手
極簡示例:同一提示詞對比三個模型
以下代碼用同一個 OpenAI SDK 客戶端依次調用三個模型,對應第 4.1 節的第 1 項測試。
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.apiyi.com/v1" # API易 統一接口
)
# 模型 ID 以平臺模型列表爲準
MODELS = ["你的GPT模型ID", "你的Claude模型ID", "你的Gemini模型ID"]
for model in MODELS:
resp = client.chat.completions.create(
model=model,
messages=[{"role": "user", "content": "用一句話解釋什麼是冪等"}],
)
print(model, "→", resp.choices[0].message.content)
print("usage:", resp.usage)
查看完整實現:統一流式事件 + 能力註冊表 + 工具校驗
import json
import openai
from openai import OpenAI
from jsonschema import validate, ValidationError
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.apiyi.com/v1" # API易 統一接口
)
# 能力註冊表:取值僅爲結構示例,請按官方文檔與實測結果維護
CAPABILITIES = {
"gpt": {"model": "你的GPT模型ID", "tools_via": "responses"}, # 工具調用需走 Responses 適配器
"claude": {"model": "你的Claude模型ID", "tools_via": "chat"},
"gemini": {"model": "你的Gemini模型ID", "tools_via": "chat"},
}
def classify_error(e: Exception) -> str:
"""統一錯誤分類,決定是否可重試"""
if isinstance(e, openai.AuthenticationError):
return "auth_failed"
if isinstance(e, openai.NotFoundError):
return "model_not_supported"
if isinstance(e, openai.RateLimitError):
return "rate_limited" # 可退避重試
if isinstance(e, openai.BadRequestError):
return "invalid_request" # 參數錯誤或超出上下文,不應盲目重試
if isinstance(e, openai.APIConnectionError):
return "network_error"
if isinstance(e, openai.InternalServerError):
return "server_error"
return "unknown"
def stream_chat(provider: str, messages: list, tools: list | None = None):
"""把 OpenAI 兼容格式的流轉換爲內部統一事件"""
cap = CAPABILITIES[provider]
if tools and cap["tools_via"] != "chat":
raise NotImplementedError(f"{provider} 的工具調用請交給原生適配器處理")
kwargs = {
"model": cap["model"],
"messages": messages,
"stream": True,
"stream_options": {"include_usage": True},
}
if tools:
kwargs["tools"] = tools
calls: dict[int, dict] = {} # 按 index 拼接並行工具調用的參數分片
finished = False
try:
for chunk in client.chat.completions.create(**kwargs):
if not chunk.choices:
if chunk.usage:
yield {"type": "usage", "data": chunk.usage.model_dump()}
continue
choice = chunk.choices[0]
delta = choice.delta
if delta.content:
yield {"type": "text_delta", "data": delta.content}
for tc in delta.tool_calls or []:
slot = calls.setdefault(tc.index, {"id": None, "name": "", "args": ""})
if tc.id:
slot["id"] = tc.id
if tc.function and tc.function.name:
slot["name"] = tc.function.name
yield {"type": "tool_call_start", "data": {"id": slot["id"], "name": slot["name"]}}
if tc.function and tc.function.arguments:
slot["args"] += tc.function.arguments
yield {"type": "tool_call_args", "data": {"index": tc.index}}
if choice.finish_reason:
finished = True
yield {"type": "completed", "data": {
"finish_reason": choice.finish_reason,
"tool_calls": list(calls.values()),
}}
except Exception as e:
yield {"type": "error", "data": classify_error(e)}
return
if not finished:
yield {"type": "error", "data": "stream_interrupted"} # 半途斷流
EXECUTED_KEYS: set[str] = set() # 生產環境請換成持久化存儲
def run_tool(call: dict, schema: dict, func, idempotency_key: str | None = None):
"""先校驗參數,再冪等執行"""
try:
args = json.loads(call["args"]) # 只在分片收齊後解析
validate(instance=args, schema=schema)
except (json.JSONDecodeError, ValidationError) as e:
return {"error": f"invalid_arguments: {e}"}
if idempotency_key:
if idempotency_key in EXECUTED_KEYS:
return {"skipped": "already_executed"}
EXECUTED_KEYS.add(idempotency_key)
return func(**args)
# 使用示例
for event in stream_chat("claude", [{"role": "user", "content": "介紹一下流式輸出"}]):
print(event)
🚀 快速開始:通過 API易 apiyi.com 註冊即可獲取免費測試額度,用上面的代碼在同一個 Key 下完成第 4.1 節的前兩項測試。工具調用和多輪推理相關測試,請結合能力註冊表逐個模型驗證。
常見問題 FAQ
Q1:多模型 API 兼容問題主要指什麼?
指同一個應用在 GPT、Claude、Gemini 之間切換時,因原生 API 結構不同而需要處理的差異。主要包括 6 類:消息角色、工具調用、推理狀態、流式事件、結構化輸出與多模態、緩存計費與錯誤處理。
Q2:用 OpenAI 兼容接口調用 Claude 和 Gemini,還需要適配層嗎?
普通聊天可以直接使用兼容接口。涉及嚴格工具參數、Prompt Caching、文件輸入、加密思考狀態時,就需要適配層。以 Claude 官方兼容層爲例,它會忽略 `strict`,也不支持緩存和 audio/file 輸入。這些差異應寫進能力註冊表。
Q3:Gemini 新項目應該用 Interactions API 還是 generateContent?
Interactions API 於 2026 年 6 月進入 GA,Google 推薦新項目優先採用。它支持服務端會話狀態、`previous_interaction_id` 和 steps 結構。`generateContent` 仍受支持,存量項目可以按計劃遷移。
Q4:會話中途切換模型,歷史記錄要怎麼處理?
用戶消息、最終回答、工具請求和工具結果存爲標準歷史,切換後由目標適配器重新組裝。簽名、reasoning 項等廠商專屬狀態單獨保存,只在請求同一廠商時原樣回傳。另外,切換後原廠商的緩存通常無法複用,要預留首輪的完整輸入成本。
Q5:如何快速驗證三個模型在我的業務裏的兼容性?
建議按以下步驟操作:
1. 訪問 API易 apiyi.com 註冊賬號,獲取 API Key 和免費測試額度。
2. 使用本文代碼,將 base_url 設爲 API易 接口地址,填入三個模型 ID。
3. 按第 4.1 節的六項測試逐級執行,並記錄成功率、異常類型、成本和總耗時。
Q6:設置模型自動回退時要注意什麼?
先判斷任務是否有副作用。付款、發郵件、改文件等工具必須帶冪等鍵,回退時從未完成的步驟繼續,避免整個任務重跑。限流和服務端錯誤適合退避重試,參數錯誤和超出上下文需要修正請求後再發送。
Q7:多模型路由時怎樣控制成本?
按分項 Token 記錄費用,以完整任務的總成本做比較。三家單價差距較大,例如 GPT-6 Astra 的輸出價格爲每百萬 Token $50,Gemini 3.8 Flash 當前促銷價爲 $3.75。在 API易 apiyi.com 統一查看各模型用量,可以更快發現高成本鏈路,再據此調整路由規則。
Q8:統一 API 網關有哪些侷限?
網關統一的是調用入口、密鑰和計費。廠商原生高級能力(如 Responses API 專屬工具調用、`cache_control`、加密簽名回傳)是否可用,取決於具體端點的支持情況,需要逐項實測。依賴這些能力的鏈路,應保留原生適配器作爲補充。
多模型 API 兼容核心要點 Key Takeaways
- 換模型 ≠ 換 ID:普通問答可以直接遷移,Agent 鏈路需要處理 6 類差異。
- 兼容層有邊界:Claude 兼容層忽略
strict,不支持緩存和文件輸入。 - 簽名必須原樣保存:thinking / thought 簽名丟失是多輪工具鏈報錯的常見原因。
- 流式事件統一化:後端輸出 8 種內部事件,前端只對接一套協議。
- 能力註冊表驅動路由:以“模型 + 端點”爲單位記錄真實支持的功能。
- 回退要冪等:有副作用的工具加冪等鍵,防止重複執行。
- 先測再上線:用 API易 apiyi.com 的免費額度跑通六項兼容測試。
總結
一個應用同時接入 GPT、Claude 和 Gemini,關鍵在於把差異集中到少數幾個組件中管理:
- 統一消息與工具格式:標準歷史與廠商專屬狀態分層存儲,切換模型時上下文不丟失。
- Provider Adapter:負責輸入轉換、輸出轉換和狀態處理,原生高級能力在這裏落地。
- 能力註冊表:如實記錄每個模型、每個端點的工具、推理、多模態、Schema 和緩存支持情況,由它決定路由和界面選項。
在此基礎上,用六項兼容測試和分項成本觀測守住上線質量。普通調用和模型對比階段,推薦通過 API易 apiyi.com 用一個 Key 快速完成多模型驗證,再根據測試結果決定哪些鏈路需要原生適配。
📚 參考資料
- OpenAI Function Calling:工具調用、
call_id與function_call_output - 鏈接:
developers.openai.com/api/docs/guides/function-calling -
說明: Responses API 工具調用協議的權威說明
-
OpenAI 最新模型遷移指南:GPT-6 系列推理參數與接口要求
- 鏈接:
developers.openai.com/api/docs/guides/latest-model -
說明:
reasoning.effort取值限制與 Responses API 要求 -
OpenAI Prompt Caching:緩存斷點與 TTL
- 鏈接:
developers.openai.com/api/docs/guides/prompt-caching -
說明: 隱式與顯式緩存機制
-
Claude OpenAI SDK 兼容:兼容層支持範圍與限制
- 鏈接:
platform.claude.com/docs/en/cli-sdks-libraries/libraries/openai-sdk -
說明:
strict、緩存、文件輸入、system 合併等差異 -
Claude Extended Thinking:Adaptive Thinking 與思考簽名
- 鏈接:
platform.claude.com/docs/en/build-with-claude/extended-thinking -
說明: 多輪工具調用中 thinking 塊的回傳規則
-
Claude 結構化輸出與緩存:JSON outputs、Strict tool use、
cache_control - 鏈接:
platform.claude.com/docs/en/build-with-claude/structured-outputs - 鏈接:
platform.claude.com/docs/en/build-with-claude/prompt-caching -
說明: 結構化約束與緩存模式
-
Gemini Interactions API 與 OpenAI 兼容:新接口與兼容入口
- 鏈接:
ai.google.dev/gemini-api/docs/interactions-overview - 鏈接:
ai.google.dev/gemini-api/docs/openai -
說明: steps 結構、會話狀態與兼容參數映射
-
Gemini 思考簽名、工具調用與緩存
- 鏈接:
ai.google.dev/gemini-api/docs/thought-signatures - 鏈接:
ai.google.dev/gemini-api/docs/function-calling - 鏈接:
ai.google.dev/gemini-api/docs/caching -
說明: stateless 模式簽名保留、工具協議與顯式緩存
-
三家官方價格頁
- 鏈接:
developers.openai.com/api/docs/pricing - 鏈接:
platform.claude.com/docs/en/models/sonnet-5-5/overview - 鏈接:
ai.google.dev/gemini-api/docs/pricing - 說明: 本文價格表的數據來源,覈對日期 2026-11-13
作者:API易 技術團隊
技術交流:歡迎在 API易 網站首頁聯繫我們,更多資料可訪問 docs.apiyi.com 文檔中心