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

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

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

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

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

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

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

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

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

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

Модели, поддерживающие эту возможность

• gemini-3.1-pro-preview
• gemini-3.8-flash (а также более старые gemini-3.7-flash , gemini-3.6-flash и gemini-3.5-flash )
• gemini-3.5-flash-lite (и более старая модель gemini-3.1-flash-lite )

В обычных моделях Gemini 2.5 эта функция поддерживается, но все они устарели.

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

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

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

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

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

• Размер схемы ответа учитывается в лимите входных токенов.

• Функция схемы ответа поддерживает следующие MIME-типы ответов:

  • application/json : вывод в формате JSON, как определено в схеме ответа (полезно для требований к структурированному выводу).

  • text/x.enum : выводит значение перечисления, определенное в схеме ответа (полезно для задач классификации).

• Функция схемы ответа поддерживает следующие поля схемы:

  enum items

  maxItems nullable

  properties required

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

• По умолчанию в SDK Firebase AI Logic все поля считаются обязательными , если вы не укажете их как необязательные в массиве optionalProperties . Для этих необязательных полей модель может заполнить их самостоятельно или пропустить. Обратите внимание, что это противоположно поведению по умолчанию двух поставщиков API Gemini , если вы используете их серверные SDK или API напрямую.

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

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

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

import FirebaseAILogic

// 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 Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Create a `GenerativeModel` instance with a model that supports your use case.
let model = ai.generativeModel(
  modelName: "GEMINI_MODEL_NAME",
  // 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 =