一個應用同時接入 GPT、Claude 和 Gemini:模型切換需解決的 6 類兼容問題

作者注:多模型應用應通過統一消息格式、廠商適配層和能力註冊表,處理工具調用、推理狀態、流式輸出、結構化數據與緩存差異。

GPT、Claude 和 Gemini 都能完成普通文本調用,Claude 和 Gemini 也提供官方的 OpenAI SDK 兼容入口。生產級應用在切換模型時,需要解決 6 類兼容問題:消息角色與系統指令、工具調用協議、推理參數與思考狀態、流式事件、結構化輸出與多模態、緩存計費與錯誤處理。只替換 Model ID 能跑通簡單問答,多輪工具調用、斷流恢復和成本覈算則需要單獨處理。比較穩妥的工程方案是“統一業務接口 + 廠商適配層(Provider Adapter)+ 模型能力註冊表”。這樣,模型切換可以作爲一項可維護的產品功能來管理。

下文先對照三家原生 API 的結構差異,並說明 OpenAI 兼容接口能覆蓋哪些場景。隨後逐一拆解 6 類兼容問題會引發哪些真實故障,再給出六層接入架構和可運行的統一調用代碼。最後列出上線前的六項兼容性測試,並說明統一 API 網關與原生能力適配之間如何分工。

multi-model-gpt-claude-gemini-compatibility-guide-zh-hant-image-0

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 模型切換最容易遇到的六類兼容問題

multi-model-gpt-claude-gemini-compatibility-guide-zh-hant-image-1

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 兼容架構應該怎樣設計

multi-model-gpt-claude-gemini-compatibility-guide-zh-hant-image-2

推薦的六層結構如下:

  1. 業務界面:用戶提問、上傳材料、選擇模型和任務。
  2. 統一請求格式:用統一結構表示消息歷史、附件、工具列表、結構化輸出要求、推理強度和任務 ID。
  3. 模型路由:根據價格、能力、延遲、可用性和業務規則選擇 GPT、Claude 或 Gemini。
  4. Provider Adapter:把標準請求轉成各家原生格式,再把返回結果映射回內部格式。
  5. 工具執行與狀態管理:維護調用 ID、執行記錄、對話上下文、廠商推理狀態、緩存和失敗恢復。
  6. 日誌與成本覈算:記錄每次請求的模型、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 從簡單問答到多輪工具鏈的六項兼容測試

按複雜度遞增,依次完成以下六項測試:

  1. 普通問答:同一段提示詞發給三個模型,檢查回答內容和 Token 統計是否正常。
  2. 流式輸出:確認輸出持續到達,並且收到正確的結束信號。
  3. 工具調用:模型調用天氣查詢或數據查詢工具,應用執行後回傳結果。
  4. 多工具循環:連續兩輪以上調用工具,確認歷史記錄和調用 ID 完整。
  5. 結構化 JSON:按同一份 Schema 輸出,並用應用側校驗器驗證結構。
  6. 模型切換:同一業務會話在 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,關鍵在於把差異集中到少數幾個組件中管理:

  1. 統一消息與工具格式:標準歷史與廠商專屬狀態分層存儲,切換模型時上下文不丟失。
  2. Provider Adapter:負責輸入轉換、輸出轉換和狀態處理,原生高級能力在這裏落地。
  3. 能力註冊表:如實記錄每個模型、每個端點的工具、推理、多模態、Schema 和緩存支持情況,由它決定路由和界面選項。

在此基礎上,用六項兼容測試和分項成本觀測守住上線質量。普通調用和模型對比階段,推薦通過 API易 apiyi.com 用一個 Key 快速完成多模型驗證,再根據測試結果決定哪些鏈路需要原生適配。


📚 參考資料

  1. OpenAI Function Calling:工具調用、call_id 與 function_call_output
  2. 鏈接: developers.openai.com/api/docs/guides/function-calling
  3. 說明: Responses API 工具調用協議的權威說明

  4. OpenAI 最新模型遷移指南:GPT-6 系列推理參數與接口要求

  5. 鏈接: developers.openai.com/api/docs/guides/latest-model
  6. 說明: reasoning.effort 取值限制與 Responses API 要求

  7. OpenAI Prompt Caching:緩存斷點與 TTL

  8. 鏈接: developers.openai.com/api/docs/guides/prompt-caching
  9. 說明: 隱式與顯式緩存機制

  10. Claude OpenAI SDK 兼容:兼容層支持範圍與限制

  11. 鏈接: platform.claude.com/docs/en/cli-sdks-libraries/libraries/openai-sdk
  12. 說明: strict、緩存、文件輸入、system 合併等差異

  13. Claude Extended Thinking:Adaptive Thinking 與思考簽名

  14. 鏈接: platform.claude.com/docs/en/build-with-claude/extended-thinking
  15. 說明: 多輪工具調用中 thinking 塊的回傳規則

  16. Claude 結構化輸出與緩存:JSON outputs、Strict tool use、cache_control

  17. 鏈接: platform.claude.com/docs/en/build-with-claude/structured-outputs
  18. 鏈接: platform.claude.com/docs/en/build-with-claude/prompt-caching
  19. 說明: 結構化約束與緩存模式

  20. Gemini Interactions API 與 OpenAI 兼容:新接口與兼容入口

  21. 鏈接: ai.google.dev/gemini-api/docs/interactions-overview
  22. 鏈接: ai.google.dev/gemini-api/docs/openai
  23. 說明: steps 結構、會話狀態與兼容參數映射

  24. Gemini 思考簽名、工具調用與緩存

  25. 鏈接: ai.google.dev/gemini-api/docs/thought-signatures
  26. 鏈接: ai.google.dev/gemini-api/docs/function-calling
  27. 鏈接: ai.google.dev/gemini-api/docs/caching
  28. 說明: stateless 模式簽名保留、工具協議與顯式緩存

  29. 三家官方價格頁

  30. 鏈接: developers.openai.com/api/docs/pricing
  31. 鏈接: platform.claude.com/docs/en/models/sonnet-5-5/overview
  32. 鏈接: ai.google.dev/gemini-api/docs/pricing
  33. 說明: 本文價格表的數據來源,覈對日期 2026-11-13

作者:API易 技術團隊
技術交流:歡迎在 API易 網站首頁聯繫我們,更多資料可訪問 docs.apiyi.com 文檔中心

發佈留言