OpenAI Realtime API 怎样处理断线后的会话恢复

OpenAI Realtime API 断线后，应用不能只把旧 WebSocket 再次打开就认为会话已经恢复。更稳妥的做法是把“传输连接”和“业务会话状态”分开：连接断开时保存事件确认点、会话摘要和待发送输入；重新建立 WebSocket 或 WebRTC 后，再发送新的 session.update，按确认点补回上下文，最后只对完整的新输入触发 response.create。这样能避免半截音频重复播放，也能减少重连后的上下文漂移。

官方文档：https://developers.openai.com/api/docs/guides/realtime

• 连接层：只负责 socket、WebRTC、鉴权和断线状态。
• 状态层：保存摘要、已确认事件和待确认输入。
• 恢复层：新连接完成初始化后再重放，不重复提交已经确认的旧响应。

先把连接状态和会话状态分开

Realtime 会话包含连续的输入、输出和工具事件，而 WebSocket 或 WebRTC 只是承载这些事件的传输层。官方 WebSocket 指南明确把“连接由 SDK 管理”和“断线后恢复会话状态”分给不同职责：应用仍要保存自己需要恢复的状态。因此不要把唯一的对话记录放在内存里的 socket 对象上。

建议给每条本地事件保留一个稳定的 event_id 或业务序号，并记录三种状态：已发送、服务端已确认、需要重放。音频正在播放时还要记录已播放位置；断线后不要把已经播过的整段音频当成新的用户输入。

重连后先创建新连接，再恢复 session 配置

浏览器场景通常由服务端创建临时客户端密钥，前端用它连接 RealtimeSession；服务端 WebSocket 则使用服务器侧 API 密钥连接。无论采用哪种方式，恢复流程都应把“获取新凭据、建立新连接、收到 session.created、发送 session.update”作为一组动作，直到新连接具备和旧连接一致的模态、工具和输入设置后，才开始重放历史。

下面的代码只展示恢复控制器的核心数据结构。openSocket 和 getEphemeralKey 是项目自己的封装，重点是用单飞锁避免多个断线回调同时重放。

const state = {
  socket: null,
  reconnecting: null,
  // 只把已经确认的消息放进稳定摘要，避免恢复时无限增长
  summary: "",
  confirmed: [],
  pending: [],
};

async function reconnect() {
  // 多个 close/error 事件只共享一次恢复任务
  if (state.reconnecting) return state.reconnecting;
  state.reconnecting = (async () => {
    const key = await getEphemeralKey();
    const socket = await openSocket(key);
    await waitForSessionCreated(socket);

    // 新连接必须重新声明会话配置，不能依赖旧 socket 的内存状态
    socket.send(JSON.stringify({
      type: "session.update",
      session: { type: "realtime", output_modalities: ["text"] },
    }));
    state.socket = socket;
    await replayConfirmedContext(socket, state.summary, state.confirmed);
    await replayPendingInput(socket, state.pending);
  })().finally(() => {
    // 允许下一次真正的断线重新创建恢复任务
    state.reconnecting = null;
  });
  return state.reconnecting;
}

按确认点重放摘要和未确认输入

不要把所有历史音频原样重放。更实用的做法是周期性生成短摘要，把已经收到 conversation.item.done 的用户消息或工具结果归入确认区；断线瞬间仍在发送、但还没有确认的输入放入待确认区。重连后可通过 conversation.item.create 写入需要恢复的用户输入，再决定是否创建新的响应。

如果上下文很长，可以只重放摘要和最近几条关键消息。若应用需要让模型看到某个已有 item，可以在 response.create 的输入上下文中引用 item ID；不要把客户端本地的临时 ID 当成服务端已经存在的 item ID。

只对完整输入触发新的 response.create

最容易重复回答的错误，是连接刚恢复就无条件发送 response.create。如果断线前的响应已经完成，应该等待新的用户输入；如果断线发生在模型输出中间，应由播放器和事件账本决定是否丢弃未播放片段，再把需要继续的用户意图整理成一条新的完整输入。只有当重放完成且输入边界明确时，才发送：

function requestNextResponse(socket) {
  // response.create 只对应一组完整、未重复提交的输入
  socket.send(JSON.stringify({
    type: "response.create",
    response: { output_modalities: ["text"] },
  }));
}

语音应用还要处理用户打断：停止播放、记录实际播放位置，并按文档使用 conversation.item.truncate 清除未播放的音频部分。这样恢复时模型看到的音频上下文与用户实际听到的内容更接近。

过期凭据、重复事件和并发重连怎么处理

临时密钥过期时不要重放旧凭据，直接让服务端重新签发；重放事件时用业务序号或幂等键过滤已经确认的消息；多个 close、error 和网络恢复回调同时到达时，只保留一个 reconnecting Promise。恢复失败则退回“需要用户重新开始”或“仅恢复摘要”的明确状态，不要静默伪造完整上下文。

最后可以用下面这张表快速判断：

常见问题

Realtime API 会自动替我恢复历史吗？

不要把自动重连和业务上下文恢复混为一谈。传输库可以帮助建立连接，但应用仍要保存并恢复自己需要的会话状态。

恢复后要不要立刻发送 response.create？

只有在重放完成、输入边界明确且确实存在需要回答的新输入时才发送；单纯收到 session.created 不代表应该生成新答案。

应该保存完整音频还是摘要？

按任务取舍：短对话可保留最近输入，长对话优先保存摘要和确认点；正在播放的输出另存播放位置，避免恢复时重复播报。

总结：断线恢复的核心不是“把旧连接拉回来”，而是把连接、事件确认点和会话上下文拆开管理。新连接完成 session.update 后，再恢复摘要与未确认输入，最后用一次新的 response.create 继续对话。