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

Crea app web e funzionalità basate sull'AI con 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 (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 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 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 o dalla connettività a internet

Funzionalità supportate per l'inferenza on-device:

L'inferenza sul dispositivo supporta solo la generazione di testo a un solo turno (non chat), con output di streaming o non 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 strutturato, 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 provider Gemini API che hai scelto (Gemini Developer API o Vertex AI Gemini API).

• Questa pagina descrive 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, dai un'occhiata alle opzioni e funzionalità di configurazione aggiuntive (come l'output strutturato).

• Dopo aver implementato la funzionalità, puoi consentire agli utenti finali di provarla nella tua app effettiva.

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 on-device, 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 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 il relativo progetto Google Cloud sottostante) inserendo un nuovo nome del progetto nel primo passaggio del flusso di lavoro.

   • 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 flusso di lavoro, inizia a inserire il nome del progetto esistente, quindi selezionalo dall'elenco visualizzato.

   Completa i passaggi rimanenti del flusso di lavoro sullo schermo per creare un progetto Firebase. 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 workflow guidato che ti aiuti a configurare le API richieste e le risorse per il tuo progetto.

4. Configura il progetto in modo che utilizzi un provider "Gemini API".

   Ti consigliamo di iniziare a utilizzare Gemini Developer API. In qualsiasi momento, puoi sempre configurare Vertex AI Gemini API (e il relativo requisito di fatturazione).

   Per Gemini Developer API, 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ù.

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:

   npm install firebase
   

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

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

1. Inizializza il servizio per il provider API scelto.

2. Crea un'istanza GenerativeModel. Assicurati di svolgere le seguenti operazioni:

   1. Chiama getGenerativeModel dopo o durante un'interazione dell'utente finale (ad esempio un clic sul pulsante). Questo è un prerequisito per inferenceMode.

   2. Imposta mode su uno dei seguenti valori:

      • PREFER_ON_DEVICE: utilizza il modello sul dispositivo se disponibile; altrimenti, utilizza il modello ospitato sul cloud.

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

      • PREFER_IN_CLOUD: utilizza il modello ospitato sul cloud se disponibile; altrimenti, utilizza il modello sul dispositivo.

      • ONLY_IN_CLOUD: utilizza il modello ospitato sul 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
// Call `getGenerativeModel` after or on an end-user interaction
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

Passaggio 5: 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:

• 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 "genera testo" e, inoltre, 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();

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

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

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

Consentire agli utenti finali di provare la tua funzionalità

Per consentire agli utenti finali di provare la tua funzionalità nella tua app, devi registrarti alle prove dell'origine di Chrome. Tieni presente che questi periodi di prova hanno una durata e un utilizzo limitati.

1. Registrati alla prova dell'origine di Chrome dell'API Prompt. Ti verrà fornito un token.

2. Fornisci il token in ogni pagina web per cui vuoi attivare la funzionalità di prova. Utilizza una delle seguenti opzioni:

   • Fornisci il token come meta tag nel tag <head>: <meta http-equiv="origin-trial" content="TOKEN">

   • Fornisci il token come intestazione HTTP: Origin-Trial: TOKEN

   • Fornisci il token in modo programmatico.

Cos'altro puoi fare?

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

• Impostare una modalità di inferenza

• Eseguire l'override del modello di riserva predefinito ospitato sul cloud

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

• Generare un output strutturato (come JSON)

Funzionalità non ancora disponibili per l'inferenza sul dispositivo

In quanto release di anteprima, non tutte le funzionalità dell'SDK web sono disponibili per l'inferenza on-device. 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.

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

• Fornire al modello strumenti per aiutarlo a generare la risposta (come chiamate di funzioni, esecuzione di codice, contesto URL e grounding con la Ricerca Google)

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