Структурированные выходные данные

Вы можете настроить модели Gemini для генерации ответов, соответствующих предоставленной JSON-схеме. Это обеспечивает предсказуемые, типобезопасные результаты и упрощает извлечение структурированных данных из неструктурированного текста.

Использование структурированных выходных данных идеально подходит для:

  • Извлечение данных: извлечение конкретной информации, такой как имена и даты, из текста.
  • Структурированная классификация: классификация текста по предопределенным категориям.
  • Рабочие процессы агентов: генерация структурированных входных данных для инструментов или API.

Помимо поддержки JSON Schema в REST API, SDK Google GenAI позволяют определять схемы с помощью Pydantic (Python) и Zod (JavaScript).

В этом примере показано, как извлекать структурированные данные из текста, используя базовые типы JSON Schema, такие как object , array , string и integer .

Python 

from google import genai
from pydantic import BaseModel, Field
from typing import List, Optional

class Ingredient(BaseModel):
    name: str = Field(description="Name of the ingredient.")
    quantity: str = Field(description="Quantity of the ingredient, including units.")

class Recipe(BaseModel):
    recipe_name: str = Field(description="The name of the recipe.")
    prep_time_minutes: Optional[int] = Field(description="Optional time in minutes to prepare the recipe.")
    ingredients: List[Ingredient]
    instructions: List[str]

client = genai.Client()

prompt = """
Please extract the recipe from the following text.
The user wants to make delicious chocolate chip cookies.
They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,
1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,
3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.
For the best part, they'll need 2 cups of semisweet chocolate chips.
First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,
baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar
until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry
ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons
onto ungreased baking sheets and bake for 9 to 11 minutes.
"""

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=prompt,
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Recipe.model_json_schema()
    },
)

recipe = Recipe.model_validate_json(interaction.steps[-1].content[0].text)
print(recipe)

JavaScript 

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const ingredientSchema = z.object({
  name: z.string().describe("Name of the ingredient."),
  quantity: z.string().describe("Quantity of the ingredient, including units."),
});

const recipeSchema = z.object({
  recipe_name: z.string().describe("The name of the recipe."),
  prep_time_minutes: z.number().optional().describe("Optional time in minutes to prepare the recipe."),
  ingredients: z.array(ingredientSchema),
  instructions: z.array(z.string()),
});

const client = new GoogleGenAI({});

const prompt = `
Please extract the recipe from the following text.
The user wants to make delicious chocolate chip cookies.
They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,
1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,
3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.
For the best part, they'll need 2 cups of semisweet chocolate chips.
First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,
baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar
until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry
ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons
onto ungreased baking sheets and bake for 9 to 11 minutes.
`;

const interaction = await client.interactions.create({
  model: "gemini-3-flash-preview",
  input: prompt,
  response_format: {
    type: 'text',
    mime_type: 'application/json',
    schema: zodToJsonSchema(recipeSchema)
  },
});

const recipe = recipeSchema.parse(JSON.parse(interaction.steps.at(-1).content[0].text));
console.log(recipe);

ОТДЫХ 

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3-flash-preview",
      "input": "Please extract the recipe from the following text.\nThe user wants to make delicious chocolate chip cookies.\nThey need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,\n1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,\n3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\nFor the best part, they will need 2 cups of semisweet chocolate chips.\nFirst, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\nbaking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\nuntil light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\ningredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\nonto ungreased baking sheets and bake for 9 to 11 minutes.",
      "response_format": {
        "type": "text",
        "mime_type": "application/json",
        "schema": {
          "type": "object",
          "properties": {
            "recipe_name": {
              "type": "string",
              "description": "The name of the recipe."
            },
            "prep_time_minutes": {
                "type": "integer",
                "description": "Optional time in minutes to prepare the recipe."
            },
            "ingredients": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": { "type": "string", "description": "Name of the ingredient."},
                  "quantity": { "type": "string", "description": "Quantity of the ingredient, including units."}
                },
                "required": ["name", "quantity"]
              }
            },
            "instructions": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "required": ["recipe_name", "ingredients", "instructions"]
        }
      }
      }
    }'

Пример ответа: 

{
  "recipe_name": "Delicious Chocolate Chip Cookies",
  "ingredients": [
    { "name": "all-purpose flour", "quantity": "2 and 1/4 cups" },
    { "name": "baking soda", "quantity": "1 teaspoon" },
    { "name": "salt", "quantity": "1 teaspoon" },
    { "name": "unsalted butter (softened)", "quantity": "1 cup" },
    { "name": "granulated sugar", "quantity": "3/4 cup" },
    { "name": "packed brown sugar", "quantity": "3/4 cup" },
    { "name": "vanilla extract", "quantity": "1 teaspoon" },
    { "name": "large eggs", "quantity": "2" },
    { "name": "semisweet chocolate chips", "quantity": "2 cups" }
  ],
  "instructions": [
    "Preheat the oven to 375°F (190°C).",
    "In a small bowl, whisk together the flour, baking soda, and salt.",
    "In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy.",
    "Beat in the vanilla and eggs, one at a time.",
    "Gradually beat in the dry ingredients until just combined.",
    "Stir in the chocolate chips.",
    "Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes."
  ]
}

Результаты трансляции

Вы можете передавать структурированные выходные данные в потоковом режиме, что позволяет начать обработку ответа по мере его генерации. Передаваемые фрагменты представляют собой допустимые частичные JSON-строки, которые можно объединять для формирования итогового JSON-объекта.

Python 

from google import genai
from pydantic import BaseModel
from typing import Literal

class Feedback(BaseModel):
    sentiment: Literal["positive", "neutral", "negative"]
    summary: str

client = genai.Client()
prompt = "The new UI is incredibly intuitive. Add a very long summary to test streaming!"

stream = client.interactions.create(
    model="gemini-3-flash-preview",
    input=prompt,
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Feedback.model_json_schema()
    },
    stream=True
)
for event in stream:
    if event.event_type == "step.delta" and event.delta.text:
        print(event.delta.text, end="")

JavaScript 

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const client = new GoogleGenAI({});
const feedbackSchema = z.object({
  sentiment: z.enum(["positive", "neutral", "negative"]),
  summary: z.string(),
});

const stream = await client.interactions.create({
  model: "gemini-3-flash-preview",
  input: "The new UI is incredibly intuitive. Add a very long summary!",
  response_format: {
    type: 'text',
    mime_type: 'application/json',
    schema: zodToJsonSchema(feedbackSchema)
  },
  stream: true,
});

for await (const event of stream) {
  if (event.type === "step.delta" && event.delta?.text) {
    process.stdout.write(event.delta.text);
  }
}

Структурированные результаты с использованием инструментов

Gemini 3 позволяет комбинировать структурированные выходные данные со встроенными инструментами, включая сопоставление с поиском Google , контекст URL , выполнение кода , поиск файлов и вызов функций .

Python 

from google import genai
from pydantic import BaseModel, Field
from typing import List

class MatchResult(BaseModel):
    winner: str = Field(description="The name of the winner.")
    final_match_score: str = Field(description="The final match score.")
    scorers: List[str] = Field(description="The name of the scorer.")

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.1-pro-preview",
    input="Search for all details for the latest Euro.",
    tools=[{"type": "google_search"}, {"type": "url_context"}],
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": MatchResult.model_json_schema()
    },
)

result = MatchResult.model_validate_json(interaction.steps[-1].content[0].text)
print(result)

JavaScript 

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const client = new GoogleGenAI({});
const matchSchema = z.object({
  winner: z.string().describe("The name of the winner."),
  final_match_score: z.string().describe("The final score."),
  scorers: z.array(z.string()).describe("The name of the scorer.")
});

const interaction = await client.interactions.create({
  model: "gemini-3.1-pro-preview",
  input: "Search for all details for the latest Euro.",
  tools: [{type: "google_search"}, {type: "url_context"}],
  response_format: {
    type: 'text',
    mime_type: 'application/json',
    schema: zodToJsonSchema(matchSchema)
  },
});

const match = matchSchema.parse(JSON.parse(interaction.steps.at(-1).content[0].text));
console.log(match);

ОТДЫХ 

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.1-pro-preview",
    "input": "Search for all details for the latest Euro.",
    "tools": [{"type": "google_search"}, {"type": "url_context"}],
    "response_format": {
      "type": "text",
      "mime_type": "application/json",
      "schema": {
        "type": "object",
        "properties": {
            "winner": {"type": "string"},
            "final_match_score": {"type": "string"},
            "scorers": {"type": "array", "items": {"type": "string"}}
        },
        "required": ["winner", "final_match_score", "scorers"]
      }
    }
  }'

Поддержка JSON-схем

Для генерации JSON-объекта настройте response_format , указав объект (или массив, содержащий объект) типа text и задав для него mime_type значение application/json . Схема должна быть указана в поле schema .

Режим структурированного вывода Gemini поддерживает подмножество спецификации JSON Schema .

Поддерживаются следующие значения type :

  • string : Для текста.
  • number : Для чисел с плавающей запятой.
  • integer : Для целых чисел.
  • boolean : для значений true или false.
  • object : Для структурированных данных, содержащих пары ключ-значение.
  • array : для списков элементов.
  • null : Чтобы разрешить свойству принимать значение null, добавьте "null" в массив типов (например, {"type": ["string", "null"]} ).

Эти описательные свойства помогают в построении модели:

  • title : Краткое описание объекта недвижимости.
  • description : Более подробное и развернутое описание объекта недвижимости.

Свойства, специфичные для типа

Для значений object :

  • properties : Объект, в котором каждый ключ — это имя свойства, а каждое значение — это схема для этого свойства.
  • required : Массив строк, в котором перечислены обязательные свойства.
  • additionalProperties : Определяет, разрешены ли свойства, не указанные в списке properties . Может быть логическим значением или схемой.

Для string значений:

  • enum : Перечисляет конкретный набор возможных строк для задач классификации.
  • format : Задает синтаксис для строки, например, date-time , date , time .

Для number и integer значений:

  • enum : Перечисляет определенный набор возможных числовых значений.
  • minimum : Минимальное значение включительно.
  • maximum : Максимальное значение включительно.

Для значений array :

  • items : Определяет схему для всех элементов массива.
  • prefixItems : Определяет список схем для первых N элементов, позволяя создавать структуры, похожие на кортежи.
  • minItems : Минимальное количество элементов в массиве.
  • maxItems : Максимальное количество элементов в массиве.

Поддержка модели

Модель Структурированные выходные данные
Gemini 3.1 Pro Preview ✔️
Предварительный просмотр Gemini 3 Flash ✔️
Gemini 2.5 Pro ✔️
Вспышка Gemini 2.5 ✔️
Фонарь Gemini 2.5 Flash-Lite ✔️
Gemini 2.0 Flash ✔️*
Фонарик Gemini 2.0 ✔️*

* Для Gemini 2.0 требуется явно указанный список propertyOrdering .

Структурированные выходные данные против вызова функций

Особенность Основной вариант использования
Структурированные выходные данные Форматирование окончательного ответа. Используйте, если вам нужен ответ модели в определенном формате.
Вызов функции Действия во время разговора. Используйте, когда модели необходимо попросить вас выполнить какое-либо задание, прежде чем дать окончательный ответ.

Передовые методы

  • Четкие описания: Используйте поле description , чтобы направлять модель.
  • Строгая типизация: используйте конкретные типы ( integer , string , enum ).
  • Оперативное проектирование: Четко сформулируйте, что именно вы хотите, чтобы делала модель.
  • Проверка: Хотя выходные данные представляют собой синтаксически корректный JSON, всегда проверяйте значения в своем приложении.
  • Обработка ошибок: Реализуйте надежную обработку ошибок для выходных данных, соответствующих схеме, но семантически некорректных.

Ограничения

  • Подмножество схем: Поддерживаются не все функции JSON Schema.
  • Сложность схемы: Очень большие или глубоко вложенные схемы могут быть отклонены.