大模型 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 等语义事件。它们是事件类型,不是浏览器断线后的自动恢复协议。

服务端要保存的不是一段最终字符串
如果服务端只保存当前拼接后的全文,重连时很难判断客户端已经收到哪一部分。建议以任务为主键,以事件序号为游标保存增量片段,至少记录以下字段:
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、连接异常或进程重启时,任务先保持可判断状态;只有确认没有终态、且业务允许重新生成时,才进入一次新的尝试。新的尝试必须拥有自己的响应记录,不能把两个响应的增量文本直接拼起来。

可以把策略写成三种结果:
- 可重放:任务仍在运行,服务端有连续事件,客户端只补缺失序号。
- 可查询:上游或业务服务能按响应标识取得完整结果,客户端读取完整结果而不是拼接新流。
- 不可恢复:上游没有续流或结果查询语义,且任务已丢失;此时返回明确失败,让调用方决定是否重新生成。
哪些做法看似续传,实际上会制造重复内容
- 浏览器断线后直接再次调用模型 API,并把新响应追加到旧文本后面。
- 用文本长度作为游标,忽略多字节字符、事件边界和非文本事件。
- 只把最终全文写入缓存,不记录事件序号,导致无法判断缺口。
- 客户端收到片段后立即确认,但服务端还没有落盘,形成“已显示、不可重放”的窗口。
- 没有
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 一致时不要自动拼接;可以返回失败、读取已有完整结果,或让用户明确发起重新生成。
-
501 收藏
-
501 收藏
-
501 收藏
-
501 收藏
-
501 收藏
-
230 收藏
-
231 收藏
-
294 收藏
-
144 收藏
-
230 收藏
-
375 收藏
-
308 收藏
-
160 收藏
-
386 收藏
-
419 收藏
-
141 收藏
-
164 收藏
-
- 前端进阶之JavaScript设计模式
- 设计模式是开发人员在软件开发过程中面临一般问题时的解决方案,代表了最佳的实践。本课程的主打内容包括JS常见设计模式以及具体应用场景,打造一站式知识长龙服务,适合有JS基础的同学学习。
- 立即学习 543次学习
-
- GO语言核心编程课程
- 本课程采用真实案例,全面具体可落地,从理论到实践,一步一步将GO核心编程技术、编程思想、底层实现融会贯通,使学习者贴近时代脉搏,做IT互联网时代的弄潮儿。
- 立即学习 516次学习
-
- 简单聊聊mysql8与网络通信
- 如有问题加微信:Le-studyg;在课程中,我们将首先介绍MySQL8的新特性,包括性能优化、安全增强、新数据类型等,帮助学生快速熟悉MySQL8的最新功能。接着,我们将深入解析MySQL的网络通信机制,包括协议、连接管理、数据传输等,让
- 立即学习 500次学习
-
- JavaScript正则表达式基础与实战
- 在任何一门编程语言中,正则表达式,都是一项重要的知识,它提供了高效的字符串匹配与捕获机制,可以极大的简化程序设计。
- 立即学习 487次学习
-
- 从零制作响应式网站—Grid布局
- 本系列教程将展示从零制作一个假想的网络科技公司官网,分为导航,轮播,关于我们,成功案例,服务流程,团队介绍,数据部分,公司动态,底部信息等内容区块。网站整体采用CSSGrid布局,支持响应式,有流畅过渡和展现动画。
- 立即学习 485次学习