如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

API 部署檢查清單

掌握幾項常被忽略、卻能有效提升部署品質、速度與可靠性並降低成本的設計選擇。

目錄 預期影響
使用 Responses API 品質、成本、延遲、可靠性
依工作負載選擇模型 品質、成本、延遲
設定 reasoning.effort 品質、成本、延遲
在對話中途調整推理強度 品質、成本、延遲
設定 text.verbosity 品質、成本、延遲
設定助理的 phase 參數 品質、成本
使用 tool_search 成本、延遲
以程式呼叫工具 品質、成本、延遲
使用多智慧體平行處理工作 品質、成本、延遲
非同步呼叫工具 延遲
運用內建工具 品質
運用上下文壓縮 成本
最佳化提示詞快取 延遲、成本
使用 reasoning.encrypted_content 品質、延遲
依任務設定影像細節等級 品質、成本、延遲
傳送安全識別碼 安全性、可靠性
處理行為偏離監控事件 安全性、可靠性
因應流量激增與模型過載 可靠性
使用 background=True 任務連續性
使用 WebSocket 模式 延遲
在回合中途調整方向 品質

使用 Responses API

一律優先使用 Responses API。這是 OpenAI 的旗艦 API,也是使用最新模型行為、內建工具、有狀態工作流程和智慧體功能的最佳途徑。

依工作負載選擇模型

針對你的工作負載評估 GPT-6 系列模型。需要最強能力時,使用 gpt-6-astra。若要以低於 Astra 的成本處理複雜的程式設計和專業工作,使用 gpt-6.1-sol。若要高效率地處理可重複執行的工作,使用 gpt-6-luna。依模型在代表性任務上的表現選擇模型,避免將所有請求都送到能力最強的模型。

遷移至 GPT-6 時,請在支援的範圍內,保留目前模型在工作負載中負責的任務及實際使用的推理強度。需要搭配工具進行推理時,請使用 Responses API。GPT-6 Astra 和 GPT-6.1 Sol 必須透過 Responses 呼叫工具。GPT-6 Sol 和 GPT-6 Luna 只有在設定 reasoning_effort: "none" 時,才支援在 Chat Completions 中使用函式呼叫。推理強度不是 none 時,請移除 temperature、top_p 和 top_logprobs,並從 Chat Completions 請求中移除 logprobs。另外,請將 message.output_text.logprobs 從 Responses 的 include 陣列中移除。選擇模型或處理層級前,請確認是否符合資料駐留資格。其他相容性檢查請參閱模型遷移指南。變更提示詞或新增功能前,請先執行具代表性的評估。比較任務成功率、延遲、輸入、輸出、推理及快取寫入的 Token 數,以及每次成功完成任務的成本。

設定 reasoning.effort

使用 reasoning.effort 決定模型回答前要投入多少推理。

GPT-6 Astra、GPT-6.1 Sol、GPT-6 Sol 和 GPT-6 Luna 支援 low、medium、high、xhigh 和 max。GPT-6 Sol 和 GPT-6 Luna 也支援 none,GPT-6 Astra 和 GPT-6.1 Sol 則不支援。推理強度越低,速度越快,使用的推理 Token 也越少。提高推理強度可讓模型有更多時間規劃、除錯、整合資訊,以及在多個步驟中權衡不同選擇。

如果工作主要是擷取資訊、路由、分類或例行改寫,請使用 low。如果模型需要診斷問題、比較選項、擬定計畫或分析程式碼邏輯,請使用 medium 或 high。只有在代表性評估顯示品質提升值得付出額外延遲與成本時,才使用 xhigh 或 max。若原先使用 minimal,或原先使用 none 而要遷移至 GPT-6 Astra 或 GPT-6.1 Sol,請先使用 low 並比較結果。其他情況下,請維持目前實際使用的強度,並依品質、延遲和成本目標測試調整後的效果。

對於難度最高且以品質為優先的工作負載,也請在相同推理強度下比較 reasoning.mode: "pro" 與標準模式。推理模式和推理強度可獨立設定。Pro 模式會讓模型投入更多運算後再傳回單一最終答案,這有助於提高可靠性,但也會增加延遲和 Token 用量。

依任務調整推理強度
from openai import OpenAI

client = OpenAI()

prompt = """
Our CI job started failing after a dependency bump.

Error:
TypeError: Timeout.__init__() got an unexpected keyword argument 'connect'

Identify the likeliest root cause and the smallest safe fix.
"""

response = client.responses.create(
    model="gpt-6-astra",
    reasoning={"effort": "xhigh", "mode": "pro"},
    input=prompt,
)

print(response.output_text)

在對話中途調整推理強度

使用 GPT-6 模型的標準單一智慧體模式時,可在下一則使用者訊息之前加入 configuration_update 輸入項目,在兩次回應之間調整推理強度。請維持請求層級的 reasoning.effort 設定,讓原始提示詞前綴仍可使用快取。更新從下一次回應起生效,直到後續更新將其覆寫。設定更新無法與自動壓縮或截斷搭配使用,/responses/compact 也會拒絕包含設定更新的歷程記錄。若要壓縮歷程記錄,請加入 compaction_trigger 項目,並在壓縮後再加入一筆新的設定更新。

設定 text.verbosity

text.verbosity 是調整回答簡潔度與完整度的主要設定。產品需要快速、精簡的答案時,請調低詳細程度。需要更充分的說明、更清楚的結構或完整的背景資訊時,則請調高。降低詳細程度會減少輸出 Token,模型要生成的內容較少,因此能更快傳回結果。

在程式設計任務中,medium 和 high 通常會產生較長、較有條理且結構清楚的輸出。low 則會讓答案更精簡。

遷移時,請確認「請簡明扼要」之類的概括指示是否仍有幫助。建議使用 text.verbosity 控制預設的詳細程度,再透過提示詞指定必要內容、結構與長度。

提示詞也會影響品質、Token 用量、成本和延遲。調整詳細程度時,請一併參閱最新模型的提示詞最佳做法,包括其中針對程式設計智慧體的測試與驗證指引。

調低詳細程度以產生精簡輸出
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    text={"verbosity": "low"},
    input="""
    Summarize this incident for the next on-call engineer.
    - checkout latency spiked from 220 ms to 4.8 s
    - only us-east-1 was affected
    - rollback is complete
    - likely trigger: cache stampede after deploy
    """,
)

print(response.output_text)

設定助理的 phase 參數

phase 是對話歷程中助理訊息的標籤,讓模型知道先前的助理訊息是工作過程中的說明,還是最終答案。對於進度更新、呼叫工具前的說明及其他過程中的訊息,請使用 phase: "commentary"。對於已完成的回應,請使用 phase: "final_answer"。

舉例來說,助理可能會傳送以下訊息:

助理的進度說明訊息
{
  "role": "assistant",
  "phase": "commentary",
  "content": "I'm checking the logs and comparing them to the last successful deploy."
}

這則訊息只是在說明進度,助理尚未給出答案。稍後,助理可能會傳送以下訊息:

助理的最終答案訊息
{
  "role": "assistant",
  "phase": "final_answer",
  "content": "The deploy failed because the migration referenced a column that does not exist in production."
}

在執行時間長或頻繁使用工具的工作流程中,助理可能在完成前先向使用者顯示進度,此時這個標籤特別有用。在後續請求中將對話歷程傳回給 gpt-5.3-codex 或更新的模型時,請保留並重新傳送助理訊息上的 phase,讓模型能區分進度更新與最終結果。這有助於減少過早停止的情況,讓智慧體更有可能持續工作,直到得出最終答案。

不必在每個請求中載入完整的工具目錄。請使用工具搜尋,加入 {"type": "tool_search"},並以 defer_loading: true 標記載入成本較高的工具定義。這樣模型就能在執行時只載入所需的工具。請求開始時,模型只會看到搜尋工具的名稱和說明。如果模型判斷需要某個延後載入的工具,就會執行工具搜尋,此時才會將相應的工具定義載入上下文。載入後,模型才會呼叫這些工具。這樣可以節省 Token 並維持快取效能。

工具搜尋有兩種模式:

  • 託管式工具搜尋較為簡單。如果你已經知道哪些工具可能供這次請求使用,請選用此模式。
  • 由用戶端執行工具搜尋適用於必須由應用程式決定哪些工具可用的情況,例如依使用者所屬的租戶、專案、權限或內部登錄資料決定。

除非應用程式確實需要自行控制工具探索流程,否則請先使用託管式工具搜尋。

依使用者意圖將工具分組,並盡可能使用命名空間或 MCP 伺服器。比起從一長串未分組的函式中挑選,模型更容易從少數幾個界線清楚的群組中做選擇。為了讓 Token 使用效率和模型效能達到最佳表現,建議每個命名空間的函式數量控制在約 10 個以下。

命名空間的說明應簡短,且能清楚區別各個群組。將詳細指示放在延後載入的工具定義中,避免把所有工具放進同一個龐大的命名空間。

搭配延後載入的工具使用託管式工具搜尋
from openai import OpenAI

client = OpenAI()

billing_namespace = {
    "type": "namespace",
    "name": "billing",
    "description": "Billing tools for invoices, payments, taxes, and credits.",
    "tools": [
        {
            "type": "function",
            "name": "lookup_invoice",
            "description": "Look up invoice state, taxes, credits, and payment attempts.",
            "parameters": {
                "type": "object",
                "properties": {
                    "invoice_id": {"type": "string"},
                },
                "required": ["invoice_id"],
                "additionalProperties": False,
            },
            "strict": True,
            "defer_loading": True,
        }
    ],
}

crm_namespace = {
    "type": "namespace",
    "name": "crm",
    "description": "CRM tools for account ownership, plans, health, and payment history.",
    "tools": [
        {
            "type": "function",
            "name": "get_account",
            "description": "Fetch account owner, plan, health, and payment history.",
            "parameters": {
                "type": "object",
                "properties": {
                    "account_id": {"type": "string"},
                },
                "required": ["account_id"],
                "additionalProperties": False,
            },
            "strict": True,
            "defer_loading": True,
        }
    ],
}

response = client.responses.create(
    model="gpt-6-astra",
    input=(
        "Find the right billing tool and explain why invoice INV-1043 still "
        "shows overdue after a payment yesterday."
    ),
    tools=[billing_namespace, crm_namespace, {"type": "tool_search"}],
)

print(response.output)

以程式呼叫工具

以程式呼叫工具可讓支援此功能的模型撰寫 JavaScript,在託管的執行環境中呼叫符合條件的工具,並精簡中間結果。這項功能適合範圍明確的工作階段,例如先用程式碼篩選、聯結、排序、去除重複項目、合併或檢查大量工具結果,再將較精簡的結構化結果傳回模型。

加入 programmatic_tool_calling 工具,並為每個符合條件的工具個別啟用此功能。只允許程式呼叫的工具請設定 allowed_callers: ["programmatic"]。若模型也可以直接呼叫該工具,請設定 allowed_callers: ["direct", "programmatic"]。如果每次呼叫的結果都可能改變模型的下一個決定、動作需要核准,或最終答案必須保留引用來源或工具原生產出物,請維持直接呼叫。記錄工具傳回的欄位及發生錯誤時的行為,讓模型無須先檢視結果就能撰寫正確的程式。

工具呼叫迴圈必須能處理 program 和 program_output 項目,以及程式發出的 function_call 項目和相應的 function_call_output 項目。保留每個 call_id,並將函式呼叫的 caller 複製到對應的輸出中,讓服務能繼續執行正確的程式。

請同時測試 program_output 和助理的最終訊息。即使程式結果正確,最終答案仍可能不完整。以同一個工作流程直接呼叫工具,並比較兩種方式的任務成功率、必要佐證、Token 總數、延遲及成本。

使用多智慧體平行處理工作

多智慧體功能可讓 GPT-6 等支援此功能的模型,將彼此獨立的工作交給子代理程式,再整合各自的結果。如果能將研究、分析或實作拆成具體且範圍明確的任務,讓各任務使用獨立的上下文並平行執行,就適合使用此功能。

在請求中將 multi_agent.enabled 設為 true。使用 HTTP 時,請透過 Beta 版 Responses SDK 的 client.beta.responses 發出請求,並將 responses_multi_agent=v1 傳入 betas。直接使用 HTTP 或透過 WebSocket 連線時,請傳送 OpenAI-Beta: responses_multi_agent=v1。多智慧體功能仍在 Beta 階段,項目的結構描述可能變動。

如果任務簡短、每個步驟都依賴前一步的結果,或多項工作會寫入同一個可變資源,建議使用單一智慧體。子代理程式可能增加 Token 用量,因此請先使用 max_concurrent_subagents 的預設值 3,再衡量端對端品質、延遲與成本。對於頻繁使用工具或執行時間長的多智慧體工作流程,WebSocket 模式可以降低接續執行的額外負擔。

啟用多智慧體功能前,請考量目前的限制:不支援 /responses/compact、reasoning.summary 和 max_tool_calls。伺服器會自動壓縮根智慧體及每個子代理程式的上下文。

非同步呼叫工具

使用 GPT-6 模型時,如果應用程式執行工具期間模型可以繼續工作,請在函式或自訂工具上設定 async: true。提早啟動耗時的工具呼叫,讓模型先處理其他獨立工作。應用程式仍負責執行及追蹤呼叫,然後在後續的 Responses 請求中使用原始 call_id 傳回結果。非同步執行不適用於內建工具或以程式發出的工具呼叫。在多智慧體模式下,請勿將非同步工具與平行工具呼叫搭配使用。完整流程請參閱非同步工具呼叫。

運用內建工具

內建工具是 API 原生提供的功能。你可以直接讓模型使用 Responses API 已提供的工具,省去逐一自行開發的工作。模型會自行決定何時使用這些工具。

OpenAI 持續新增原生工具。如果內建工具符合你的工作流程,請優先使用。如果現有原生工具無法滿足任務需求,再建立自訂工具。目前的內建工具和相關選項包括:

  • 網頁搜尋:在網路上搜尋最新資訊
  • 檔案搜尋:搜尋已上傳的檔案或向量儲存區
  • 程式碼解譯器:執行 Python 以分析資料、進行數學運算、繪製圖表及處理檔案
  • Shell:在託管容器或自己的執行環境中執行 Shell 指令
  • 電腦:透過螢幕截圖、點選、輸入文字和捲動來操作使用者介面
  • 圖像生成:生成或編輯影像
  • MCP/連接器:將模型連接至外部服務與工具
  • 技能:附加可重複使用的指示套件及工作流程檔案
  • 套用修補程式:以結構化方式修改程式碼

模型的表現也是優先使用內建工具的原因。內建工具符合模型後訓練的資料分布,也就是說,模型的訓練和評估都涵蓋這些工具的結構、行為及輸出。相較於新工具,使用內建工具時,OpenAI 模型更能選對工具,執行更順暢,失敗的情況也更少。

運用上下文壓縮

壓縮是一種上下文工程工具,用來決定模型在多個回合之間保留哪些資訊。對於長時間執行的智慧體,除了要考慮「會不會達到上下文上限?」,還要留意舊訊息、工具記錄、重試記錄和過時的細節可能排擠模型需要的狀態資訊。

透過壓縮,你可以控制上下文大小,同時保留後續回合所需的狀態。完成重要階段後,例如結束某個除錯階段或縮小根本原因的範圍時,可以壓縮先前的上下文視窗,再從壓縮後的輸出繼續工作。這樣一來,下一回合就能聚焦於重要狀態,無須帶入所有中間推理、失敗的指令和已不適用的推理分支,有助於維持模型的表現。

你可以透過兩種方式使用壓縮:

  • 交由伺服器處理:如果使用 previous_response_id,請啟用 context_management 並設定 compact_threshold。對話過大時,伺服器會自動壓縮對話。你只需繼續傳送最新的使用者訊息。
  • 自行處理:如果自行管理完整的輸入陣列,請呼叫 client.responses.compact()。它會傳回較小的上下文視窗。請在下一次呼叫 responses.create() 時直接使用傳回的輸出。

請勿編輯壓縮後的輸出。 這份輸出是讓模型繼續工作的機器狀態,並非供人閱讀的摘要。請原樣傳遞,再加入下一則使用者訊息。

從壓縮後的回應狀態繼續執行
from openai import OpenAI

client = OpenAI()

# Full window collected from a long debugging session:
# user messages, assistant outputs, tool calls, and tool outputs.
long_window = session_items

compacted = client.responses.compact(
    model="gpt-6-astra",
    input=long_window,
)

next_response = client.responses.create(
    model="gpt-6-astra",
    store=False,
    input=[
        *compacted.output,  # Use compact output as-is.
        {
            "type": "message",
            "role": "user",
            "content": (
                "We found the bad cache invalidation path. Write the fix plan "
                "and the verification checklist."
            ),
        },
    ],
)

print(next_response.output_text)

最佳化提示詞快取

多個請求重複使用相同的長前綴時,提示詞快取會自動降低延遲和成本。先放入固定的指示、範例和參考資料,再放入因使用者而異的動態內容。保持工具定義與順序一致,將新的對話回合附加在末尾,避免改寫先前的上下文。

GPT-5.6 開始支援明確設定提示詞快取。預設仍使用隱含快取,但 GPT-5.6 和後續系列模型也支援明確指定快取斷點,以及設定適用於整個請求的快取原則。如果固定前綴後面接著會變動的後綴,請在可重複使用的內容結束處明確加入 prompt_cache_breakpoint。只有在請求應僅使用你提供的斷點、完全不使用隱含斷點時,才將 prompt_cache_options.mode 設為 explicit。較早的模型仍只支援自動提示詞快取。

從 GPT-5.5 或更早版本遷移時,請將 prompt_cache_retention 替換為 prompt_cache_options.ttl: "30m"。變更快取設定前,請先參閱各模型的提示詞快取差異。

在 GPT-5.6 和後續系列模型上,快取寫入費率是未快取輸入 Token 費率的 1.25 倍。請記錄 cached_tokens 和 cache_write_tokens,再比較寫入量和後續的快取讀取量,以衡量淨成本並調整斷點位置。

對於共用可重複使用前綴的請求,請使用固定的 prompt_cache_key。這有助於將相關請求路由至同一個快取,並讓 GPT-5.6 之前的模型達到最佳快取命中率。對於流量較大的群組,請依照使用更多快取鍵分散流量的指引操作。

在 GPT-5.6 和更新的模型上,prompt_cache_key 是選用設定,即使不設定也能達到最佳快取命中率。你可以使用它為不同客戶、使用者或工作區分別統計快取用量,方便向各群組說明快取 Token 用量及計費方式。請為每位客戶指派不同的快取鍵,並在該客戶的相關請求中使用同一個鍵。使用不同的鍵也有助於防止跨客戶探測快取命中情形。請參閱使用快取鍵分別統計快取用量。

為客戶單獨統計快取用量
from openai import OpenAI

client = OpenAI()

instructions = """
You are the support agent for Acme.
Follow the Acme support policy and escalation rubric.
Use the same tone, safety rules, and tool plan for each ticket.
"""

response = client.responses.create(
    model="gpt-6-astra",
    prompt_cache_key="tenant-acme-support-agent",
    instructions=instructions,
    input="Summarize the current escalation for the on-call lead.",
)

print(response.output_text)

使用 reasoning.encrypted_content

GPT-6 等支援此功能的模型可以在多次呼叫之間保留推理內容。任務目標、假設和優先順序維持不變時,請使用 reasoning.context: "all_turns"。如果先前的推理已不再相關,而且可能讓模型受限於過時的做法,請使用 current_turn。如果省略 reasoning.context 或將其設為 auto,請檢查回應中的 reasoning.context 欄位,確認實際生效的模式。

只有在先前的推理項目仍可取得時,才能沿用已保留的推理內容。對於已儲存的回應,請使用 previous_response_id。如果你的零資料保留(ZDR)要求不允許儲存回應資料,可以透過加密推理內容,以無狀態方式接續工作。

回應輸出中的推理項目預設包含加密推理內容。你可以從各推理項目的 encrypted_content 屬性取得這些內容。應用程式無須解讀該值,只需原樣保留每個傳回的推理項目,並在下一回合將其傳回模型,讓模型據此繼續執行工作流程。

在無狀態回合之間傳遞加密推理內容
from openai import OpenAI

client = OpenAI()

history = [
    {
        "role": "user",
        "content": "Investigate why invoice INV-1043 has mismatched tax totals.",
    }
]

first = client.responses.create(
    model="gpt-6-astra",
    store=False,
    reasoning={"effort": "medium", "context": "current_turn"},
    input=history,
)

history.extend(item.to_dict() for item in first.output)
history.append(
    {
        "role": "user",
        "content": "Now write the customer-facing explanation in plain English.",
    }
)

second = client.responses.create(
    model="gpt-6-astra",
    store=False,
    reasoning={"effort": "medium", "context": "all_turns"},
    input=history,
)

print(second.output_text)

依任務設定影像細節等級

影像的 detail 預設為 auto,尺寸處理方式依模型而異。大型影像可能使用更多輸入 Token,並增加延遲。請查看各模型的影像尺寸處理方式一覽表,並在部署前用所選模型實測影像 Token 用量和限制。

請依任務選擇 detail。你可以調整影像尺寸,在細微的視覺特徵不重要時使用 low,或使用 high 進行標準的高傳真影像理解。如果任務涉及大型影像、密集資訊、精確座標、OCR、位置辨識或視覺檢查,且更多細節能提高品質,請在模型支援時使用 original。部署前,請測量最差情況下的影像 Token 用量和延遲。

傳送安全識別碼

如果應用程式為個別終端使用者提供服務,請隨每個請求傳送固定且能保護隱私的 safety_identifier。這有助於 OpenAI 偵測濫用行為,也讓團隊能透過一致的識別碼追查違反政策的情形,並降低單一使用者的濫用行為影響組織內其他人存取服務的可能性。

請將使用者名稱或電子郵件地址雜湊後再傳送,避免直接傳送可識別身分的資訊。對於未登入的使用者,請使用固定的工作階段 ID。

處理行為偏離監控事件

使用 GPT-6 Astra 建立智慧體工作流程時,請預先規劃如何處理行為偏離監控事件。如果請求傳回 403 且錯誤碼為 misalignment_policy_violation,請停止為該對話派送動作,並且不要自動重試遭封鎖的工作流程。也請處理串流期間發生的錯誤,並檢查可能已執行的動作。如果團隊需要接收專案警示,請訂閱 safety.alert.created。即使使用 Webhook,仍須處理請求錯誤。請參閱指南,瞭解哪些 Responses 請求可能被自動停止。

因應流量激增與模型過載

決定如何復原之前,請先檢查 HTTP 狀態碼和 error.code。如果收到 429 且錯誤碼為 slow_down,表示請求速率上升過快。若有 Retry-After 標頭,請依其指示操作,降低流量後再逐步提高。如果收到 503 且錯誤碼為 server_is_overloaded,表示所請求的模型暫時過載。若有 Retry-After 標頭,請依其指示等待後再重試。如果沒有該標頭,請以指數方式延長重試間隔,加入隨機抖動,並限制重試次數。計費、支出或配額錯誤必須先處理才能重試,請勿將所有 429 錯誤都視為暫時的速率限制。請參閱速率限制及錯誤碼。

使用 background=True

對於可能耗時較長的請求,請使用 background=True。API 會啟動作業並傳回 ID,無須保持用戶端連線。應用程式可以輪詢該作業,直到作業完成、失敗或取消。這適用於大規模分析、耗時較長的工具執行,或需要追蹤狀態及重試的工作。

在背景執行回應並輪詢狀態
# Replace the illustrative IDs and URLs below with your own resource values.
from openai import OpenAI
import time

client = OpenAI()
log_bundle_file_id = "file_123"

job = client.responses.create(
    model="gpt-6-astra",
    background=True,
    store=False,
    input="Analyze this large log bundle and cluster the primary failure modes.",
    tools=[
        {
            "type": "code_interpreter",
            "container": {
                "type": "auto",
                "file_ids": [log_bundle_file_id],
            },
        }
    ],
)

while job.status in {"queued", "in_progress"}:
    time.sleep(2)
    job = client.responses.retrieve(job.id)

print(job.output_text)

你可以搭配 stream=True 接收進度事件,但等到第一個事件的時間可能比一般請求更長。

在使用者介面中,背景模式可以這樣呈現:「作業執行中,你可以在這裡查看進度。完成後,結果會顯示在這裡。」

使用 WebSocket 模式

WebSocket 模式專為長時間執行且頻繁呼叫工具的工作流程設計。保持連線開啟,每次只要傳送新的輸入項目和 previous_response_id,即可接續執行。對於包含至少 20 次工具呼叫的工作流程,我們觀察到端對端執行速度最多可提升約 40%。

運作方式:第一則訊息和一般 Responses 請求類似,包含模型、指示、工具和使用者輸入。伺服器會以串流方式傳回事件。如果模型要求呼叫工具,應用程式就執行該工具。接著,透過同一個通訊端傳送另一個 response.create 事件,附上先前的 previous_response_id 和新的項目,無須另發 HTTP 請求。這正是延遲降低的原因。使用一般 HTTP 時,每次接續執行都需要新的請求。使用 WebSocket 模式時,連線保持開啟,而且該連線最近一次回應的狀態仍在記憶體中,可供直接使用。下一回合接續該回應時,服務所需的準備工作就較少。

如果工作流程只需發出一個請求、取得一個答案,請繼續使用 HTTP。如果工作流程類似長時間執行的智慧體,請試用 WebSocket 模式。

若在同一條連線上平行進行多個對話,請為各對話使用不同的 stream_id 值,並依 stream_id 分派交錯抵達的事件。每條連線最多支援 16 個進行中的回應,同一串流上的請求則依序執行。每條連線最長可維持 60 分鐘。接續執行時,previous_response_id 的用法與 HTTP 模式相同,且各串流的最新回應會保留在該連線專用的快取中。

注意:WebSocket 模式可搭配 ZDR 使用,因為資料只會保存在記憶體中,不會寫入磁碟。

Python 範例使用 pip install "openai[realtime]>=3.8.0"。 TypeScript 範例使用 npm install openai@^7.10.0 ws。 Ruby 範例使用 gem install openai async-websocket。

使用 Go 時,請執行 go get github.com/openai/openai-go/v3@v3.98.0。 使用 Java 時,請加入 Maven 相依套件 com.openai:openai-java:4.101.0。 這些版本的 Go 和 Java SDK 原生支援 Responses WebSocket。

啟動 Responses API WebSocket 工作階段
from openai import OpenAI
from openai.types.responses import FunctionToolParam

test_log_tool: FunctionToolParam = {
    "type": "function",
    "name": "search_test_logs",
    "description": "Search test logs.",
    "parameters": {
        "type": "object",
        "properties": {"query": {"type": "string"}},
        "required": ["query"],
        "additionalProperties": False,
    },
    "strict": True,
}
code_search_tool: FunctionToolParam = {
    "type": "function",
    "name": "search_code",
    "description": "Search source code.",
    "parameters": {
        "type": "object",
        "properties": {"query": {"type": "string"}},
        "required": ["query"],
        "additionalProperties": False,
    },
    "strict": True,
}

client = OpenAI()

with client.responses.connect() as connection:
    # Use the same typed parameters as client.responses.create(...).
    connection.response.create(
        model="gpt-6-astra",
        store=False,
        input=[
            {
                "type": "message",
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": (
                            "Find the flaky test in this run, call the tools "
                            "you need, and keep going until you can explain "
                            "the root cause."
                        ),
                    }
                ],
            }
        ],
        tools=[test_log_tool, code_search_tool],
    )
    for event in connection:
        if event.type == "response.completed":
            print(event.response.output)
            break
        if event.type in {"response.failed", "response.incomplete", "error"}:
            raise RuntimeError(event.to_json())
    else:
        raise RuntimeError("Connection closed before the response finished.")

在回合中途調整方向

如果使用者可能在 GPT-6 模型執行任務期間新增需求,請透過 WebSocket 連線至 Responses API。傳送 response.steer 時,請在 previous_response_id 中填入進行中回應的 ID,並附上新的使用者輸入。繼續讀取後續執行的事件。收到 response.steer.accepted 表示更新已排入佇列。在回合中途調整方向不會變更已傳送至應用程式的輸出,也不會撤銷已開始執行的工具操作。事件流程及工具結果的處理方式請參閱在回合中途調整方向。

總結

Responses API 是打造更聰明、能力更強的 OpenAI 應用程式的基礎。透過這個 API,開發者可以從單次提示詞進一步建立能持續執行、使用工具並掌握上下文的工作流程,依任務的複雜程度調整做法。請運用本指南中的做法,提升實際部署的效能。