流式响应

实时流式输出实现指南，让 AI 回复如打字般实时呈现

什么是流式响应

流式响应（Streaming Response）允许 API 在生成内容的同时逐块返回数据， 而不是等待完整回复生成后再一次性返回。这种方式让用户可以实时看到 AI 的回复， 显著提升交互体验，尤其适合对话式应用。

对真实产品来说，流式输出的价值不只是“更酷”，而是能显著降低等待感。对于长回答、代码生成、报告输出和多轮聊天来说，用户往往更愿意看到内容持续出现，而不是长时间空白等待。

Python 流式实现

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")
model = genai.GenerativeModel('gemini-2.0-flash')

# 流式生成
response = model.generate_content("讲一个科幻故事", stream=True)

for chunk in response:
    print(chunk.text, end="", flush=True)

Node.js 流式实现

const { GoogleGenerativeAI } = require("@google/generative-ai");
const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-2.0-flash" });

const result = await model.generateContentStream("讲一个科幻故事");
for await (const chunk of result.stream) {
  process.stdout.write(chunk.text());
}

SSE (Server-Sent Events)

// 前端使用 EventSource 接收流式数据
const eventSource = new EventSource('/api/stream');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  appendToChat(data.text);
};

eventSource.onerror = () => {
  eventSource.close();
};

前后端实现思路

  • 服务端调用 Gemini 的流式接口，逐块接收内容。
  • 将内容通过 SSE、WebSocket 或分块响应继续推送给前端。
  • 前端边接收边渲染，避免用户长时间等待完整结果。
  • 流结束后再统一补充结束标记、引用信息或额外元数据。

最常见的问题

  • 中间断流：需要补超时控制和重试策略。
  • 前端渲染抖动：应按块累积，而不是每个字符都强制刷新。
  • 日志难追踪：应记录请求 ID、模型名和流结束状态。
  • 成本不清晰：长输出更需要限制长度和中途终止机制。

什么时候优先用流式响应

聊天类产品，希望用户立即看到内容开始生成。
代码生成或长文本场景，回答往往较长。
需要营造实时互动感的前台界面。
面向终端用户的产品，希望降低等待焦虑。

相关文档

Node.js SDK

结合 JS/TS 服务构建流式接口。

错误处理

为断流、异常和重试补齐处理逻辑。

最佳实践

继续优化性能、成本和稳定性。

什么时候值得优先做流式

  • 你的核心交互是聊天、问答、写作或代码生成。
  • 回答经常较长，用户等待空白时间明显。
  • 你希望界面更像实时助手，而不是一次性返回结果。
  • 前台体验和停留时间对产品非常重要。

什么时候可以先不做

  • 主要是后台批处理、定时任务或一次性结果输出。
  • 用户并不会直接看到生成过程。
  • 当前重点是先打通业务逻辑，而不是优化前台交互感。
  • 系统还没有稳定的错误处理和重试机制，贸然上流式更难排查。
开发说明

流式响应 在 Gemini 接入流程中的作用

流式响应 更适合放在完整接入链路中去理解，而不是孤立阅读。对于 Gemini API 来说，开发者通常不会只靠一页文档完成所有工作，而是需要在快速入门、认证、模型选择、错误处理、安全控制和计费规则之间不断来回对照。

当前页面所覆盖的内容，更多是在帮助你补齐某一个关键环节。实时流式输出实现指南，让 AI 回复如打字般实时呈现 如果这部分理解不够充分，前期也许能跑通，但到了业务扩容、多人协作和生产环境阶段，问题往往会逐渐放大。

阅读这类页面时，最好同时思考自己的项目状态：你是处于试验阶段、正式接入阶段，还是正在做稳定性补强。不同阶段关注的重点不同，页面里的同一段内容，在不同时间点的价值也会不同。

如果你希望当前页面的内容真正服务实际开发，建议边读边确认自己的模型、语言、部署环境和权限策略。这样再回看相关链接时，会更容易形成可执行的开发方案，而不是停留在概念层。

阅读重点

  • 单页文档更适合放回完整接入链路里理解。
  • 开发文档应服务实际项目而不是只解释名词。
  • 上线前建议把认证、异常、成本和安全一起检查。

延伸阅读

API 快速入门错误处理安全指南模型列表

阅读 流式响应 时可以顺手确认的细节

很多技术主题看起来像局部问题，但一旦进入真实项目，就会和模型选择、日志记录、部署环境和调用成本产生连锁关系。因此，单页文档越是基础，越值得结合整体流程去看。

如果当前主题涉及 SDK、接口格式、异常状态或鉴权方式，最好马上用自己的项目场景试着对应一遍。这样可以更快发现还有哪些缺口需要回到其他文档补齐。

对于正式商用场景，建议把文档中的默认用法进一步改造成符合自己环境的实现，例如更明确的重试策略、密钥隔离和监控记录。这样更接近长期可维护的接入方式。

看上下游关系

当前页面通常只是开发链路中的一个节点，前后内容往往同样关键。

看实际环境

浏览器试验、服务端接入和企业环境，对同一主题的要求并不完全相同。

看后续维护

越早把异常处理和权限边界想清楚，后面越容易稳定扩展。