Gerar saída estruturada com a API Gemini


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.

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 -> format
  • boolean
  • 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": "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"]
}

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 incoerente 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.