Gemini Live API 的 session resumption 怎么避免实时语音会话中断：恢复令牌与重连边界

实时语音助手最怕的不是一次网络抖动，而是 WebSocket 断开后用户还得从头说一遍。Gemini Live API 的连接寿命和会话状态是两件事：连接可以结束，会话却能借助 session resumption 跨连接续上。实现时保存服务端发来的最新句柄，在下一次连接的 sessionResumption.handle 中带回，同时把正在生成的那一轮和不可恢复点单独处理。

可靠的重连不是“断线就重新 connect”，而是只在拿到可恢复句柄时续接上下文；遇到生成中或函数调用中的不可恢复点，要先完成或丢弃当前轮次，再决定是否建立新会话。

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

Live API 的 session 是持续传输音频、视频或文本的连接，但连接本身可能在大约 10 分钟后结束。若不开启上下文窗口压缩，音频会话和音视频会话还分别受到约 15 分钟、2 分钟的上下文限制。连接生命周期到了，不代表业务上必须丢掉已有对话；session resumption 就是给下一条连接提供恢复入口。

这也解释了一个常见误区：客户端自己保存最近几句转写，只能重建部分文本，不能等价替代服务端会话恢复。恢复句柄由服务端消息提供，客户端要把它当作短期状态保存，而不是自造一个字符串。

用 sessionResumption 保存最新恢复句柄

建立连接时在配置中打开 sessionResumption。服务端随后会发送 SessionResumptionUpdate，其中的 newHandle 代表一个可以尝试恢复的状态。每次收到新更新，都覆盖旧句柄；如果 resumable=false 或句柄为空，就不要把它当作可恢复检查点。

let previousHandle = null;

function onMessage(message) {
  const update = message.sessionResumptionUpdate;
  if (update && update.resumable && update.newHandle) {
    previousHandle = update.newHandle;
  }
}

function nextConfig() {
  return {
    responseModalities: [Modality.AUDIO],
    sessionResumption: { handle: previousHandle }
  };
}

这里的关键是“最新”。旧句柄可能仍在有效期内，却不一定代表最近一次可恢复的状态。首次连接可以把 handle 留空；重连时再传入刚刚保存的 previousHandle。

不可恢复点不能靠重试掩盖

官方 WebSocket 参考说明，模型正在生成或执行函数调用时，恢复点可能暂时不可用。此时消息会表明当前状态不可恢复；客户端如果仍然把空句柄写入持久状态，下一次连接就可能退化成新会话。更稳妥的做法是保留上一个有效句柄，同时给当前生成标记为待收尾或待重新发起。

GoAway 到达前如何决定重连

服务端关闭连接前会发送 GoAway，其中的 timeLeft 表示还剩多少连接时间。收到它时不要立刻关闭正在播报的音频，也不要把它误判成 generationComplete。前者是连接层预警，后者才是模型完成当前响应的业务信号。

let reconnectPlanned = false;
let generationDone = false;

function onGoAway(goAway) {
  if (goAway.timeLeft > 0) {
    reconnectPlanned = true;
  }
}

function onServerContent(content) {
  if (content.generationComplete) {
    generationDone = true;
  }
}

function shouldReconnect() {
  return reconnectPlanned && generationDone && previousHandle !== null;
}

示例只表达决策关系：先收到 GoAway，再等待 generationComplete，最后用已经保存的句柄连接。真实客户端还要把麦克风发送、播放器排空和连接关闭放进同一个状态机，避免新旧连接同时消费音频。

上下文压缩和恢复句柄要一起评估

长时间音频对话还需要考虑上下文窗口压缩。官方建议通过滑动窗口压缩延长会话；这解决的是上下文累积问题，不会替客户端保存恢复句柄。两者职责不同：压缩控制会话能走多远，session resumption 处理连接断开后的续接。

恢复句柄也有保留边界。官方文档给出的有效期是上一次会话终止后 2 小时；如果业务要求零数据保留，则不应配置 session resumption。生产环境要把句柄当作敏感短期凭据管理，限制日志打印和跨用户共享。

用四组状态验证重连实现

联调时至少模拟服务端周期关闭、生成中收到 GoAway、函数调用中收到不可恢复更新、句柄超过 2 小时四种情况。日志只记录状态名和时间差，不要打印恢复句柄本身。

常见问题：Gemini Live API 重连怎么排查

为什么重新连接后上下文还是丢了？

先检查下一条连接是否真的传入了最新的 sessionResumption.handle，以及上一条更新是否标记为可恢复。只保存客户端转写文本，不能证明服务端会话已恢复。

收到 GoAway 就应该马上断开吗？

不应该。GoAway 是连接即将结束的提示，要结合 timeLeft 和 generationComplete 安排收尾，避免截断当前响应。

session resumption 能无限保留会话吗？

不能。恢复句柄在上一次会话终止后有 2 小时有效期；上下文压缩和句柄恢复也都受服务端会话状态规则约束。

把重连变成可验收的状态机

实现的验收标准可以落到三个可观测点：是否持续保存可恢复的最新句柄，是否等到当前生成完成后再切换，是否在句柄失效或不可恢复时明确降级。把这些信号写进测试而不是只看“WebSocket 已连接”，重连才不会在演示环境正常、真实语音流里丢上下文。