Genera resultados estructurados con la API de Gemini


Gemini genera texto no estructurado de forma predeterminada, pero algunas aplicaciones requieren texto estructurado. Para estos casos de uso, puedes restringir Gemini para que responda con JSON, un formato de datos estructurados adecuado para el procesamiento automatizado. También puedes restringir el modelo para que responda con una de las opciones especificadas en una enumeración.

Estos son algunos casos de uso que podrían requerir un resultado estructurado del modelo:

  • Crea una base de datos de empresas extrayendo información de los artículos de los periódicos.
  • Extraer información estandarizada de los currículums
  • Extraer los ingredientes de las recetas y mostrar un vínculo a un sitio web de venta de comestibles para cada ingrediente

En tu instrucción, puedes pedirle a Gemini que genere un resultado con formato JSON, pero ten en cuenta que no se garantiza que el modelo genere JSON y nada más. Para obtener una respuesta más determinista, puedes pasar un esquema JSON específico en un campo responseSchema para que Gemini siempre responda con una estructura esperada. Para obtener más información sobre cómo trabajar con esquemas, consulta Más información sobre los esquemas JSON.

En esta guía, se muestra cómo generar JSON con el método generateContent a través del SDK que elijas o directamente con la API de REST. En los ejemplos, se muestra una entrada de solo texto, aunque Gemini también puede producir respuestas JSON a solicitudes multimodales que incluyen imágenes, videos y audio.

Más información sobre los esquemas JSON

Cuando configuras el modelo para que muestre una respuesta JSON, puedes usar un objeto Schema para definir la forma de los datos JSON. Schema representa un subconjunto selecto del objeto de esquema de OpenAPI 3.0.

Esta es una representación pseudo-JSON de todos los 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)
  }
}

El Type del esquema debe ser uno de los tipos de datos de OpenAPI. Solo un subconjunto de campos es válido para cada Type. En la siguiente lista, se asigna cada Type a campos válidos para ese tipo:

  • string -> enum, format
  • integer -> format
  • number -> format
  • boolean
  • array -> minItems, maxItems, items
  • object -> properties, required, propertyOrdering, nullable

Estos son algunos ejemplos de esquemas que muestran combinaciones válidas de tipo y 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 obtener la documentación completa de los campos del esquema tal como se usan en la API de Gemini, consulta la referencia del esquema.

Ordenamiento de propiedades

Cuando trabajas con esquemas JSON en la API de Gemini, el orden de las propiedades es importante. De forma predeterminada, la API ordena las propiedades alfabéticamente y no conserva el orden en el que se definen (aunque los SDKs de Google Gen AI pueden conservar este orden). Si proporcionas ejemplos al modelo con un esquema configurado y el orden de las propiedades de los ejemplos no es coherente con el orden de las propiedades del esquema, el resultado podría ser incoherente o inesperado.

Para garantizar un orden coherente y predecible de las propiedades, puedes usar el campo opcional propertyOrdering[].

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

propertyOrdering[], que no es un campo estándar en la especificación de OpenAPI, es un array de cadenas que se usa para determinar el orden de las propiedades en la respuesta. Si especificas el orden de las propiedades y, luego, proporcionas ejemplos con propiedades en ese mismo orden, es posible que mejores la calidad de los resultados.