OpenAI Realtime API 開發者筆記:GA 後語音對語音更新要點
Sep 12 Developer notes on the Realtime API Details worth noticing in recent realtime speech-to-speech updates Audio
OpenAI 整理 Realtime API 與 gpt-realtime 語音對語音模型進入 GA 後的介面變更、新功能及整合注意事項。文章建議客户遷移至 GA 介面,並説明 beta 與 GA 在功能支援、temperature 和非同步函式呼叫上的差異。
文章對照 beta 與 GA 的功能支援差異,並説明介面遷移、temperature 設定及長對話截斷的處理方式,方便開發者按整合環節核對需要調整的設定。
我們最近宣佈最新的語音轉語音模型 gpt-realtime,同時 Realtime API 正式全面推出,並加入多項全新 API 功能。Realtime API 和語音轉語音(s2s)模型正式推出,並大幅提升模型品質、可靠性和開發者使用體驗。
你可在説明文件和 API 參考查看新 API 功能;本文會重點介紹幾項容易錯過的功能,並提供使用時機建議。若你正整合 Realtime API,希望以下內容對你有幫助。
模型改進
新模型加入多項改進,目標是更好地支援正式環境語音應用程式。本文聚焦 API 變更。若想深入瞭解和使用模型,建議閲讀發布公告和Realtime 提示詞指南。下文亦會指出一些具體事項。
使用這個模型時,有幾項重要建議:
- 在 Realtime playground 試驗提示詞。
- 若要取得最佳助理語音品質,請使用
marin或cedar語音。 - 為新模型重寫提示詞。由於指令遵循能力有所提升,明確指示現在會發揮更大作用。
- 例如,舊模型可能把「Y 發生時一律説 X」視為含糊指引;新模型則可能在出乎意料的情況下也遵照執行。
- 請留意你提供的具體指示,並假設模型會遵循。
API 結構變更
Realtime API 隨 GA 發布更新了 API 結構,現在有 Beta 介面和 GA 介面。我們建議用戶遷移至 GA 介面,因為它提供新功能,而 Beta 介面最終會被棄用。
遷移所需變更的完整清單,請參閲Beta 轉 GA 遷移説明。
你可以透過 Beta 介面使用全新 gpt-realtime 模型,但部分功能可能不受支援。詳情見下文。
功能支援情況
Realtime API GA 版本包含多項新功能,其中部分亦支援舊模型,另一些則不支援。
| 功能 | GA 模型 | Beta 模型 |
|---|---|---|
| 圖像輸入 | ✅ | ❌ |
| 長上下文 | ✅ | ✅ |
| 非同步函數呼叫 | ✅ | ❌ |
| 提示詞 | ✅ | ✅ |
| MCP | ✅ 配合非同步 FC 效果最佳 | ✅ 沒有非同步 FC 時功能受限* |
| 音訊 token → 文字 | ✅ | ❌ |
| 歐盟數據駐留 | ✅ | ✅ 僅支援 06-03 |
| SIP | ✅ | ✅ |
| 閒置逾時 | ✅ | ✅ |
*由於 Beta 模型不支援非同步函數呼叫,模型可能無法妥善處理尚未收到輸出的待處理 MCP 工具呼叫。我們建議使用 GA 模型配合 MCP。
温度設定變更
GA 介面已移除 temperature 模型參數;Beta 介面則把 temperature 限制在 0.6 - 1.2,預設值為 0.8。
你可能會問:「為甚麼用戶不能任意設定 temperature,並用它令回應更確定?」原因是 temperature 在這種模型架構中的作用不同;用戶幾乎總是採用建議值 0.8 最合適。
根據我們的觀察,低 temperature 無法令音訊回應變得確定,而較高 temperature 則會導致音訊失真。我們建議透過試驗提示詞來控制這些模型行為。
新功能
除了 Beta 轉 GA 的變更,我們亦為 Realtime API 新增多項功能。
所有功能均載於説明文件和 API 參考;本文會介紹整合和遷移時如何理解這些新功能。
對話閒置逾時
對某些應用程式而言,若用戶長時間沒有輸入內容會令人困惑。想像正在通電話:若我們很久沒聽到對方説話,便會詢問對方是否安好。可能是模型錯過了用戶説的話,也可能是用戶不確定模型是否仍在説話。我們新增自動觸發模型説出「你還在嗎?」等內容的功能。
若要啟用此功能,請在輪次偵測設定中指定 idle_timeout_ms(server_vad 設定)。
逾時倒數會在模型最後一次回應的音訊播放完畢後開始;亦即逾時時間為 response.done 時間,加上音訊播放時長,再加上逾時設定。若 VAD 在該段時間內沒有觸發,便會啟動逾時處理。
逾時觸發時,伺服器會傳送 input_audio_buffer.timeout_triggered 事件,然後把空白音訊片段提交至對話歷史並觸發模型回應。提交空白音訊,讓模型有機會檢查 VAD 是否失效,以及相關時段是否其實有用戶發言。
用戶端可按以下方式啟用此功能:
{
"type": "session.update",
"session": {
"type": "realtime",
"instructions": "You are a helpful assistant.",
"audio": {
"input": {
"turn_detection": {
"type": "server_vad",
"idle_timeout_ms": 6000
}
}
}
}
}長對話和上下文處理
我們調整了 Realtime API 處理長時間工作階段的方式。請留意以下事項:
- Realtime 工作階段現在最長可持續 60 分鐘,以前上限為 30 分鐘。
gpt-realtime模型的 token 視窗為 32,768 個 token,每次回應最多可使用 4,096 個 token。因此模型的最大輸入量為 28,672 個 token。- 工作階段指示和工具的總長度上限為 16,384 個 token。
- 工作階段達到 28,672 個 token 時,服務會自動截斷(丟棄)部分訊息,但此行為可設定。
- GA 服務會在有轉錄文本時自動丟棄部分音訊 token,以節省 token 用量。
設定截斷方式
對話上下文視窗達到 token 上限時,Realtime API 會自動從工作階段開端(最舊的訊息)開始截斷並丟棄訊息。
你可設定 "truncation": "disabled" 關閉截斷;若回應的輸入 token 過多,系統便會改為擲出錯誤。不過,截斷很有用,因為即使輸入大小超出模型容量,工作階段仍可繼續。Realtime API 不會為已丟棄訊息生成摘要或壓縮內容,但你可以自行實作。
截斷的一項負面影響是,改動對話開端的訊息會令提示詞 token 快取失效。提示詞快取會比對提示詞開端是否包含完全相同的內容。之後每個回合只會快取未變更的 token。截斷若改動對話開端,便會減少可快取的 token 數量。
我們新增一項功能,截斷時會多丟棄一些內容,以減輕這種負面影響。將保留比例設為 0.8,即可一次截斷上下文視窗的 20%,而非只截斷到輸入 token 數低於上限為止。做法是在更多內容上截斷一次,而不是每次只截斷少量,從而減少快取失效。這種有利快取的方式,可降低長工作階段達到輸入上限時的成本。
{
"type": "session.update",
"session": {
"truncation": {
"type": "retention_ratio",
"retention_ratio": 0.8
}
}
}非同步函數呼叫
Responses API 會強制在函數呼叫後立即傳回函數結果;Realtime API 則容許用戶端在函數呼叫處於待處理狀態時繼續工作階段。這種延續方式有利用戶體驗,讓即時對話自然繼續,但模型有時會幻覺出不存在的函數結果。
為減輕這個問題,GA Responses API 會加入佔位回應;這些內容經過評估和實驗調整,確保模型即使在等待函數結果期間也能妥善回應。若你向模型查詢函數呼叫的結果,它會説「我仍在等候」。新模型會自動啟用這項功能,無須你作任何修改。
歐盟數據駐留
目前只有 gpt-realtime-2025-08-28 和 gpt-4o-realtime-preview-2025-06-03 支援歐盟數據駐留。組織必須明確啟用數據駐留,並透過 https://eu.api.openai.com 存取。
追蹤記錄
Realtime API 會把追蹤記錄寫入開發者控制台,記錄 Realtime 工作階段中的重要事件,方便調查和除錯。GA 版本亦新增了幾種事件類型:
- 工作階段更新(向用戶端傳送
session.updated事件時) - 輸出文字生成(模型生成文字時)
託管提示詞
現在你可以透過 Realtime API 使用提示詞,讓應用程式程式碼引用可獨立編輯的提示詞,方便管理。提示詞包含指示和工作階段設定,例如輪次偵測設定。
你可以在 Realtime playground 建立提示詞、反覆調整和管理版本,然後讓用戶端按 ID 引用提示詞,例如:
{
"type": "session.update",
"session": {
"type": "realtime",
"prompt": {
"id": "pmpt_123", // your stored prompt ID
"version": "89", // optional: pin a specific version
"variables": {
"city": "Paris" // example variable used by your prompt
}
},
// You can still set direct session fields; these override prompt fields if they overlap:
"instructions": "Speak clearly and briefly. Confirm understanding before taking actions."
}
}如果提示詞設定與傳入工作階段的其他配置重疊,如上例所示,工作階段配置會優先生效。因此,用戶端可採用提示詞中的配置,也可在工作階段開始時修改。
Sideband 連線
Realtime API 允許用戶端透過 WebRTC 或 SIP 直接連接 API 伺服器。不過,你通常會希望工具使用和其他商業邏輯留在應用程式伺服器上,以確保邏輯私密且不受用戶端影響。
透過 Sideband 控制通道連線,便可將工具使用、商業邏輯和其他細節安全地保留在伺服器端。現在 SIP 和 WebRTC 連線都支援 Sideband 選項。
Sideband 連線代表同一個 Realtime 工作階段有兩條啟用中的連線:一條來自用戶端,另一條來自應用程式伺服器。伺服器連線可用來監控工作階段、更新指示和回應工具呼叫。
詳情請參閲 Sideband 連線説明文件。
開始建構
希望本文有助你瞭解 Realtime API 正式推出和全新 Realtime 模型的變更。
瞭解最新設計後,請參閲Realtime 説明文件,開始建立語音代理程式、建立連線,或為 Realtime 模型編寫提示詞。
來源:OpenAI Developers:Blog · developers.openai.com