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 enumerazioni). Ad esempio, potresti utilizzare la risposta per altre attività downstream che richiedono uno schema di dati stabilito.

Per assicurarti 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. Puoi quindi estrarre direttamente i dati dall'output del modello con una post-elaborazione minore.

Ecco alcuni casi d'uso di esempio:

  • Assicurati che la risposta di un modello produca un JSON valido e sia conforme allo schema che hai 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, potrai 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 chiedere al modello di annotare il testo con un insieme specifico di etichette (ad esempio, un insieme specifico di enum come positive e negative), anziché con etichette prodotte dal modello (che potrebbero avere un certo grado di variabilità come good, positive, negative o bad).

Questa pagina descrive come generare output strutturati (come JSON ed enumerazioni) 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 strutturato (come JSON ed enum) è supportata per l'inferenza utilizzando modelli ospitati sul cloud e sul dispositivo.

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

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

    • Per i modelli ospitati sul 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 in precedenza.

Prima di iniziare

Fai clic sul tuo fornitore Gemini API per visualizzare i contenuti e il codice specifici del fornitore 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 adattarsi all'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 opzionali.

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

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

  • 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 importa 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, fai clic anche su un pulsante per il provider Gemini API che hai 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, fai clic anche su un pulsante per il provider Gemini API che hai 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 di enumerazione generale per adattarsi all'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 Schema di Firebase (consigliato): utilizza metodi helper (come Schema.object() e Schema.enumString()) per scrivere schemi concisi e compatti direttamente nel codice senza boilerplate aggiuntivo.

  • 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 importa 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, fai clic anche su un pulsante per il provider Gemini API che hai 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, fai clic anche su un pulsante per il provider Gemini API che hai 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());


Fornisci un feedback sulla tua esperienza con Firebase AI Logic