选择您使用的 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 与应用中的用户记录和对话记录一并保存。 -
从服务器连接到以下 WebSocket URL,将占位符替换为先前保存的 ID,保留 ID 的原始值。使用创建或接受该会话时所用的项目凭据,通过
Authorization: Bearer $OPENAI_API_KEY进行身份验证。请一并发送创建会话时所需的相同连接请求头。wss://api.openai.com/v1/live/sessions/{session_id}/attach -
通过接入会话的套接字接收事件和发送命令。会话已在运行,请勿再次发送
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 非空,它必须指向现有的客户端委派。有关配置、函数执行和追加上下文的示例,请参阅委派与工具。
对于浏览器会话,麦克风输入和扬声器输出应继续使用已协商好的 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",
},
});- 请求的响应包含
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 URL 发送 webhook,通知应用当前的会话状态。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 连接。该连接会在整个 SIP 通话期间保持打开。
接下来,您可以通过该 WebSocket 连接收发事件来控制通话,方式与通过 WebSocket 发起会话时相同。您可以监控通话、动态更新指令并响应工具调用。