Gerar saída estruturada com a API Gemini

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

O Gemini gera texto não estruturado por padrão, mas alguns aplicativos exigem texto estruturado. Para esses casos de uso, você pode restringir o Gemini para responder com JSON, um formato de dados estruturado adequado para processamento automatizado. Também é possível restringir o modelo para responder com uma das opções especificadas em um tipo enumerado.

Confira alguns casos de uso que podem exigir uma saída estruturada do modelo:

• Crie um banco de dados de empresas extraindo informações de artigos de jornal.
• Extrair informações padronizadas dos currículos.
• Extrair ingredientes de receitas e mostrar um link para um site de compras para cada ingrediente.

No comando, você pode pedir que o Gemini produza uma saída formatada em JSON, mas não há garantia de que o modelo vai produzir JSON e nada além disso. Para uma resposta mais determinística, transmita um esquema JSON específico em um campo responseSchema para que o Gemini sempre responda com uma estrutura esperada. Para saber mais sobre como trabalhar com esquemas, consulte Mais informações sobre esquemas JSON.

Este guia mostra como gerar JSON usando o método generateContent pelo SDK de sua preferência ou diretamente pela API REST. Os exemplos mostram entradas somente em texto, mas o Gemini também pode produzir respostas JSON para solicitações multimodais que incluem imagens, vídeos e áudio.

Antes de começar: configure o projeto e a chave de API

Antes de chamar a API Gemini, você precisa configurar seu projeto e a chave de API.

Gerar JSON

Quando o modelo é configurado para gerar JSON, ele responde a qualquer comando com saída formatada em JSON.

É possível controlar a estrutura da resposta JSON fornecendo um esquema. Há duas maneiras de fornecer um esquema ao modelo:

• Como texto no comando
• Como um esquema estruturado fornecido pela configuração do modelo

Fornecer um esquema como texto no comando

O exemplo a seguir solicita que o modelo retorne receitas de biscoitos em um formato JSON específico.

Como o modelo recebe a especificação de formato do texto no comando, você pode ter alguma flexibilidade na representação da especificação. Qualquer formato razoável para representar um esquema JSON pode funcionar.

// 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

A saída pode ser semelhante a esta:

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

Fornecer um esquema pela configuração do modelo

O exemplo a seguir faz o seguinte:

1. Cria um modelo configurado por um esquema para responder com JSON.
2. Solicita ao modelo que retorne receitas de biscoitos.

Esse método mais formal de declaração do esquema JSON oferece um controle mais preciso do que depender apenas do texto no prompt.

// 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

A saída pode ser semelhante a esta:

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

Mais informações sobre os esquemas JSON

Ao configurar o modelo para retornar uma resposta JSON, você pode usar um objeto Schema para definir a forma dos dados JSON. O Schema representa um subconjunto selecionado do objeto de esquema da OpenAPI 3.0.

Confira uma representação pseudo-JSON de todos os campos 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)
  }
}

O Type do esquema precisa ser um dos tipos de dados da OpenAPI. Apenas um subconjunto de campos é válido para cada Type. A lista a seguir mapeia cada Type para campos válidos para esse tipo:

• string: -> tipo enumerado, formato
• integer -> formato
• number -> formato
• bool
• array -> minItems, maxItems, items
• object -> properties, required, propertyOrdering, nullable

Confira alguns exemplos de esquemas que mostram combinações válidas de tipo e campo:

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

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

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

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

{ "type": "bool" }

{ "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"]
}

Para conferir a documentação completa dos campos do esquema conforme eles são usados na API Gemini, consulte a Referência do esquema.

Ordenação de propriedades

Ao trabalhar com esquemas JSON na API Gemini, a ordem das propriedades é importante. Por padrão, a API ordena as propriedades em ordem alfabética e não preserva a ordem em que as propriedades são definidas, embora os SDKs do Google Gen AI possam preservar essa ordem. Se você estiver fornecendo exemplos ao modelo com um esquema configurado e a ordem das propriedades dos exemplos não for consistente com a ordem das propriedades do esquema, a saída poderá ser confusa ou inesperada.

Para garantir uma ordenação consistente e previsível das propriedades, use o campo propertyOrdering[] opcional.

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

propertyOrdering[], que não é um campo padrão na especificação da OpenAPI, é uma matriz de strings usada para determinar a ordem das propriedades na resposta. Ao especificar a ordem das propriedades e fornecer exemplos com propriedades nessa mesma ordem, você pode melhorar a qualidade dos resultados.