連線至 GPT-Live 後,可透過工作階段事件新增上下文、顯示逐字稿及管理連線。GPT-Live 可以同時聆聽與說話。請分別追蹤逐字稿文字、已播放的音訊和後端任務進度,讓介面能顯示助理正在說什麼,以及哪些任務仍在執行。
本指南假設你的連線已發出 session.started 事件。如需瞭解如何建立連線及串流音訊,請參閱連線。如需瞭解如何處理後端任務,請參閱委派與工具。
設定工作階段
建立工作階段時,請選擇模型、聲音及委派模式,並提供對話指示和相關的對話記錄。隨著對話進行,GPT-Live 會自動管理上下文。
設定欄位
| 設定 | 啟動時設定 | 工作階段期間變更 |
|---|---|---|
| 模型 | 設定必填的 model 欄位。 |
如需變更,請啟動新的工作階段。 |
| 指示 | 使用 instructions 指定對話行為,上限為 16,384 個 Token。 |
使用 session.instructions.append 新增指示。 |
| 對話記錄 | 將先前的相關文字訊息放入 input。預設值為 []。 |
使用附加事件新增上下文。 |
| 聲音 | 將 audio.output.voice 設為支援的聲音或已獲授權的自訂聲音。預設值為 marin。 |
如需變更,請啟動新的工作階段。 |
| 委派 | 將 delegation.type 設為 client 或 responses。省略委派設定或將其設為 null 時,會採用用戶端模式。 |
在現有模式下更新 Responses 設定。 |
| 儲存 | 將 store 設為 true,之後即可從這個工作階段建立分支。預設值為 false。 |
在啟動時決定。 |
聲音選項
建立工作階段時,請選擇聲音,並將 audio.output.voice 設為該聲音的 API 名稱,例如 "quartz"。GPT-Live 另外提供下列聲音選項:
| 聲音 | API 名稱 | 語言 | 地區特色 | 聲線 | 來源 |
|---|---|---|---|---|---|
| Quartz | quartz |
英語 | 澳洲 | 女性 | 生成語音 |
| Ripple | ripple |
英語 | 澳洲 | 男性 | 自然人聲 |
| Vesper | vesper |
英語 | 英國 | 男性 | 自然人聲 |
| Willow | willow |
英語 | 愛爾蘭 | 女性 | 自然人聲 |
| Stone | stone |
英語 | 愛爾蘭 | 男性 | 自然人聲 |
| Gleam | gleam |
英語 | 北美 | 女性 | 自然人聲 |
| Meridian | meridian |
英語 | 北美 | 男性 | 自然人聲 |
| Bossa | bossa |
葡萄牙語 | 巴西 | 女性 | 自然人聲 |
| Tempo | tempo |
葡萄牙語 | 巴西 | 男性 | 自然人聲 |
| Beacon | beacon |
英語 | 菲律賓 | 男性 | 生成語音 |
| Delta | delta |
英語 | 美國南部 | 女性 | 生成語音 |
| Cinder | cinder |
英語 | 美國南部 | 男性 | 生成語音 |
| Nuri | nuri |
德語 | — | 女性 | 自然人聲 |
| Juni | juni |
德語 | — | 女性 | 自然人聲 |
| Flitz | flitz |
德語 | — | 男性 | 自然人聲 |
| Brise | brise |
法語 | — | 女性 | 自然人聲 |
| Sillage | sillage |
法語 | — | 男性 | 自然人聲 |
| Nira | nira |
印地語 | — | 女性 | 自然人聲 |
| Harema | harema |
日語 | — | 女性 | 自然人聲 |
| Shida | shida |
日語 | — | 男性 | 自然人聲 |
| Noeul | noeul |
韓語 | — | 女性 | 自然人聲 |
地區特色描述的是聲音的說話風格。請依應用程式所需的語言與發音測試聲音。如要根據文字描述或經核准的錄音建立聲音,請參閱自訂聲音。
使用 WebSocket 時,請在啟動時選擇 audio.format。工作階段的輸入與輸出音訊會使用相同格式。如需改用其他格式,請啟動新的工作階段。WebRTC 會在建立連線時協商音訊格式,因此請在 WebRTC 請求中省略 audio.format。如需瞭解支援的格式與串流細節,請參閱 WebSocket 音訊格式。
更新執行中的工作階段
若工作階段已採用 Responses 委派,請使用 session.update 變更 session.delegation.responses。只需傳送要變更的設定,省略的設定會保留原值。如需瞭解各項設定及更新流程,請參閱設定 Responses 委派。
請在啟動時選擇委派模式,並設定 model、instructions、input、audio 和 store 欄位。session.update 僅支援上述 Responses 設定,更新其他設定欄位的請求會遭拒。如需切換委派模式,請建立新的工作階段。啟動時指定 delegation: null 會選用用戶端委派,不會還原 Responses 的預設設定。
更新成功後,工作階段會發出 session.updated,其中包含更新後的工作階段設定。請將送出指令時使用的 event_id 與確認事件中的 client_event_id 配對。在同一個事件迴圈中處理遭拒的指令。後端任務和語音輸出則應透過各自的事件追蹤。
提供對話記錄與上下文
在啟動時提供對話記錄,即可接續先前的話題。隨著對話進行,可再補充相關上下文。請將可信任的應用程式指示與使用者訊息、陳述事實的結果分開處理。
使用先前的對話初始化工作階段
建立工作階段時,請將先前的文字訊息放入 session.input。例如,可將下列 input 欄位加入建立工作階段的設定:
export const session = {
model: "gpt-live-1",
input: [
{
type: "message",
role: "user",
content: [
{
type: "input_text",
text: "I need help with my recent order.",
},
],
},
{
type: "message",
role: "assistant",
content: [
{
type: "output_text",
text: "What is the order number?",
},
],
},
],
};清單最多可包含 128 則訊息,總計不得超過 8,192 個 Token。每則訊息包含一個文字內容片段,並指定下列其中一個角色:developer、user 或 assistant。開發者與使用者訊息使用 input_text,助理訊息則使用 text 或 output_text。請將可信任的應用程式指示放入 instructions 或開發者訊息中。
請選出下一次互動所需的文字記錄,在啟動時提供。工作階段進行期間,可透過下列上下文事件補充最新資訊。工具結果等後端專屬項目則應透過委派流程傳送。
瞭解模型何時收到上下文
將模型一開始就需要的上下文放入 input。工作階段啟動時,模型即可取得該欄位的完整內容。
在工作階段執行期間,可透過 session.instructions.append、session.thinking.append 和 session.commentary.append 陸續新增上下文。當工作階段時間軸推進至新增內容的預估結束時間時,你會收到確認事件。事件中的 start_ms 和 end_ms 表示這次更新在工作階段時間軸上的預估起訖位置。
這些時間描述上下文的傳遞時機,與說話或播放的時間無關。模型可能在使用完整的更新內容前就做出回應。若某項動作取決於新的指示或事實,請在應用程式中驗證實際行為。
如果工作階段時間軸停止推進,可能一直收不到確認事件。請將送出時的 event_id 與確認事件中的 client_event_id 配對,並在等待期間持續處理錯誤。關閉工作階段時,仍待處理的附加請求會收到錯誤。
在對話期間新增上下文
請根據模型應如何使用更新內容來選擇事件:
session.instructions.append:新增可信任的應用程式指示,引導模型的行為與說話方式。session.thinking.append:補充事實資訊作為上下文,無須要求模型立即說出來。session.commentary.append:提供要讓模型說出來的資訊。模型可能會換句話說。
每個事件的 content 都是純字串,最多可包含 500 個 Token,且必須提供 delegation_id。若上下文適用於整個工作階段,請使用 null。例如,應用程式確認使用者已同意並開始查詢後,可傳送以下事件:
import type { ClientEvent } from "openai/resources/live/live";
export function sendUpdate(connection: { send: (event: ClientEvent) => void }) {
connection.send({
type: "session.thinking.append",
event_id: "context_1",
delegation_id: null,
content:
"The user has already accepted the terms. The account lookup is still running.",
});
}若要追蹤這次更新,請處理 session.thinking.appended 事件(其中含有 client_event_id: "context_1")或對應的錯誤。如需瞭解何時會收到確認事件,請參閱瞭解模型何時收到上下文。
助理可能會複述透過上述任何事件提供的資訊。請只傳送適合在對話中提及的資訊,並將憑證與機密資訊留在後端。若要指定應用程式定義的行為,請使用 session.instructions.append。將工具傳回的事實資訊作為上下文提供,並在應用程式碼中落實權限檢查與必要的確認程序。
若要告知模型頁面導覽、選取項目或其他介面變更,請參閱分享使用者介面的上下文,瞭解如何透過簡短的更新協助 GPT-Live 理解使用者指的是什麼。
若更新與特定後端任務有關,請使用對應的用戶端委派 ID。委派 ID 用來識別 Live 任務,Responses 的回應 ID 和工具呼叫 ID 則分別識別不同的物件。如需瞭解操作流程,請參閱選擇適當的更新類型。
當應用程式偵測到問題時,請透過工作階段的主要 WebSocket 或側頻 WebSocket 傳送簡短的更正訊息。如需瞭解如何執行檢查、控制動作及處理播放,請參閱套用對話防護措施。
管理語音與逐字稿
逐字稿增量事件
請監聽 session.input_transcript.delta 以取得使用者的語音逐字稿,並監聽 session.output_transcript.delta 以取得助理的語音逐字稿。每個事件都包含一段文字及其在工作階段時間軸上的區間:
{
"type": "session.input_transcript.delta",
"event_id": "event_transcript_1",
"delta": "What is",
"start_ms": 1000,
"end_ms": 1200
}
請將每位說話者的 delta 片段依接收時的原樣附加至各自的逐字稿,保留空格和重複的詞語。也請保留各片段的 start_ms 和 end_ms。這兩個值以毫秒為單位,從工作階段開始時計算。上例的區間從第 1,000 毫秒開始,到第 1,200 毫秒為止,不含第 1,200 毫秒。這些值是片段的大致時間範圍,並非每個詞的精確起訖時間。整理逐字稿時,請以這些值為準,避免使用封包抵達時間。
只有含有文字的時間區間才會產生逐字稿事件,而且事件抵達的間隔可能不一。單一片段可能只包含句子的一部分,傳送間隔較長也可能是網路延遲所致。逐字稿增量事件沒有項目 ID,也沒有事件標示一輪對話結束,因此應用程式需自行決定如何將片段分組顯示。
你可以選擇是否處理逐字稿片段。在對話進行期間,可利用片段更新使用者介面、執行檢查或提早開始處理任務。若只需執行簡單的檢查,可考慮使用 gpt-5.6-luna 等小型模型,並將推理強度設低。如需範例與連線指引,請參閱因應逐字稿片段執行動作。
透過逐字稿防護措施,可在語音對話進行期間監控對話並觸發介入措施。若應用程式需要在播放前檢查助理語音,請參閱播放前檢查語音,瞭解如何處理緩衝、核准、中斷與恢復。
請分別處理逐字稿的時間資訊與音訊播放。WebSocket 的 session.output_audio.delta 事件沒有時間欄位,也沒有另行通知音訊輸出完成的事件。WebRTC 則透過媒體軌傳送音訊。如需瞭解音訊處理方式,請參閱連線。
顯示字幕
GPT-Live 支援全雙工通訊,來電者和助理可以同時說話。請分別更新雙方的字幕,讓兩人同時說話時,各自的文字都能持續增加。
如果應用程式使用對話泡泡,可以將「我想」和「更改我的預訂」兩個片段放在同一個來電者泡泡中。若來電者還在說話時助理說了「好的」,請另外顯示這句回應,同時讓來電者的泡泡繼續加入文字。請保留原始片段與時間戳記,以便將稍後抵達的文字加入正確的泡泡。
請使用 session.output_transcript.delta 顯示語音字幕,另行顯示後端更新。是否執行工具或取消任務,應由應用程式的任務邏輯決定,與介面如何將文字分組顯示分開處理。
控制麥克風輸入
傳送 session.input_audio.mute 即可將輸入靜音,同時保持工作階段開啟:
import type { ClientEvent } from "openai/resources/live/live";
export function sendUpdate(connection: { send: (event: ClientEvent) => void }) {
connection.send({
type: "session.input_audio.mute",
event_id: "mute_1",
});
}請等到收到 session.input_audio.muted 且其中包含 client_event_id: "mute_1",再將指令視為已接受。若要恢復輸入,請傳送 session.input_audio.unmute 並等待 session.input_audio.unmuted。這兩個指令都需要處理錯誤。
將輸入靜音後,工作階段仍會繼續執行,模型仍可產生語音,已委派的任務也能繼續進行。若還需要停止本機錄音或播放,請使用應用程式的麥克風擷取與音訊播放控制功能。
在來電者開口前問候
若要讓 GPT-Live 主動開啟對話,建議在建立工作階段時,將問候指示寫入 developer 訊息,並放入 session.input。使用 WebSocket 時,請在 session.start 事件中加入該訊息。這樣模型從一開始就能取得問候指示。
請指定問候語言、助理應說的內容,以及助理應立即開口,說完後暫停並聆聽。在來電者開口前,請使用應用程式選定的問候語言。例如,開發者訊息可以使用以下文字:
現在就用英語向來電者打招呼。介紹自己是客服助理,並詢問對方需要什麼協助。然後停下來聆聽。
- 將訊息加入
session.input,指定role: "developer",並加入一個input_text內容片段。如需瞭解訊息格式,請參閱使用先前的對話初始化工作階段。 - 等待
session.started,然後透過session.commentary.append將相同的問候指示傳送一次,並使用唯一的event_id和delegation_id: null,如下所示。持續傳送輸入音訊,包括來電者開口前的靜音片段。使用 WebSocket 時,請持續傳送session.input_audio.append。使用 WebRTC 時,請保持輸入音軌啟用。 - 檢查輸出音訊與逐字稿,確認助理已向來電者打招呼。啟動時提供指示有助於模型主動問候,但無法保證模型一定會開口。
{
"type": "session.commentary.append",
"event_id": "greeting_1",
"delegation_id": null,
"content": "Greet the caller now in English. Introduce yourself as the support assistant and ask how you can help. Then pause and listen."
}
session.commentary.appended 事件表示工作階段已接受請求,無法據此確認助理已說出問候語或應用程式已播放語音。GPT-Live 可能會換個說法、補充其他詞句,或保持沉默。
若需要穩定播放問候語、使用確切措辭,或確知播放完成的時間點,請透過應用程式播放經過驗證的錄音或已產生的音訊片段,並在播放期間控制 GPT-Live 的音訊播放。請以支援的各種語言測試問候語,測試情境應包含來電者在問候期間開口說話。如需瞭解如何設計提示詞,請參閱為語音模型撰寫提示詞。
播報告知事項
使用 session.instructions.append 要求模型以指定措辭播報告知事項。使用 session.commentary.append 時,模型可能會改述文字。例如,收到 session.started 後,可傳送以下事件:
import type { ClientEvent } from "openai/resources/live/live";
export function sendUpdate(connection: { send: (event: ClientEvent) => void }) {
connection.send({
type: "session.instructions.append",
event_id: "disclosure_1",
delegation_id: null,
content:
"Immediately say the following disclosure exactly and in full before responding to the caller: This call may be recorded for quality and training purposes.",
});
}請依照在來電者開口前問候中的說明,持續傳送輸入音訊。在對話中傳送指示可能會打斷正在進行的發言。
請先檢查產生的告知內容及其播放情況,再將其標記為已送達。指示的確認事件只表示指示已獲接受,請檢查實際音訊以核對措辭。若必須使用確切措辭並確知播放完成的時間點,請透過應用程式播放經過驗證的錄音或已產生的音訊片段,並在播放期間控制 GPT-Live 的輸出。請參閱視需要控制播放。
管理長時間對話
GPT-Live 會自動管理長時間對話,並保留你在啟動時提供的原始指示。
預設的上下文視窗可容納 128,000 個 Token,涵蓋指示、對話文字,以及不會出現在逐字稿中的音訊 Token。
GPT-Live 會在背景為較早的對話記錄產生摘要。當上下文使用率超過 90% 時,GPT-Live 會在同一個工作階段內啟動替代的語音引擎。新引擎會收到原始指示,以及最多 8,192 個 Token 的對話記錄,其中包含近期訊息,如果已有較早訊息的摘要,也會一併納入。產生摘要時,執行中引擎的上下文不會立即改變。
較早的對話細節可能會被濃縮成摘要或省略。請在應用程式中保留重要事實、已確認的動作與目前的任務狀態,並在需要時提供相關上下文。
儲存工作階段並建立分支
建立分支可從已儲存的語音對話啟動新的工作階段。你可以從同一段參考對話進行多次評估,也可以讓使用者在先前的工作階段結束後繼續對話。每個分支都有新的連線與工作階段 ID,並以來源對話及其儲存的設定為起點。
從參考對話執行評估
假設你想測試智慧體如何處理來電者變更訂單的要求。先將情境開頭錄製一次,錄到來電者已指明是哪一筆訂單為止。在來電者提出變更要求前,結束該工作階段並完成收尾。之後每次評估都可以從同一個參考工作階段建立分支,並提供相同的下一段來電者語音:「Actually, can you send it to my office instead?」
每次測試時,請還原相同的測試訂單與應用程式狀態,提供來電者的下一段輸入,再評估新產生的回應與工具執行的動作。你可以重複測試同一情境,也可以比較支援的 Responses 後端設定。請分別測量分支啟動時間和回應時間。如需瞭解如何選擇情境與衡量結果,請參閱 GPT-Live 評估指南。
分支會沿用 GPT-Live 模型、聲音與原始指示。若要比較不同的語音模型或啟動提示詞,請使用對應的設定建立新的工作階段。分支 API 使用已完成的來源錄音,因此請在希望開始評估的位置結束參考工作階段。
在工作階段結束後繼續對話
例如,來電者可能掛斷後再次來電,或在通話中斷後重新連線。如果先前工作階段的錄音已完成並儲存,應用程式就能在新連線上建立分支,接續已儲存的對話。
請一併儲存應用程式的任務狀態與來源工作階段 ID。繼續對話前,請檢查所有未完成後端任務的狀態,並將最新結果提供給新工作階段。例如,若已提交訂單更新,請先確認結果,再嘗試另一次更新。請使用新工作階段 ID 控制工作階段及建立側頻連線,並將後續的後端結果傳送至新工作階段。
準備可供建立分支的工作階段
- 建立來源工作階段時啟用儲存功能。 在工作階段設定中指定
store: true。儲存設定預設為false。你必須為專案啟用儲存功能,且資料政策必須允許持久儲存。 - 儲存來源工作階段 ID。 從
session.started或 WebRTC 建立工作階段的回應中讀取 ID,並將其與應用程式的對話記錄建立關聯。 - 完成並關閉來源工作階段。 完成必要的後端任務,再依照用量與正常關閉程序操作。在收到
session.closed前請保持連線,並處理收尾時發生的任何錯誤。只有錄音已完成並儲存,才能建立分支。儲存錄音可能會延長收尾時間。 - 在新連線上啟動分支。 依照下方的傳輸流程使用來源 ID,儲存新的工作階段 ID,並在啟動完成後繼續對話。請明確設定子工作階段的
store:若之後還要從接續的對話建立分支,請設為true。若無須儲存這次測試,請設為false。省略此欄位時會沿用來源設定。
已儲存的錄音可存取 30 天。啟用零資料保留(ZDR)時,store 一律視為 false,無法建立分支。若要透過分支進行評估,請使用未啟用 ZDR 的組織,並為專案啟用儲存功能。
如果沒有已完成並儲存的錄音,請使用已儲存的相關文字記錄啟動新的工作階段。如需瞭解儲存條件,請參閱 GPT-Live 資料控制。
例如,可在來源工作階段的 WebSocket session.start 設定或 WebRTC 建立請求中設定以下欄位:
{
"store": true
}
請依應用程式使用的傳輸方式啟動分支:
| 傳輸方式 | 啟動分支 |
|---|---|
| WebSocket | 連線至 wss://api.openai.com/v1/live/sessions/{source_session_id}/fork。 |
| WebRTC | 將新的 SDP 提議傳送至 POST /v1/live/sessions/{source_session_id}/fork。將傳回的 transport.sdp 應答套用至新的對等連線。 |
分支會沿用來源工作階段的模型、原始指示與輸入。啟動時只能傳送下列支援覆寫的設定:
- WebSocket:
store、Responses 委派設定,以及新連線的audio.format。請傳送session.start事件,並在其中加入session物件。若要保留可繼承的設定,請使用{}。 - WebRTC:
store、Responses 委派設定,以及前端用戶端權限。
使用 WebSocket 建立分支時,請設定新連線的 audio.format,或使用預設的 24 kHz PCM16。新連線不會沿用來源音訊格式與前端資料通道權限。WebRTC 會在建立連線時協商音訊格式,因此請省略 audio.format。除非另行覆寫,WebRTC 會保留前端權限設定。
使用 WebSocket 時,請等到收到 session.started 再傳送其他指令。使用 WebRTC 時,HTTP 請求就會啟動工作階段。請透過協商完成的連線繼續操作,無須再次傳送 session.start。
啟動 WebSocket 分支
請設定 OPENAI_API_KEY。下列範例使用應用程式先前儲存的來源工作階段 ID,確認啟動成功後便關閉分支。若要繼續對話,請在收到 session.started 後,依照 WebSocket 連線流程收發音訊。如需瞭解啟動時使用的欄位與事件,請參閱 WebSocket 分支參考文件。
import OpenAI from "openai";
import { ForksWS } from "openai/resources/live/forks/ws";
async function forkSession(sourceSessionId: string) {
const ws = new ForksWS(new OpenAI(), { session_id: sourceSessionId });
let finalized = false;
let closeRequested = false;
try {
for await (const event of ws) {
if (event.type === "open") {
ws.send({ type: "session.start", session: {} });
} else if (event.type === "error") {
throw event.error;
} else if (event.type === "message") {
if (event.message.type === "session.started") {
console.log("Fork ready:", event.message.session.id);
// This startup example closes the fork after confirming it is ready.
ws.send({ type: "session.close" });
closeRequested = true;
} else if (event.message.type === "session.closed") {
console.log("Final usage:", event.message.usage);
if (!closeRequested) {
throw new Error("Fork ended before startup completed");
}
finalized = true;
break;
}
}
}
if (!finalized) throw new Error("Connection closed before session.closed");
} finally {
ws.close();
}
}啟動 WebRTC 分支
請在前端建立新的 SDP 提議,並將其傳送至後端。下列後端範例使用該提議,以及應用程式先前儲存的來源工作階段 ID:
import OpenAI from "openai";
async function forkSession(sourceSessionId: string, offerSdp: string) {
const client = new OpenAI();
const fork = await client.live.sessions.fork(sourceSessionId, {
transport: { type: "webrtc", sdp: offerSdp },
});
console.log(JSON.stringify(fork));
}請將回應傳回前端,將 transport.sdp 套用為新對等連線的應答,並保留新的 session.id。API 金鑰請留在後端。
請使用新的工作階段 ID 建立側頻連線及控制工作階段。重試未完成的動作前,請先在後端檢查執行結果,並還原應用程式目前的任務狀態。如果沒有已完成並儲存的錄音,請使用已儲存的對話記錄初始化新的工作階段。
下載錄音
錄音完成儲存後,請使用 GET /v1/live/sessions/{session_id}/content 下載音訊。回應是二進位的立體聲 WAV,左聲道為輸入音訊,右聲道為輸出音訊。下列範例使用應用程式儲存的工作階段 ID,並將回應以串流方式寫入 recording.wav:
import OpenAI from "openai";
import { createWriteStream } from "node:fs";
import { pipeline } from "node:stream/promises";
async function downloadRecording(sessionId: string) {
const client = new OpenAI();
const response = await client.live.sessions.downloadRecording(sessionId);
if (!response.body) throw new Error("Recording response has no body");
await pipeline(response.body, createWriteStream("recording.wav"));
}關閉閒置的工作階段並恢復對話
如果應用程式中兩次互動之間可能相隔很久,請在閒置期間關閉語音工作階段,並在使用者返回時啟動新的工作階段。請保留對話上下文與應用程式的任務狀態,讓使用者可以接續對話,無須重述先前說過的內容。例如,駕駛人再次啟用語音功能時,車載助理可以接續對話。程式設計助理則可以在兩次語音對話之間,讓後端工作程序繼續執行。
- 決定何時關閉。 由應用程式根據音訊活動、助理語音播放情況及應用程式內的互動判定閒置逾時。設定逾時時間時,請考量閱讀或思考等預期中的停頓。只有在播放已結束,且沒有待處理任務需要目前的語音工作階段時,才關閉工作階段。僅憑逐字稿事件之間的間隔無法判定是否無人說話。
- 儲存狀態並正常關閉。 儲存來源工作階段 ID、對話上下文與目前的任務狀態。完成所有必要的 Responses 任務,接著依照用量與正常關閉程序操作:先註冊
session.closed監聽器,再傳送session.close,並等到收到session.closed後才釋放連線。若使用用戶端委派,應用程式管理的後端任務可以在語音工作階段關閉期間獨立執行。 - 偵測何時重新啟動。 可提供標示為繼續對話的按鈕、按住說話控制項,或由應用程式管理的喚醒機制。Live 工作階段關閉後,便無法聆聽使用者說話。如果使用本機語音偵測功能自動重新啟動工作階段,請持續擷取麥克風輸入,並在建立連線期間暫存使用者剛開口時的語音。等新工作階段準備就緒後再傳送這段音訊,即可保留使用者最先說出的話。
- 在新的工作階段中還原上下文。 如果建立來源工作階段時已設定
store: true,儲存功能已啟用且政策允許儲存,錄音也已順利完成收尾,請從已儲存的工作階段建立分支。否則,請使用已儲存的文字記錄啟動新的工作階段。儲存新的工作階段 ID,檢查未完成的後端作業狀態,並將後續結果傳送至新工作階段。請在應用程式中保留作業狀態,以免重新啟動時重複執行已完成的動作。
將麥克風靜音後,工作階段仍會持續執行。設定閒置逾時時間時,請權衡可省下的語音使用時間、建立工作階段的費用,以及語音功能重新就緒所需的時間。請參閱語音工作階段費用與 WebRTC 初始化費用。
處理錯誤並結束工作階段
請持續讀取工作階段事件,直到工作階段完成收尾。應用程式應區分指令遭拒、連線失敗和工作階段已完成這三種情況,以便採取適當的復原方式。
處理遭拒的指令
請同時讀取 error 事件與確認事件。若事件包含 error.client_event_id,就可以用它識別先前送出的哪個指令執行失敗:
{
"type": "error",
"event_id": "event_error",
"error": {
"type": "invalid_request_error",
"code": "immutable_field_update",
"message": "The delegation type cannot change after session startup.",
"param": "session.delegation.type",
"client_event_id": "event_update"
}
}
請提供通用的錯誤處理常式,以處理錯誤碼為 null 或缺少用戶端事件 ID 的錯誤。如果錯誤是因為嘗試更新不可變更的欄位,請保留目前設定,或使用所需設定建立新的工作階段。
處理內容審核事件
內容審核可能以兩種方式影響工作階段:
- 部分內容審核事件會結束工作階段。
- 其他事件會截斷助理本次發言剩餘的音訊,並發出
error事件,但工作階段會繼續執行。
播放音訊時,請持續處理 error 事件。請分別追蹤音訊中斷與工作階段關閉,並在檢查播放情況後,才將語音訊息標記為已送達。除了內建的內容審核功能,也請套用自己的對話防護措施。
用量與正常關閉程序
session.usage.updated 會以秒為單位回報累計的語音使用時間:
{
"type": "session.usage.updated",
"event_id": "event_usage_1",
"usage": { "seconds": 12 },
"context_window": { "usage_ratio": 0.42 }
}
請以最新的 usage.seconds 作為目前累計的語音使用時間。例如,若先後收到 12 秒與 15 秒的更新,累計用量就是 15 秒。後端 Token 用量請另外透過巢狀的 Responses 完成事件追蹤。如需瞭解用量計算方式,請參閱成本最佳化。
若要正常關閉工作階段,請依序執行下列步驟:
- 完成應用程式所需的所有 Responses 委派任務,包括提交待處理的函式結果,以及接續處理尚未完成的回應。
- 先註冊
session.closed監聽器,再傳送session.close。 - 傳送
session.close,並停止向工作階段提交新任務。在待處理的工作階段事件全部處理完畢前,請保持 WebSocket 或 WebRTC 連線、資料通道,以及所有已連接的側頻接收器正常運作。 - 讀取最終的
usage.seconds、reason和工作階段快照。這些資訊都包含在session.closed事件中。請保留先前透過response.event收到的委派任務用量。 - 收到該事件後,釋放傳輸連線與音訊裝置。如果收尾失敗,或超過應用程式設定的逾時時間,請回報收尾未完成並釋放資源。
傳送 session.close 會取消佇列中的 Responses 請求,後續指令也會遭拒。正在執行的回應仍可完成,但如果回應正在等待函式結果,工作階段一旦開始關閉,該回應就無法繼續。對於應用程式透過用戶端委派執行的任務,請另行決定要完成還是取消。
請透過 session.closed 確認收尾完成,並讀取最終設定快照。收到此事件前,請保持傳輸連線開啟。如果通訊端先關閉,請將收尾狀態記錄為尚未確認。如果通訊端是在收到有效的 session.closed 後才關閉,請保留已確認的結果。
最終事件中的 reason 會說明工作階段結束的原因:
| 原因 | 意義 |
|---|---|
close_requested |
應用程式傳送了 session.close,或呼叫了掛斷端點。 |
expired |
工作階段已達時間上限。 |
content |
安全篩選機制結束了工作階段。 |
remote_hangup |
遠端的主要連線正常結束。 |
connection_lost |
主要連線或上游連線意外中斷。 |
即使結束原因是連線中斷或安全機制終止工作階段,收到 session.closed 事件仍可確認收尾已完成。若未收到該事件,最終用量仍未確認。啟用儲存的工作階段可能需要較長時間來儲存錄音並完成收尾,因此設定應用程式的逾時時間時,請將儲存所需的時間納入考量。
在連線失敗後恢復對話
如果建立工作階段的 HTTP 請求發生錯誤,表示工作階段尚未進入 session.started 階段。請分別處理啟動時的錯誤和工作階段執行期間的錯誤。如果執行中的連線在收到 session.closed 前失敗,請保留最近一次收到的用量,並將最終用量標記為尚未確認。
如果有已完成並儲存的錄音,請建立分支,在新的工作階段中繼續對話。否則,請使用已儲存的相關對話記錄建立替代工作階段。繼續對話前,請向後端查詢未完成動作的狀態,還原目前的任務狀態,並更新結果的傳送路徑,以免前一個工作階段延遲抵達的結果覆寫較新的工作成果。