Genera output strutturato per esperienze ibride nelle app web

Per impostazione predefinita, i modelli Gemini restituiscono le risposte come testo non strutturato. Tuttavia, alcuni casi d'uso richiedono testo strutturato (come JSON o enum). Ad esempio, potresti utilizzare la risposta per altre attività downstream che richiedono uno schema di dati stabilito.

Per garantire che l'output generato dal modello rispetti sempre uno schema specifico, puoi definire uno schema, che funziona come un progetto per le risposte del modello. In questo modo, puoi estrarre direttamente i dati dall'output del modello con una minore post-elaborazione.

Ecco alcuni casi d'uso di esempio:

  • Assicurati che la risposta di un modello produca un JSON valido e sia conforme allo schema fornito.
    Ad esempio, il modello può generare voci strutturate per le ricette che includono sempre il nome della ricetta, l'elenco degli ingredienti e i passaggi. In questo modo, puoi analizzare e visualizzare più facilmente queste informazioni nell'interfaccia utente della tua app.

  • Limita il modo in cui un modello può rispondere durante le attività di classificazione.
    Ad esempio, puoi fare in modo che il modello annoti il testo con un insieme specifico di etichette (ad esempio, un insieme specifico di enum come positive e negative), anziché con le etichette prodotte dal modello (che potrebbero avere un grado di variabilità come good, positive, negative o bad).

Questa pagina descrive come generare output strutturato (come JSON ed enum) nelle tue esperienze ibride per le app web.

Vai all'output JSON Vai all'output enum

Configurazione per l'output strutturato

La generazione di output strutturati (come JSON ed enum) è supportata per l'inferenza utilizzando modelli ospitati nel cloud e on-device.

  • Modalità di inferenza ibride: configura sia inCloudParams sia onDeviceParams in modo che il modello risponda con un output strutturato indipendentemente dal fatto che l'inferenza venga eseguita nel cloud o on-device:

    • Per i modelli on-device: specifica responseConstraint in onDeviceParams utilizzando uno schema creato con i metodi helper Schema o uno schema JSON semplice.

    • Per i modelli ospitati nel cloud: specifica responseMimeType (application/json per JSON o text/x.enum per gli enum) e responseSchema in inCloudParams.

  • Modalità di inferenza non ibride: utilizza solo la configurazione applicabile descritta sopra.

Prima di iniziare

Fai clic sul tuo provider Gemini API per visualizzare i contenuti e il codice specifici del provider in questa pagina.

Assicurati di aver completato la guida introduttiva alla creazione di esperienze ibride.


Vai all'output JSON Vai all'output enum

Output JSON

Gli esempi seguenti adattano l'esempio di output JSON generale per supportare l'inferenza ibrida (ad esempio, PREFER_ON_DEVICE).

Nello scenario di questi esempi, il modello genera un elenco di profili di personaggi per una storia fantasy, con attributi strutturati come nome, età, specie e accessori facoltativi.

Puoi definire gli schemi di risposta utilizzando uno dei seguenti approcci:

  • Metodi helper di Firebase Schema (consigliato): utilizza i metodi helper (come Schema.object() e Schema.enumString()) per scrivere schemi concisi e compatti direttamente nel codice senza boilerplate aggiuntivi.

  • Schema JSON semplice: utilizza un oggetto schema JSON standard se hai già definizioni di schema esistenti, condividi schemi tra piattaforme o servizi di backend o importi schemi da file JSON.

Esempio 1: utilizzo dei metodi helper di Firebase Schema

Questo esempio utilizza i metodi helper Schema (come Schema.object, Schema.array, Schema.string e Schema.number) forniti dall'SDK Firebase AI Logic per definire lo schema dell'oggetto.

Prima di provare questo esempio, completa la sezione Prima di iniziare di questa guida per configurare il progetto e l'app.
In questa sezione, farai anche clic su un pulsante per il provider Gemini API scelto, in modo da visualizzare i contenuti specifici del provider in questa pagina. 

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()));

Esempio 2: utilizzo di uno schema JSON semplice

Questo esempio definisce lo schema utilizzando solo JSON.

Prima di provare questo esempio, completa la sezione Prima di iniziare di questa guida per configurare il progetto e l'app.
In questa sezione, farai anche clic su un pulsante per il provider Gemini API scelto, in modo da visualizzare i contenuti specifici del provider in questa pagina. 

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()));

Output enum

Gli esempi seguenti adattano l'esempio di output enum generale per supportare l'inferenza ibrida (ad esempio, PREFER_ON_DEVICE).

Nello scenario di questi esempi, il modello classifica la descrizione di un film selezionando un singolo genere da un elenco predefinito di opzioni consentite (drama, comedy o documentary).

Puoi definire gli schemi di risposta utilizzando uno dei seguenti approcci:

  • Metodi helper di Firebase Schema (consigliato): utilizza i metodi helper (come Schema.object() e Schema.enumString()) per scrivere schemi concisi e compatti direttamente nel codice senza boilerplate aggiuntivi.

  • Schema JSON semplice: utilizza un oggetto schema JSON standard se hai già definizioni di schema esistenti, condividi schemi tra piattaforme o servizi di backend o importi schemi da file JSON.

Esempio 1: utilizzo dei metodi helper di Firebase Schema

Questo esempio utilizza il metodo helper Schema.enumString fornito dall'SDK Firebase AI Logic per definire i valori enum consentiti.

Prima di provare questo esempio, completa la sezione Prima di iniziare di questa guida per configurare il progetto e l'app.
In questa sezione, farai anche clic su un pulsante per il provider Gemini API scelto, in modo da visualizzare i contenuti specifici del provider in questa pagina. 

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());

Esempio 2: utilizzo di uno schema JSON semplice

Questo esempio definisce lo schema enum utilizzando solo JSON.

Prima di provare questo esempio, completa la sezione Prima di iniziare di questa guida per configurare il progetto e l'app.
In questa sezione, farai anche clic su un pulsante per il provider Gemini API scelto, in modo da visualizzare i contenuti specifici del provider in questa pagina. 

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());


Invia un feedback sulla tua esperienza con Firebase AI Logic