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

管理 GPT-Live 工作階段

設定工作階段、維護上下文,並管理對話生命週期。

連線至 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 事件中加入該訊息。這樣模型從一開始就能取得問候指示。

請指定問候語言、助理應說的內容,以及助理應立即開口,說完後暫停並聆聽。在來電者開口前,請使用應用程式選定的問候語言。例如,開發者訊息可以使用以下文字:

現在就用英語向來電者打招呼。介紹自己是客服助理,並詢問對方需要什麼協助。然後停下來聆聽。

  1. 將訊息加入 session.input,指定 role: "developer",並加入一個 input_text 內容片段。如需瞭解訊息格式,請參閱使用先前的對話初始化工作階段。
  2. 等待 session.started,然後透過 session.commentary.append 將相同的問候指示傳送一次,並使用唯一的 event_id 和 delegation_id: null,如下所示。持續傳送輸入音訊,包括來電者開口前的靜音片段。使用 WebSocket 時,請持續傳送 session.input_audio.append。使用 WebRTC 時,請保持輸入音軌啟用。
  3. 檢查輸出音訊與逐字稿,確認助理已向來電者打招呼。啟動時提供指示有助於模型主動問候,但無法保證模型一定會開口。
{
  "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 控制工作階段及建立側頻連線,並將後續的後端結果傳送至新工作階段。

準備可供建立分支的工作階段

  1. 建立來源工作階段時啟用儲存功能。 在工作階段設定中指定 store: true。儲存設定預設為 false。你必須為專案啟用儲存功能,且資料政策必須允許持久儲存。
  2. 儲存來源工作階段 ID。 從 session.started 或 WebRTC 建立工作階段的回應中讀取 ID,並將其與應用程式的對話記錄建立關聯。
  3. 完成並關閉來源工作階段。 完成必要的後端任務,再依照用量與正常關閉程序操作。在收到 session.closed 前請保持連線,並處理收尾時發生的任何錯誤。只有錄音已完成並儲存,才能建立分支。儲存錄音可能會延長收尾時間。
  4. 在新連線上啟動分支。 依照下方的傳輸流程使用來源 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"));
}

關閉閒置的工作階段並恢復對話

如果應用程式中兩次互動之間可能相隔很久,請在閒置期間關閉語音工作階段,並在使用者返回時啟動新的工作階段。請保留對話上下文與應用程式的任務狀態,讓使用者可以接續對話,無須重述先前說過的內容。例如,駕駛人再次啟用語音功能時,車載助理可以接續對話。程式設計助理則可以在兩次語音對話之間,讓後端工作程序繼續執行。

  1. 決定何時關閉。 由應用程式根據音訊活動、助理語音播放情況及應用程式內的互動判定閒置逾時。設定逾時時間時,請考量閱讀或思考等預期中的停頓。只有在播放已結束,且沒有待處理任務需要目前的語音工作階段時,才關閉工作階段。僅憑逐字稿事件之間的間隔無法判定是否無人說話。
  2. 儲存狀態並正常關閉。 儲存來源工作階段 ID、對話上下文與目前的任務狀態。完成所有必要的 Responses 任務,接著依照用量與正常關閉程序操作:先註冊 session.closed 監聽器,再傳送 session.close,並等到收到 session.closed 後才釋放連線。若使用用戶端委派,應用程式管理的後端任務可以在語音工作階段關閉期間獨立執行。
  3. 偵測何時重新啟動。 可提供標示為繼續對話的按鈕、按住說話控制項,或由應用程式管理的喚醒機制。Live 工作階段關閉後,便無法聆聽使用者說話。如果使用本機語音偵測功能自動重新啟動工作階段,請持續擷取麥克風輸入,並在建立連線期間暫存使用者剛開口時的語音。等新工作階段準備就緒後再傳送這段音訊,即可保留使用者最先說出的話。
  4. 在新的工作階段中還原上下文。 如果建立來源工作階段時已設定 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 完成事件追蹤。如需瞭解用量計算方式,請參閱成本最佳化。

若要正常關閉工作階段,請依序執行下列步驟:

  1. 完成應用程式所需的所有 Responses 委派任務,包括提交待處理的函式結果,以及接續處理尚未完成的回應。
  2. 先註冊 session.closed 監聽器,再傳送 session.close。
  3. 傳送 session.close,並停止向工作階段提交新任務。在待處理的工作階段事件全部處理完畢前,請保持 WebSocket 或 WebRTC 連線、資料通道,以及所有已連接的側頻接收器正常運作。
  4. 讀取最終的 usage.seconds、reason 和工作階段快照。這些資訊都包含在 session.closed 事件中。請保留先前透過 response.event 收到的委派任務用量。
  5. 收到該事件後,釋放傳輸連線與音訊裝置。如果收尾失敗,或超過應用程式設定的逾時時間,請回報收尾未完成並釋放資源。

傳送 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 前失敗,請保留最近一次收到的用量,並將最終用量標記為尚未確認。

如果有已完成並儲存的錄音,請建立分支,在新的工作階段中繼續對話。否則,請使用已儲存的相關對話記錄建立替代工作階段。繼續對話前,請向後端查詢未完成動作的狀態,還原目前的任務狀態,並更新結果的傳送路徑,以免前一個工作階段延遲抵達的結果覆寫較新的工作成果。