Creare esperienze ibride nelle app web con modelli ospitati sul dispositivo e nel cloud

Puoi creare app web e funzionalità basate sull'AI con l'inferenza ibrida utilizzando Firebase AI Logic. L'inferenza ibrida consente di eseguire l'inferenza utilizzando modelli on-device, se disponibili, e di passare senza problemi ai modelli ospitati nel cloud in caso contrario (e viceversa).

In questa pagina viene descritto come iniziare a utilizzare l'SDK client. Dopo aver completato questa configurazione standard, consulta le opzioni di configurazione e le funzionalità aggiuntive.

Tieni presente che l'inferenza on-device tramite Firebase AI Logic è supportata per le app web che utilizzano l'SDK Firebase AI Logic v12.5.0 o versioni successive e che vengono eseguite su Chrome su computer (versione 139 o successive).

arrow_downward Vai agli esempi di codice

Casi d'uso e funzionalità supportate

A seconda dei casi d'uso della tua app, puoi sfruttare diversi vantaggi delle esperienze on-device o ibride:

• Vantaggi dell'utilizzo di un modello on-device per l'inferenza:

  • Privacy avanzata
  • Local Context
  • Inferenza senza costi
  • Funzionalità offline

• Vantaggi dell'utilizzo di un approccio ibrido:

  • Offri un'esperienza con l'app simile, indipendentemente dal dispositivo dell'utente finale
  • Migliorare la disponibilità delle funzionalità di AI generativa, indipendentemente dalla connettività a internet, dalle limitazioni delle quote o dalle funzionalità del dispositivo

Funzionalità di inferenza on-device supportate

L'inferenza on-device supporta solo la generazione di testo a turno singolo (non chat) (con output in streaming o non in streaming), in particolare le seguenti funzionalità:

• Generazione di testo da un 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.

Assicurati di consultare l'elenco delle funzionalità non ancora supportate per l'inferenza ibrida o on-device in fondo a questa pagina.

API e piattaforme supportate

Le sezioni seguenti descrivono le API supportate, nonché le piattaforme e i browser supportati.

API supportate per l'inferenza in cloud e on-device

• L'inferenza in-cloud utilizza il provider Gemini API scelto (Gemini Developer API o Agent Platform Gemini API (formerly Vertex AI)).

• L'inferenza on-device utilizza l'API Prompt di Chrome.

Piattaforme e browser supportati

Per l'inferenza on-device (che utilizza l'API Prompt di Chrome), l'utente finale della tua app deve eseguire Chrome su computer (versione 139 o successive). Scopri di più nella documentazione di Chrome.

Inizia a utilizzare localhost

Questi passaggi per iniziare descrivono la configurazione generale richiesta per qualsiasi richiesta di prompt supportata che vuoi inviare.

Puoi scoprire di più sull'utilizzo delle API su localhost nella documentazione di Chrome.

Passaggio 1: configura Chrome e l'API Prompt per l'inferenza on-device

1. Assicurati di utilizzare una versione recente di Chrome. Esegui l'aggiornamento in chrome://settings/help.
   L'inferenza on-device è disponibile a partire da Chrome v139.

2. Attiva il modello multimodale on-device impostando il seguente flag su Attivato:

   • chrome://flags/#prompt-api-for-gemini-nano-multimodal-input

3. Riavvia Chrome.

4. (Facoltativo) Scarica il modello on-device prima della prima richiesta.

   L'API Prompt è integrata in Chrome, ma il modello on-device non è disponibile per impostazione predefinita. Se non hai ancora scaricato il modello prima della prima richiesta di inferenza on-device, la richiesta avvierà automaticamente il download del modello in background.

   Visualizza le istruzioni per scaricare il modello on-device

   1. Apri Strumenti per sviluppatori > Console.

   2. Esegui questo comando:

      await LanguageModel.availability();
      

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

   4. Se l'output è downloadable, avvia il download del modello eseguendo:

      await LanguageModel.create();
      

   5. Puoi utilizzare il seguente callback monitor per monitorare l'avanzamento del download e assicurarti che il modello sia available prima di effettuare richieste:

      const session = await LanguageModel.create({
        monitor(m) {
          m.addEventListener("downloadprogress", (e) => {
            console.log(`Downloaded ${e.loaded * 100}%`);
          });
        },
      });
      

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 sul pulsante per crearne uno nuovo e poi utilizza una delle seguenti opzioni:

   • Opzione 1: crea un progetto Firebase completamente nuovo (e automaticamente il progetto Google Cloud sottostante) inserendo un nuovo nome del progetto nel primo passaggio del workflow.

   • Opzione 2: "Aggiungi Firebase" a un progetto Google Cloud esistente facendo clic su Aggiungi Firebase al progetto Google Cloud (in fondo alla pagina). Nel primo passaggio del workflow, inizia a inserire il nome del progetto esistente, quindi seleziona il progetto dall'elenco visualizzato.

   Completa i passaggi rimanenti del workflow sullo schermo per creare un progetto Firebase. Tieni presente che, quando richiesto, non è necessario configurare Google Analytics per utilizzare gli SDK Firebase AI Logic.

2. Nella console Firebase, vai a AI Services > 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. Se richiesto, segui le istruzioni sullo schermo per registrare la tua app e aggiungere la configurazione di Firebase alla tua app.

5. Quando ti viene chiesto di scegliere un "provider dell'API Gemini", ti consigliamo di selezionare l'API Gemini Developer, che ti consente di iniziare rapidamente senza costi.

   In qualsiasi momento successivo, puoi sempre configurare Agent Platform Gemini API (formerly Vertex AI) (e il relativo requisito per la fatturazione).

6. Continua nel workflow per configurare le API richieste e i servizi associati per Firebase AI Logic.

   Questa fase del workflow applica automaticamente Firebase App Check per AI Logic, che è un servizio critico per proteggere Gemini API quando l'accesso avviene direttamente dalla tua app. Come parte dei primi passi (vedi i passaggi più avanti in questa guida), dovrai configurare il provider di debug App Check per lo sviluppo locale quando App Check viene applicato.

7. Vai al passaggio successivo di questa guida per aggiungere gli SDK richiesti 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:

   npm install firebase
   

2. Inizializza Firebase nella tua app:

   import { initializeApp } from "firebase/app";
   import { initializeAppCheck } from "firebase/app-check";
   
   // 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: configura il provider di debug App Check per lo sviluppo locale

Nell'ambito del flusso di lavoro di configurazione guidata per AI Logic nella console, Firebase App Check viene applicato automaticamente per proteggere Gemini API. Per lo sviluppo locale, devi configurare il App Check provider di debug per bypassare l'attestazione, mantenendo comunque l'applicazione di App Check.

Ecco come utilizzare il provider di debug durante l'esecuzione interattiva dell'app da localhost (ad esempio, durante lo sviluppo locale):

1. Nella build di debug, attiva la modalità di debug impostando self.FIREBASE_APPCHECK_DEBUG_TOKEN su true prima di inizializzare App Check. Ad esempio:

   self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
   initializeAppCheck(firebaseApp, { /* App Check options */ });
   

2. Visita la tua app web localmente e apri gli strumenti per sviluppatori del browser. Nella console di debug, vedrai un token di debug:

   AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678".
   You will need to safelist it in the Firebase console for it to work.
   

3. Registra il token di debug con App Check:

   1. Nella console Firebase, vai alla scheda Sicurezza > App Check > App.

   2. Trova la tua app, fai clic sul menu extra (more_vert) e poi seleziona Gestisci token di debug.

   3. Segui le istruzioni sullo schermo per registrare il token di debug.

Per informazioni dettagliate sul provider di debug (tra cui come ottenere un nuovo token di debug), consulta la documentazione ufficiale di App Check.

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

Prima di inviare una richiesta di prompt al modello, configura quanto segue:

1. Inizializza il servizio per il provider API scelto.

2. Crea un'istanza GenerativeModel. Assicurati di impostare mode su uno dei seguenti valori:

   • PREFER_ON_DEVICE: utilizza il modello on-device, se disponibile; altrimenti, utilizza il modello ospitato nel cloud.

   • ONLY_ON_DEVICE: utilizza il modello on-device, se disponibile; altrimenti, genera un'eccezione.

   • PREFER_IN_CLOUD: utilizza il modello ospitato nel cloud, se disponibile; altrimenti, utilizza il modello on-device.

   • ONLY_IN_CLOUD: utilizza il modello ospitato nel cloud, se disponibile; altrimenti, genera un'eccezione.

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

// Create a `GenerativeModel` instance
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

Passaggio 6: inizializza il modello on-device

Devi chiamare initializeDeviceModel() dopo o durante un'interazione con la pagina dell'utente finale (ad esempio un clic su un pulsante) e prima di inviare una richiesta di prompt al modello. Scopri di più sul requisito di attivazione dell'utente nella documentazione di Chrome.

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

// Create a `GenerativeModel` instance
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

// `initializeDeviceModel` must be called:
// (1) after or on an end-user page interaction such as a button click
// and
// (2) before any queries to the model (such as `generateContent()`)
// You may want to `await` this promise if using `ONLY_ON_DEVICE` (see note below).
model.initializeDeviceModel((val) =>
  // Example: "Download progress: 72.62%""
  console.log(`Download progress: ${Math.round(val*10000) / 100}%`)
);

Passaggio 7: invia una richiesta di prompt a un modello

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

• Genera testo da un input di solo testo
• Genera testo generato da input di testo e immagini (multimodale)

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

Genera testo da un 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();

Tieni presente che Firebase AI Logic supporta anche lo streaming di risposte di testo utilizzando generateContentStream (anziché generateContent).

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 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 {
    type: "inlineData",
    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();

Tieni presente che Firebase AI Logic supporta anche lo streaming di risposte di testo utilizzando generateContentStream (anziché generateContent).

Cos'altro sai fare?

Puoi utilizzare varie opzioni e funzionalità di configurazione aggiuntive per le tue esperienze ibride:

• Imposta una modalità di inferenza.

• Determina se è stata utilizzata l'inferenza on-device o nel cloud.

• Esegui l'override del modello di riserva predefinito ospitato nel cloud.

• Utilizza la configurazione del modello per controllare le risposte.

• Generare output strutturati (come JSON ed enum).

Funzionalità non ancora supportate

Non tutte le funzionalità dell'SDK web o dei modelli ospitati nel cloud sono disponibili per l'inferenza ibrida o on-device.

Funzionalità non ancora supportate per le implementazioni ibride

Le seguenti funzionalità non possono essere utilizzate con le implementazioni ibride (né on-device né tramite fallback cloud):

• Gemini Live API: lo streaming bidirezionale in tempo reale non è supportato.

• Template di prompt del server: i template di prompt del server gestiti non sono supportati.

• Conteggio dei token: non fare affidamento sul conteggio dei token perché il conteggio sarà diverso tra i modelli ospitati nel cloud e quelli on-device, quindi non esiste un fallback intuitivo.

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

Le seguenti funzionalità non sono ancora supportate per l'inferenza on-device, ma sono disponibili per i modelli ospitati nel cloud.

• Generazione di immagini utilizzando i modelli Gemini Nano Banana

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

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

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

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

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

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

• Chat a più turni

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

• Fornire al modello strumenti per aiutarlo a generare la risposta (come chiamata di funzione, esecuzione di codice, contesto dell'URL, grounding con Google Search e grounding con Google Maps)

• Il monitoraggio AI nella console Firebase non mostra dati per l'inferenza on-device (inclusi i log del dispositivo on-device). Tuttavia, qualsiasi inferenza che utilizza un modello ospitato nel cloud può essere monitorata come qualsiasi altra inferenza tramite Firebase AI Logic.

Ulteriori limitazioni

Oltre a quanto sopra, l'inferenza on-device presenta le seguenti limitazioni:

• L'utente finale della tua app deve utilizzare Chrome su computer (versione 139 o successiva) con i flag richiesti attivati.

• Il modello on-device richiede spazio di archiviazione sufficiente sul dispositivo dell'utente per il download iniziale del modello.

Invia un feedback sulla tua esperienza con Firebase AI Logic