Gemini API/Gemini 响应、流式与错误处理

Gemini generateContent 响应结构、多内容块 SSE 流式聚合、usageMetadata 统计指标与跨云通道错误容灾及响应自愈重试。

Gemini 响应、流式与错误处理

本文档详细说明通过 UniGateway 调用 Gemini API 时的响应体结构(candidates 与 usageMetadata)、Server-Sent Events (SSE) 流式传输规范、多内容块聚合机制、标准错误响应格式以及跨通道容灾故障转移与响应自愈重试策略。


章节导引

本篇为 Gemini API 参考文档的第 7 章节:

  1. Gemini 概览与接入
  2. generateContent 概述与快速开始
  3. 请求参数与多模态内容格式
  4. 扩展思考与思维链签名
  5. 工具调用与搜索检索
  6. 结构化输出与生成配置
  7. 响应、流式与错误处理(当前章节)

响应体结构与字段规范

非流式 POST /v1beta/models/{model}:generateContent 请求成功完成后,API 返回如下格式的 JSON 对象:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "thought": true,
            "text": "用户询问分布式系统的 CAP 定理。我需要简要阐明一致性、可用性与分区容错性的权衡关系..."
          },
          {
            "text": "CAP 定理指出,在分布式数据存储系统中,无法同时满足以下三个保证..."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 24,
    "candidatesTokenCount": 182,
    "totalTokenCount": 206
  },
  "modelVersion": "gemini-3.1-flash"
}

1. 核心字段说明

字段类型说明
candidates[]array模型生成的候选回复数组(默认包含 1 个候选)。
candidates[].contentobject生成内容主体,包含 role: "model" 与 parts 数组。
candidates[].content.parts[]array内容块列表。包含思考文本块(thought: true)、正文文本块、工具调用(functionCall)或多模态数据。
candidates[].finishReasonstring生成停止原因:<br>• STOP:自然生成结束<br>• MAX_TOKENS:达到 maxOutputTokens 上限<br>• SAFETY:触发安全内容策略拦截<br>• RECITATION:触发重复率引用拦截
usageMetadataobject本次调用的 Token 消耗统计,包含 promptTokenCount、candidatesTokenCount 与 totalTokenCount。
modelVersionstring实际处理请求的模型版本标识。

Server-Sent Events (SSE) 流式传输

当调用流式端点 POST /v1beta/models/{model}:streamGenerateContent?alt=sse 时,API 将以 text/event-stream 格式持续推送事件增量。

1. 流式响应格式

每个 SSE chunk 遵循标准事件流格式:

data: {"candidates":[{"content":{"parts":[{"text":"CAP 定理指出..."}],"role":"model"},"index":0}]}

data: {"candidates":[{"content":{"parts":[{"text":"一致性(Consistency)..."}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":24,"candidatesTokenCount":50,"totalTokenCount":74}}

2. 高保真多内容块聚合管道

在网关执行流式与非流式互转或中间层观测时,UniGateway 采用确定性的多块合并算法(mergeCollectedPartsToResponse):

  • 全要素合并:保全思考块(thought: true)、正文文本、工具调用块(functionCall 及 args 拼接)与加密签名(thoughtSignature);
  • 元数据保留:完整保留末轮返回的 usageMetadata 与 groundingMetadata 搜索引用标记;
  • 安全过滤保护:当流式末尾出现内容安全截断时,确保 finishReason 与阻断状态准确回传,避免状态丢失;
  • 流式中继异常净化:在流式输出生命周期中,若捕获到上游在通道或事件流中携带的非标或中继异常信息,网关通过清洗管道将其自动规范化为标准的 Google API 错误数据块,掩码底层网络拓扑与私有堆栈信息,且避免过早中断合法连接。

错误处理与响应自愈规范

1. 标准错误响应结构

所有异常响应严格对齐 Google 官方错误格式:

{
  "error": {
    "code": 400,
    "message": "Invalid argument: contents[0].parts must not be empty.",
    "status": "INVALID_ARGUMENT"
  }
}

2. 状态码与网关容灾重试策略

状态码错误状态 (error.status)触发原因与网关处理策略
400INVALID_ARGUMENT参数校验错误。网关首先识别是否为可自愈的模式(includeThoughts 不受支持、thinkingLevel 不受支持、thoughtSignature 损坏、parametersJsonSchema / responseJsonSchema 或扩展 JSON Schema 关键字不兼容);若是则在同账号就地修复并透明重发;若属于包含明确参数诊断的客户端传参错误(包含首包输出前在 SSE 流内返回的带内 400 INVALID_ARGUMENT),则直接返回标准 400 错误响应;若后端仅返回无参数定位的笼统 400 错误,则自动切换候选通道并在耗尽后返回 502(X-Gateway-Error-Class: inference_undetermined_rejection)。
401UNAUTHENTICATEDAPI Key 无效、缺失或过期,网关自动标记并触发通道故障转移。
403PERMISSION_DENIED账号对该模型无权限或已被封禁,网关自动切换到健康备用账号。
404NOT_FOUND请求的模型未在网关发布(若已发布模型在所有候选推理通道均暂不可用,网关在故障转移耗尽后返回 502 与 X-Gateway-Error-Class: inference_model_unavailable)。
408 / 504DEADLINE_EXCEEDED请求超时,网关根据调度策略自动切换通道重试。
409ABORTED / CONFLICT过载与冲突区分:网关区分容量过载与业务状态冲突。当 409 指示暂时性资源枯竭、模型冷却(model_cooldown)、配额耗尽(resource_exhausted)或候选渠道繁忙时,自动将请求故障转移至可用健康通道;当 409 指示资源状态冲突(如 Resource already exists)时,直接透传给客户端。
429RESOURCE_EXHAUSTED触发频次、RPM 或配额限制(含流内带内 INSUFFICIENT_QUOTA 信号),网关对该通道执行静默冷却,并将流量导向其余健康通道。
451UNAVAILABLE_FOR_LEGAL_REASONS触发合规性或地域限制,网关自动执行通道故障转移。
502 / 503INTERNAL / UNAVAILABLE推理服务异常或算力临时过载(含后端 500 / 503 / 529 耗尽场景):网关在跨渠道重试耗尽后返回标准 Google 错误结构及 X-Gateway-Error-Class(如 inference_service_error、inference_capacity_exhausted、inference_overloaded);对于可重试异常,响应头附带 X-Gateway-Retryable: true、Retry-After,并在 error.details 中提供 google.rpc.RetryInfo。

反应式自愈机制一览

为减少因上游协议微差导致的调用失败,UniGateway 在同账号内提供毫秒级就地自愈能力:

  1. thinkingLevel 转换自愈:当上游因 thinkingLevel 返回 400 时,网关自动将其转换为等效的数值型 thinkingBudget 或安全修剪并在同账号立即重发;
  2. thinkingConfig 全量净化自愈:当模型不支持思考能力且上游返回思考相关参数报错或通用参数无效时,网关在出站请求中安全剥离所有 thinkingConfig 并在同一账号立即重新请求;
  3. thoughtSignature 占位自愈:当多轮会话因历史签名损坏或跨通道迁移返回 400 时,网关自动替换为安全跳过签名并重试,确保 Agent 复杂调用链不断流;
  4. JSON Schema 降级净化自愈:当上游因 parametersJsonSchema、responseJsonSchema 或扩展 JSON Schema 约束返回 400 时,网关自动降级为标准 parameters / responseSchema 并执行深度 Protobuf Schema 清洗后在同账号重试。

下一步