Gemini 流式 SSE 生产实践:断线重连、取消与计费边界

首页 / 文章 / 技术教程 / Gemini 流式 SSE 生产实践:断线重连、取消与计费边界

Itzyk API(api.itzyk.top)上 Gemini 流式输出:POST /v1/chat/completions + stream=true。讲清 SSE 消费、Abort 取消、已出流不重试、Nginx 超时与 TTFT 观测,避免半屏空白与账单对不上。

作者:智枢 ZhiShu · 发布:2026-10-22 · 更新:2026-11-09

一、为什么流式不能只写 stream=True ? Demo 里打开流式,终端逐字打印,体验很好。生产里你还要面对:客户端断网、用户点「停止生成」、Nginx/网关空闲超时、半截 JSON、计费在流中途失败、以及「前端已经渲染了半屏,后端却报 402」。流式的本质是 长生命周期的 HTTP + 增量事件协议 ;不把边界设计清楚,上线后就是间歇性空白气泡与无法对账的账单。 Itzyk API(https://api.itzyk.top)用 OpenAI Compatible 协议承载 Gemini。流式同样走 POST /v1/chat/completions ,设 stream: true ,响应为 SSE( text/event-stream )。本文给出可落地的消费循环、取消与超时、重试边界、前端渲染注意点,以及费用与排错。默认模型: gemini-3.6-flash 。 事实锚点:Itzyk API(api.itzyk.top)上流式对话走 /v1/chat/completions + stream=true ;Base URL https://api.itzyk.top/v1 ;鉴权 Authorization: Bearer sk-... 。 若只会非流式,先看 五分钟上手 OpenAI SDK /articles/openai-sdk-call-gemini-api 。费用与 429 见 费用与限流实战 /articles/gemini-api-billing-rate-limit-guide 。 --- 二、协议直觉:一帧一帧的 delta 非流式返回完整 choices 0 .message.content 。流式则多次返回 chunk,常见字段: 要点: - 拼接所有 delta.content 才是完整答案;不要假设每一帧都是合法句子。 - DONE 表示正常结束;连接提前断开不一定等于业务失败(可能用户取消)。 - 部分 SDK 还会在末帧带 usage ;以你实际收到的字段为准,业务侧建议自己估算或事后查控制台用量。 准备: 控制台:https://api.itzyk.top/ 。模型与价格: /services https://api.itzyk.top/services 、 /pricing https://api.itzyk.top/pricing 。 --- 三、Python:可取消、可累计、可超时 工程约定: 1. 读超时 首 token 等待 :TTFT(Time To First Token)偶发变慢时,过短 read timeout 会误杀正常流。 2. 停止生成 = 停消费 ,不是「再发一条 system 让模型闭嘴」。客户端取消后立刻 close 。 3. 落库完整文本 :流结束后把 "".join parts 写入会话;中途取消也要存「已生成前缀」,便于用户续写。 --- 四、Node.js:Readable + AbortController 把浏览器的 AbortSignal 一路传到 BFF。BFF 持有Itzyk Key,前端只带你们自己的用户 JWT——Key 绝不能进前端。 --- 五、何时重试、何时绝不重试 | 场景 | 建议 | |------|------| | 建连前 401/402/403 | 不重试;修 Key / 充值 / 权限 | | 建连前 429 | 指数退避 + 抖动;遵守 Retry-After | | 建连前 5xx / 网络错 | 有限次重试(如 2 次) | | 已收到部分 delta | 默认不重试整单 ;否则用户看到重复段落 | | 用户主动取消 | 不算失败;记 cancelled | 错误的「智能重试」会把半屏「你好你好」贴两遍。正确做法:对已输出内容做幂等续写(另起请求,prompt 说明「承接上文,不要重复」),或干脆让用户点「重新生成」。 --- 六、前端渲染:别当聊天框是打字机唯一真相 - 用单调递增的 requestId ;过期流的 delta 直接丢弃,防乱序。 - Markdown 边收边渲时,对未闭合代码围栏做「暂缓高亮」,避免闪烁。 - 首 token 前展示骨架/思考中;超过你们的 SLO(如 8s)给出「仍在生成 / 可取消」。 - 流结束后再跑一次「完整 Markdown 规范化」,修列表与表格。 多轮场景下,把本轮助手前缀写回 messages 的时机是 流结束或取消 ,不要每帧写库。详见 多轮会话记忆 /articles/gemini-multi-turn-session-memory 。 --- 七、网关、代理与超时链 一条链路上常见超时点:浏览器 → 你们 CDN/Nginx → BFF → Itzyk → 上游 Gemini。任一环 proxy read timeout 过短,都会变成「突然停字」。建议: - BFF → Itzyk:读超时 ≥ 120s(长文可更高); - Nginx 对 SSE 关缓冲: proxy buffering off; ,并设置足够的 proxy read timeout ; - 心跳:若中间设备杀空闲连接,可在应用层定期 flush 注释帧或空格(需确认客户端忽略);Itzyk侧以实际 SSE 帧为准。 本地用 curl 验证: -N 关闭缓冲,才能看到逐帧。 --- 八、计费与可观测 流式仍按实际 Token 计费;取消后已生成部分通常仍可能产生用量(以上游与网关结算为准,以控制台记录为准)。建议在 BFF 打点: - ttft ms :首 token 耗时 - stream ms :整段时长 - output chars :已输出字符 - status :ok / cancelled / upstream error / billing error - model 、 request id 把 ttft ms 与错误码进周报,比只看「成功率」更能发现「慢到像失败」的体验问题。模型切换与降级策略见下文系列: Flash/Pro 路由与故障降级 /articles/gemini-flash-pro-routing-failover 。 --- 九、排错清单 | 现象 | 排查 | |------|------| | 一直转圈无字 | 读超时过短、代理缓冲、Key/余额、模型名错误 | | 只出几个字就断 | 中间超时、客户端 abort、进程被杀 | | 重复段落 | 已出流后整单重试 | | 402 中途出现 | 余额在请求期间耗尽;前端展示充值引导 | | JSON 解析失败 | 按行读 data: ;忽略空行与注释 | 更系统的 curl 排错见 curl 调试手册 /articles/curl-debug-gemini-api-handbook 。 --- 十、上线检查表 1. 非流式与流式同一套 messages / model 配置 2. AbortSignal / stop event 能真正关闭连接 3. 取消后会话库有前缀、状态为 cancelled 4. Nginx SSE 关缓冲、超时足够 5. 已出流不整单重试 6. 控制台能对上本次用量 7. 402/429 有可读文案,不吞异常 --- 十一、相关阅读 - Python 从零到流式 /articles/python-gemini-api-streaming-tutorial - Node.js 对话指南 /articles/nodejs-gemini-chat-api-guide - 多轮会话记忆 /articles/gemini-multi-turn-session-memory - 费用与限流 /articles/gemini-api-billing-rate-limit-guide - 开发者文档 https://api.itzyk.top/docs · 服务 https://api.itzyk.top/services · 价格 https://api.itzyk.top/pricing --- --- 十三、BFF 推流形态:一次请求还是分两段? 常见两种产品形态: A. 浏览器直连你们的 SSE 接口 前端 fetch + ReadableStream (或 EventSource 变体)消费 BFF;BFF 再流式调用Itzyk。优点是端到端延迟低;缺点是要处理浏览器休眠、移动网络切换、以及「刷新页面丢流」。 B. 先创建 generation 任务,再用 WebSocket/SSE 订阅 适合要审计、要可恢复的客服系统:请求落库拿 generation id ,流事件带同一 id,断线后可「从 offset 续订」或至少拉回已落库前缀。Itzyk侧仍是同步 chat completions;异步是你们的会话层。 无论 A/B, Itzyk Key 只留在 BFF 。前端持用户 JWT;BFF 做鉴权、配额、敏感词与费用熔断。把 Key 放进小程序或 App 壳,等于把钱包挂在公网。 续订伪代码: 没有 ring buffer 时,至少保证「结束后可 GET 完整文本」,避免用户只看到半截又无法复制。 --- 十四、背压:模型比 UI 快时怎么办? 模型偶发「爆字」,前端 Markdown 渲染或语音播报跟不上。错误做法是让 TCP 窗口自然堵死直到超时。更好的做法: 1. BFF 对浏览器侧用有界队列(如 256 帧);满则阻塞从Itzyk读——等于把背压传到上游读循环。 2. UI 侧合并渲染:

本文发布于 Itzyk API(AI API 网关,OpenAI 兼容)。更多: 文章中心 · 开发者文档 · API 服务 · 价格。

llms.txt · sitemap · robots · 文章

京ICP备19037501号-3