Gemini 结构化输出与生成配置
本文档详细说明通过 UniGateway 调用 Gemini API 时的结构化 JSON 输出规范(responseMimeType 与 responseSchema)、生成超参数(temperature、topP、topK)、惩罚参数边界约束(presencePenalty 与 frequencyPenalty)以及生图专用配置(imageConfig)。
章节导引
本篇为 Gemini API 参考文档的第 6 章节:
- Gemini 概览与接入
- generateContent 概述与快速开始
- 请求参数与多模态内容格式
- 扩展思考与思维链签名
- 工具调用与搜索检索
- 结构化输出与生成配置(当前章节)
- 响应、流式与错误处理
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。 |
常用采样参数说明
| 字段 | 类型 | 默认值 | 推荐范围 | 说明 |
|---|---|---|---|---|
maxOutputTokens | integer | 由模型决定 | 1 ~ 最大上限 | 本次响应允许生成的最大 Token 数量。达到上限后停止,finishReason 置为 MAX_TOKENS。 |
temperature | number | 1.0 (因模型而异) | 0.0 ~ 2.0 | 控制生成随机性。值越低,输出越聚焦和确定;值越高,创造性越强。 |
topP | number | 0.95 | 0.0 ~ 1.0 | 核采样阈值。模型仅从累积概率达到 topP 的高概率 Token 集合中采样。 |
topK | integer | 40 | 1 ~ 40 | Top-K 采样参数。每一步仅保留概率最高的前 K 个候选 Token。 |
seed | integer | 无 | 整数 | 随机数发生器种子,用于尽可能提高输出的可复现性。 |
结构化 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"
}
]
}
下一步
- 查阅完整错误码与流式传输:响应、流式与错误处理
- 回顾工具调用与搜索检索:工具调用与搜索检索
- 了解请求参数与多模态格式:请求参数与多模态内容格式