值班记录：Gemini整段回包与流式回包的接入要点

接班时收到一个需求：把一段故障记录交给Gemini，生成交接摘要。后台任务希望拿到结果后直接保存，聊天窗口希望让用户边等边读。这两种交付方式，分别适合用generateContent和streamGenerateContent。它们都用于生成内容，主要区别在于答案怎样返回。([ai.google.dev](https://ai.google.dev/api))

同一份摘要请求，可以整段交付或分块送达

调用generateContent后，程序等待本次生成结束，再收到一个完整响应。可以把它想成值班员写好交接单后一次递过来。对于摘要归档、内容分类等需要拿到结果再处理的任务，这种方式比较容易组织程序流程。([ai.google.dev](https://ai.google.dev/api))

调用streamGenerateContent后，程序会陆续收到响应片段。直接使用接口时，可以通过SSE，也就是服务器发送事件，持续接收这些片段。聊天窗口可以将收到的文字逐步显示出来，让用户看到回答正在形成。这里的“流式”描述的是交付过程；选择时应考虑界面是否需要逐步展示。([ai.google.dev](https://ai.google.dev/api))

先看懂contents，再处理返回的文字

两种方法使用相同的请求结构。入门时，先关注模型名称和contents。contents承载发送给模型的内容，每条内容可以包含role和parts：role表示发言角色，parts放具体材料。一次简单提问可以只放一段文字；继续追问时，需要把相关对话历史和新问题一起提供给模型。([ai.google.dev](https://ai.google.dev/api/generate-content))

例如，让Gemini 3.8 Flash“把以下故障记录整理成三条交接事项”，可以先用generateContent跑通请求，再为聊天界面加入流式接收。响应里的candidates可以理解为候选回答，回答内容放在content的parts中。流式接口返回的是一串GenerateContentResponse对象，因此接收程序需要逐块处理其中的内容。([ai.google.dev](https://ai.google.dev/api/generate-content))

流式接收要把“正在生成”与“已经完成”分开

建议给界面设置等待、接收中、完成和失败几个明确状态。这样，用户看到部分文字时，程序仍能准确表达这次请求是否已经结束。

• 收到内容片段后，按顺序更新显示，并保留已接收的内容供后续处理。
• 如果目标是结构化数据，应在收集完成并校验通过后，再提交给下游业务。
• 如果连接中途断开，应提示回答尚未完成，让用户能够识别当前内容的状态。
• 记录请求失败时的状态和错误信息，为重试或排查保留依据。

排查失败时，可以先检查模型名称、接口版本和参数是否匹配。对于限流或服务暂时不可用等可重试错误，应限制重试次数，并逐步延长等待时间；参数错误则应先修正请求。Google的排障文档也建议采用这种处理顺序。([ai.google.dev](https://ai.google.dev/gemini-api/docs/troubleshooting))

通过Relay365接入时，先确认客户端协议

如果项目还需要接入多个模型家族，可以考虑按量付费的Relay365中转服务。它可配合Claude Code、Codex、Gemini CLI及OpenAI SDK使用。配置前，建议先确认所用客户端的请求格式、模型标识和流式事件格式，尤其要核对Gemini原生接口与OpenAI兼容接口各自的接入说明。

准备试接入时，可以创建一个Relay365账户，先用一条短摘要验证请求、返回内容和结束状态，再接入实际工作流。首轮验收可同时记录首次显示文字所需时间与完整回答所需时间，分别观察等待体验和任务完成情况。