使用 Realtime API 建立語音到語音智慧體。模型可直接處理音訊、維持對話狀態,並呼叫工具。本指南先介紹如何使用 Agents SDK 建立瀏覽器應用程式。如需直接控制連線,請參閱底層連線指南。
若要使用獨立的後端處理委派的工作並支援全雙工對話,請參閱 GPT-Live。若要比較不同的語音架構與串接式處理流程,請參閱語音智慧體。
建立語音到語音智慧體
若希望互動像交談一樣自然、即時,可以使用 Realtime API。如果語音智慧體需要讓使用者隨時插話、縮短首段音訊的延遲、自然地輪流發言,並即時使用工具,Realtime API 是最適合的起點。
瀏覽器應用程式的典型流程如下:
- 應用程式伺服器為 Realtime 工作階段建立短效用戶端密鑰。
- 前端建立
RealtimeSession。 - 工作階段在瀏覽器中透過 WebRTC 連線,在伺服器上則透過 WebSocket 連線。
- 智慧體在該工作階段中處理語音對話的各個回合、工具呼叫、插話中斷及任務交接。
import { RealtimeAgent, RealtimeSession } from "@openai/agents/realtime";
const ephemeralKey = process.env.OPENAI_REALTIME_EPHEMERAL_KEY;
if (!ephemeralKey)
throw new Error("Set OPENAI_REALTIME_EPHEMERAL_KEY from your server.");
const agent = new RealtimeAgent({
name: "Assistant",
instructions: "You are a helpful voice assistant.",
});
const session = new RealtimeSession(agent, {
model: "gpt-realtime-2.1",
});
await session.connect({
apiKey: ephemeralKey,
});接著,以和文字智慧體相同的方式,為 RealtimeAgent 加入工具、任務交接和防護機制。在工作階段層處理音訊傳輸,並在智慧體定義中實作業務邏輯。
如需控制底層傳輸,請先參閱下列文件:
安全識別碼
如果應用程式能識別個別終端使用者,請在 Realtime API 請求中附上安全識別碼。OpenAI 建議使用安全識別碼,但這並非必要條件。安全識別碼可協助 OpenAI 偵測有害行為,並將處置範圍限於個別使用者,避免影響整個組織。請選用固定且能保護隱私的值,例如內部使用者 ID 的雜湊值。
傳送 Realtime API 請求時,請將識別碼放在 OpenAI-Safety-Identifier 標頭中。使用短效 Token 時,請在伺服器端建立用戶端密鑰的請求中設定此標頭,將識別碼與工作階段建立關聯。從受信任的伺服器透過 WebSocket 或統一的 WebRTC 介面連線時,請在連線請求中設定此標頭。
Realtime 工作階段不會沿用 Responses API 請求或其他工作階段的安全識別碼。如果在應用程式的其他地方使用 Responses API 的 safety_identifier 參數,請在每次建立或連線至 Realtime 工作階段時傳入相同的固定值。
從 Beta 版遷移至正式版(GA)
如果應用程式仍使用 Realtime 的 Beta 版介面,請先將現有整合遷移至 GA 介面,再繼續新的開發工作。主要變更如下:
- 呼叫 GA 介面時,請移除
OpenAI-Beta: realtime=v1標頭。 - 使用
POST /v1/realtime/client_secrets為瀏覽器或行動用戶端建立短效憑證。 - 建立 WebRTC 工作階段時,請使用
/v1/realtime/calls。 - 更新工作階段和事件的資料結構,以符合 GA 介面的要求。請特別留意以下變更:設定
session.type,將輸出音訊設定移至session.audio.output下,並改用新版回應事件名稱,例如response.output_text.delta、response.output_audio.delta和response.output_audio_transcript.delta。 - 如果要遷移語音到語音應用程式,請從瀏覽器範例開始。如果要遷移轉錄工作流程,請參閱即時轉錄。
如需瞭解目前的 GA 流程,請參閱 Realtime 用戶端事件參考文件、Realtime 工作階段參考文件和瀏覽器範例。
後續步驟
- 管理對話:設定工作階段,並處理音訊、文字和事件。
- 語音活動偵測:設定如何自動偵測發言回合。
- 工具與 MCP:加入函式、MCP 伺服器和連接器。
- 為語音模型撰寫提示詞:參閱所用 Realtime 模型的對應指南。
- 成本最佳化:瞭解 Realtime 如何計算用量,以及快取的運作方式。
- 伺服器端控制:在伺服器上執行工具並控制工作階段。
其他音訊工作流程
選擇工作流程的指引與各流程共用的音訊術語現已收錄於音訊與語音。如需持續翻譯,請使用即時翻譯。如需產生即時字幕,請使用即時轉錄。如需轉錄已錄製的音訊,請使用檔案轉錄。