Genera resultados estructurados para experiencias híbridas en apps web

De forma predeterminada, los modelos de Gemini muestran respuestas como texto no estructurado. Sin embargo, algunos casos de uso requieren texto estructurado, como JSON. Por ejemplo, es posible que uses la respuesta para otras tareas posteriores que requieran un esquema de datos establecido.

Para garantizar que el resultado generado por el modelo siempre cumpla con un esquema específico, puedes definir un esquema, que funciona como un modelo para las respuestas del modelo. Luego, puedes extraer datos directamente del resultado del modelo con menos procesamiento posterior.

Estos son algunos ejemplos:

  • Asegúrate de que la respuesta de un modelo genere un JSON válido y cumpla con el esquema que proporcionaste.
    Por ejemplo, el modelo puede generar entradas estructuradas para recetas que siempre incluyan el nombre de la receta, la lista de ingredientes y los pasos. Luego, puedes analizar y mostrar esta información con mayor facilidad en la IU de tu app.

  • Restringe la forma en que un modelo puede responder durante las tareas de clasificación.
    Por ejemplo, puedes hacer que el modelo anote texto con un conjunto específico de etiquetas (por ejemplo, un conjunto específico de enumeraciones como positive y negative), en lugar de etiquetas que produce el modelo (que podrían tener un grado de variabilidad como good, positive, negative o bad).

En esta página, se describe cómo generar resultados estructurados (como JSON y enumeraciones) en tus experiencias híbridas para apps web.

Antes de comenzar

Asegúrate de haber completado la guía de introducción para compilar experiencias híbridas.

Configura los resultados estructurados

Se admite la generación de resultados estructurados (como JSON y enumeraciones) para la inferencia con modelos alojados en la nube e integrados en el dispositivo.

Para la inferencia híbrida, usa tanto inCloudParams como onDeviceParams para configurar el modelo para que responda con resultados estructurados. Para los demás modos, usa solo la configuración aplicable.

  • Para inCloudParams: Especifica el responseMimeType adecuado (por ejemplo, application/json), así como el responseSchema que quieres que use el modelo.

  • Para onDeviceParams: Especifica la responseConstraint que quieres que use el modelo.

Salida de JSON

En los siguientes ejemplos, se adapta el ejemplo general de salida de JSON para adaptarse a la inferencia híbrida (en este ejemplo, PREFER_ON_DEVICE):

Ejemplo 1: Uso de métodos auxiliares Schema de Firebase

En este ejemplo, se usan métodos auxiliares que proporciona el SDK de Firebase AI Logic para que la definición del esquema sea más compacta.

import {
  getAI,
  getGenerativeModel,
  Schema
} from "firebase/ai";

// This schema can also be defined as a plain JSON object.
// See next snippet for an example of a plain JSON schema.
const jsonSchema = Schema.object({
 properties: {
    characters: Schema.array({
      items: Schema.object({
        properties: {
          name: Schema.string(),
          accessory: Schema.string(),
          age: Schema.number(),
          species: Schema.string(),
        },
        optionalProperties: ["accessory"],
      }),
    }),
  }
});

const model = getGenerativeModel(ai, {
  mode: InferenceMode.PREFER_ON_DEVICE,
  inCloudParams: {
    generationConfig: {
      model: "gemini-3.1-flash-lite",
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});

const result = await model
  .generateContent(
    "Create profiles for some characters for a fantasy story.");

console.log(result.response.text());
console.log(JSON.parse(result.response.text()));

// ...

Ejemplo 2: Uso de un esquema JSON simple

En este ejemplo, se define el esquema solo con JSON y se muestran los mismos resultados.

import {
  getAI,
  getGenerativeModel,
  Schema
} from "firebase/ai";

// The JSON schema defined as a plain JSON object.
const jsonSchema = {
    "type": "object",
    "properties": {
        "characters": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "nullable": false
                    },
                    "accessory": {
                        "type": "string",
                        "nullable": false
                    },
                    "age": {
                        "type": "number",
                        "nullable": false
                    },
                    "species": {
                        "type": "string",
                        "nullable": false
                    }
                },
                "nullable": false,
                "required": [
                    "name",
                    "age",
                    "species"
                ]
            },
            "nullable": false
        }
    },
    "nullable": false,
    "required": [
        "characters"
    ]
};

const model = getGenerativeModel(ai, {
  mode: InferenceMode.PREFER_ON_DEVICE,
  inCloudParams: {
    generationConfig: {
      model: "gemini-3.1-flash-lite",
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});

const result = await model
  .generateContent(
    "Create profiles for some characters for a fantasy story.");

console.log(result.response.text());
console.log(JSON.parse(result.response.text()));

Salida de enum

En el siguiente ejemplo, se adapta el ejemplo general de resultado de enum para adaptarse a la inferencia híbrida (en este ejemplo, PREFER_ON_DEVICE):

import {
  getAI,
  getGenerativeModel,
  Schema
} from "firebase/ai";

// enumSchema can also be defined as a plain JSON schema instead of
// using the `Schema` helper methods, just as in the JSON output example.
const enumSchema = Schema.enumString({
  enum: ["drama", "comedy", "documentary"],
});

const model = getGenerativeModel(ai, {
  mode: InferenceMode.PREFER_ON_DEVICE,
  inCloudParams: {
    generationConfig: {
      responseMimeType: "text/x.enum",
      responseSchema: enumSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: enumSchema
    }
  }
});

// ...