OpenAI API 的應用開發涉及請求格式、回應驗證、工具結果回填與失敗恢復。Chat Completions 和 Responses 使用不同的資料結構,對話歷史、工具呼叫與串流也各有對應的處理方式。
結構化輸出處理資料格式,工具執行負責外部查詢與業務操作,串流與背景工作則涉及事件和執行狀態。應用程式在這些階段各有驗證與保存需求。
系列與主題索引
| 目前的工作 | 閱讀方式 |
|---|---|
| 建立第一個 Chat Completions 功能 | 先讀(一);再接(二)的功能實作 |
| 已經能呼叫,但回傳、用量或紀錄有問題 | 直接查(三)的回傳與診斷 |
| 要設計較複雜的結構或業務工具 | (四)資料模型;(五)業務工具 |
| 現有程式要轉向 Responses | 先完成(六)的遷移對照;再讀新系列 |
| 直接以 Responses 建立功能 | 從 Responses(一)開始;接上(二)的工具與資料驗證 |
| 串流、取消與長工作要能恢復 | Responses(三)的狀態與恢復流程 |
Chat Completions 以 messages 提供完整對話,Responses 以 input/output items 表達文字、推理與工具項目。兩種介面的接續方式和工具資料結構不同,模型可用功能也需和端點一起確認。
Chat Completions API
(一)Chat Completions API 基礎參數解析
Chat Completions 的請求由 model、messages 和生成控制參數組成,回應則包含候選訊息、停止原因與用量。
(二)結構化輸出、Tool Calling 與 Streaming
JSON Schema 約束回答格式,工具由後端執行並回填,串流與多模態則有各自的資料格式。圖片、PDF 和音訊也需配合模型能力處理。
(三)回傳物件、除錯與實務設定
回應的 finish_reason、usage 與串流 chunk 提供完成狀態及用量,請求紀錄則關聯延遲、資料保留設定與版本差異。
(四)Structured Outputs 與複雜 Schema 設計
Pydantic、巢狀及遞迴 Schema 用於描述複雜資料與動態 UI,欄位關係與業務值則由額外的驗證規則處理。
(五)Tool Calling 與業務資料整合
營業額、人流與換匯查詢透過多個業務工具整合,後端驗證授權範圍並回填結果,模型再依資料產生回答。
(六)從 Chat Completions 轉向 Responses API
Chat Completions 與 Responses 在端點、請求欄位、回應項目及對話管理上有所不同,最小遷移程式可用來對照資料結構的變化。
Responses API
技術文件查詢助理使用固定文件資料,分別處理多輪對話、查詢工具、結構化回答與長任務。各項實作也包含失敗狀態、診斷欄位與回歸測試,應用程式驗證和模型品質測試分別記錄。
Responses API 實戰(一):回應解析與對話狀態管理
Response 包含文字、工具與推理項目,回應狀態和完整 output 可用來處理空白回覆、對話接續、歷史重播及上下文成本。
Responses API 實戰(二):工具呼叫與結構化輸出的除錯
工具結果依 call_id 配對,結構化回答經 Schema 與 JSON 解析後,還需核對資料來源、權限和業務值;工具重試則受冪等規則約束。
Responses API 實戰(三):串流、背景任務與失敗恢復
串流以整輪終止狀態判斷生成結果,背景工作透過 response ID 輪詢,事件游標、Webhook 去重與工具紀錄則支援取消和失敗後的恢復。
參數與資料型別索引
| 查找項目 | 完整說明位置 |
|---|---|
| messages、角色、上下文、model 與生成控制 | 前往對應文章 |
| temperature、top_p、max_completion_tokens、stop、n、懲罰與 logit_bias | 前往對應文章 |
| response_format、JSON mode、strict schema、tools 與 tool_choice | 前往對應文章 |
| parallel_tool_calls、stream、stream_options 與工具片段累積 | 前往對應文章 |
| 圖片、PDF、audio、modalities 與 prediction | 前往對應文章 |
| store、metadata、識別欄位、service_tier 與 request log | 前往對應文章 |
| finish_reason、usage、logprobs、seed 與 system_fingerprint | 前往對應文章 |
| 舊 functions/function_call、max_tokens 與相容性差異 | 前往對應文章 |
| Pydantic、nullable、遞迴結構與 Schema 限制 | 前往對應文章 |
| 跨工具資料、授權範圍、金額與幣別驗證 | 前往對應文章 |
| messages → input、response_format → text.format、工具結果格式 | 前往對應文章 |
| output、phase、previous_response_id、conversation 與 compaction | 前往對應文章 |
| function_call_output、call_id、output_parsed 與業務驗證 | 前往對應文章 |
| typed events、背景工作、sequence_number 與 Webhook | 前往對應文章 |
範例環境與模型設定
Chat Completions 的文字與工具程式使用 GPT-6 Sol,工具流程設定 reasoning_effort=none;Responses 程式使用 GPT-6 Astra,推理程度為 low。音訊與 prediction 各使用支援該功能的模型,參數也按對應契約設定。模型可用端點與能力見官方模型指南。
Python 程式使用 OpenAI 官方 SDK,API 金鑰由執行環境提供。回應是否完成、資料是否符合 Schema,以及業務結果是否正確,是三項獨立的檢查;工具往返與錯誤恢復也須保留對應的狀態與執行紀錄。
