连接到 GPT-Live 后,您可以通过会话事件添加上下文、显示转录文本并管理连接。GPT-Live 可以同时听和说。请分别跟踪转录文本、已播放的音频和后台任务进度,以便在界面中显示助手正在说什么,以及哪些任务仍在运行。
本指南中的大多数操作都假设您的连接已发出 session.started 事件。如果 WebRTC 会话配置为等待用户开口后再开始推理,请参阅管理空闲会话。有关建立连接和流式传输音频的说明,请参阅连接。有关后台任务的说明,请参阅委派与工具。
配置会话
创建会话时,选择模型、音色和委派模式。向模型提供对话指令,并附上相关历史消息。随着对话进行,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 匹配,并在等待期间继续处理错误。关闭会话时,仍在等待确认的追加请求会收到错误。
在对话期间添加上下文
GPT-Live-1.1 与 GPT-Live-1 使用相同的上下文事件。例如,查询预订信息时,可以通过 session.thinking.append 告知模型查询正在进行。后端确认预订后,再使用 session.commentary.append 让模型向来电者告知结果。
根据您希望模型如何使用更新内容,选择相应事件:
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 毫秒结束,不含结束时刻。这些值表示片段的大致时间范围,不能精确定位每个词的起止时间。请依据这些值整理转录文本,而不要依据数据包的到达时间。
只有含文本的时间区间才会产生转录事件,事件到达的间隔也可能不均匀。一个片段可能只包含一句话的一部分,两次事件之间的间隔可能源于网络延迟。增量转录片段没有条目 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后,持续传输输入音频,包括来电者开口前的静音段。使用 WebSocket 时,请继续发送session.input_audio.append。使用 WebRTC 时,请保持输入音轨启用。 - 检查输出音频和转录文本,确认助手已向来电者问候。启动指令可以提高助手主动问候的可能性,但不能保证模型一定会开口。
如果需要确保问候语按预期播放、措辞完全一致,或需要确切知道播放何时结束,请通过应用播放已验证的录音或已渲染的音频片段,并在此期间控制 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% 时,它会在同一会话中启动新的语音引擎以接替原引擎。新引擎会收到原始指令和最多 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 offer 发送到 POST /v1/live/sessions/{source_session_id}/fork。将返回的 transport.sdp 作为 SDP answer 应用于新的对等连接。 |
派生会话会继承源会话的模型、原始指令和输入。启动时,只能发送以下受支持的覆盖设置:
- 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 会话派生 API 参考。
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 offer,并将其发送到后端。以下后端示例使用该 offer 和应用保存的源会话 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 作为 SDP answer 应用于新的对等连接,并保存新的 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"));
}管理空闲会话
使用待机模式可以在空闲期间保持 WebRTC 连接,并在有人说话时恢复推理。如果交互间隔较长且应用可以断开连接,请关闭会话,等用户回来时再启动新会话。
配置待机模式
创建 WebRTC 会话时,将 session.wake_policy.type 设为 speech,即可等到检测到语音后再开始推理。将 session.idle_timeout_s 设为 5 到 60 之间的整数。如果连续这么多秒都没有输入或输出转录文本,会话就会重新进入待机状态。如果省略超时设置,首次唤醒后,推理会持续运行,直到会话结束。
可选字段 session.wake_policy.vad_threshold 用于设置服务器端语音活动检测器(VAD)触发推理的阈值。取值范围为 0 到 1,默认值为 0.5。值越高,检测器就需要越明确的语音迹象才会启动推理。该阈值适用于首次唤醒以及每次暂停后的唤醒。
会话待机期间,请保持麦克风音轨启用。连接和会话 ID 保持不变。用户开口时,会话会恢复运行并还原对话历史。从待机状态恢复后,如果用户说的话很短,收到首次回复可能需要更长时间。
请在带外连接上监听以下事件。如果 WebRTC 数据通道的事件设置允许接收这些事件,也可以在数据通道上监听:
session.resumed表示推理已就绪,首次唤醒时也会发出此事件。session.paused表示空闲超时已触发,推理已停止,会话已进入待机状态。主连接和带外连接均保持开启。
与活跃时段相比,GPT-Live 对待机时段按较低费率计费。
关闭空闲会话并启动新会话
如果应用中的交互间隔较长,可以在没有交互时关闭语音会话,等用户回来时再启动新会话。请保留对话上下文和应用任务状态,以便用户继续交谈,无需重复之前说过的话。例如,驾驶员再次启用语音时,车载助手可以接着之前的对话继续;编程助手则可以在两次语音对话之间保持后台工作进程运行。
- 确定何时关闭。 由应用根据音频活动、助手语音播放情况和用户与应用的交互设置空闲超时。请为阅读、思考等正常停顿留出时间。只有在播放结束且没有待处理任务需要当前语音会话时,才关闭会话。仅凭转录事件之间的间隔,无法判断是否处于静音状态。
- 保存状态并正常关闭会话。 保存源会话 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 秒。请从嵌套的 Responses 完成事件中单独统计后端 Token 用量。有关用量统计,请参阅成本优化。
要正常关闭会话,请执行以下步骤:
- 完成应用所需的所有 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 之前中断,请保留最近一次观测到的用量,并将最终用量标记为未确认。
如果已有完整保存的录音,请从源会话派生新会话,以便继续对话。否则,请使用已保存的相关历史消息创建替代会话。继续对话之前,请向后端核实未完成操作的状态,恢复当前任务状态,并更新结果的路由规则,以免上一会话延迟到达的结果覆盖较新的任务成果。