Genera resultados estructurados para experiencias híbridas en apps web

De forma predeterminada, los modelos de Gemini devuelven respuestas como texto no estructurado. Sin embargo, algunos casos de uso requieren texto estructurado (como JSON o enumeraciones). 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 de casos de uso:

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

Ir a la salida de JSON Ir a la salida de enumeración

Configuración de los resultados estructurados

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

  • Modos de inferencia híbrida: 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 los modelos integrados en el dispositivo: Especifica el responseConstraint en onDeviceParams con un esquema creado con los métodos de ayuda de Schema o un esquema JSON simple.

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

  • Modos de inferencia no híbridos: Usa solo la configuración aplicable que se describió 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 a la salida de JSON Ir a la salida de enumeración

Salida de JSON

En los siguientes ejemplos, se adapta el ejemplo general de salida en formato JSON para admitir 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 un cuento 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 Schema de Firebase (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 adicional.

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

Ejemplo 1: Uso de 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 del objeto.

Antes de probar esta muestra, completa la sección Antes de comenzar de esta guía para configurar tu proyecto y tu 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 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: Uso de un esquema JSON simple

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

Antes de probar esta muestra, completa la sección Antes de comenzar de esta guía para configurar tu proyecto y tu 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 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()));

Salida de enumeración

En los siguientes ejemplos, se adapta el ejemplo general de resultado de enum para admitir 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 Schema de Firebase (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 adicional.

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

Ejemplo 1: Uso de 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 esta muestra, completa la sección Antes de comenzar de esta guía para configurar tu proyecto y tu 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 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: Uso de un esquema JSON simple

En este ejemplo, se define el esquema de enumeración solo con JSON.

Antes de probar esta muestra, completa la sección Antes de comenzar de esta guía para configurar tu proyecto y tu 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 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