Gemini 2.5 Pro 预览版现已可用于生产环境！了解详情

此页面由 Cloud Translation API 翻译。

使用 Gemini API 生成结构化输出

Gemini 默认会生成非结构化文本，但某些应用需要结构化文本。对于这些用例，您可以限制 Gemini 以 JSON 格式（一种适合自动处理的结构化数据格式）进行响应。您还可以限制模型使用枚举中指定的选项之一进行响应。

以下是可能需要模型提供结构化输出的几种用例：

从报纸文章中提取公司信息，构建公司数据库。
从简历中提取标准化信息。
从食谱中提取食材，并为每种食材显示指向杂货网站的链接。

在问题中，您可以要求 Gemini 生成 JSON 格式的输出，但请注意，模型无法保证只会生成 JSON 格式的输出。如需获得更确定性的响应，您可以在 responseSchema 字段中传递特定的 JSON 架构，以便 Gemini 始终以预期结构响应。如需详细了解如何使用架构，请参阅详细了解 JSON 架构。

本指南介绍了如何通过您选择的 SDK 使用 generateContent 方法生成 JSON，或者直接使用 REST API 生成 JSON。示例展示了仅包含文本的输入，但 Gemini 还可以针对包含图片、视频和音频的多模态请求生成 JSON 响应。

生成 JSON

将模型配置为输出 JSON 后，它会以 JSON 格式的输出回答任何问题。

您可以通过提供架构来控制 JSON 响应的结构。您可以通过以下两种方式向模型提供架构：

作为提示中的文本
作为通过模型配置提供的结构化架构

在提示中以文本形式提供架构

以下示例会提示模型以特定 JSON 格式返回饼干食谱。

由于模型会从问题中的文本中获取格式规范，因此您在表示规范的方式上可能会有一定的灵活性。任何用于表示 JSON 架构的合理格式都可以使用。

from google import genai

prompt = """List a few popular cookie recipes in JSON format.

Use this JSON schema:

Recipe = {'recipe_name': str, 'ingredients': list[str]}
Return: list[Recipe]"""

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents=prompt,
)

# Use the response as a JSON string.
print(response.text)

输出可能如下所示：

[
  {
    "recipe_name": "Chocolate Chip Cookies",
    "ingredients": [
      "2 1/4 cups all-purpose flour",
      "1 teaspoon baking soda",
      "1 teaspoon salt",
      "1 cup (2 sticks) unsalted butter, softened",
      "3/4 cup granulated sugar",
      "3/4 cup packed brown sugar",
      "1 teaspoon vanilla extract",
      "2 large eggs",
      "2 cups chocolate chips"
    ]
  },
  ...
]

通过模型配置提供架构

以下示例会执行以下操作：

通过架构实例化配置的模型，以 JSON 格式进行响应。
提示模型返回饼干食谱。

与仅依靠提示中的文本相比，这种更为正式的 JSON 架构声明方法可让您更精确地控制模型。

from google import genai
from pydantic import BaseModel


class Recipe(BaseModel):
  recipe_name: str
  ingredients: list[str]


client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='List a few popular cookie recipes. Be sure to include the amounts of ingredients.',
    config={
        'response_mime_type': 'application/json',
        'response_schema': list[Recipe],
    },
)
# Use the response as a JSON string.
print(response.text)

# Use instantiated objects.
my_recipes: list[Recipe] = response.parsed

输出可能如下所示：

[
  {
    "recipe_name": "Chocolate Chip Cookies",
    "ingredients": [
      "1 cup (2 sticks) unsalted butter, softened",
      "3/4 cup granulated sugar",
      "3/4 cup packed brown sugar",
      "1 teaspoon vanilla extract",
      "2 large eggs",
      "2 1/4 cups all-purpose flour",
      "1 teaspoon baking soda",
      "1 teaspoon salt",
      "2 cups chocolate chips"
    ]
  },
  ...
]

架构定义语法

在模型配置的 response_schema 属性中指定 JSON 响应的架构。response_schema 的值必须为：

类型，如在类型注解中所用。请参阅 Python typing 模块。
一个 genai.types.Schema 的实例。
genai.types.Schema 的 dict 等效项。

使用类型定义架构

定义架构的最简单方法是使用直接类型。这是前面的示例中所用的方法：

config={'response_mime_type': 'application/json',
        'response_schema': list[Recipe]}

Gemini API Python 客户端库支持使用以下类型定义的架构（其中 AllowedType 是任何允许的类型）：

int
float
bool
str
list[AllowedType]
对于结构化类型：
- dict[str, AllowedType]。此注解声明所有字典值均为同一类型，但未指定应包含哪些键。
- 用户定义的 Pydantic 模型。通过这种方法，您可以指定键名称，并为与每个键关联的值定义不同的类型，包括嵌套结构。

使用枚举来约束输出

在某些情况下，您可能希望模型从选项列表中选择单个选项。如需实现此行为，您可以在架构中传递枚举。您可以在 response_schema 中可以使用 str 的任何位置使用枚举选项，因为枚举是字符串列表。与 JSON 架构一样，枚举可让您约束模型输出，以满足应用的要求。

例如，假设您正在开发一款应用，用于将乐器分类到以下五个类别之一："Percussion"、"String"、"Woodwind"、"Brass" 或“"Keyboard"”。您可以创建一个枚举来帮助完成此任务。

在以下示例中，您将枚举类 Instrument 作为 response_schema 传递，模型应选择最合适的枚举选项。

from google import genai
import enum

class Instrument(enum.Enum):
  PERCUSSION = "Percussion"
  STRING = "String"
  WOODWIND = "Woodwind"
  BRASS = "Brass"
  KEYBOARD = "Keyboard"

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='What type of instrument is an oboe?',
    config={
        'response_mime_type': 'text/x.enum',
        'response_schema': Instrument,
    },
)

print(response.text)
# Woodwind

Python SDK 将转换 API 的类型声明。不过，该 API 接受 OpenAPI 3.0 架构的子集（架构）。您也可以将架构作为 JSON 传递：

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='What type of instrument is an oboe?',
    config={
        'response_mime_type': 'text/x.enum',
        'response_schema': {
            "type": "STRING",
            "enum": ["Percussion", "String", "Woodwind", "Brass", "Keyboard"],
        },
    },
)

print(response.text)
# Woodwind

除了基本多选题之外，您还可以在架构中的任何位置使用枚举来进行 JSON 或函数调用。例如，您可以向模型请求获取食谱标题列表，并使用 Grade 枚举为每个标题分配一个热门程度等级：

from google import genai

import enum
from pydantic import BaseModel

class Grade(enum.Enum):
    A_PLUS = "a+"
    A = "a"
    B = "b"
    C = "c"
    D = "d"
    F = "f"

class Recipe(BaseModel):
  recipe_name: str
  rating: Grade

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='List 10 home-baked cookies and give them grades based on tastiness.',
    config={
        'response_mime_type': 'application/json',
        'response_schema': list[Recipe],
    },
)

print(response.text)
# [{"rating": "a+", "recipe_name": "Classic Chocolate Chip Cookies"}, ...]

有关 JSON 架构的详细信息

将模型配置为返回 JSON 响应时，您可以使用 Schema 对象来定义 JSON 数据的形状。Schema 表示 OpenAPI 3.0 架构对象的选定子集。

下面是所有 Schema 字段的伪 JSON 表示法：

{
  "type": enum (Type),
  "format": string,
  "description": string,
  "nullable": boolean,
  "enum": [
    string
  ],
  "maxItems": string,
  "minItems": string,
  "properties": {
    string: {
      object (Schema)
    },
    ...
  },
  "required": [
    string
  ],
  "propertyOrdering": [
    string
  ],
  "items": {
    object (Schema)
  }
}

架构的 Type 必须是 OpenAPI 数据类型之一。对于每个 Type，只有部分字段有效。以下列表会将每个 Type 映射到该类型的有效字段：

string -> 枚举、格式
integer -> 格式
number -> 格式
boolean
array -> minItems、maxItems、items
object -> properties、required、propertyOrdering、nullable

以下是一些示例架构，展示了有效的类型和字段组合：

{ "type": "string", "enum": ["a", "b", "c"] }

{ "type": "string", "format": "date-time" }

{ "type": "integer", "format": "int64" }

{ "type": "number", "format": "double" }

{ "type": "boolean" }

{ "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": ... } }

{ "type": "object",
  "properties": {
    "a": { "type": ... },
    "b": { "type": ... },
    "c": { "type": ... }
  },
  "nullable": true,
  "required": ["c"],
  "propertyOrdering": ["c", "b", "a"]
}

如需详细了解 Gemini API 中使用的架构字段，请参阅架构参考文档。

媒体资源排序

在 Gemini API 中使用 JSON 架构时，属性的顺序非常重要。默认情况下，该 API 会按字母顺序对房源进行排序，而不会保留房源的定义顺序（不过 Google Gen AI SDK 可能会保留此顺序）。如果您向配置了架构的模型提供示例，并且示例的属性顺序与架构的属性顺序不一致，则输出可能会杂乱无章或出乎意料。

为确保属性的排序一致且可预测，您可以使用可选的 propertyOrdering[] 字段。

"propertyOrdering": ["recipe_name", "ingredients"]

propertyOrdering[]（不是 OpenAPI 规范中的标准字段）是一个字符串数组，用于确定响应中的属性顺序。通过指定属性的顺序，然后提供包含按相同顺序排列的属性的示例，您有望提高结果的质量。