把流式做对:SSE 代理最容易踩的七个坑
流式接口是所有网关功能里最容易「看起来能用、实际一塌糊涂」的部分。Demo 阶段一切正常,上了生产开始出现「偶尔卡住」「最后一段丢了」「明明上游报错了却显示成功」。
帧边界要自己守
上游返回的是一帧一帧的 SSE,你不能假设一次 read 就能拿到完整一帧。必须按空行分隔、按 data: 前缀解析,并且对单帧大小设上限——一个畸形帧就能把内存拉出尖峰。
真正的流式代理要处理三件事:帧的边界、上游的中途报错、以及客户端中途断开时的取消传播。
不对它设限的结果是:一帧畸形数据就能把网关的内存曲线拉成一个尖峰。
上游 200 里也可能藏着错误
有一类故障是 HTTP 200、响应体里裹着 error 事件。对非流式来说这就是失败,应该切换渠道;对流式来说响应头已发,只能冷却该渠道。
很多自建转发在流式上做得糙:要么等上游整个响应回来再切片伪流式,要么把 SSE 帧原样透传但不做任何错误处理。
有一类特别隐蔽的故障:上游返回 HTTP 200,响应体里却裹着一个 error 事件。
取消传播直接影响账单
客户端断开后如果网关不把取消传给上游,上游会把整个响应算完,这部分 token 费用照付。取消传播不是锦上添花,是省钱功能。
所以取消传播不是锦上添花,是直接影响账单的功能。
工具参数必须在流式下聚合
文本增量可以即时交付,但工具参数往往是分片到达的 JSON,必须在有界内存里拼完整再交付。没有这个聚合,模型会拿到半截 JSON 然后开始胡说八道。
流式场景下,工具参数是分片到达的,网关需要在内存里把它们拼接成完整 JSON。
这里必须设上限:单个请求的工具参数总量、工具调用个数、以及非流式响应体大小,都要有硬顶。
实操:用 Node 写一个最小的 SSE 消费端,把流式结果转成纯文本输出。
自己写一个最朴素的 SSE 客户端,能把流式的真实结构看得很清楚。
const res = await fetch("https://aiminis.info/v1/chat/completions", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.GATEWAY_API_KEY}`,
"Content-Type": "application/json",
},
signal: AbortSignal.timeout(120_000), // 流式的超时要比普通请求宽
body: JSON.stringify({
model: "gpt-6-sol",
stream: true,
messages: [{ role: "user", content: "解释一下事件驱动架构" }],
}),
});
const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
while (true) {
const { value, done } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
// SSE 以空行分帧,必须自己攒够一帧再解析
const frames = buffer.split("
");
buffer = frames.pop();
for (const frame of frames) {
for (const line of frame.split("
")) {
if (!line.startsWith("data:")) continue;
const payload = line.slice(5).trim();
if (payload === "[DONE]") return;
const chunk = JSON.parse(payload);
if (chunk.error) throw new Error(chunk.error.message ?? "上游错误");
process.stdout.write(chunk.choices?.[0]?.delta?.content ?? "");
}
}
}
几个容易踩的坑
- 客户端没关闭响应缓冲,看起来像流式其实在攒完一次性吐出。
- 长连接套了统一的写超时,流式输出到一半被网关自己掐断。
- 把上游 HTTP 200 里裹着的 error 事件当成了正常数据解析。
- 客户端断开后没有取消上游,请求算完了但费用照付。
小结
技术上的事大多不复杂,难的是把每个异常分支都想清楚。把这份清单存下来,下次排障会快不少。
文中的示例接口都可以在 https://aiminis.info/ 上直接验证,用量与额度在用户中心 https://aiminis.info/console 随时可查。
- 点赞
- 收藏
- 关注作者
评论(0)