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

Crea app e funzionalità web basate sull'AI con l'inferenza ibrida utilizzando Firebase AI Logic. L'inferenza ibrida consente di eseguire l'inferenza utilizzando i modelli sul dispositivo, se disponibili, e di eseguire automaticamente il fallback ai modelli ospitati sul cloud in caso contrario (e viceversa).

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

Tieni presente che l'inferenza sul dispositivo è 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 sul dispositivo per l'inferenza offre:

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

• L'utilizzo della funzionalità ibrida offre:

  • Raggiungi il 100% del pubblico, indipendentemente dalla disponibilità del modello sul dispositivo o dalla connettività a internet

Funzionalità supportate per l'inferenza sul dispositivo:

L'inferenza sul dispositivo supporta solo la generazione di testo a turno singolo (non la 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 sul dispositivo utilizza l' API Prompt di Chrome; mentre l'inferenza che utilizza un modello ospitato sul cloud utilizza il Gemini API provider scelto (l'Gemini Developer API o l' 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 le funzionalità di configurazione aggiuntive (come l'output strutturato).

Inizia a utilizzare localhost

Questi passaggi iniziali 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 sul dispositivo

1. Assicurati di utilizzare una versione recente di Chrome. Aggiorna in chrome://settings/help.
   L'inferenza sul dispositivo è disponibile a partire da Chrome v139 e versioni successive.

2. Attiva il modello multimodale sul dispositivo impostando il seguente flag su Attivato:

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

3. Riavvia Chrome.

4. (Facoltativo) Scarica il modello sul dispositivo prima della prima richiesta.

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

   Visualizza le istruzioni per scaricare il modello sul dispositivo

   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 ascoltare l'avanzamento del download e assicurarti che il modello sia available prima di effettuare le 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 Firebase console, 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 il relativo progetto sottostante Google Cloud automaticamente) 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 ti viene richiesto, non devi configurare Google Analytics per utilizzare gli Firebase AI Logic SDK.

2. Nella Firebase console, vai a Servizi AI > AI Logic.

3. Fai clic su Inizia per avviare un workflow guidato che ti aiuterà a configurare le API richieste e le risorse per il tuo progetto.

4. Se ti viene richiesto, segui le istruzioni sullo schermo per registrare la tua app e aggiungere la configurazione Firebase alla tua app.

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

   In un secondo momento, puoi sempre configurare Agent Platform Gemini API (formerly Vertex AI) (e il relativo requisito di fatturazione).

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

   A partire dall'inizio di luglio 2026, questa fase del workflow applicherà automaticamente Firebase App CheckFirebase App Check per AI LogicAI Logic, un servizio critico che aiuta a proteggere l'API GeminiGemini API quando viene eseguito l'accesso direttamente dalla tua app. Nell'ambito della procedura di configurazione iniziale (vedi i passaggi più avanti in questa guida), dovrai configurare il App CheckApp Checkprovider di debug per lo sviluppo locale quando App CheckApp Check è applicato.

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

A partire dall'inizio di luglio 2026, nell'ambito del workflow di configurazione guidata per AI Logic nella console, Firebase App Check viene applicato automaticamente per proteggere l' Gemini API. Per lo sviluppo locale, devi configurare il App Check provider di debug per ignorare 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 in locale 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), quindi seleziona Gestisci token di debug.

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

Per maggiori dettagli sul provider di debug (incluso come ottenere un nuovo token di debug), consulta la documentazione App Checkufficiale.

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

Configura quanto segue prima di inviare una richiesta di prompt al modello:

1. Inizializza il servizio per il provider dell'API scelto.

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

   • PREFER_ON_DEVICE: utilizza il modello sul dispositivo se disponibile; in caso contrario, esegui il fallback al modello ospitato sul cloud.

   • ONLY_ON_DEVICE: utilizza il modello sul dispositivo se disponibile; in caso contrario, genera un'eccezione.

   • PREFER_IN_CLOUD: utilizza il modello ospitato sul cloud se disponibile; in caso contrario, esegui il fallback al modello sul dispositivo.

   • ONLY_IN_CLOUD: utilizza il modello ospitato sul cloud se disponibile; in caso contrario, 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 sul dispositivo

Devi chiamare initializeDeviceModel() dopo o durante un'interazione dell'utente finale con la pagina (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

In questa sezione viene illustrato come inviare vari tipi di input per generare diversi tipi di output, tra cui:

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

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

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

Tieni presente che Firebase AI Logic supporta anche lo streaming delle 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 immagini, fornendo il di ogni file di input mimeType 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();

Tieni presente che Firebase AI Logic supporta anche lo streaming delle 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

• Sostituisci il modello di fallback ospitato sul cloud predefinito

• Utilizza la configurazione del modello per controllare le risposte (ad esempio la temperatura)

• Genera output strutturati (come JSON)

Funzionalità non ancora disponibili per l'inferenza sul dispositivo

Non tutte le funzionalità dell'SDK web sono disponibili per l'inferenza sul dispositivo. Le seguenti funzionalità non sono ancora supportate per l'inferenza sul dispositivo (ma sono in genere 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 PDF)

  • Può eseguire il fallback al modello ospitato sul cloud; tuttavia, la modalità ONLY_ON_DEVICE genererà 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 genererà un errore.

• Fornitura di file utilizzando gli URL nelle richieste multimodali. Devi fornire i file come dati in linea ai modelli sul dispositivo.

• Chat a più turni

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

• Streaming bidirezionale con il Gemini Live API

• Fornitura al modello di strumenti per aiutarlo a generare la risposta (ad esempio chiamate di funzione, esecuzione di codice, contesto 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 sul cloud e quelli sul dispositivo, quindi non esiste un fallback intuitivo.

• Monitoraggio AI nella console Firebase per l'inferenza sul dispositivo.

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

Dai un feedback sulla tua esperienza con Firebase AI Logic