Gemini API怎么稳定输出JSON?response_format、Schema与事实校验
用官方Interactions response_format约束固定字段,借Pydantic验…
文章目录
下游程序需要固定字段时,只写“输出JSON”仍可能得到额外说明或字段漂移。Gemini结构化输出允许提供JSON Schema。本文用人工事项文本提取字段,说明格式验证与事实核对是两道检查,不把Schema当成真实性保证。

第一步:定义字段与未知值
先列字段、类型和是否允许null。标题是文本、日期缺失允许空值,完成状态仅使用已确认枚举。不能为了让字段非空而要求模型猜日期或负责人;原文没有信息时保持未知。
API权限与消费者套餐分别核对。当前官方示例使用Interactions response_format和兼容Google Gen AI SDK,示例模型gemini-4-hydrogen需项目支持,不混用旧接口的配置字段。
第二步:定义小型Schema
先用Pydantic建立明确数据结构,再生成JSON Schema。初次不要把几十层复杂嵌套都放进去,先验证官方支持的类型与约束。描述帮助理解字段,但不能代替业务规则。
from pydantic import BaseModel
class Task(BaseModel):
title: str
due_date: str | None
owner: str | None
第三步:按官方response_format提交
使用同一份Schema验证返回值,不把模型输出直接eval。下面人工文本没有明确人员和日期,预期对应字段为空;代码不执行真实付费调用。凭据由受控环境配置,不写到示例文件里。
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="从这段练习文字提取任务:需要整理项目资料。没有明确日期或负责人,不要猜。",
response_format={"type": "text", "mime_type": "application/json",
"schema": Task.model_json_schema()},
)
task = Task.model_validate_json(interaction.output_text)
print(task)
第四步:检查三个不同层次
先检查请求是否完成,再解析JSON并验证Schema,最后对照原文核实事实。JSON可解析但类型错、类型正确但日期编造,都是不同错误。记录失败阶段,不能用默认值填充后默默标成功。
日期字符串字段不自动保证合法日期;业务层应继续验证日期格式、日历有效性、允许范围和证据。严格枚举也可能在事实不足时被错误选中,应给未知状态设计清楚出口。
样本验收:title对应整理项目资料;due_date与owner为空;没有外加解释破坏JSON;没有编造日期;Schema版本与解析器一致;异常进入明确失败分支。
第五步:扩展样本再接下游
补充含明确日期、否定句、多任务和缺失字段的样本,先人工写预期,再评估输出。大批处理按记录编号回填,不靠返回顺序。结构稳定后才接入业务动作,避免一个虚构字段触发真实操作。
保存Schema、提示、模型和输入版本,模型或字段修改后重新检查兼容性。完成标准是格式、类型和事实三层通过,不只是调用返回200。文档中的可用约束和限制可能变化,新增规则先核对当前官方支持。
未知值与空字符串不是同义,入库前保留明确的数据字典。
官方资料
资料核对日期:2026年11月17日。
本文地址:https://www.163264.com/21510


