登录
推荐 文章 Go 技术 课程 下载 专题 AI
首页 >  科技周边 >  人工智能

大模型 API 流式输出的断线续传处理方案

来源:17golang原创

时间:2026-11-18 00:02:29 403浏览 收藏

大模型 API 的流式输出通常是 stream=true 的 Server-Sent Events(SSE):服务端把生成过程拆成多个事件,客户端边收边显示。真正可靠的“断线续传”不能只在浏览器里重新发起一次请求,因为那很可能会启动第二次生成。更稳妥的做法是让业务服务持有任务和事件检查点,客户端只按游标补齐自己缺失的片段。

官方地址:https://developers.openai.com/api/docs/guides/streaming-responses

先区分两种断线:客户端与业务服务之间断开时,可以用序号和重放实现无缝恢复;业务服务与模型 API 之间断开时,只有在上游明确提供可恢复语义时才能继续,否则应把重试当作一次新的生成,不能把两次结果直接拼接成“续传”。
这套方案的核心
  • 上游只负责产生流事件,业务服务负责把事件变成可重放记录。
  • 每个片段拥有单调递增的 seq,客户端重连时携带最后确认的序号。
  • 任务使用幂等键去重,response.completed、error 等终态决定是否还能重试。
  • 不把“重新请求模型”误写成“从上一个 token 继续生成”。

先把断线拆成两个独立边界

流式链路至少有三层:模型 API、业务服务、最终客户端。模型 API 到业务服务的连接负责取得上游事件;业务服务到客户端的 SSE 连接负责把事件送给浏览器或 App。两条连接的故障表现相似,但恢复策略完全不同。

断线位置可以恢复什么推荐动作
客户端 ↔ 业务服务已经写入服务端的事件按 seq 重放缺口,再订阅新事件
业务服务 ↔ 模型 API取决于上游是否有恢复语义保留任务状态;没有原生续流时不要拼接两次生成
业务服务进程重启已落盘的任务和片段从任务表恢复,未完成任务进入可重试或失败终态

官方流式文档把 Responses API 的输出描述为 SSE,并列出 response.created、response.output_text.delta、response.completed 和 error 等语义事件。它们是事件类型,不是浏览器断线后的自动恢复协议。

大模型流式输出从请求标识、Response ID、SSE 事件到检查点存储和客户端渲染的静态关系图
图1:请求身份、SSE 事件、检查点和客户端展示之间的关系说明图,用于理解哪一层负责保存与重放;不是运行截图或运行证据。

服务端要保存的不是一段最终字符串

如果服务端只保存当前拼接后的全文,重连时很难判断客户端已经收到哪一部分。建议以任务为主键,以事件序号为游标保存增量片段,至少记录以下字段:

  • task_id:业务任务标识,贯穿客户端重连和日志。
  • idempotency_key:同一提交动作的幂等键,防止重试重复创建任务。
  • response_id:上游响应标识,用于关联官方返回的生命周期。
  • seq:业务服务生成的单调序号,不能直接依赖网络到达顺序。
  • delta:当前事件承载的增量文本或结构化片段。
  • status:running、completed、failed、expired 等终态。

写入事件时,先把事件落到可恢复存储,再向客户端发送;如果顺序反过来,网络恰好在发送后断开,客户端可能看到了片段,而服务端没有记录,下一次重连就无法准确补齐。这个取舍会增加一点写入开销,但换来了明确的恢复边界。

客户端重连应携带最后确认的游标

客户端不要把“已经渲染过的字符数”当作可靠游标,因为一个事件可能包含多个 Unicode 字符,也可能包含工具调用或非文本事件。更稳的做法是服务端为每个可重放事件分配 seq,客户端只确认已经完整处理的序号。

下面的 TypeScript 片段展示业务层的关键接口。它没有把重新请求模型包装成上游续流,而是把“客户端重连”和“上游任务重试”拆开;真实项目中,store 可以由数据库、Redis Stream 或持久化消息日志实现。

type TaskStatus = "running" | "completed" | "failed" | "expired";

interface StreamEvent {
  taskId: string;
  seq: number;
  type: string;
  delta?: string;
  responseId?: string;
}

interface StreamStore {
  // 中文注释:读取客户端已经确认之后的事件,保证重连只补缺口。
  readAfter(taskId: string, seq: number): Promise;
  // 中文注释:先持久化再发送,避免“客户端看到了但服务端没有记录”。
  append(event: StreamEvent): Promise;
  // 中文注释:任务状态是重试和结束判断的唯一来源。
  getStatus(taskId: string): Promise;
}

async function replayMissing(
  store: StreamStore,
  taskId: string,
  lastConfirmedSeq: number,
  send: (event: StreamEvent) => void,
) {
  const missing = await store.readAfter(taskId, lastConfirmedSeq);
  for (const event of missing) {
    // 中文注释:按 seq 顺序重放,客户端收到后再推进自己的确认游标。
    send(event);
  }

  const status = await store.getStatus(taskId);
  if (status === "completed" || status === "failed" || status === "expired") {
    // 中文注释:终态任务只需要补历史,不再建立一个永不结束的实时订阅。
    send({ taskId, seq: lastConfirmedSeq, type: `task.${status}` });
  }
}

这段代码只解决客户端到业务服务这一段:如果客户端断在第 18 个事件,服务端可以从 seq=18 之后重放。它没有声称模型供应商会从第 18 个 token 继续生成,这个边界必须在接口设计文档中写清楚。

上游重试要靠幂等键和终态保护

业务服务连接模型 API 时,应先创建任务记录,再启动上游流。客户端重复点击、移动网络反复重连,都只带来同一个 idempotency_key 的查询或订阅,不应该创建两个并行生成任务。

上游流正常完成时,收到 response.completed 后再把任务改成 completed。收到 error、连接异常或进程重启时,任务先保持可判断状态;只有确认没有终态、且业务允许重新生成时,才进入一次新的尝试。新的尝试必须拥有自己的响应记录,不能把两个响应的增量文本直接拼起来。

用户消息、幂等键、请求记录、流式响应、已确认片段、重放缓冲和完成标记的静态关系图
图2:幂等键、请求记录、重放缓冲和终态保护的关系说明图,帮助区分“重连订阅”和“重新生成”;不是运行截图或运行证据。

可以把策略写成三种结果:

  • 可重放:任务仍在运行,服务端有连续事件,客户端只补缺失序号。
  • 可查询:上游或业务服务能按响应标识取得完整结果,客户端读取完整结果而不是拼接新流。
  • 不可恢复:上游没有续流或结果查询语义,且任务已丢失;此时返回明确失败,让调用方决定是否重新生成。

哪些做法看似续传,实际上会制造重复内容

  1. 浏览器断线后直接再次调用模型 API,并把新响应追加到旧文本后面。
  2. 用文本长度作为游标,忽略多字节字符、事件边界和非文本事件。
  3. 只把最终全文写入缓存,不记录事件序号,导致无法判断缺口。
  4. 客户端收到片段后立即确认,但服务端还没有落盘,形成“已显示、不可重放”的窗口。
  5. 没有 completed 与 failed 的终态保护,重连请求会让后台任务越积越多。

如果业务真的要求逐 token 一致,优先把模型调用放进服务端任务,并让客户端只连接自己的可恢复 SSE;如果业务只需要“最终答案尽量可用”,可以在新尝试中重新生成,但要向用户标记这是重新生成而不是原流续接。

上线前应观察哪些指标

断线续传不是只看 HTTP 200。至少记录任务创建数、客户端重连数、重放事件数、重复事件数、上游异常数、任务最终状态和恢复耗时。特别关注“客户端重连成功但任务已失败”的比例,以及同一个幂等键关联多个上游响应的数量;后者通常说明任务去重边界没有生效。

指标能回答的问题
replay_events客户端平均丢了多少已落盘事件
duplicate_events是否重复发送或重复渲染同一序号
upstream_retry_count上游连接异常是否集中在某个模型或网络链路
resume_success_rate断线后最终回到 completed 的比例

结语

大模型 API 的流式输出适合降低首字节等待,但 SSE 连接本身不等于可恢复任务。把事件序号、检查点、游标重放、幂等键和终态保护放在业务服务层,才能把客户端断线变成可控的订阅恢复;对上游重新生成则要保持诚实的语义边界,不把“新请求”包装成“原响应续传”。

常见问题

重新连接 SSE 时可以使用浏览器的 Last-Event-ID 吗?

可以把它作为传递游标的一个载体,但业务服务仍应校验任务身份、序号范围和任务状态。不要假设模型 API 会因为这个请求头自动恢复原始生成。

为什么不直接保存完整答案?

完整答案适合最终归档,但不适合作为唯一恢复依据。只有事件序号才能说明客户端缺少哪一段,也能避免重放时重复追加。

模型 API 重试后内容不同怎么办?

把它记录为新的生成尝试,保留原任务的失败原因和新响应标识。需要逐 token 一致时不要自动拼接;可以返回失败、读取已有完整结果,或让用户明确发起重新生成。

声明:本文转载于:17golang原创 如有侵犯,请联系study_golang@163.com删除
相关阅读
更多>
最新阅读
更多>
课程推荐
更多>