Genera resultados estructurados para experiencias híbridas en apps web

Los modelos de Gemini devuelven respuestas como texto no estructurado de forma predeterminada. Sin embargo, algunos casos de uso requieren texto estructurado (como JSON o enumeraciones). Por ejemplo, es posible que uses la respuesta para otras tareas downstream 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 de casos de uso:

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

  • Restringir 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 las 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.

Ir al resultado de JSON Ir al resultado de enum

Configuración para resultados estructurados

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

  • Modos de inferencia híbridos: Configura inCloudParams y onDeviceParams para que el modelo responda con un resultado estructurado, independientemente de si la inferencia se ejecuta en la nube o integrado en el dispositivo:

    • Para modelos integrados en el dispositivo: Especifica el responseConstraint en onDeviceParams con un esquema creado con métodos auxiliares de Schema o un esquema JSON simple.

    • Para los modelos alojados en la nube: Especifica el responseMimeType (application/json para JSON o text/x.enum para enumeraciones) y el responseSchema en inCloudParams.

  • Modos de inferencia no híbridos: Usa solo la configuración aplicable descrita anteriormente.

Antes de comenzar

Haz clic en tu proveedor de Gemini API para ver el contenido y el código específicos del proveedor en esta página.

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


Ir al resultado de JSON Ir al resultado de enum

Salida de JSON

En los siguientes ejemplos, se adapta el ejemplo de resultado de JSON general para dar cabida a la inferencia híbrida (por ejemplo, PREFER_ON_DEVICE).

En la situación de estos ejemplos, el modelo genera una lista de perfiles de personajes para una historia de fantasía, con atributos estructurados, como nombre, edad, especie y accesorios opcionales.

Puedes definir tus esquemas de respuesta con cualquiera de los siguientes enfoques:

  • Métodos auxiliares de Firebase Schema (recomendado): Usa métodos auxiliares (como Schema.object() y Schema.enumString()) para escribir esquemas concisos y compactos directamente en tu código sin código estándar adicional.

  • Esquema JSON simple: Usa un objeto de esquema JSON estándar si ya tienes definiciones de esquema existentes, compartes esquemas entre plataformas o servicios de backend, o importas esquemas desde archivos JSON.

Ejemplo 1: Usa los métodos auxiliares de Schema de Firebase

En este ejemplo, se usan métodos auxiliares de Schema (como Schema.object, Schema.array, Schema.string y Schema.number) que proporciona el SDK de Firebase AI Logic para definir el esquema de objetos.

Antes de probar este ejemplo, completa la sección Antes de comenzar de esta guía para configurar tu proyecto y app.
En esa sección, también harás clic en un botón para el proveedor de Gemini API que elijas, de modo que veas el contenido específico del proveedor en esta página. 

import { initializeApp } from "firebase/app";
import {
  getAI,
  getGenerativeModel,
  GoogleAIBackend,
  InferenceMode,
  Schema
} from "firebase/ai";

// TODO(developer): Replace the following with your app's Firebase configuration.
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp.
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service.
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Define a schema using the `Schema` helper methods.
// Optional properties are specified in optionalProperties.
const jsonSchema = Schema.object({
  properties: {
    characters: Schema.array({
      items: Schema.object({
        properties: {
          name: Schema.string(),
          age: Schema.number(),
          species: Schema.string(),
          accessory: Schema.string()
        },
        optionalProperties: ["accessory"]
      })
    })
  }
});

// Create a GenerativeModel instance configured to use a hybrid inference mode (like PREFER_ON_DEVICE).
const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  // For cloud-hosted models, specify MIME type and response schema.
  inCloudParams: {
    model: "CLOUD_MODEL_NAME",
    generationConfig: {
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    }
  },
  // For on-device models, pass the schema as the response constraint.
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});

const prompt = "Create profiles for some characters for a fantasy story.";

// Generate the structured output.
const result = await model.generateContent(prompt);

// Access the generated JSON string conforming to the schema from response.text().
console.log(result.response.text());

// Parse the JSON string into a JavaScript object.
console.log(JSON.parse(result.response.text()));

Ejemplo 2: Usa un esquema JSON simple

En este ejemplo, se define el esquema solo con JSON.

Antes de probar este ejemplo, completa la sección Antes de comenzar de esta guía para configurar tu proyecto y app.
En esa sección, también harás clic en un botón para el proveedor de Gemini API que elijas, de modo que veas el contenido específico del proveedor en esta página. 

import { initializeApp } from "firebase/app";
import {
  getAI,
  getGenerativeModel,
  GoogleAIBackend,
  InferenceMode
} from "firebase/ai";

// TODO(developer): Replace the following with your app's Firebase configuration.
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp.
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service.
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Define the schema as a plain JSON object.
// Properties are required by default unless omitted from the required array.
const jsonSchema = {
  type: "object",
  properties: {
    characters: {
      type: "array",
      items: {
        type: "object",
        properties: {
          name: {
            type: "string",
            nullable: false
          },
          age: {
            type: "number",
            nullable: false
          },
          species: {
            type: "string",
            nullable: false
          },
          accessory: {
            type: "string",
            nullable: true
          }
        },
        nullable: false,
        required: [
          "name",
          "age",
          "species"
        ]
      },
      nullable: false
    }
  },
  nullable: false,
  required: [
    "characters"
  ]
};

// Create a GenerativeModel instance configured to use a hybrid inference mode (like PREFER_ON_DEVICE).
const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  // For cloud-hosted models, specify MIME type and response schema.
  inCloudParams: {
    model: "CLOUD_MODEL_NAME",
    generationConfig: {
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    }
  },
  // For on-device models, pass the schema as the response constraint.
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});

const prompt = "Create profiles for some characters for a fantasy story.";

// Generate the structured output.
const result = await model.generateContent(prompt);

// Access the generated JSON string conforming to the schema from response.text().
console.log(result.response.text());

// Parse the JSON string into a JavaScript object.
console.log(JSON.parse(result.response.text()));

Resultado de enum

En los siguientes ejemplos, se adapta el ejemplo de resultado de enumeración general para dar cabida a la inferencia híbrida (por ejemplo, PREFER_ON_DEVICE).

En la situación de estos ejemplos, el modelo clasifica la descripción de una película seleccionando un solo género de una lista predefinida de opciones permitidas (drama, comedy o documentary).

Puedes definir tus esquemas de respuesta con cualquiera de los siguientes enfoques:

  • Métodos auxiliares de Firebase Schema (recomendado): Usa métodos auxiliares (como Schema.object() y Schema.enumString()) para escribir esquemas concisos y compactos directamente en tu código sin código estándar adicional.

  • Esquema JSON simple: Usa un objeto de esquema JSON estándar si ya tienes definiciones de esquema existentes, compartes esquemas entre plataformas o servicios de backend, o importas esquemas desde archivos JSON.

Ejemplo 1: Usa los métodos auxiliares de Schema de Firebase

En este ejemplo, se usa el método auxiliar Schema.enumString que proporciona el SDK de Firebase AI Logic para definir los valores de enumeración permitidos.

Antes de probar este ejemplo, completa la sección Antes de comenzar de esta guía para configurar tu proyecto y app.
En esa sección, también harás clic en un botón para el proveedor de Gemini API que elijas, de modo que veas el contenido específico del proveedor en esta página. 

import { initializeApp } from "firebase/app";
import {
  getAI,
  getGenerativeModel,
  GoogleAIBackend,
  InferenceMode,
  Schema
} from "firebase/ai";

// TODO(developer): Replace the following with your app's Firebase configuration.
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp.
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service.
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Define an enum schema using the `Schema` helper method with allowed string values.
const enumSchema = Schema.enumString({
  enum: ["drama", "comedy", "documentary"]
});

// Create a GenerativeModel instance configured to use a hybrid inference mode (like PREFER_ON_DEVICE).
const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  // For cloud-hosted models, specify MIME type and response schema.
  inCloudParams: {
    model: "CLOUD_MODEL_NAME",
    generationConfig: {
      responseMimeType: "text/x.enum",
      responseSchema: enumSchema
    }
  },
  // For on-device models, pass the enum schema as the response constraint.
  onDeviceParams: {
    promptOptions: {
      responseConstraint: enumSchema
    }
  }
});

const prompt = `The film aims to educate and inform viewers about real-life
subjects, events, or people. It offers a factual record of a particular topic
by combining interviews, historical footage, and narration. The primary purpose
of a film is to present information and provide insights into various aspects
of reality.`;

// Generate the structured enum output.
const result = await model.generateContent(prompt);

// Access the selected enum value string from response.text().
console.log(result.response.text());

Ejemplo 2: Usa un esquema JSON simple

En este ejemplo, se define el esquema de enum solo con JSON.

Antes de probar este ejemplo, completa la sección Antes de comenzar de esta guía para configurar tu proyecto y app.
En esa sección, también harás clic en un botón para el proveedor de Gemini API que elijas, de modo que veas el contenido específico del proveedor en esta página. 

import { initializeApp } from "firebase/app";
import {
  getAI,
  getGenerativeModel,
  GoogleAIBackend,
  InferenceMode
} from "firebase/ai";

// TODO(developer): Replace the following with your app's Firebase configuration.
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp.
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service.
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Define the enum schema as a plain JSON object.
const enumSchema = {
  type: "string",
  enum: ["drama", "comedy", "documentary"]
};

// Create a GenerativeModel instance configured to use a hybrid inference mode (like PREFER_ON_DEVICE).
const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  // For cloud-hosted models, specify MIME type and response schema.
  inCloudParams: {
    model: "CLOUD_MODEL_NAME",
    generationConfig: {
      responseMimeType: "text/x.enum",
      responseSchema: enumSchema
    }
  },
  // For on-device models, pass the enum schema as the response constraint.
  onDeviceParams: {
    promptOptions: {
      responseConstraint: enumSchema
    }
  }
});

const prompt = `The film aims to educate and inform viewers about real-life
subjects, events, or people. It offers a factual record of a particular topic
by combining interviews, historical footage, and narration. The primary purpose
of a film is to present information and provide insights into various aspects
of reality.`;

// Generate the structured enum output.
const result = await model.generateContent(prompt);

// Access the selected enum value string from response.text().
console.log(result.response.text());


Envía comentarios sobre tu experiencia con Firebase AI Logic