Gemini API 结构化输出 JSON Schema 怎么设置

准备

先准备 Gemini API 密钥、可用的模型名称，以及项目使用的 Google Gen AI SDK。资料显示，Gemini API 支持通过模型配置提供 JSON Schema，也支持使用 response_mime_type 请求 JSON 格式响应。具体字段名称可能随 SDK 版本变化，接入前应以当前 SDK 文档为准。

• 明确输出字段，例如标题、摘要、标签和正文。
• 为每个字段确定类型、是否必填以及允许的取值范围。
• 准备应用侧的 JSON 解析和 Schema 校验逻辑。

分步操作

1. 先设计数据结构。例如文章生成任务可以约定 title、summary、tags 和 body 四个字段，其中标题和正文是字符串，标签是字符串数组。

2. 设置响应类型。在生成配置中指定 JSON MIME 类型，让接口目标从普通文本变成 JSON 对象。不要只依赖提示词中的“请输出 JSON”。

3. 传入 Schema。Schema 至少应描述对象类型、字段类型和必填字段。字段越清楚，后续解析和入库越容易。

4. 解析响应并校验。先读取模型返回的文本，再执行 JSON 解析；解析成功后继续检查必填字段、数据类型和业务规则。

5. 校验通过后再入库或发布。校验失败时保留原始响应和任务编号，进入重试或人工处理队列，不要直接写入正式内容。

可复制模板或示例

下面是一个 Python 风格的配置示例。不同 SDK 版本的客户端初始化和配置对象可能不同，请将字段映射到你当前版本的接口。

schema = {
    "type": "OBJECT",
    "properties": {
        "title": {"type": "STRING"},
        "summary": {"type": "STRING"},
        "tags": {
            "type": "ARRAY",
            "items": {"type": "STRING"}
        },
        "body": {"type": "STRING"}
    },
    "required": ["title", "summary", "tags", "body"]
}

config = {
    "response_mime_type": "application/json",
    "response_schema": schema
}

prompt = """
请根据给定资料生成一篇文章。
只返回符合 Schema 的 JSON 对象，不要添加额外说明。
资料：{materials}
主题：{topic}
"""

response = client.models.generate_content(
    model=model_name,
    contents=prompt,
    config=config
)

raw_text = response.text
result = json.loads(raw_text)
assert isinstance(result["title"], str)
assert isinstance(result["summary"], str)
assert isinstance(result["tags"], list)
assert isinstance(result["body"], str)

如果你的业务需要限制标签数量、正文不能为空或标题长度有限，还要在 JSON Schema 之外增加业务校验。例如：len(result["tags"]) <= 5，以及检查正文去除空白后仍有内容。

批量写作时，可以把每次请求的模型名称、输入材料、配置、原始响应、解析结果和校验状态一起保存。已有的结构化检查流程也可以作为应用侧验收设计的参考。

翻车怎么改

常见故障：返回内容无法被 JSON 解析。原因可能是响应前后混入说明文字、代码围栏，或当前模型和配置没有正确启用 JSON 响应。修正时先确认 response_mime_type 和 Schema 是否确实传入，再把提示词改为“只返回 JSON 对象”，同时在解析失败时记录原始响应并重试，不能用字符串截取方式盲目修复。

常见故障：JSON 能解析，但字段缺失或类型错误。原因是 Schema 没有把字段列入 required，或者应用侧没有做二次校验。修正动作是补齐必填字段、检查数组和字符串类型，并把失败结果标记为不可发布。

常见故障：字段完整但内容不符合业务要求。原因是 JSON Schema 只能约束结构，不能替代事实核对、敏感词审核或发布规则。修正时增加业务规则检查和人工抽检，把结构校验与内容审核分成两个状态。

完成前检查

• 确认 title、summary、tags、body 等必填字段都存在，类型符合 Schema。
• 确认响应文本能被标准 JSON 解析，没有额外说明或代码围栏。
• 确认数组数量、字符串长度、空值和枚举值符合业务规则。
• 确认校验失败时不会自动发布，并且原始响应可以追溯。
• 确认当前模型和 SDK 版本的配置字段已在实际请求中生效。