選取你使用的 API,即可查看連線步驟與工作階段事件。
從伺服器控制 GPT-Live 工作階段
當應用程式伺服器需要接收對話事件、執行私有工具或更新對話時,請將伺服器連到既有的 GPT-Live WebRTC 或 SIP 工作階段。這條額外的連線稱為旁路 WebSocket。兩條連線共用同一個工作階段,主要音訊則透過 WebRTC 或 SIP 傳輸。
旁路連線負責傳送事件與指令。應用程式負責執行工具、檢查授權及套用業務規則。請將 API 金鑰和工具憑證保存在伺服器上。
判斷是否需要旁路連線
瀏覽器應用程式可透過 WebRTC 資料通道顯示字幕及更新本機使用者介面。如果伺服器需要處理逐字稿,例如執行安全防護檢查、分析情緒或預先呼叫可能用到的工具,請使用旁路連線。伺服器可以接收事件並直接控制同一個工作階段,瀏覽器則繼續透過 WebRTC 傳輸音訊。範例請參閱回應逐字稿片段。
如果後端透過主要 WebSocket 連線串流傳輸音訊,請使用該連線接收事件與傳送指令。
即使沒有旁路連線,也可以使用 Responses 委派。瀏覽器可以將資料通道收到的函式呼叫事件轉送至已通過驗證的後端,由後端執行函式。OpenAI 託管的工具會透過受委派的後端執行,應用程式無須提供工具執行器。
連到既有的工作階段
-
儲存後端要控制的工作階段 ID。若使用 WebRTC 或撥出 SIP 通話,請使用
session.id欄位的值。這個欄位位於POST /v1/live/sessions的 JSON 回應中。若是 SIP 來電,請先接聽來電,再使用該通話 webhook 中的data.session_id。將 ID 與應用程式的使用者及對話記錄一起儲存。 -
在伺服器上使用下列 URL 建立 WebSocket 連線,將預留位置替換為先前儲存的完整 ID。請使用建立工作階段或接聽來電時所用專案的驗證資訊,透過
Authorization: Bearer $OPENAI_API_KEY進行驗證。連線時須包含建立工作階段時所需的相同標頭。wss://api.openai.com/v1/live/sessions/{session_id}/attach -
透過連到該工作階段的 WebSocket 接收事件與傳送指令。工作階段已在執行,請勿再次傳送
session.start。
請原樣使用工作階段 ID,包括其前綴,並確認應用程式已獲授權存取該工作階段。
建立旁路連線時重播事件
每次連到工作階段時,旁路連線都會先重播連線前 3 秒內的事件,再接續傳送新事件。重播範圍包括對話事件、通話進度事件,以及輸入和輸出音訊的副本。超過 3 秒的事件不會重播,因此請及早建立旁路連線,並自行保存應用程式需要的更早記錄。
如果事件原本就有 event_id,重播時會保留該值。請依 event_id 排除重複事件,尤其是在重新連線後,以免重複執行工具或其他動作。音訊副本事件沒有 event_id。如需了解這些事件提供哪些時間欄位,請參閱接收音訊副本。
監看事件與傳送指令
| 任務 | 事件或指令 |
|---|---|
| 追蹤對話 | 接收使用者與助理逐字稿的增量、委派事件,以及巢狀的 Responses 事件。 |
| 更新後端設定 | 使用 session.update 變更目前委派模式支援的設定。前端模型和音訊設定等啟動設定無法變更。 |
| 提供上下文 | 使用 session.instructions.append 新增指示、session.thinking.append 新增無須說出口的上下文,以及 session.commentary.append 新增可透過語音告知使用者的最新資訊。 |
| 傳回工具結果 | 使用 Responses 委派時,先傳送 response.item.create,再傳送 response.create,讓後端繼續執行工作。 |
| 控制麥克風輸入 | 使用 session.input_audio.mute 和 session.input_audio.unmute。將輸入靜音不會停止助理的輸出。 |
| 結束工作階段 | 傳送 session.close,等收到 session.closed 後再中斷連線。 |
旁路連線上的指令與主要連線遵循相同的驗證及委派規則。新增一般工作階段上下文時,請使用 delegation_id: null。若 ID 不為 null,就必須對應至既有的用戶端委派。如需了解設定方式、函式執行方式及新增上下文的範例,請參閱委派與工具。
在瀏覽器工作階段中,請持續透過協商好的 WebRTC 媒體軌傳輸麥克風輸入與喇叭輸出。使用旁路連線處理對話事件及控制對話,並在音訊播放器中追蹤播放狀態。
接收音訊副本
主要連線傳輸即時媒體時,旁路連線會收到輸入與輸出音訊的副本,其中也包括重播時段內的音訊:
| 事件 | 音訊欄位 | 時間資訊 |
|---|---|---|
session.input_audio.append |
audio |
無時間戳記。 |
session.output_audio.delta |
delta |
start_ms 和 end_ms 表示這段輸出在工作階段時間軸上的起訖時間。 |
無論主要連線採用何種音訊格式,這兩種事件的酬載都是以 base64 編碼的 24 kHz 原始單聲道 PCM16LE 音訊。兩種事件都沒有 event_id。輸入音訊副本包含套用輸入靜音前收到的音訊,無法據此確認模型是否已使用這些取樣。若有音訊影格遭捨棄,輸出音訊副本涵蓋的時間範圍可能不連續。這些範圍也無法用來判斷來電者何時聽到音訊。
麥克風音訊一律透過主要連線傳送。請使用旁路連線接收音訊副本。
每項動作只交由一方負責
逐一決定各項動作由瀏覽器或後端處理。如果兩條連線都收到同一個函式呼叫事件,該函式只應執行一次。更新上下文或要求後端繼續工作時,也應遵循相同的分工原則。
如果後端需要從頭監看對話,請及早建立旁路連線。請在應用程式中儲存逐字稿與工具狀態,包括建立旁路連線前收集的歷史記錄。
建立旁路連線後,瀏覽器仍可接收工作階段事件。請將敏感的工具憑證保存在後端,由後端判斷是否授權,並只傳回對話所需的上下文。
為對話加上安全防護
使用伺服器的主要 WebSocket 或旁路連線監看對話,並檢查請求是否符合應用程式政策。應用程式負責執行檢查,並在觸發防護時封鎖受影響的動作、傳送修正指示。
在對話進行期間同步執行檢查
安全防護是即時處理逐字稿片段的用途之一。在執行檢查的同時,應用程式也可以利用同一個資料流預先查詢可能需要的資訊,或更新使用者介面。
- 監看逐字稿。 累積
session.input_transcript.delta片段,檢查使用者請求中是否有越獄嘗試、敏感資訊或違反政策的內容。使用session.output_transcript.delta檢查助理的發言是否包含缺乏依據的說法,或超出應用程式範圍的回覆。請保留每項檢查與其評估的逐字稿及應用程式請求之間的對應關係。 - 並行執行檢查。 對話進行期間,可以用快速、輕量的模型評估請求。讓模型傳回精簡的結構化結果,例如
{"triggered": true},供應用程式據此採取行動。需要核准的動作必須通過檢查後才能執行。如果檢查失敗或逾時,請繼續封鎖這些動作。 - 封鎖受影響的動作。 一旦觸發防護,就在應用程式狀態中將該請求標記為已封鎖。執行工具或提交變更前,請先確認該狀態,即使工作已排入佇列也一樣。
- 停止相關工作。 如果後端支援取消作業,請取消由應用程式管理的相關作業,並捨棄已封鎖或已被取代的請求延遲傳回的結果。使用 Responses 委派時,請停止執行受影響的自訂函式,且不要傳送
response.create來繼續已封鎖的工作。這些措施無法取消已在執行的託管回應,也無法停止前端的語音輸出。 - 記錄決定並引導對話。 將判定結果與受影響的請求 ID 和委派 ID 一起寫入記錄,再傳送修正指示。
如需了解如何收集片段,請參閱逐字稿增量。如需了解如何讓後端結果符合目前的任務,請參閱委派與工具。
重新引導對話
觸發安全防護時,請使用 session.instructions.append 引導對話。這個指令可以中斷正在進行的發言並套用新指示。例如,應用程式封鎖請求後,可傳送以下指示:
import type { ClientEvent } from "openai/resources/live/live";
export function sendUpdate(connection: { send: (event: ClientEvent) => void }) {
connection.send({
type: "session.instructions.append",
event_id: "guardrail_block_17",
delegation_id: null,
content:
"Stop speaking immediately. Do not continue or act on the last request. Refuse briefly, then wait.",
});
}指示內容應由應用程式撰寫。請勿複製不受信任的使用者文字並將其當作指示。這項修正適用於整個工作階段,請使用 delegation_id: null,並將 content 控制在 500 個 Token 以內。
透過 session.instructions.appended 的 client_event_id,將確認事件與你傳送的指令配對。確認事件會在預估的上下文注入時間過後送達。若要避免音訊傳到來電者端,請使用下方的播放控制方式。
如果揭露資訊時必須說出特定措辭,也請使用指示。如需範例及播放時的注意事項,請參閱以語音揭露資訊。
視需要控制播放
如果應用程式需要封鎖模型音訊,請在用戶端或媒體轉送端控制播放。暫時將輸出靜音或捨棄輸出,清除本機播放佇列中的音訊,並傳送修正指示。清除不再適用的音訊後,再依應用程式的復原政策恢復播放。收到指示確認事件並不代表可以恢復播放。單靠旁路連線無法控制播放,修正指示也無法收回來電者已聽到的音訊。
session.input_audio.mute 控制來電者的麥克風輸入。這個指令不會將模型輸出靜音,也不會取消已委派的工作。
播放前檢查語音
大多數應用程式可以在對話進行期間監看使用者與助理的逐字稿。一旦觸發安全防護,應用程式就可以封鎖受影響的動作或傳送修正指示。
如果應用程式必須在播放前檢查助理的發言,請先在播放器或媒體橋接器中緩衝音訊,再將音訊傳送給來電者。執行檢查期間,請持續接收音訊和逐字稿事件,並獨立讀取逐字稿,無須等待播放。
- 收集音訊及其逐字稿。 在應用程式中對輸出音訊實作語音活動偵測(VAD),或使用媒體框架提供的噪音閘門,找出待檢查的語音片段。GPT-Live 不提供這項流程所需的輸出 VAD 或噪音閘門。請等到收到檢查各片段所需的逐字稿,再進行檢查。
- 播放通過檢查的音訊。 片段通過檢查後,將緩衝區中對應的原始音訊加入播放佇列。如果檢查失敗、缺少逐字稿或檢查逾時,請捨棄該片段,並採用應用程式定義的安全替代方案。
- 處理中斷。 使用應用程式產生的 ID,將音訊、逐字稿、檢查結果和播放狀態關聯起來。如果發言因中斷而取消,請清除緩衝區和播放佇列中對應的音訊,並忽略之後才收到的核准結果。
即使模型仍在組織回答,語音停頓也可能形成一個待檢查片段的分界。如果政策要求檢查完整回答,請明確定義應用程式如何判定回答已完成。單靠語音活動偵測無法確認整段回答已結束。
緩衝會增加延遲。即使語音遭捨棄,其內容仍會留在模型的對話上下文中,因此請測試應用程式攔下音訊或採用替代方案後,對話會如何繼續。
測試防護措施
測試應涵蓋允許及封鎖的請求、誤判為違規的情況、檢查過慢或失敗、發言或工具執行期間觸發防護,以及工作取消後才傳回結果等情境。請分別驗證動作是否遭封鎖、應用程式狀態是否正確、助理是否依修正指示發言,以及實際播放了哪些內容。如果應用程式控制輸出,測試也應涵蓋播放佇列中的音訊及恢復播放的流程。可使用語音智慧體評估 Cookbook 比較任務成功率與語音回應時間。
妥善結束工作階段
在等待工具執行完畢及工作階段回報最終用量時,請持續接收事件。先註冊 session.closed 事件處理常式,再傳送 session.close。在待處理工作完成前,請保持 WebRTC 連線、資料通道及旁路連線開啟。清理資源前,請儲存工作階段的最終用量,以及透過 Responses 事件收到的所有後端用量資料。如果在最終事件送達前連線失敗,請記錄結束程序尚未完成。如需了解關閉順序,請參閱管理工作階段。
Realtime API 允許用戶端透過 WebRTC 或 SIP 直接連到 API 伺服器。不過,通常會在應用程式伺服器上處理工具呼叫和其他業務邏輯,讓這些邏輯保持私有,且不依賴特定用戶端。
透過「旁路」控制通道連線,就能在伺服器端安全地處理工具呼叫、業務邏輯及其他細節。SIP 與 WebRTC 連線目前都支援旁路連線。
使用旁路連線時,同一個 Realtime 工作階段會同時有兩條作用中的連線,一條來自使用者的用戶端,另一條來自應用程式伺服器。透過伺服器連線,可以監看工作階段、更新指示及回應工具呼叫。
使用 WebRTC
- 建立對等連線時,請向 Realtime API 發出請求,並使用收到的 SDP 回應設定連線。如果使用 WebRTC 指南中的範例程式碼,做法如下:
const baseUrl = "https://api.openai.com/v1/realtime/calls";
const sdpResponse = await fetch(baseUrl, {
method: "POST",
body: offer.sdp,
headers: {
Authorization: `Bearer ${EPHEMERAL_KEY}`,
"Content-Type": "application/sdp",
},
});- fetch 請求的回應中會有
Location標頭,其中包含唯一的通話 ID。伺服器可以使用該 ID 建立連到同一個 Realtime 工作階段的 WebSocket 連線。
// Location: /v1/realtime/calls/rtc_123456
const location = sdpResponse.headers.get("Location");
const callId = location?.split("/").pop();
console.log(callId);- 接著,就能在伺服器上監聽事件並設定工作階段,做法與一般 Realtime API WebSocket 連線相同。將通話 ID 填入 URL
wss://api.openai.com/v1/realtime?call_id=rtc_xxxxx,如下所示:
import WebSocket from "ws";
const callId = "rtc_u1_9c6574da8b8a41a18da9308f4ad974ce";
// Connect to a WebSocket for the in-progress call
const url = "wss://api.openai.com/v1/realtime?call_id=" + callId;
const ws = new WebSocket(url, {
headers: {
Authorization: "Bearer " + process.env.OPENAI_API_KEY,
},
});
ws.on("open", function open() {
console.log("Connected to server.");
// Send client events over the WebSocket once connected
ws.send(
JSON.stringify({
type: "session.update",
session: {
type: "realtime",
instructions: "Be extra nice today!",
},
})
);
});
// Listen for and parse server events
ws.on("message", function incoming(message) {
console.log(JSON.parse(message.toString()));
});如果使用 Go,請將通話 ID 傳給伺服器端用來更新工作階段的函式:
func updateSession(ctx context.Context, client openai.Client, callID string) error {
conn, err := client.Realtime.Connect(ctx, realtime.RealtimeConnectionOptions{}, option.WithQuery("call_id", callID))
if err != nil {
return err
}
defer conn.Close()
if err := conn.Send(ctx, realtime.RealtimeClientEventParamOfSessionUpdate(realtime.RealtimeSessionCreateRequestParam{
Instructions: openai.String("Be extra nice today!"),
})); err != nil {
return err
}
for {
event, err := conn.Recv(ctx)
if err != nil {
return err
}
if event.Type == "error" {
return fmt.Errorf("Realtime API error: %s", event.OfRealtimeErrorEvent.Error.Message)
}
if event.Type == "session.updated" {
if event.OfSessionUpdatedEvent.Session.OfRealtimeSessionCreateRequest.Instructions != "Be extra nice today!" {
return fmt.Errorf("session update was not applied")
}
fmt.Println("session.updated")
return nil
}
}
}如此一來,就能在伺服器上新增工具、監看工作階段並執行業務邏輯,無須在用戶端設定這些動作。
使用 SIP
- 使用者以電話透過 SIP 連到 OpenAI。
- OpenAI 會將 webhook 傳送至應用程式伺服器的 webhook URL,通知應用程式目前的工作階段狀態。以下是 webhook 的內容範例:
POST https://my_website.com/webhook_endpoint
user-agent: OpenAI/1.0 (+https://platform.openai.com/docs/webhooks)
content-type: application/json
webhook-id: wh_685342e6c53c8190a1be43f081506c52 # unique id for idempotency
webhook-timestamp: 1750287078 # timestamp of delivery attempt
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= # signature to verify authenticity from OpenAI
{
"object": "event",
"id": "evt_685343a1381c819085d44c354e1b330e",
"type": "realtime.call.incoming",
"created_at": 1750287018, // Unix timestamp
"data": {
"call_id": "some_unique_id",
"sip_headers": [
{ "name": "From", "value": "sip:+142555512112@sip.example.com" },
{ "name": "To", "value": "sip:+18005551212@sip.example.com" },
{ "name": "Call-ID", "value": "03782086-4ce9-44bf-8b0d-4e303d2cc590"}
]
}
}- 應用程式伺服器使用 webhook 提供的
call_id值,透過類似wss://api.openai.com/v1/realtime?call_id={callId}的 URL 建立連到 Realtime API 的 WebSocket 連線。這條 WebSocket 連線會持續到 SIP 通話結束。
接著,即可透過 WebSocket 連線收發事件以控制通話,操作方式與透過 WebSocket 連線啟動工作階段時相同。你可以監看通話、動態更新指示,以及回應工具呼叫。