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.

Antes de comenzar: Configura tu proyecto y clave de API

Antes de llamar a la API de Gemini, debes configurar tu proyecto y tu clave de API.

Generar JSON

Cuando el modelo está configurado para generar JSON, responde a cualquier instrucción con una salida en formato JSON.

Para controlar la estructura de la respuesta JSON, proporciona un esquema. Existen dos maneras de proporcionar un esquema al modelo:

  • Como texto en la instrucción
  • Como un esquema estructurado que se proporciona a través de la configuración del modelo

Proporciona un esquema como texto en la instrucción

En el siguiente ejemplo, se le solicita al modelo que devuelva recetas de galletas en un formato JSON específico.

Dado que el modelo obtiene la especificación de formato del texto de la instrucción, es posible que tengas cierta flexibilidad en la forma en que representas la especificación. Puede funcionar cualquier formato razonable para representar un esquema JSON.

from google import genai

prompt = """List a few popular cookie recipes in JSON format.

Use this JSON schema:

Recipe = {'recipe_name': str, 'ingredients': list[str]}
Return: list[Recipe]"""

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents=prompt,
)

# Use the response as a JSON string.
print(response.text)

El resultado podría verse de la siguiente manera:

[
  {
    "recipe_name": "Chocolate Chip Cookies",
    "ingredients": [
      "2 1/4 cups all-purpose flour",
      "1 teaspoon baking soda",
      "1 teaspoon salt",
      "1 cup (2 sticks) unsalted butter, softened",
      "3/4 cup granulated sugar",
      "3/4 cup packed brown sugar",
      "1 teaspoon vanilla extract",
      "2 large eggs",
      "2 cups chocolate chips"
    ]
  },
  ...
]

Proporciona un esquema a través de la configuración del modelo

En el siguiente ejemplo, se hace lo siguiente:

  1. Crea una instancia de un modelo configurado a través de un esquema para responder con JSON.
  2. Le solicita al modelo que muestre recetas de galletas.

Este método más formal para declarar el esquema JSON te brinda un control más preciso que depender solo del texto en la instrucción.

from google import genai
from pydantic import BaseModel


class Recipe(BaseModel):
  recipe_name: str
  ingredients: list[str]


client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='List a few popular cookie recipes. Be sure to include the amounts of ingredients.',
    config={
        'response_mime_type': 'application/json',
        'response_schema': list[Recipe],
    },
)
# Use the response as a JSON string.
print(response.text)

# Use instantiated objects.
my_recipes: list[Recipe] = response.parsed

El resultado podría verse de la siguiente manera:

[
  {
    "recipe_name": "Chocolate Chip Cookies",
    "ingredients": [
      "1 cup (2 sticks) unsalted butter, softened",
      "3/4 cup granulated sugar",
      "3/4 cup packed brown sugar",
      "1 teaspoon vanilla extract",
      "2 large eggs",
      "2 1/4 cups all-purpose flour",
      "1 teaspoon baking soda",
      "1 teaspoon salt",
      "2 cups chocolate chips"
    ]
  },
  ...
]

Sintaxis de la definición de esquema

Especifica el esquema de la respuesta JSON en la propiedad response_schema de la configuración de tu modelo. El valor de response_schema debe ser uno de los siguientes:

  • Un tipo, como lo usarías en una anotación de tipo. Consulta el módulo typing de Python.
  • Una instancia de genai.types.Schema.
  • El equivalente dict de genai.types.Schema.
Define un esquema con un tipo

La forma más fácil de definir un esquema es con un tipo directo. Este es el enfoque que se usó en el ejemplo anterior:

config={'response_mime_type': 'application/json',
        'response_schema': list[Recipe]}

La biblioteca cliente de Python de la API de Gemini admite esquemas definidos con los siguientes tipos (donde AllowedType es cualquier tipo permitido):

  • int
  • float
  • bool
  • str
  • list[AllowedType]
  • Para tipos estructurados:
    • dict[str, AllowedType]. Esta anotación declara que todos los valores del diccionario son del mismo tipo, pero no especifica qué claves se deben incluir.
    • Modelos de Pydantic definidos por el usuario Este enfoque te permite especificar los nombres de las claves y definir diferentes tipos para los valores asociados con cada una de las claves, incluidas las estructuras anidadas.

Usa una enum para restringir el resultado

En algunos casos, es posible que desees que el modelo elija una sola opción de una lista de opciones. Para implementar este comportamiento, puedes pasar una enum en tu esquema. Puedes usar una opción de enum en cualquier lugar en el que puedas usar un str en response_schema, porque una enum es una lista de cadenas. Al igual que un esquema JSON, una enumeración te permite construir el resultado del modelo para que cumpla con los requisitos de tu aplicación.

Por ejemplo, supongamos que estás desarrollando una aplicación para clasificar los instrumentos musicales en una de las cinco categorías: "Percussion", "String", "Woodwind", "Brass" o “"Keyboard"”. Podrías crear una enumeración para ayudar con esta tarea.

En el siguiente ejemplo, pasas la clase enum Instrument como response_schema, y el modelo debe elegir la opción de enum más apropiada.

from google import genai
import enum

class Instrument(enum.Enum):
  PERCUSSION = "Percussion"
  STRING = "String"
  WOODWIND = "Woodwind"
  BRASS = "Brass"
  KEYBOARD = "Keyboard"

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='What type of instrument is an oboe?',
    config={
        'response_mime_type': 'text/x.enum',
        'response_schema': Instrument,
    },
)

print(response.text)
# Woodwind

El SDK de Python traducirá las declaraciones de tipo para la API. Sin embargo, la API acepta un subconjunto del esquema de OpenAPI 3.0 (esquema). También puedes pasar el esquema como JSON:

from google import genai

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='What type of instrument is an oboe?',
    config={
        'response_mime_type': 'text/x.enum',
        'response_schema': {
            "type": "STRING",
            "enum": ["Percussion", "String", "Woodwind", "Brass", "Keyboard"],
        },
    },
)

print(response.text)
# Woodwind

Más allá de los problemas básicos de opción múltiple, puedes usar una enumeración en cualquier parte de un esquema para JSON o llamadas a funciones. Por ejemplo, puedes pedirle al modelo una lista de títulos de recetas y usar una enumeración Grade para asignarle a cada título una calificación de popularidad:

from google import genai

import enum
from pydantic import BaseModel

class Grade(enum.Enum):
    A_PLUS = "a+"
    A = "a"
    B = "b"
    C = "c"
    D = "d"
    F = "f"

class Recipe(BaseModel):
  recipe_name: str
  rating: Grade

client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.0-flash',
    contents='List 10 home-baked cookies and give them grades based on tastiness.',
    config={
        'response_mime_type': 'application/json',
        'response_schema': list[Recipe],
    },
)

print(response.text)
# [{"rating": "a+", "recipe_name": "Classic Chocolate Chip Cookies"}, ...]

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
  • bool
  • 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": "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 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.