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

Crea app e funzionalità basate sull'AI con l'inferenza ibrida utilizzando Firebase AI Logic. L'inferenza ibrida consente di eseguire l'inferenza utilizzando modelli sul dispositivo, se disponibili, e di passare senza problemi a 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 supporto per l'inferenza sul dispositivo 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 sul dispositivo per le offerte di inferenza:

  • Maggiore privacy
  • Contesto locale
  • Inferenza senza costi
  • Funzionalità offline

• Utilizzo delle offerte di funzionalità ibride:

  • Raggiungere il 100% del pubblico, indipendentemente dalla disponibilità del modello sul dispositivo

Funzionalità supportate per l'inferenza sul dispositivo:

• Generazione di contenuti in un solo passaggio, streaming e non streaming
• Generare 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 strutturati, inclusi JSON ed enumerazioni

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 sul dispositivo utilizza l'API Prompt di Chrome, mentre l'inferenza che utilizza un modello ospitato sul cloud utilizza il provider Gemini API che hai scelto (Gemini Developer API o Vertex AI Gemini API).

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

1. Scarica l'ultima build di Chrome Beta.

   L'inferenza sul dispositivo è disponibile a partire da Chrome v138 e versioni successive.

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

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

   Scopri di più sull'utilizzo delle API su localhost nella documentazione di Chrome. (Facoltativo) Iscriviti al Programma di anteprima anticipata (EPP) di Chrome per fornire feedback.

3. Attiva il modello multimodale sul dispositivo impostando il seguente flag:

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

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 di inferenza sul dispositivo avvierà il download di un 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.

   Non hai ancora un progetto Firebase?

   Se non hai ancora un progetto Firebase, fai clic su Crea progetto e utilizza una delle seguenti opzioni:

   • Opzione 1: crea un progetto Firebase completamente nuovo (e il relativo progetto Google Cloud sottostante) inserendo un nuovo nome del progetto nel primo passaggio del flusso di lavoro "Crea progetto".

   • Opzione 2: "Aggiungi Firebase" a un progetto Google Cloud esistente selezionando il nome del progetto Google Cloud dal menu a discesa nel primo passaggio del flusso di lavoro "Crea progetto".

   Tieni presente che, quando richiesto, non devi configurare Google Analytics per utilizzare gli SDK Firebase AI Logic.

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

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

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

   • Gemini Developer API: opzione di fatturazione (disponibile con il piano tariffario Spark senza costi, con possibilità di eseguire l'upgrade in un secondo momento, se desiderato)
     La console abiliterà le API richieste e creerà una chiave API Gemini nel tuo progetto.
     Non aggiungere questa chiave API Gemini al codebase della tua app. Scopri di più.

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

5. Se richiesto nel flusso di lavoro della console, segui le istruzioni sullo schermo per registrare la tua app e connetterla a Firebase.

6. Continua con il 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 includerlo 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

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

Imposta mode su uno dei seguenti valori:

• prefer_on_device: configura l'SDK in modo che utilizzi il modello sul dispositivo, se disponibile, o esegua il failover sul modello ospitato sul cloud.

• only_on_device: configura l'SDK in modo che utilizzi il modello sul dispositivo o generi un'eccezione.

• only_in_cloud: configura l'SDK in modo che non utilizzi mai il modello sul dispositivo.

Per impostazione predefinita, quando utilizzi prefer_on_device o only_in_cloud, il modello ospitato su cloud è gemini-2.0-flash-lite, ma puoi ignorare l'impostazione predefinita.

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:

• Generare testo da input solo di testo
• Generare testo da input di testo e immagini (multimodale)

Se vuoi generare un output strutturato (come JSON o enumerazioni), utilizza uno dei seguenti esempi di "generazione di testo" e configura il modello in modo che risponda in base a uno schema fornito.

Generare testo da input di solo testo

Puoi utilizzare generateContent() per generare testo da un prompt che contiene 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)

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

I tipi di immagini di input supportati per l'inferenza sul dispositivo 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 riportati sopra, puoi anche utilizzare modalità di inferenza alternative, ignorare il modello di riserva predefinito e utilizzare la configurazione del modello per controllare le risposte.

Utilizzare modalità di inferenza alternative

Gli esempi precedenti utilizzavano la modalità prefer_on_device per configurare l'SDK in modo da utilizzare un modello sul dispositivo, se disponibile, o eseguire il failover a 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 sul dispositivo. In questa configurazione, l'API genererà 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" });
  

Eseguire l'override del modello di riserva predefinito

Quando utilizzi la modalità prefer_on_device, l'SDK utilizzerà un modello ospitato sul cloud se un modello sul dispositivo non è disponibile. Il modello di riserva ospitato sul cloud predefinito è 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 alternativo predefinito ospitato sul cloud:

const model = getGenerativeModel(ai, {
  mode: 'prefer_on_device',
  inCloudParams: {
    model: "gemini-2.5-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 il modo in cui il modello genera una risposta. I modelli ospitati sul cloud e i modelli sul dispositivo offrono diverse opzioni di configurazione.

La configurazione viene mantenuta per l'intera durata dell'istanza. Se vuoi utilizzare una configurazione diversa, crea una nuova istanza di GenerativeModel con quella configurazione.

Imposta la configurazione per un modello ospitato sul cloud

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

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

Impostare la configurazione per un modello on-device

Tieni presente che l'inferenza che utilizza un modello sul dispositivo utilizza l'API Prompt di Chrome.

Utilizza l'opzione onDeviceParams per configurare un modello sul dispositivo. 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 strutturati (come JSON ed enumerazioni) è supportata per l'inferenza utilizzando modelli ospitati sul cloud e sul dispositivo.

Per l'inferenza ibrida, utilizza sia inCloudParams sia onDeviceParams per configurare il modello in modo che risponda con un output strutturato. 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 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.5-flash"
    generationConfig: {
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});

Output enum

Come sopra, ma adattando la documentazione sull'output 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 sul dispositivo

In quanto release sperimentale, non tutte le funzionalità dell'SDK web sono disponibili per l'inferenza on-device. Le seguenti funzionalità non sono ancora supportate per l'inferenza on-device (ma sono solitamente disponibili per l'inferenza basata sul 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 genererà un errore.

• Generazione di testo da input audio, video e documenti (come i PDF)

  • Può eseguire il fallback al modello ospitato sul cloud; tuttavia, la modalità only_on_device genererà un errore.

• Generare immagini utilizzando i modelli Gemini o Imagen

  • Può eseguire il fallback al modello ospitato sul cloud; tuttavia, la modalità only_on_device genererà un errore.

• Fornire file utilizzando URL nelle richieste multimodali. Devi fornire i file come dati incorporati ai modelli sul dispositivo.

• Chat multi-turno

  • Può eseguire il fallback al modello ospitato sul cloud; tuttavia, la modalità only_on_device genererà un errore.

• Streaming bidirezionale con Gemini Live API

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

• Chiamata di funzione

  • Presto disponibile.

• Conteggio dei token

  • Genera sempre un errore. Il conteggio sarà diverso tra i modelli ospitati sul cloud e quelli sul dispositivo, quindi non esiste un fallback intuitivo.

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

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

Fornisci un feedback sulla tua esperienza con Firebase AI Logic