如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

管理 GPT-Live 会话

配置会话、维护上下文并管理对话生命周期。

连接到 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 事件中包含这条消息。这样,模型从会话开始就能获得问候指令。

请指定问候的语言、助手应说的内容,并要求助手立即开口,随后停下来听对方说话。在来电者开口前,使用应用选定的问候语言。例如,开发者消息可以这样写:

现在用英语问候来电者。介绍自己是客服助手,并询问对方需要什么帮助。然后停下来听对方说话。

  1. 将该消息添加到 session.input,设置 role: "developer",并提供一个 input_text 内容部分。消息格式请参阅用历史对话初始化会话。
  2. 收到 session.started 后,持续传输输入音频,包括来电者开口前的静音段。使用 WebSocket 时,请继续发送 session.input_audio.append。使用 WebRTC 时,请保持输入音轨启用。
  3. 检查输出音频和转录文本,确认助手已向来电者问候。启动指令可以提高助手主动问候的可能性,但不能保证模型一定会开口。

如果需要确保问候语按预期播放、措辞完全一致,或需要确切知道播放何时结束,请通过应用播放已验证的录音或已渲染的音频片段,并在此期间控制 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 执行控制操作、建立带外连接,并将后续后台结果路由到新会话。

为派生会话做准备

  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 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 对待机时段按较低费率计费。

关闭空闲会话并启动新会话

如果应用中的交互间隔较长,可以在没有交互时关闭语音会话,等用户回来时再启动新会话。请保留对话上下文和应用任务状态,以便用户继续交谈,无需重复之前说过的话。例如,驾驶员再次启用语音时,车载助手可以接着之前的对话继续;编程助手则可以在两次语音对话之间保持后台工作进程运行。

  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 秒。请从嵌套的 Responses 完成事件中单独统计后端 Token 用量。有关用量统计,请参阅成本优化。

要正常关闭会话,请执行以下步骤:

  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 之前中断,请保留最近一次观测到的用量,并将最终用量标记为未确认。

如果已有完整保存的录音,请从源会话派生新会话,以便继续对话。否则,请使用已保存的相关历史消息创建替代会话。继续对话之前,请向后端核实未完成操作的状态,恢复当前任务状态,并更新结果的路由规则,以免上一会话延迟到达的结果覆盖较新的任务成果。