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

Crea 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).

Questa pagina descrive come iniziare a utilizzare l'SDK client. Dopo aver completato questa configurazione standard, dai un'occhiata alle opzioni e funzionalità di configurazione aggiuntive (come l'output strutturato).

Tieni presente che l'inferenza on-device è supportata per le app web eseguite su 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 l'inferenza offre:

  • Maggiore privacy
  • Local Context
  • Inferenza senza costi
  • Funzionalità offline

• L'utilizzo della funzionalità ibrida offre:

  • Raggiungi il 100% del tuo pubblico, indipendentemente dalla disponibilità del modello on-device o dalla connessione a internet

Funzionalità supportate per l'inferenza on-device:

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

• 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

Puoi anche generare output strutturati, inclusi JSON ed enum.

Prima di iniziare

Tieni presente quanto segue:

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

• In questa pagina viene descritto come iniziare a sviluppare utilizzando localhost (scopri di più sull'utilizzo delle API su localhost nella documentazione di Chrome).

  Dopo aver completato questa configurazione standard, consulta le opzioni e funzionalità di configurazione aggiuntive (come l'output strutturato).

Inizia a utilizzare localhost

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

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, quindi 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 flusso di lavoro 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 e le risorse richieste per il tuo progetto.

4. Se richiesto, segui le istruzioni sullo schermo per registrare la tua app e aggiungere la configurazione Firebase all'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 di 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

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

• Utilizza la configurazione del modello per controllare le risposte

• Genera output strutturato (come JSON)

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

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 generalmente disponibili per l'inferenza basata su cloud).

• 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 di audio, video e documenti (come i PDF)

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

• 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.

• 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.

• Streaming bidirezionale con Gemini Live API

• 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)

• Contare i token

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

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

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

Invia un feedback sulla tua esperienza con Firebase AI Logic