Gemini API 结构化输出怎样限制 JSON 字段

Gemini API 结构化输出要限制 JSON 字段，不能只在提示词里写“请返回固定格式”。更稳妥的做法是把 response_mime_type 设为 application/json，再用 response_schema 声明对象、字段类型和必填项；如果业务要求更严格，解析后还要在客户端检查长度、枚举和跨字段关系。

官方地址：https://ai.google.dev/gemini-api/docs/structured-output

只设置 JSON MIME 类型只能保证输出是 JSON 形态；真正限制字段要写 Schema。properties 描述允许的键，required 描述必须出现的键，additionalProperties 决定是否接受未声明的键。

先把格式开关和字段约束分开

我第一次把 Gemini 接到工单抽取接口时，最容易混淆的是“能解析”和“字段正确”这两件事。response_mime_type=application/json 主要告诉接口返回 JSON；它不会凭空知道结果只能有 title、priority 和 labels 三个字段。

真正的字段边界来自 Schema：对象用 properties 列出字段，required 列出必填字段，字段内部再用 string、integer、array 或 enum 限定类型和值域。手工写 Schema 时，如果不希望出现未声明字段，可以把对象的 additionalProperties 设为 false。

用 Pydantic 模型声明固定字段

Python SDK 可以直接把 Pydantic 模型作为 response_schema。下面的模型只允许工单标题、优先级和标签，Literal 把优先级收紧到三个值，extra="forbid" 表示生成结果不应接受模型中没有声明的额外键。

# 安装 Google GenAI SDK 与 Pydantic，避免把 API 密钥写进源码
python -m pip install google-genai pydantic

import os
from typing import Literal

from google import genai
from pydantic import BaseModel, ConfigDict, Field


class Ticket(BaseModel):
    # forbid 会把未声明字段也纳入 Schema 的额外字段策略
    model_config = ConfigDict(extra="forbid")

    title: str = Field(description="工单的简短标题")
    priority: Literal["low", "medium", "high"]
    labels: list[str]


client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="用户反馈：导出任务连续两次超时，影响今天的报表。",
    config={
        # MIME 类型负责 JSON 形态，Schema 负责字段结构
        "response_mime_type": "application/json",
        "response_schema": Ticket,
    },
)

# 解析后再次建模，顺便执行客户端可表达的业务校验
ticket = Ticket.model_validate_json(response.text)
print(ticket.title, ticket.priority, ticket.labels)

这里的关键不是把所有规则都塞进提示词，而是让接口配置和应用模型使用同一份字段定义。required 解决字段是否存在，Literal 解决有限值域，Pydantic 的再次解析则负责客户端能够表达的约束。API 密钥仍从环境变量读取，避免在示例或日志中泄露。

哪些 Schema 约束真的会生效

Gemini 的结构化输出只支持 JSON Schema 的一个子集，不能把任意 JSON Schema 关键字都当成服务端强约束。常用字段可以这样理解：

这也是旧代码迁移时最容易踩的边界：Schema 能把结果形状收紧，却不能替你判断标题是否有意义、优先级是否符合公司规则，或者一组字段之间是否自洽。官方文档还提醒，过深、过大或分支过多的 Schema 可能因约束状态太多而被接口拒绝，复杂结构应拆小并减少不必要的嵌套。

把解析和业务校验放在模型响应之后

实际接入时，我会把处理链固定成“请求配置—模型响应—JSON 解析—业务校验—下游写入”。只要其中一步失败，就不要把原始字符串直接写入数据库或触发后续动作。

def accept_ticket(raw_text: str) -> Ticket:
    # 先按 Schema 解析，格式不对时立即停止下游处理
    ticket = Ticket.model_validate_json(raw_text)

    # 业务规则独立于模型 Schema，便于随业务变化调整
    if len(ticket.title.strip())  8:
        raise ValueError("标签数量超过业务上限")
    return ticket

如果报错是“响应不是合法 JSON”，先检查是否真的把 Schema 传入了生成配置；如果是“字段存在但内容不符合规则”，应看客户端校验；如果接口返回 400 INVALID_ARGUMENT 并提示约束过复杂，则优先减少嵌套、枚举数量和数组上限，而不是继续扩大提示词。

常见问题

只写 response_mime_type 能限制字段吗？ 不能。它主要约束返回媒介是 JSON，字段名、类型和必填关系要放进 response_schema。

required 能保证字段值有意义吗？ 不能。它只表达字段必须出现；业务枚举、长度、权限和跨字段关系仍要在客户端校验。

结构化输出和函数调用是一回事吗？ 不是。结构化输出用于规定最终响应格式，函数调用用于让模型请求应用执行动作；两者都可能使用 Schema，但职责不同。

小结

Gemini API 限制 JSON 字段的最小做法是同时配置 JSON MIME 类型和 Schema，再根据需要加入 required、enum、additionalProperties 与数组边界。服务端保证的是可预测的结构，应用层还要完成语义校验和错误处理，这样字段约束才不会变成“看起来是 JSON、实际不可用”的假稳定。