Генерируйте структурированный вывод с помощью Gemini API

Python Node.js Go Dart (Flutter) Android Swift Web REST

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

Вот несколько случаев использования, которые могут потребовать структурированного вывода модели:

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

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

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

Прежде чем начать: настройте проект и ключ API.

Прежде чем вызывать API Gemini, вам необходимо настроить проект и ключ API.

Создать JSON

Когда модель настроена для вывода JSON, она отвечает на любой запрос выводом в формате JSON.

Вы можете управлять структурой ответа JSON, предоставив схему. Существует два способа предоставления схемы в модель:

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

Предоставьте схему в виде текста в приглашении

В следующем примере модели предлагается вернуть рецепты файлов cookie в определенном формате JSON.

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

// Make sure to include these imports:
// import { GoogleGenerativeAI } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

const model = genAI.getGenerativeModel({
  model: "gemini-1.5-flash",
});

const prompt = `List a few popular cookie recipes using this JSON schema:

Recipe = {'recipeName': string}
Return: Array<Recipe>`;

const result = await model.generateContent(prompt);
console.log(result.response.text());
controlled_generation.js

Вывод может выглядеть так:

[{"recipeName": "Chocolate Chip Cookies"}, {"recipeName": "Oatmeal Raisin Cookies"}, {"recipeName": "Snickerdoodles"}, {"recipeName": "Sugar Cookies"}, {"recipeName": "Peanut Butter Cookies"}]

Предоставьте схему через конфигурацию модели.

Следующий пример делает следующее:

1. Создает экземпляр модели, настроенной с помощью схемы для ответа в формате JSON.
2. Предлагает модели вернуть рецепты печенья.

Этот более формальный метод объявления схемы JSON обеспечивает более точный контроль, чем просто использование текста в приглашении.

// Make sure to include these imports:
// import { GoogleGenerativeAI, SchemaType } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

const schema = {
  description: "List of recipes",
  type: SchemaType.ARRAY,
  items: {
    type: SchemaType.OBJECT,
    properties: {
      recipeName: {
        type: SchemaType.STRING,
        description: "Name of the recipe",
        nullable: false,
      },
    },
    required: ["recipeName"],
  },
};

const model = genAI.getGenerativeModel({
  model: "gemini-1.5-pro",
  generationConfig: {
    responseMimeType: "application/json",
    responseSchema: schema,
  },
});

const result = await model.generateContent(
  "List a few popular cookie recipes.",
);
console.log(result.response.text());
controlled_generation.js

Вывод может выглядеть так:

[{"recipeName": "Chocolate Chip Cookies"}, {"recipeName": "Oatmeal Raisin Cookies"}, {"recipeName": "Snickerdoodles"}, {"recipeName": "Sugar Cookies"}, {"recipeName": "Peanut Butter Cookies"}]

Подробнее о схемах JSON

Когда вы настраиваете модель для возврата ответа JSON, вы можете использовать объект Schema , чтобы определить форму данных JSON. Schema представляет собой избранное подмножество объекта схемы OpenAPI 3.0 .

Вот псевдо-JSON-представление всех полей Schema :

{
  "type": enum (Type),
  "format": string,
  "description": string,
  "nullable": boolean,
  "enum": [
    string
  ],
  "maxItems": string,
  "minItems": string,
  "properties": {
    string: {
      object (Schema)
    },
    ...
  },
  "required": [
    string
  ],
  "propertyOrdering": [
    string
  ],
  "items": {
    object (Schema)
  }
}

Type схемы должен быть одним из типов данных OpenAPI. Для каждого Type допустимо только подмножество полей. В следующем списке каждый Type сопоставлен с допустимыми полями для этого типа:

• string -> перечисление, формат
• integer -> формат
• number -> формат
• boolean
• array -> minItems, maxItems, элементы
• object -> свойства, обязательные, propertyOrdering, обнуляемые

Вот несколько примеров схем, показывающих допустимые комбинации типа и поля:

{ "type": "string", "enum": ["a", "b", "c"] }

{ "type": "string", "format": "date-time" }

{ "type": "integer", "format": "int64" }

{ "type": "number", "format": "double" }

{ "type": "boolean" }

{ "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": ... } }

{ "type": "object",
  "properties": {
    "a": { "type": ... },
    "b": { "type": ... },
    "c": { "type": ... }
  },
  "nullable": true,
  "required": ["c"],
  "propertyOrdering": ["c", "b", "a"]
}

Полную документацию по полям схемы, которые используются в Gemini API, см. в справочнике по схеме .

Заказ недвижимости

Когда вы работаете со схемами JSON в Gemini API, порядок свойств важен. По умолчанию API упорядочивает свойства в алфавитном порядке и не сохраняет порядок, в котором они определены (хотя SDK Google Gen AI могут сохранять этот порядок). Если вы предоставляете примеры для модели с настроенной схемой, а порядок свойств примеров не соответствует порядку свойств схемы, выходные данные могут быть бессвязными или неожиданными.

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

"propertyOrdering": ["recipe_name", "ingredients"]

propertyOrdering[] — не стандартное поле в спецификации OpenAPI — представляет собой массив строк, используемый для определения порядка свойств в ответе. Указав порядок свойств, а затем предоставив примеры свойств в том же порядке, вы потенциально можете улучшить качество результатов.