Gemini API/Gemini 结构化输出与生成配置

Gemini 结构化 JSON 输出与 responseSchema 约束、responseMimeType 规范化、惩罚参数边界钳制与 generationConfig 采样规则。

Gemini 结构化输出与生成配置

本文档详细说明通过 UniGateway 调用 Gemini API 时的结构化 JSON 输出规范(responseMimeType 与 responseSchema)、生成超参数(temperature、topP、topK)、惩罚参数边界约束(presencePenalty 与 frequencyPenalty)以及生图专用配置(imageConfig)。


章节导引

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

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

generationConfig 结构化生成配置

Gemini 通过顶层 generationConfig 对象控制生成随机性、输出长度、结构约束与模型采样行为:

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "提取文本中的人物、地点与时间信息。"}]
    }
  ],
  "generationConfig": {
    "temperature": 0.1,
    "maxOutputTokens": 1024,
    "responseMimeType": "application/json",
    "responseSchema": {
      "type": "object",
      "properties": {
        "person": {"type": "string"},
        "location": {"type": "string"},
        "time": {"type": "string"}
      },
      "required": ["person", "location"]
    }
  }
}

生成参数三维对照表

参数 / 场景Google Gemini 官方规范UniGateway 处理规则
responseMimeType、responseSchema 与 responseJsonSchema 联动要求返回结构化 JSON 时,必须显式设置 responseMimeType: "application/json"。若仅提供了 responseSchema 或 responseJsonSchema 而未设置 MIME 类型,官方接口将忽略 Schema 约束。MIME 类型自动推导与双层 Schema 处理:若客户端提供了 responseSchema 或 responseJsonSchema 但未传 responseMimeType,网关自动补齐 responseMimeType: "application/json"。标准 v1beta 出站时原样保留 responseJsonSchema 并对 responseSchema 执行 Protobuf 规范化净化;在 v1internal 通道或上游因 Schema 字段返回 400 错误时,自动将 responseJsonSchema 降级转换为净化后的 responseSchema 并在同账号自动重试。
惩罚参数区间边界约束Gemini 官方规定 presencePenalty 与 frequencyPenalty 取值范围为 [-2.0, 2.0)(左闭右开区间)。传入 >= 2.0(例如 2.0)会导致上游直接抛出参数校验 400 错误。边界钳制:网关在出站前自动将数值钳制在安全区间 [-2.0, 1.999999] 内,有效防止边界值导致请求失败。
停止序列 stopSequences允许传入最多 5 个自定义停止字符串。若传入空数组 [],部分严格校验的上游会返回报错。空数组自动修剪:若客户端传入了空数组 stopSequences: [],网关自动从 generationConfig 中移除该字段。
图像生成配置 imageConfig用于 Gemini 生图模型(如 gemini-3-pro-image-preview)设置纵横比(aspectRatio,如 "16:9"、"1:1")与输出尺寸。上游不支持 outputMimeType 或 imageOutputOptions 等已弃用字段。无效字段剥离:网关自动从 imageConfig 中剔除 outputMimeType 与 imageOutputOptions;若清理后对象为空则自动删除 imageConfig。

常用采样参数说明

字段类型默认值推荐范围说明
maxOutputTokensinteger由模型决定1 ~ 最大上限本次响应允许生成的最大 Token 数量。达到上限后停止,finishReason 置为 MAX_TOKENS。
temperaturenumber1.0 (因模型而异)0.0 ~ 2.0控制生成随机性。值越低,输出越聚焦和确定;值越高,创造性越强。
topPnumber0.950.0 ~ 1.0核采样阈值。模型仅从累积概率达到 topP 的高概率 Token 集合中采样。
topKinteger401 ~ 40Top-K 采样参数。每一步仅保留概率最高的前 K 个候选 Token。
seedinteger无整数随机数发生器种子,用于尽可能提高输出的可复现性。

结构化 JSON 输出实战

复杂嵌套 Schema 定义

{
  "generationConfig": {
    "responseMimeType": "application/json",
    "responseSchema": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": ["success", "pending", "failed"]
        },
        "records": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {"type": "integer"},
              "title": {"type": "string"}
            },
            "required": ["id", "title"]
          }
        }
      },
      "required": ["status", "records"]
    }
  }
}

模型返回的内容块将保证为符合上述结构的合法 JSON 字符串:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "{\"status\": \"success\", \"records\": [{\"id\": 1, \"title\": \"Task A\"}]}"
          }
        ]
      },
      "finishReason": "STOP"
    }
  ]
}

下一步