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

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

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

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

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

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

Питон 

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.

Питон 

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)
}

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

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

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

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

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

  • string : Для текста.
  • number : Для чисел с плавающей точкой.
  • integer : для целых чисел.
  • boolean : для значений «истина»/«ложь».
  • 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 : максимальное количество элементов в массиве.

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

Следующие модели поддерживают структурированный вывод:

Модель Структурированные выходы
Джемини 2.5 Про ✔️
Близнецы 2.5 Флэш ✔️
Gemini 2.5 Flash-Lite ✔️
Gemini 2.0 Flash ✔️*
Gemini 2.0 Flash-Lite ✔️*

* Обратите внимание, что Gemini 2.0 требует явного списка propertyOrdering во входных данных JSON для определения предпочтительной структуры. Пример можно найти в этой кулинарной книге .

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

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

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

Лучшие практики

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

Ограничения

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