Chat Completions → Responses

Chat Completions 使用 messages 和 choices 組織對話；Responses 使用 input、Typed Items 和 output 表達輸入、工具呼叫與結果。移轉時不僅要更換端點，還要調整輸入結構、回應解析、工具循環和串流狀態機。

是否需要移轉

適合移轉到 Responses 的情況：

• 新專案希望使用統一的 Typed Input 和 Output Items；
• 需要 previous_response_id 等多輪狀態能力；
• 需要 Responses 已支援的內建工具；
• 應用程式願意按照 Item 類型處理文字、工具呼叫和其他輸出。

可以繼續使用 Chat Completions 的情況：

• 現有應用程式穩定依賴 messages、choices 和 Chat Delta；
• 目標模型或所需工具只支援 Chat Completions；
• 目前沒有足夠迴歸測試覆蓋工具、多輪和 Streaming；
• 移轉收益不足以覆蓋回應解析和狀態管理的改造成本。

核心變化

最小請求 Before / After

{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "system",
      "content": "回答要簡潔、準確。"
    },
    {
      "role": "user",
      "content": "請用一句話介紹 AGTCloud。"
    }
  ]
}

使用 OpenAI SDK 時，Client 的 Base URL 仍為 https://api.agtcloud.cn/v1。方法從 client.chat.completions.create(...) 改為 client.responses.create(...)。完整 Python 和 TypeScript 初始化方式請參閱 OpenAI SDK。

移轉回應讀取

Chat Completions 通常從第一條 Choice 讀取助手訊息：

choices[0].message.content

Responses 傳回有序的 output[]。其中可能同時包含訊息、函式呼叫、搜尋呼叫或其他 Item。SDK 的 output_text 可以用於讀取彙整文字，但需要處理工具或其他輸出時，應遍歷完整 output。

response.output_text
response.output[]

移轉多輪狀態

使用 previous_response_id 時，上一輪 instructions 不會自動繼承。每一輪仍需要根據應用程式需要重新設定指令。

移轉後不要同時完整重播同一段歷史並再次透過 previous_response_id 引用它，否則可能造成重複上下文。

移轉 Function Calling

工具定義

Chat Completions 將函式定義放在 tools[].function 中：

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "查詢城市天氣",
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string" }
      },
      "required": ["city"]
    }
  }
}

Responses 將函式資訊直接放在 Function Tool 物件中：

{
  "type": "function",
  "name": "get_weather",
  "description": "查詢城市天氣",
  "parameters": {
    "type": "object",
    "properties": {
      "city": { "type": "string" }
    },
    "required": ["city"]
  }
}

結果回傳

• Chat：從 assistant.tool_calls[] 讀取呼叫，並追加帶 tool_call_id 的 Tool Message。
• Responses：從 output[] 讀取 function_call，再傳送 function_call_output，其中 call_id 必須與原呼叫一致。

無論使用哪種協議，函式都由你的應用程式執行。不要直接執行未經驗證的參數，也不要把工具異常偽裝成正常結果。

移轉 Streaming

Chat Completions 透過每個 Chunk 的 choices[].delta 傳回增量，通常以 [DONE] 結束。

Responses 使用具名事件，例如：

• response.created；
• response.output_item.added；
• response.content_part.added；
• response.output_text.delta；
• response.output_text.done；
• response.completed。

移轉時應將原來的“只串接文字”邏輯改成事件分派器：先按事件類型處理，再根據 output_index、content_index、item_id 等識別碼更新對應狀態。

移轉 Structured Outputs

Chat Completions 將輸出格式設定放在 response_format；Responses 將對應設定放在 text.format。移轉時需要同步修改：

1. 請求欄位位置；
2. JSON Schema 封裝結構；
3. SDK 的解析輔助方法；
4. 拒絕、不完整回應和 Schema 驗證失敗的處理。

詳細欄位請分別檢視 Chat Completions 和 OpenAI Responses。

移轉 Web Search

兩種協議的搜尋入口不同：

• Chat Completions 使用 web_search_options，並要求選擇支援搜尋的模型；
• Responses 在 tools 中啟用支援的 Web Search Tool，並可能傳回搜尋呼叫 Item 和引用。

域名過濾、來源清單、使用者位置和即時互聯網存取等設定取決於所選協議與模型。完整範例請參閱 OpenAI Web Search。

Usage、錯誤與中斷

移轉監控與計費讀取邏輯時，至少調整：

同時保留 HTTP 狀態碼、錯誤物件和 Request ID。不要只捕獲 SDK 異常文字；應用程式記錄應能區分身分驗證失敗、模型不可見、限流、服務錯誤和連線中斷。

分階段移轉

迴歸與回退清單

• 一般文字、空輸出、拒絕、不完整和失敗狀態；
• 單工具、多工具、工具失敗和參數驗證失敗；
• 無狀態歷史重播與 previous_response_id；
• Streaming 正常完成、斷流和重複事件；
• Structured Outputs 驗證失敗；
• Usage、錯誤資訊、Request ID、逾時和限流；
• 目標模型不支援某項 Responses 能力時，能夠切回 Chat Completions。

在正式環境切換前，為 Chat 與 Responses 保留獨立設定和可控開關。確認業務指標、記錄和錯誤處理穩定後，再清理舊解析路徑。

下一步

• 使用 OpenAI SDK 設定 Python 或 TypeScript Client；
• 檢視文字與對話理解 Responses 的日常呼叫流程；
• 在 OpenAI Responses 核對完整欄位和回應；
• 遇到呼叫錯誤時檢視 錯誤與疑難排解。