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

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

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

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

Помимо поддержки JSON Schema в REST API, SDK Google GenAI для Python и JavaScript также упрощают определение схем объектов с помощью Pydantic и Zod соответственно. Приведенный ниже пример демонстрирует, как извлечь информацию из неструктурированного текста, соответствующего схеме, определенной в коде.

В этом примере показано, как извлекать структурированные данные из текста, используя базовые типы 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.
"""

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=prompt,
    config={
        "response_mime_type": "application/json",
        "response_json_schema": Recipe.model_json_schema(),
    },
)

recipe = Recipe.model_validate_json(response.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 ai = 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 response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: prompt,
  config: {
    responseMimeType: "application/json",
    responseJsonSchema: zodToJsonSchema(recipeSchema),
  },
});

const recipe = recipeSchema.parse(JSON.parse(response.text));
console.log(recipe);

Идти 

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    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.
  `
    config := &genai.GenerateContentConfig{
        ResponseMIMEType: "application/json",
        ResponseJsonSchema: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "recipe_name": map[string]any{
                    "type":        "string",
                    "description": "The name of the recipe.",
                },
                "prep_time_minutes": map[string]any{
                    "type":        "integer",
                    "description": "Optional time in minutes to prepare the recipe.",
                },
                "ingredients": map[string]any{
                    "type": "array",
                    "items": map[string]any{
                        "type": "object",
                        "properties": map[string]any{
                            "name": map[string]any{
                                "type":        "string",
                                "description": "Name of the ingredient.",
                            },
                            "quantity": map[string]any{
                                "type":        "string",
                                "description": "Quantity of the ingredient, including units.",
                            },
                        },
                        "required": []string{"name", "quantity"},
                    },
                },
                "instructions": map[string]any{
                    "type":  "array",
                    "items": map[string]any{"type": "string"},
                },
            },
            "required": []string{"recipe_name", "ingredients", "instructions"},
        },
    }

    result, err := client.Models.GenerateContent(
        ctx,
        "gemini-2.5-flash",
        genai.Text(prompt),
        config,
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text())
}

ОТДЫХ 

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          { "text": "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." }
        ]
      }],
      "generationConfig": {
        "responseMimeType": "application/json",
        "responseJsonSchema": {
          "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, Field
from typing import Literal

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

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

response_stream = client.models.generate_content_stream(
    model="gemini-2.5-flash",
    contents=prompt,
    config={
        "response_mime_type": "application/json",
        "response_json_schema": Feedback.model_json_schema(),
    },
)

for chunk in response_stream:
    print(chunk.candidates[0].content.parts[0].text)

JavaScript 

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

const ai = new GoogleGenAI({});
const prompt = "The new UI is incredibly intuitive and visually appealing. Great job! Add a very long summary to test streaming!";

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

const stream = await ai.models.generateContentStream({
  model: "gemini-2.5-flash",
  contents: prompt,
  config: {
    responseMimeType: "application/json",
    responseJsonSchema: zodToJsonSchema(feedbackSchema),
  },
});

for await (const chunk of stream) {
  console.log(chunk.candidates[0].content.parts[0].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()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Search for all details for the latest Euro.",
    config={
        "tools": [
            {"google_search": {}},
            {"url_context": {}}
        ],
        "response_mime_type": "application/json",
        "response_json_schema": MatchResult.model_json_schema(),
    },  
)

result = MatchResult.model_validate_json(response.text)
print(result)

JavaScript 

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

const ai = 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.")
});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: "Search for all details for the latest Euro.",
    config: {
      tools: [
        { googleSearch: {} },
        { urlContext: {} }
      ],
      responseMimeType: "application/json",
      responseJsonSchema: zodToJsonSchema(matchSchema),
    },
  });

  const match = matchSchema.parse(JSON.parse(response.text));
  console.log(match);
}

run();

ОТДЫХ 

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Search for all details for the latest Euro."}]
    }],
    "tools": [
      {"googleSearch": {}},
      {"urlContext": {}}
    ],
    "generationConfig": {
        "responseMimeType": "application/json",
        "responseJsonSchema": {
            "type": "object",
            "properties": {
                "winner": {"type": "string", "description": "The name of the winner."},
                "final_match_score": {"type": "string", "description": "The final score."},
                "scorers": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "The name of the scorer."
                }
            },
            "required": ["winner", "final_match_score", "scorers"]
        }
    }
  }'

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

Для генерации объекта JSON установите response_mime_type в конфигурации генерации на application/json и укажите response_json_schema . Схема должна быть допустимой схемой JSON , описывающей желаемый формат вывода.

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

Режим структурированного вывода 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 Pro ✔️
Предварительный просмотр 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 в JSON-входе для определения предпочтительной структуры. Пример можно найти в этом руководстве .

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

И структурированные выходные данные, и вызовы функций используют JSON-схемы, но служат разным целям:

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

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

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

Ограничения

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