Esegui la migrazione agli SDK Firebase AI Logic dalla versione di anteprima di Vertex AI in Firebase


Firebase AI Logic e i relativi SDK client erano precedentemente chiamati "Vertex AI in Firebase". Per riflettere meglio i nostri servizi e le nostre funzionalità ampliati (ad esempio, ora supportiamo Gemini Developer API!), abbiamo rinominato e riconfezionato i nostri servizi in Firebase AI Logic.

Per accedere in modo sicuro ai modelli di AI generativa di Google direttamente dalle tue app web o mobile, ora puoi scegliere un fornitore "Gemini API", ovvero Vertex AI Gemini API, disponibile da tempo, o Gemini Developer API, ora disponibile. Ciò significa che ora hai la possibilità di utilizzare l'Gemini Developer API, che offre un livello senza costi con limiti di frequenza e quote ragionevoli.

Panoramica dei passaggi per eseguire la migrazione agli SDK Firebase AI Logic 

  • Passaggio 1: scegli il miglior fornitore di "API Gemini" per la tua app e i tuoi casi d'uso.

  • Passaggio 2: attiva le API richieste.

  • Passaggio 3: aggiorna la libreria utilizzata nella tua app.

  • Passaggio 4: aggiorna l'inizializzazione nell'app.

  • Passaggio 5: aggiorna il codice a seconda delle funzionalità che utilizzi.

Passaggio 1: scegli il miglior fornitore di "API Gemini" per la tua app

Con questa migrazione, puoi scegliere il fornitore di "Gemini API":

  • Le vecchie SDK "Vertex AI in Firebase" potevano utilizzare solo Vertex AI Gemini API.

  • I nuovi SDK Firebase AI Logic ti consentono di scegliere quale provider di "Gemini API" vuoi chiamare direttamente dalla tua app web o mobile: Gemini Developer API o Vertex AI Gemini API.

Esamina le differenze tra l'utilizzo dei due fornitori Gemini API, soprattutto in termini di funzionalità supportate, prezzi e limiti di frequenza. Ad esempio, Gemini Developer API non supporta la fornitura di file utilizzando URL Cloud Storage, ma potrebbe essere una buona scelta se vuoi usufruire del livello senza costi e della quota ragionevole.

Passaggio 2: attiva le API richieste

Assicurati che tutte le API richieste siano abilitate nel tuo progetto Firebase per utilizzare il fornitore "Gemini API" che hai scelto.

Tieni presente che puoi abilitare entrambi i provider di API nel tuo progetto contemporaneamente.

  1. Accedi alla console Firebase, quindi seleziona il tuo progetto Firebase.

  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 provider "API Gemini" 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 nel piano tariffario Spark senza costi)
      Il flusso di lavoro della console attiverà 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)
      Il flusso di lavoro della console consente di abilitare le API richieste nel progetto.

  5. Continua a seguire questa guida alla migrazione per aggiornare la libreria e l'inizializzazione nella tua app.

Passaggio 3: aggiorna la libreria utilizzata nella tua app

Aggiorna il codebase dell'app per utilizzare la libreria Firebase AI Logic.

Swift

  1. In Xcode, con il progetto dell'app aperto, aggiorna il pacchetto Firebase alla versione 11.13.0 o successive utilizzando una delle seguenti opzioni:

    • Opzione 1: aggiorna tutti i pacchetti. Vai a File > Pacchetti > Aggiorna alle versioni più recenti dei pacchetti.

    • Opzione 2: aggiorna Firebase singolarmente. Vai al pacchetto Firebase nella sezione Package Dependencies (Dipendenze dei pacchetti). Fai clic con il tasto destro del mouse sul pacchetto Firebase e seleziona Aggiorna pacchetto.

  2. Assicurati che il pacchetto Firebase ora mostri la versione 11.13.0 o successive. In caso contrario, verifica che i requisiti del pacchetto specificati consentano l'aggiornamento alla versione 11.13.0 o successive.

  3. Seleziona la destinazione della tua app nell'editor del progetto, quindi vai alla sezione Framework, librerie e contenuti incorporati.

  4. Aggiungi la nuova libreria: seleziona il pulsante + e poi aggiungi FirebaseAI dal pacchetto Firebase.

  5. Dopo aver completato la migrazione dell'app (vedi le sezioni rimanenti di questa guida), assicurati di rimuovere la vecchia libreria:
    seleziona FirebaseVertexAI-Preview, quindi premi il pulsante .

Kotlin

  1. Nel file Gradle del modulo (a livello di app) (di solito <project>/<app-module>/build.gradle.kts o <project>/<app-module>/build.gradle), sostituisci le vecchie dipendenze (se applicabile) con le seguenti.

    Tieni presente che potrebbe essere più facile eseguire la migrazione del codebase dell'app (vedi le sezioni rimanenti di questa guida) prima di eliminare la vecchia dipendenza.

    // BEFORE
    dependencies {
      implementation("com.google.firebase:firebase-vertexai:16.0.0-betaXX")
    }
    
    
    // AFTER
    dependencies {
      // Import the BoM for the Firebase platform
      implementation(platform("com.google.firebase:firebase-bom:33.15.0"))
    
      // Add the dependency for the Firebase AI Logic library
      // When using the BoM, you don't specify versions in Firebase library dependencies
      implementation("com.google.firebase:firebase-ai")
    }
  2. Sincronizza il tuo progetto Android con i file Gradle.

Tieni presente che se scegli di non utilizzare Firebase Android BoM, aggiungi solo la dipendenza per la libreria firebase-ai e accetta l'ultima versione suggerita da Android Studio.

Java

  1. Nel file Gradle del modulo (a livello di app) (di solito <project>/<app-module>/build.gradle.kts o <project>/<app-module>/build.gradle), sostituisci le vecchie dipendenze (se applicabile) con le seguenti.

    Tieni presente che potrebbe essere più facile eseguire la migrazione del codebase dell'app (vedi le sezioni rimanenti di questa guida) prima di eliminare la vecchia dipendenza.

    // BEFORE
    dependencies {
      implementation("com.google.firebase:firebase-vertexai:16.0.0-betaXX")
    }
    
    
    // AFTER
    dependencies {
      // Import the BoM for the Firebase platform
      implementation(platform("com.google.firebase:firebase-bom:33.15.0"))
    
      // Add the dependency for the Firebase AI Logic library
      // When using the BoM, you don't specify versions in Firebase library dependencies
      implementation("com.google.firebase:firebase-ai")
    }
  2. Sincronizza il tuo progetto Android con i file Gradle.

Tieni presente che se scegli di non utilizzare Firebase Android BoM, aggiungi solo la dipendenza per la libreria firebase-ai e accetta l'ultima versione suggerita da Android Studio.

Web

  1. Ottieni l'ultima versione dell'SDK Firebase JS per il web utilizzando npm:

    npm i firebase@latest

    OPPURE

    yarn add firebase@latest
  2. Ovunque tu abbia importato la libreria, aggiorna le istruzioni di importazione in modo che utilizzino firebase/ai.

    Tieni presente che potrebbe essere più facile eseguire la migrazione del codebase della tua app (vedi le sezioni rimanenti di questa guida) prima di eliminare le importazioni precedenti.

    // BEFORE
    import { initializeApp } from "firebase/app";
    import { getVertexAI, getGenerativeModel } from "firebase/vertexai-preview";
    
    
    // AFTER
    import { initializeApp } from "firebase/app";
    import { getAI, getGenerativeModel } from "firebase/ai";

Dart

  1. Aggiorna l'utilizzo del pacchetto firebase_ai nel file pubspec.yaml eseguendo il seguente comando dalla directory del progetto Flutter:

    flutter pub add firebase_ai
  2. Ricompila il progetto Flutter:

    flutter run
  3. Dopo aver completato la migrazione dell'app (vedi le sezioni rimanenti di questa guida), assicurati di eliminare il vecchio pacchetto:

    flutter pub remove firebase_vertexai

Unity

Il supporto per Unity non era disponibile da "Vertex AI in Firebase".

Scopri come iniziare a utilizzare l'SDK Firebase AI Logic per Unity.

Passaggio 4: aggiorna l'inizializzazione nell'app

Fai clic sul tuo fornitore Gemini API per visualizzare i contenuti e il codice specifici del fornitore in questa pagina.

Aggiorna la modalità di inizializzazione del servizio per il provider API scelto e crea un'istanza GenerativeModel.

Swift


import FirebaseAI

// Initialize the Gemini Developer API backend service
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Create a `GenerativeModel` instance with a model that supports your use case
let model = ai.generativeModel(modelName: "gemini-2.5-flash")

Kotlin


// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
                        .generativeModel("gemini-2.5-flash")

Java


// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
        .generativeModel("gemini-2.5-flash");

// Use the GenerativeModelFutures Java compatibility layer which offers
// support for ListenableFuture and Publisher APIs
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

Web


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 with a model that supports your use case
const model = getGenerativeModel(ai, { model: "gemini-2.5-flash" });

Dart


import 'package:firebase_ai/firebase_ai.dart';
import 'package:firebase_core/firebase_core.dart';
import 'firebase_options.dart';

// Initialize FirebaseApp
await Firebase.initializeApp(
  options: DefaultFirebaseOptions.currentPlatform,
);

// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
final model =
      FirebaseAI.googleAI().generativeModel(model: 'gemini-2.5-flash');

Unity

Il supporto per Unity non era disponibile a partire dal giorno "Vertex AI in Firebase".

Scopri come iniziare a utilizzare l'SDK Firebase AI Logic per Unity.

Tieni presente che, a seconda della funzionalità che utilizzi, potresti non creare sempre un'istanza GenerativeModel.

Passaggio 5: aggiorna il codice in base alle funzionalità che utilizzi

Questo passaggio descrive le modifiche che potrebbero essere necessarie a seconda delle funzionalità che utilizzi.

  • Se utilizzi gli URL Cloud Storage e hai eseguito il passaggio all'utilizzo di Gemini Developer API in questa migrazione, devi aggiornare le richieste multimodali per includere i file come dati incorporati (o utilizzare gli URL di YouTube per i video).

  • Sono state introdotte diverse modifiche per le versioni GA degli SDK "Vertex AI in Firebase". Queste stesse modifiche sono necessarie per utilizzare gli SDK Firebase AI Logic. Consulta i seguenti elenchi per verificare la presenza di eventuali modifiche che potresti dover apportare al codice per adattarlo all'SDK Firebase AI Logic.

Obbligatorio per tutte le lingue e le piattaforme

  • Chiamata di funzioni
    Se hai implementato questa funzionalità prima della disponibilità generale, dovrai apportare aggiornamenti alla definizione dello schema. Ti consigliamo di consultare la guida alla chiamata di funzioni aggiornata per scoprire come scrivere le dichiarazioni di funzioni.

  • Generazione di output strutturato (ad esempio JSON) utilizzando responseSchema
    Se hai implementato questa funzionalità prima della disponibilità generale, dovrai aggiornare la modalità di definizione dello schema. Ti consigliamo di consultare la nuova guida all'output strutturato per scoprire come scrivere schemi JSON.

  • Timeout

    • È stato modificato il timeout predefinito per le richieste a 180 secondi.

Obbligatorio in base alla piattaforma o alla lingua

Swift

  • Enumerazioni

    • La maggior parte dei tipi enum sono stati sostituiti con struct con variabili statiche. Questa modifica consente una maggiore flessibilità per l'evoluzione dell'API in modo compatibile con le versioni precedenti. Quando utilizzi le istruzioni switch, ora devi includere un caso default: per coprire valori sconosciuti o non gestiti, inclusi i nuovi valori che verranno aggiunti all'SDK in futuro.

    • L'enumerazione BlockThreshold è stata rinominata in HarmBlockThreshold; questo tipo ora è un struct.

    • Rimozione dei casi unknown e unspecified dalle seguenti enumerazioni (ora struct): HarmCategory, HarmBlockThreshold, HarmProbability, BlockReason e FinishReason.

    • Ha sostituito l'enumerazione ModelContent.Part con un protocollo denominato Part per consentire l'aggiunta di nuovi tipi in modo compatibile con le versioni precedenti. Questa modifica è descritta in modo più dettagliato nella sezione Parti dei contenuti.

  • Parti dei contenuti

    • È stato rimosso il protocollo ThrowingPartsRepresentable e sono stati semplificati gli inizializzatori per ModelContent per evitare errori occasionali del compilatore. Le immagini che non vengono codificate correttamente genereranno comunque errori quando vengono utilizzate in generateContent.

    • Sostituiti i casi ModelContent.Part con i seguenti tipi struct conformi al protocollo Part:

      • Da .text a TextPart
      • Da .data a InlineDataPart
      • Da .fileData a FileDataPart
      • Da .functionCall a FunctionCallPart
      • Da .functionResponse a FunctionResponsePart
  • Categoria di danno

    • È stato modificato il tipo HarmCategory in modo che non sia più nidificato nel tipo SafetySetting. Se lo chiami SafetySetting.HarmCategory, puoi sostituirlo con HarmCategory.
  • Feedback sulla sicurezza

    • È stato rimosso il tipo SafetyFeedback, poiché non è stato utilizzato in nessuna delle risposte.
  • Metadati delle citazioni

    • È stata rinominata la proprietà citationSources in citations in CitationMetadata.
  • Totale caratteri fatturabili

    • È stata modificata la proprietà totalBillableCharacters in CountTokensResponse per renderla facoltativa e riflettere le situazioni in cui non vengono inviati caratteri.
  • Risposta del candidato

    • Il nome CandidateResponse è stato modificato in Candidate in modo che corrisponda a quello di altre piattaforme.
  • Configurazione della generazione

    • Modificate le proprietà pubbliche di GenerationConfig in internal. Sono tutti configurabili nell'inizializzatore.

Kotlin

  • Enumerazioni

    • Le classi enum e sealed sono state sostituite da classi regolari. Questa modifica consente una maggiore flessibilità per l'evoluzione dell'API in modo compatibile con le versioni precedenti.

    • L'enumerazione BlockThreshold è stata rinominata in HarmBlockThreshold.

    • Valori rimossi dalle seguenti enumerazioni: HarmBlockThreshold, HarmProbability, HarmSeverity, BlockReason e FinishReason.

  • Metodi blob

    • Tutti i metodi che includevano Blob nel nome sono stati rinominati in modo che utilizzassero InlineData.
  • Impostazioni di sicurezza

    • Il campo method è stato modificato in modo da accettare valori nulli.
  • Classe Duration

    • Sono stati rimossi tutti gli utilizzi della classe Duration di Kotlin, che è stata sostituita con long. Questa modifica offre una migliore interoperabilità con Java.
  • Metadati delle citazioni

    • Ha incluso tutti i campi dichiarati in precedenza in CitationMetadata in una nuova classe chiamata Citation. Le citazioni sono disponibili nell'elenco citations in CitationMetadata. Questa modifica consente un migliore allineamento dei tipi tra le piattaforme.
  • Token di conteggio

    • Il campo totalBillableCharacters è stato modificato in modo da accettare valori nulli.
  • Totale caratteri fatturabili

    • È stata modificata la proprietà totalBillableCharacters in CountTokensResponse per renderla facoltativa e riflettere le situazioni in cui non vengono inviati caratteri.
  • Creazione di un'istanza di un modello

    • Il parametro requestOptions è stato spostato alla fine dell'elenco dei parametri per allinearsi ad altre piattaforme.
  • Live API

    • Valore UNSPECIFIED rimosso per la classe enum ResponseModality. Utilizza invece null.

    • LiveGenerationConfig.setResponseModalities rinominato in LiveGenerationConfig.setResponseModality.

    • È stata rimossa la classe LiveContentResponse.Status e i campi di stato sono stati nidificati come proprietà di LiveContentResponse.

    • È stata rimossa la classe LiveContentResponse e sono state fornite sottoclassi di LiveServerMessage che corrispondono alle risposte del modello.

    • LiveModelFutures.connect è stato modificato per restituire ListenableFuture<LiveSessionFutures> anziché ListenableFuture<LiveSession>.

Java

  • Enumerazioni

    • Le classi enum e sealed sono state sostituite da classi regolari. Questa modifica consente una maggiore flessibilità per l'evoluzione dell'API in modo compatibile con le versioni precedenti.

    • L'enumerazione BlockThreshold è stata rinominata in HarmBlockThreshold.

    • Valori rimossi dalle seguenti enumerazioni: HarmBlockThreshold, HarmProbability, HarmSeverity, BlockReason e FinishReason.

  • Metodi blob

    • Tutti i metodi che includevano Blob nel nome sono stati rinominati in modo che utilizzassero InlineData.
  • Impostazioni di sicurezza

    • Il campo method è stato modificato in modo da accettare valori nulli.
  • Classe Duration

    • Sono stati rimossi tutti gli utilizzi della classe Duration di Kotlin, che è stata sostituita con long. Questa modifica offre una migliore interoperabilità con Java.
  • Metadati delle citazioni

    • Ha incluso tutti i campi dichiarati in precedenza in CitationMetadata in una nuova classe chiamata Citation. Le citazioni sono disponibili nell'elenco citations in CitationMetadata. Questa modifica consente un migliore allineamento dei tipi tra le piattaforme.
  • Token di conteggio

    • Il campo totalBillableCharacters è stato modificato in modo da accettare valori nulli.
  • Totale caratteri fatturabili

    • È stata modificata la proprietà totalBillableCharacters in CountTokensResponse per renderla facoltativa e riflettere le situazioni in cui non vengono inviati caratteri.
  • Creazione di un'istanza di un modello

    • Il parametro requestOptions è stato spostato alla fine dell'elenco dei parametri per allinearsi ad altre piattaforme.
  • Live API

    • Valore UNSPECIFIED rimosso per la classe enum ResponseModality. Utilizza invece null.

    • LiveGenerationConfig.setResponseModalities rinominato in LiveGenerationConfig.setResponseModality.

    • È stata rimossa la classe LiveContentResponse.Status e i campi di stato sono stati nidificati come proprietà di LiveContentResponse.

    • È stata rimossa la classe LiveContentResponse e sono state fornite sottoclassi di LiveServerMessage che corrispondono alle risposte del modello.

    • LiveModelFutures.connect è stato modificato per restituire ListenableFuture<LiveSessionFutures> anziché ListenableFuture<LiveSession>.

  • Sono stati modificati vari metodi di creazione Java per restituire correttamente l'istanza della classe, anziché void.

Web

  • Enumerazioni

    • Valori rimossi dalle seguenti enumerazioni: HarmCategory, BlockThreshold, HarmProbability, HarmSeverity, BlockReason e FinishReason.
  • Motivo del blocco

    • Il campo blockReason in PromptFeedback è ora facoltativo.

Modifiche richieste solo se inizi a utilizzare Gemini Developer API (anziché Vertex AI Gemini API):

  • Impostazioni di sicurezza

    • Sono stati rimossi gli utilizzi di SafetySetting.method non supportato.
  • Dati in linea

    • Sono stati rimossi gli utilizzi di InlineDataPart.videoMetadata non supportato.

Dart

  • Enumerazioni

    • Sono stati rimossi valori dalle seguenti enumerazioni: HarmCategory, HarmProbability, BlockReason e FinishReason.
  • Parte dei dati

    • DataPart è stato rinominato in InlineDataPart e la funzione static data in inlineData per allinearsi ad altre piattaforme.
  • Opzioni di richiesta

    • RequestOptions è stato rimosso perché timeout non era funzionante. Verrà aggiunto di nuovo nel prossimo futuro, ma verrà spostato nel tipo GenerativeModel per corrispondere ad altre piattaforme.
  • Sequenze di interruzioni

    • Il parametro stopSequences in GenerationConfig è stato modificato in modo che sia facoltativo e che il valore predefinito sia null anziché un array vuoto.
  • Citazioni

    • È stata rinominata la proprietà citationSources in citations in CitationMetadata. Il tipo CitationSource è stato rinominato in Citation per corrispondere ad altre piattaforme.
  • Tipi, metodi e proprietà pubblici non necessari

    • Sono stati rimossi i seguenti tipi, metodi e proprietà che erano stati esposti involontariamente: defaultTimeout, CountTokensResponseFields, parseCountTokensResponse, parseEmbedContentResponse, parseGenerateContentResponse, parseContent, BatchEmbedContentsResponse, ContentEmbedding, EmbedContentRequest, e EmbedContentResponse.
  • Token di conteggio

    • Sono stati rimossi i campi aggiuntivi dalla funzione countTokens che non sono più necessari. È necessario solo contents.
  • Creazione di un'istanza di un modello

    • Il parametro systemInstruction è stato spostato alla fine dell'elenco dei parametri per allinearsi ad altre piattaforme.
  • Funzionalità di incorporamento

    • Rimossa la funzionalità di incorporamento non supportata (embedContent e batchEmbedContents) dal modello.

Unity

Il supporto per Unity non era disponibile da "Vertex AI in Firebase".

Scopri come iniziare a utilizzare l'SDK Firebase AI Logic per Unity.

Possibili errori relativi alla migrazione

Durante la migrazione per utilizzare la versione GA di Firebase AI Logic, potresti riscontrare errori se non hai completato tutte le modifiche richieste come descritto in questa guida alla migrazione.

Errore 403: Requests to this API firebasevertexai.googleapis.com ... are blocked.

Se ricevi un errore 403 che indica Requests to this API firebasevertexai.googleapis.com ... are blocked., in genere significa che la chiave API Firebase nel tuo file o oggetto di configurazione Firebase non ha un'API richiesta nella lista consentita per il prodotto che stai tentando di utilizzare.

Assicurati che la chiave API Firebase utilizzata dalla tua app includa tutte le API richieste nell'elenco consentito "Limitazioni API" della chiave. Per Firebase AI Logic, la chiave API Firebase deve avere almeno l'API Firebase AI Logic nella relativa lista consentita. Questa API avrebbe dovuto essere aggiunta automaticamente alla lista consentita della chiave API quando hai abilitato le API richieste nella console Firebase.

Puoi visualizzare tutte le tue chiavi API nel riquadro API e servizi > Credenziali della console Google Cloud.


Fornisci un feedback sulla tua esperienza con Firebase AI Logic