Crea esperienze ibride con modelli on-device e ospitati sul cloud


Crea app e funzionalità basate sull'IA con inferenza ibrida utilizzando Firebase AI Logic. L'inferenza ibrida consente di eseguire l'inferenza utilizzando i modelli on-device, se disponibili, e di eseguire il fallback ai modelli ospitati sul cloud in caso contrario.

Con questa release, l'inferenza ibrida è disponibile utilizzando l'SDK client Firebase AI Logic per il web con il supporto dell'inferenza on-device per Chrome su computer.

Vai agli esempi di codice

Casi d'uso consigliati e funzionalità supportate

Casi d'uso consigliati:

  • L'utilizzo di un modello on-device per le offerte di inferenza:

    • Privacy migliorata
    • Contesto locale
    • Inferenza senza costi
    • Funzionalità offline

  • Utilizzo delle offerte di funzionalità ibride:

    • Raggiungi il 100% del pubblico, indipendentemente dalla disponibilità del modello di dispositivo

Funzionalità e capacità supportate per l'inferenza on-device:

  • Generazione di contenuti a un solo passaggio, in streaming e non
  • Generazione di testo da input di solo testo
  • Generazione di testo da input di testo e immagini, in particolare tipi di immagini di input JPEG e PNG
  • Generazione di output strutturato, inclusi JSON ed enum

Inizia

Questa guida mostra come iniziare a utilizzare l'SDK Firebase AI Logic per il web per eseguire l'inferenza ibrida.

L'inferenza che utilizza un modello on-device utilizza l'API Prompt di Chrome, mentre l'inferenza che utilizza un modello ospitato sul cloud utilizza il provider Gemini API scelto (Gemini Developer API o Vertex AI Gemini API).

Passaggio 1: configura Chrome e l'API Prompt per l'inferenza sul dispositivo

  1. Scarica la compilazione più recente di Chrome Dev.

    L'inferenza sul dispositivo è disponibile a partire dalla versione 138 di Chrome.

  2. Abilita l'API Prompt per la tua istanza di Chrome impostando i seguenti flag:

    • chrome://flags/#optimization-guide-on-device-model: impostato su Enabled.
    • chrome://flags/#prompt-api-for-gemini-nano: impostato su Enabled.

    Scopri di più sull'utilizzo delle API su localhost nella documentazione di Chrome. Se vuoi, puoi partecipare al Early Preview Program (EPP) di Chrome per fornire un feedback.

  3. Attiva il modello multimodale on-device impostando il seguente flag:

    • chrome://flags/#prompt-api-for-gemini-nano-multimodal-input: impostato su Enabled.

  4. Verifica l'API localmente:

    1. Riavvia Chrome.

    2. Apri Strumenti per sviluppatori > Console.

    3. Esegui questo comando:

      await LanguageModel.availability();

    4. Assicurati che l'output sia available, downloading o downloadable. .

    5. Se l'output è downloadable, puoi avviare il download del modello eseguendo await LanguageModel.create();. In caso contrario, la prima richiesta per l'inferenza on-device avvierà un download del modello in background, che potrebbe richiedere diversi minuti.

Passaggio 2: configura un progetto Firebase e connetti la tua app a Firebase

  1. Accedi alla console Firebase, quindi seleziona il tuo progetto Firebase.

  2. Nella console Firebase, vai alla pagina Firebase AI Logic.

  3. Fai clic su Inizia per avviare un flusso di lavoro guidato che ti aiuta a configurare le API richieste e le risorse per il tuo progetto.

  4. Seleziona il provider "Gemini API" che vuoi utilizzare con gli SDK Firebase AI Logic. Se vuoi, puoi sempre configurare e utilizzare l'altro provider di API in un secondo momento.

    • Gemini Developer API - fatturazione facoltativa (disponibile nel piano tariffario Spark senza costi)
      La console abiliterà le API richieste e creerà una chiave API Gemini nel progetto.
      Non aggiungere questa chiave API Gemini al codice di base della tua app. Scopri di più.

      Puoi configurare la fatturazione in un secondo momento se vuoi eseguire l'upgrade del piano tariffario.

    • Vertex AI Gemini API: fatturazione obbligatoria (richiede il piano tariffario Blaze con pagamento a consumo)
      La console ti aiuterà a configurare la fatturazione e ad attivare le API obbligatorie nel tuo progetto.

  5. Se richiesto nel flusso di lavoro della console, segui le istruzioni sullo schermo per registrare l'app e collegarla a Firebase.

  6. Vai al passaggio successivo di questa guida per aggiungere l'SDK alla tua app.

Passaggio 3: aggiungi l'SDK

La libreria Firebase fornisce l'accesso alle API per interagire con i modelli generativi. La libreria è inclusa nell'SDK Firebase JavaScript per il web.

  1. Installa l'SDK Firebase JS per il web utilizzando npm.

    La funzionalità ibrida viene rilasciata con un tag npm diverso, quindi assicurati di includerla nel comando di installazione.

    npm install firebase@eap-ai-hybridinference

  2. Inizializza Firebase nella tua app:

    import { initializeApp } from "firebase/app";

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

Passaggio 4: inizializza il servizio e crea un'istanza del modello

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

Prima di inviare un prompt a un modello Gemini, inizializza il servizio per il provider dell'API scelto e crea un'istanza GenerativeModel.

Imposta mode su una delle seguenti opzioni:

  • prefer_on_device: configura l'SDK in modo da utilizzare il modello on-device, se disponibile, o passa al modello ospitato sul cloud.

  • only_on_device: configura l'SDK in modo da utilizzare il modello on-device o lancia un'eccezione.

  • only_in_cloud: configura l'SDK in modo da non utilizzare mai il modello on-device.

Per impostazione predefinita, quando utilizzi prefer_on_device o only_in_cloud, il modello ospitato su cloud è gemini-2.0-flash-lite, ma puoi sostituire il valore predefinito.

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend } 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() });

// Create a `GenerativeModel` instance
// Set the mode, for example to use on-device model when possible
const model = getGenerativeModel(ai, { mode: "prefer_on_device" });

Inviare una richiesta di prompt a un modello

Questa sezione fornisce esempi di come inviare vari tipi di input per generare diversi tipi di output, tra cui:

Se vuoi generare output strutturato (ad esempio JSON o enum), usa uno dei seguenti esempi di "generazione di testo" e, inoltre, configura il modello in modo che risponda in base a uno schema fornito.

Generare testo da input di solo testo

Prima di provare questo esempio, assicurati di aver completato la sezione Inizia di questa guida.

Puoi utilizzare generateContent() per generare testo da un prompt contenente testo:

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Wrap in an async function so you can use await
async function run() {
  // Provide a prompt that contains text
  const prompt = "Write a story about a magic backpack."

  // To generate text output, call `generateContent` with the text input
  const result = await model.generateContent(prompt);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

Genera testo da input di testo e immagini (multimodale)

Prima di provare questo esempio, assicurati di aver completato la sezione Inizia di questa guida.

Puoi utilizzare generateContent() per generare testo da un prompt contenente file di testo e immagini, fornendo il mimeType di ogni file di input e il file stesso.

I tipi di immagini di input supportati per l'inferenza on-device sono PNG e JPEG.

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Converts a File object to a Part object.
async function fileToGenerativePart(file) {
  const base64EncodedDataPromise = new Promise((resolve) => {
    const reader = new FileReader();
    reader.onloadend = () => resolve(reader.result.split(',')[1]);
    reader.readAsDataURL(file);
  });
  return {
    inlineData: { data: await base64EncodedDataPromise, mimeType: file.type },
  };
}

async function run() {
  // Provide a text prompt to include with the image
  const prompt = "Write a poem about this picture:";

  const fileInputEl = document.querySelector("input[type=file]");
  const imagePart = await fileToGenerativePart(fileInputEl.files[0]);

  // To generate text output, call `generateContent` with the text and image
  const result = await model.generateContent([prompt, imagePart]);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

Cos'altro puoi fare?

Oltre agli esempi precedenti, puoi anche utilizzare modalità di inferenza alternative, sostituire il modello di riserva predefinito e utilizzare la configurazione del modello per controllare le risposte.

Utilizzare modalità di inferenza alternativa

Gli esempi precedenti hanno utilizzato la modalità prefer_on_device per configurare l'SDK in modo da utilizzare un modello on-device, se disponibile, o un modello ospitato sul cloud. L'SDK offre due modalità di inferenza alternative: only_on_device e only_in_cloud.

  • Utilizza la modalità only_on_device in modo che l'SDK possa utilizzare solo un modello on-device. In questa configurazione, l'API restituirà un errore se non è disponibile un modello sul dispositivo.

    const model = getGenerativeModel(ai, { mode: "only_on_device" });

  • Utilizza la modalità only_in_cloud in modo che l'SDK possa utilizzare solo un modello ospitato sul cloud.

    const model = getGenerativeModel(ai, { mode: "only_in_cloud" });

Sostituire il modello di riserva predefinito

Quando utilizzi la modalità prefer_on_device, l'SDK utilizzerà un modello ospitato sul cloud se non è disponibile un modello on-device. Il modello predefinito ospitato su cloud di riserva è gemini-2.0-flash-lite. Questo modello ospitato su cloud è anche quello predefinito quando utilizzi la modalitàonly_in_cloud.

Puoi utilizzare l'opzione di configurazione inCloudParams per specificare un modello predefinito alternativo ospitato sul cloud:

const model = getGenerativeModel(ai, {
  mode: 'prefer_on_device',
  inCloudParams: {
    model: "gemini-2.0-flash"
  }
});

Trova i nomi dei modelli per tutti i modelli Gemini supportati.

Utilizzare la configurazione del modello per controllare le risposte

In ogni richiesta a un modello, puoi inviare una configurazione del modello per controllare come il modello genera una risposta. I modelli ospitati sul cloud e i modelli on-device offeriscono opzioni di configurazione diverse.

La configurazione viene mantenuta per tutta la durata dell'istanza. Se vuoi usare una configurazione diversa, crea una nuova istanza GenerativeModel con quella configurazione.

Impostare la configurazione per un modello ospitato su cloud

Utilizza l'opzione inCloudParams per configurare un modello Gemini ospitato su cloud. Scopri di più sui parametri disponibili.

const model = getGenerativeModel(ai, {
  mode: 'prefer_on_device',
  inCloudParams: {
    model: "gemini-2.0-flash"
    temperature: 0.8,
    topK: 10
  }
});

Impostare la configurazione per un modello on-device

Tieni presente che l'inferenza che utilizza un modello on-device utilizza l'API Prompt di Chrome.

Utilizza l'opzione onDeviceParams per configurare un modello on-device. Scopri di più sui parametri disponibili.

const model = getGenerativeModel(ai, {
  mode: 'prefer_on_device',
  onDeviceParams: {
    createOptions: {
      temperature: 0.8,
      topK: 8
    }
  }
});

Imposta la configurazione per l'output strutturato

La generazione di output strutturato (come JSON ed enum) è supportata per l'inferenza utilizzando sia i modelli ospitati sul cloud sia quelli on-device.

Per l'inferenza ibrida, utilizza sia inCloudParams sia onDeviceParams per configurare il modello in modo che risponda con un'uscita strutturata. Per le altre modalità, utilizza solo la configurazione applicabile.

  • Per inCloudParams: specifica il responseMimeType appropriato (in questo esempio, application/json) e il responseSchema che vuoi che il modello utilizzi.

  • Per onDeviceParams: specifica il valore responseConstraint che vuoi che il modello utilizzi.

Output JSON

Il seguente esempio adatta l'esempio di output JSON generale per l'inferenza ibrida:

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

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: 'prefer_on_device',
  inCloudParams: {
    model: "gemini-2.0-flash"
    generationConfig: {
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});
Output enum

Come sopra, ma adattando la documentazione sull'output dell'enum per l'inferenza ibrida:

// ...

const enumSchema = Schema.enumString({
  enum: ["drama", "comedy", "documentary"],
});

const model = getGenerativeModel(ai, {

// ...

    generationConfig: {
      responseMimeType: "text/x.enum",
      responseSchema: enumSchema
    },

// ...

Funzionalità non ancora disponibili per l'inferenza on-device

Poiché si tratta di una release sperimentale, non tutte le funzionalità dell'SDK web sono disponibili per l'inferenza sul dispositivo. Le seguenti funzionalità non sono ancora supportate per l'inferenza on-device (ma in genere sono disponibili per l'inferenza basata su cloud).

  • Generazione di testo da tipi di input di file immagine diversi da JPEG e PNG

    • Può eseguire il fallback al modello ospitato sul cloud. Tuttavia, la modalità only_on_device genera un errore.

  • Generazione di testo da input audio, video e documenti (ad esempio PDF)

    • Può eseguire il fallback al modello ospitato sul cloud. Tuttavia, la modalità only_on_device genera un errore.

  • Generazione di immagini utilizzando i modelli Gemini o Imagen

    • Può eseguire il fallback al modello ospitato sul cloud. Tuttavia, la modalità only_on_device genera un errore.

  • Fornire file utilizzando gli URL nelle richieste multimodali. Devi fornire i file come dati in linea ai modelli on-device.

  • Chat multi-turno

    • Può eseguire il fallback al modello ospitato sul cloud. Tuttavia, la modalità only_on_device genera un errore.

  • Streaming bidirezionale con Gemini Live API

    • Tieni presente che questa operazione non è supportata dall'SDK client Firebase AI Logic per il web anche per i modelli ospitati sul cloud.

  • Chiamata di funzione

    • Presto disponibile.

  • Contare i token

    • Genera sempre un errore. Il conteggio sarà diverso tra i modelli ospitati sul cloud e quelli on-device, quindi non esiste un'opzione di riserva intuitiva.

  • Monitoraggio dell'IA nella console Firebase per l'inferenza on-device.

    • Tieni presente che qualsiasi inferenza che utilizza i modelli ospitati sul cloud può essere monitorata come qualsiasi altra inferenza che utilizza l'SDK client Firebase AI Logic per il web.


Inviare un feedback sulla tua esperienza con Firebase AI Logic