I/O is live! Tune in for livestreamed keynotes and sessions May 20-21 starting at 10 AM PT. Watch now.

Эта страница переведена с помощью Cloud Translation API.

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

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

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

Вот несколько примеров:

Убедитесь, что ответ модели создает допустимый JSON и соответствует предоставленной вами схеме.
Например, модель может генерировать структурированные записи для рецептов, которые всегда включают название рецепта, список ингредиентов и шаги. Затем вы можете более легко анализировать и отображать эту информацию в пользовательском интерфейсе вашего приложения.
Ограничьте реакцию модели при выполнении задач классификации.
Например, вы можете заставить модель аннотировать текст с помощью определенного набора меток (например, определенного набора перечислений, таких как positive и negative ), а не меток, которые создает модель (которые могут иметь определенную степень изменчивости, например good , positive , negative или bad ).

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

Внизу этой страницы приведены дополнительные примеры, например, как генерировать значения перечисления в качестве выходных данных .

Прежде чем начать

Щелкните своего поставщика API Gemini , чтобы просмотреть специфичный для этого поставщика контент и код на этой странице.

Если вы еще этого не сделали, ознакомьтесь с руководством по началу работы , в котором описывается, как настроить проект Firebase, подключить приложение к Firebase, добавить SDK, инициализировать внутреннюю службу для выбранного поставщика API Gemini и создать экземпляр GenerativeModel .

Для тестирования и итерации ваших подсказок и даже получения сгенерированного фрагмента кода мы рекомендуем использовать Google AI Studio .

Шаг 1 : Определите схему ответа

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

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

Соображения относительно схем реагирования

При написании схемы ответа помните следующее:

Размер схемы ответа учитывается при расчете лимита входных токенов.
Функция схемы ответа поддерживает следующие типы MIME ответов:
- application/json : вывод JSON, как определено в схеме ответа (полезно для требований структурированного вывода)
- text/x.enum : вывести значение перечисления, как определено в схеме ответа (полезно для задач классификации)
Функция схемы ответа поддерживает следующие поля схемы:
enum
items
maxItems
nullable
properties
required
Если вы используете неподдерживаемое поле, модель все равно может обработать ваш запрос, но она проигнорирует поле. Обратите внимание, что список выше является подмножеством объекта схемы OpenAPI 3.0.
По умолчанию для Firebase AI Logic SDK все поля считаются обязательными , если вы не укажете их как необязательные в массиве optionalProperties . Для этих необязательных полей модель может заполнять поля или пропускать их. Обратите внимание, что это противоположно поведению по умолчанию двух поставщиков API Gemini , если вы используете их серверные SDK или API напрямую.

Шаг 2 : Сгенерируйте вывод JSON, используя схему ответа

Прежде чем приступить к работе с этим примером, выполните действия, описанные в разделе «Перед началом работы» данного руководства, чтобы настроить свой проект и приложение.
В этом разделе вы также нажмете кнопку для выбранного вами поставщика API Gemini , чтобы увидеть на этой странице контент, специфичный для этого поставщика .

В следующем примере показано, как сгенерировать структурированный вывод JSON.

При создании экземпляра GenerativeModel укажите соответствующий responseMimeType (в этом примере application/json ), а также responseSchema , которую должна использовать модель.

Быстрый

import FirebaseVertexAI

// Provide a JSON schema object using a standard format.
// Later, pass this schema object into `responseSchema` in the generation config.
let jsonSchema = Schema.object(
  properties: [
    "characters": Schema.array(
      items: .object(
        properties: [
          "name": .string(),
          "age": .integer(),
          "species": .string(),
          "accessory": .enumeration(values: ["hat", "belt", "shoes"]),
        ],
        optionalProperties: ["accessory"]
      )
    ),
  ]
)

// Initialize the Vertex AI service and the generative model.
let model = VertexAI.vertexAI().generativeModel(
  modelName: "gemini-2.0-flash",
  // In the generation config, set the `responseMimeType` to `application/json`
  // and pass the JSON schema object into `responseSchema`.
  generationConfig: GenerationConfig(
    responseMIMEType: "application/json",
    responseSchema: jsonSchema
  )
)

let prompt = "For use in a children's card game, generate 10 animal-based characters."

let response = try await model.generateContent(prompt)
print(response.text ?? "No text in response.")

Kotlin

^{Для Kotlin методы в этом SDK являются функциями приостановки и должны вызываться из области действия сопрограммы .}

// Provide a JSON schema object using a standard format.
// Later, pass this schema object into `responseSchema` in the generation config.
val jsonSchema = Schema.obj(
    mapOf("characters" to Schema.array(
        Schema.obj(
            mapOf(
                "name" to Schema.string(),
                "age" to Schema.integer(),
                "species" to Schema.string(),
                "accessory" to Schema.enumeration(listOf("hat", "belt", "shoes")),
            ),
            optionalProperties = listOf("accessory")
        )
    ))
)

// Initialize the Vertex AI service and the generative model.
val generativeModel = Firebase.ai(backend = GenerativeBackend.vertexAI()).generativeModel(
    modelName = "gemini-2.0-flash",
    // In the generation config, set the `responseMimeType` to `application/json`
    // and pass the JSON schema object into `responseSchema`.
    generationConfig = generationConfig {
        responseMimeType = "application/json"
        responseSchema = jsonSchema
    })

val prompt = "For use in a children's card game, generate 10 animal-based characters."
val response = generativeModel.generateContent(prompt)
print(response.text)

Java

^{Для Java потоковые методы в этом SDK возвращают тип Publisher из библиотеки Reactive Streams .}

// Provide a JSON schema object using a standard format.
// Later, pass this schema object into `responseSchema` in the generation config.
Schema jsonSchema = Schema.obj(
        /* properties */
        Map.of(
                "characters", Schema.array(
                        /* items */ Schema.obj(
                                /* properties */
                                Map.of("name", Schema.str(),
                                        "age", Schema.numInt(),
                                        "species", Schema.str(),
                                        "accessory",
                                        Schema.enumeration(
                                                List.of("hat", "belt", "shoes")))
                        ))),
        List.of("accessory"));

// In the generation config, set the `responseMimeType` to `application/json`
// and pass the JSON schema object into `responseSchema`.
GenerationConfig.Builder configBuilder = new GenerationConfig.Builder();
configBuilder.responseMimeType = "application/json";
configBuilder.responseSchema = jsonSchema;

GenerationConfig generationConfig = configBuilder.build();

// Initialize the Vertex AI service and the generative model.
GenerativeModel gm = FirebaseVertexAI.getInstance().generativeModel(
  /* modelName */ "gemini-2.0-flash",
  /* generationConfig */ generationConfig);
GenerativeModelFutures model = GenerativeModelFutures.from(gm);

Content content = new Content.Builder()
    .addText("For use in a children's card game, generate 10 animal-based characters.")
    .build();

// For illustrative purposes only. You should use an executor that fits your needs.
Executor executor = Executors.newSingleThreadExecutor();

ListenableFuture<GenerateContentResponse> response = model.generateContent(content);
Futures.addCallback(
    response,
    new FutureCallback<GenerateContentResponse>() {
      @Override
      public void onSuccess(GenerateContentResponse result) {
        String resultText = result.getText();
        System.out.println(resultText);
      }

      @Override
      public void onFailure(Throwable t) {
        t.printStackTrace();
      }
    },
    executor);

Web

import { initializeApp } from "firebase/app";
import { getVertexAI, getGenerativeModel, Schema } from "firebase/vertexai";

// TODO(developer) Replace the following with your app's Firebase configuration.
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Vertex AI service.
const vertexAI = getVertexAI(firebaseApp);

// Provide a JSON schema object using a standard format.
// Later, pass this schema object into `responseSchema` in the generation config.
const jsonSchema = Schema.object({
 properties: {
    characters: Schema.array({
      items: Schema.object({
        properties: {
          name: Schema.string(),
          accessory: Schema.string(),
          age: Schema.number(),
          species: Schema.string(),
        },
        optionalProperties: ["accessory"],
      }),
    }),
  }
});

// Initialize the generative model.
const model = getGenerativeModel(vertexAI, {
  model: "gemini-2.0-flash",
  // In the generation config, set the `responseMimeType` to `application/json`
  // and pass the JSON schema object into `responseSchema`.
  generationConfig: {
    responseMimeType: "application/json",
    responseSchema: jsonSchema
  },
});


let prompt = "For use in a children's card game, generate 10 animal-based characters.";

let result = await model.generateContent(prompt)
console.log(result.response.text());

Dart

import 'package:firebase_vertexai/firebase_vertexai.dart';
import 'package:firebase_core/firebase_core.dart';

// Provide a JSON schema object using a standard format.
// Later, pass this schema object into `responseSchema` in the generation config.
final jsonSchema = Schema.object(
        properties: {
          'characters': Schema.array(
            items: Schema.object(
              properties: {
                'name': Schema.string(),
                'age': Schema.integer(),
                'species': Schema.string(),
                'accessory':
                    Schema.enumString(enumValues: ['hat', 'belt', 'shoes']),
              },
            ),
          ),
        },
        optionalProperties: ['accessory'],
      );

await Firebase.initializeApp();
// Initialize the Vertex AI service and the generative model.
final model =
      FirebaseVertexAI.instance.generativeModel(
        model: 'gemini-2.0-flash',
        // In the generation config, set the `responseMimeType` to `application/json`
        // and pass the JSON schema object into `responseSchema`.
        generationConfig: GenerationConfig(
            responseMimeType: 'application/json', responseSchema: jsonSchema));

final prompt = "For use in a children's card game, generate 10 animal-based characters.";
final response = await model.generateContent([Content.text(prompt)]);
print(response.text);

Единство

using Firebase;
using Firebase.AI;

// Provide a JSON schema object using a standard format.
// Later, pass this schema object into `responseSchema` in the generation config.
var jsonSchema = Schema.Object(
  properties: new System.Collections.Generic.Dictionary<string, Schema> {
    { "characters", Schema.Array(
      items: Schema.Object(
        properties: new System.Collections.Generic.Dictionary<string, Schema> {
          { "name", Schema.String() },
          { "age", Schema.Int() },
          { "species", Schema.String() },
          { "accessory", Schema.Enum(new string[] { "hat", "belt", "shoes" }) },
        },
        optionalProperties: new string[] { "accessory" }
      )
    ) },
  }
);

// Initialize the Firebase AI service and the generative model.
var model = FirebaseAI.DefaultInstance.GetGenerativeModel(
  modelName: "gemini-2.0-flash",
  // In the generation config, set the `responseMimeType` to `application/json`
  // and pass the JSON schema object into `responseSchema`.
  generationConfig: new GenerationConfig(
    responseMimeType: "application/json",
    responseSchema: jsonSchema
  )
);

var prompt = "For use in a children's card game, generate 10 animal-based characters.";

var response = await model.GenerateContentAsync(prompt);
UnityEngine.Debug.Log(response.Text ?? "No text in response.");

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

Дополнительные примеры

Вот несколько дополнительных примеров того, как можно использовать и генерировать структурированный вывод.

Генерировать значения перечисления в качестве выходных данных

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

Для выполнения этой задачи структурированной классификации вам необходимо указать во время инициализации модели соответствующий responseMimeType (в этом примере text/x.enum ), а также responseSchema , которую вы хотите использовать в модели.