Esegui la migrazione agli SDK Firebase AI Logic dagli SDK client Google AI


Vai direttamente alle istruzioni per la migrazione

Perché eseguire la migrazione per utilizzare gli SDK Firebase AI Logic?

Potresti aver provato un set alternativo di SDK client web o mobile che ti ha dato accesso a Gemini Developer API.

Questi SDK client non erano integrati nel solido ecosistema Firebase che offre servizi critici per le app web e mobile. Ora sono deprecate a favore degli SDK client Firebase AI Logic, che possono darti accesso a Gemini Developer API.

Funzionalità di sicurezza per app web e mobile

Per le app web e mobile, la sicurezza è fondamentale e richiede considerazioni speciali perché il codice, incluse le chiamate alla Gemini API, viene eseguito in un ambiente non protetto. Puoi utilizzare Firebase App Check per proteggere le API da usi impropri da parte di client non autorizzati.

Quando utilizzi Firebase App Check con Firebase AI Logic, non aggiungi mai la chiave API Gemini per Gemini Developer API direttamente nel codebase della tua app web o mobile. Invece, la chiave API Gemini rimane sul server, non esposta ad attori malintenzionati.

Ecosistema creato per app web e mobile

Firebase è la piattaforma di Google per lo sviluppo di app web e mobile. L'utilizzo di Firebase AI Logic significa che le tue app si trovano in un ecosistema incentrato sulle esigenze di app e sviluppatori full-stack. Ad esempio:

  • Imposta dinamicamente le configurazioni di runtime o scambia i valori nella tua app (come il nome e la versione di un modello) senza rilasciare una nuova versione dell'app utilizzando Firebase Remote Config.

  • Utilizza Cloud Storage for Firebase per includere file di grandi dimensioni nelle tue richieste multimodali (se utilizzi Agent Platform Gemini API (formerly Vertex AI)). Gli SDK client Cloud Storage ti aiutano a gestire i caricamenti e i download dei file (anche in condizioni di rete scadenti) e offrono una maggiore sicurezza per i dati degli utenti finali. Scopri di più nella nostra guida alle soluzioni sull'utilizzo di Cloud Storage for Firebase.

  • Gestisci i dati strutturati utilizzando gli SDK del database creati per le app web e mobile (come Cloud Firestore).

Esegui la migrazione agli SDK Firebase AI Logic

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

  • Passaggio 1: configura un progetto Firebase nuovo o esistente e connetti la tua app a Firebase.

  • Passaggio 2: aggiungi gli SDK Firebase AI Logic alla tua app.

  • Passaggio 3: aggiorna le importazioni e l'inizializzazione nell'app.

  • Passaggio 4: aggiorna il codice in base alle funzionalità che utilizzi.

Passaggio 1: configura un progetto Firebase e connetti la tua app

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

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

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

  4. Seleziona Gemini Developer API. Se vuoi, puoi sempre configurare e utilizzare l'altro provider di API in un secondo momento.

    La console abiliterà le API richieste e creerà una nuova chiave API Gemini dedicata nel tuo progetto.
    Non aggiungere questa nuova chiave API Gemini al codebase della tua app. Scopri di più.

  5. Se richiesto nel workflow della console, segui le istruzioni sullo schermo per registrare l'app e collegarla a Firebase.

  6. Continua con questa guida alla migrazione per aggiornare la libreria e l'inizializzazione nella tua app.

Passaggio 2: aggiungi l'SDK Firebase AI Logic alla tua app

Dopo aver configurato il progetto Firebase e collegato l'app a Firebase (vedi il passaggio precedente), ora puoi aggiungere l'SDK Firebase AI Logic alla tua app.

Swift

Utilizza Swift Package Manager per installare e gestire le dipendenze di Firebase. Scopri altre opzioni di installazione, se necessario.

La libreria Firebase AI Logic fornisce l'accesso alle API per interagire con i modelli Gemini. La libreria è inclusa nell'SDK Firebase per piattaforme Apple (firebase-ios-sdk).

Se utilizzi già Firebase, assicurati che il pacchetto Firebase sia v12.5.0 o successiva.

  1. In Xcode, con il progetto dell'app aperto, vai a File > Add Package Dependencies (File > Aggiungi dipendenze pacchetto).

  2. Quando richiesto, aggiungi il repository dell'SDK Firebase per le piattaforme Apple:

    https://github.com/firebase/firebase-ios-sdk
    
  3. Seleziona l'ultima versione dell'SDK.

  4. Seleziona la libreria FirebaseAILogic e la libreria FirebaseAppCheck.

Al termine, Xcode inizierà automaticamente a risolvere e a scaricare le tue dipendenze in background.

Kotlin

L'SDK Firebase AI Logic per Android (firebase-ai) fornisce l'accesso alle API per interagire con i modelli Gemini.

Nel file Gradle del modulo (a livello di app) (ad esempio <project>/<app-module>/build.gradle.kts), aggiungi le dipendenze per le librerie Firebase AI Logic e App Check per Android. Ti consigliamo di utilizzare Firebase Android BoM per controllare il controllo delle versioni della libreria.

dependencies {
  // ... other androidx dependencies

  // Import the BoM for the Firebase platform
  implementation(platform("com.google.firebase:firebase-bom:35.2.0"))

  // Add the dependencies for the Firebase AI Logic and App Check libraries
  // When using the BoM, you don't specify versions in Firebase library dependencies
  implementation("com.google.firebase:firebase-ai")
  implementation("com.google.firebase:firebase-appcheck-debug")
}

Con la Firebase Android BoM, la tua app utilizzerà sempre versioni compatibili delle librerie Firebase Android.

Java

L'SDK Firebase AI Logic per Android (firebase-ai) fornisce l'accesso alle API per interagire con i modelli Gemini.

Nel file Gradle del modulo (a livello di app) (ad esempio <project>/<app-module>/build.gradle.kts), aggiungi le dipendenze per le librerie Firebase AI Logic e App Check per Android. Ti consigliamo di utilizzare Firebase Android BoM per controllare il controllo delle versioni della libreria.

Per Java, devi aggiungere due librerie aggiuntive.

dependencies {
  // ... other androidx dependencies

  // Import the BoM for the Firebase platform
  implementation(platform("com.google.firebase:firebase-bom:35.2.0"))

  // Add the dependencies for the Firebase AI Logic and App Check libraries
  // When using the BoM, you don't specify versions in Firebase library dependencies
  implementation("com.google.firebase:firebase-ai")
  implementation("com.google.firebase:firebase-appcheck-debug")

  // Required for one-shot operations (to use `ListenableFuture` from Guava Android)
  implementation("com.google.guava:guava:31.0.1-android")

  // Required for streaming operations (to use `Publisher` from Reactive Streams)
  implementation("org.reactivestreams:reactive-streams:1.0.4")
}

Con la Firebase Android BoM, la tua app utilizzerà sempre versioni compatibili delle librerie Firebase Android.

Web

La libreria Firebase AI Logic fornisce l'accesso alle API per interagire con i modelli Gemini. 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, DebugProvider } 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);
    

Dart

Il plug-in Firebase AI Logic per Flutter (firebase_ai) fornisce l'accesso alle API per interagire con i modelli Gemini.

  1. Dalla directory del progetto Flutter, esegui questo comando per installare i plug-in Firebase AI Logic e App Check:

    flutter pub add firebase_ai firebase_app_check
    
  2. Nel file lib/main.dart, importa i plug-in Firebase AI Logic e App Check:

    import 'package:firebase_core/firebase_core.dart';
    import 'package:firebase_ai/firebase_ai.dart';
    import 'package:firebase_app_check/firebase_app_check.dart';
    import 'firebase_options.dart';
    
  3. Inoltre, nel file lib/main.dart, assicurati di aver inizializzato Firebase utilizzando l'oggetto DefaultFirebaseOptions esportato dal file di configurazione:

    await Firebase.initializeApp(
      options: DefaultFirebaseOptions.currentPlatform,
    );
    
  4. Ricostruisci l'applicazione Flutter:

    flutter run
    

Unity

Il supporto per Unity non era disponibile negli SDK client Google AI.

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

Rimuovi il vecchio SDK dalla tua app

Dopo aver completato la migrazione dell'app (consulta le sezioni rimanenti di questa guida), assicurati di eliminare la vecchia libreria.

Swift

Rimuovi la vecchia libreria:

  1. In Xcode, con il progetto dell'app aperto, vai al riquadro Packages Dependencies (Dipendenze pacchetti).

  2. Seleziona il pacchetto generative-ai-swift dall'elenco delle dipendenze dei pacchetti.

  3. Fai clic sul pulsante - in fondo all'elenco e fai clic su Rimuovi per confermare.

Kotlin

dependencies {
    implementation("com.google.ai.client.generativeai:generativeai:VERSION")
}

Java

dependencies {
    implementation("com.google.ai.client.generativeai:generativeai:VERSION")
}

Web

// BEFORE
import { initializeApp } from "firebase/app";
import { GoogleGenerativeAI } from "@google/generative-ai";

Dart

Elimina il vecchio pacchetto:
flutter pub remove google_generative_ai

Unity

Il supporto per Unity non era disponibile dagli SDK client Google AI.

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

Passaggio 3: aggiorna le importazioni e l'inizializzazione nell'app

Aggiorna le importazioni e il modo in cui inizializzi il servizio di backend Gemini Developer API e crea un'istanza GenerativeModel.

Swift

// BEFORE
import GoogleGenerativeAI

let model = GenerativeModel(name: "MODEL_NAME", apiKey: APIKey.default)

// AFTER
import FirebaseAILogic

// 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-4-hydrogen")

Kotlin

// BEFORE
import com.google.ai.client.generativeai.Chat
import com.google.ai.client.generativeai.type.Content
import com.google.ai.client.generativeai.java.GenerativeModuleFutures

...

val generativeModel = GenerativeModel(modelName = "MODEL_NAME",
  // Access your API key as a Build Configuration variable
  apiKey = BuildConfig.apiKey
)

// AFTER
import com.google.firebase.Firebase
import com.google.firebase.ai.ai
import com.google.firebase.ai.type.GenerativeBackend

...

// 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-4-hydrogen")

Java

// BEFORE
import com.google.ai.client.generativeai.Chat;
import com.google.ai.client.generativeai.type.Content;
import com.google.ai.client.generativeai.java.GenerativeModuleFutures;

...

GenerativeModel gm = new GenerativeModel("MODEL_NAME",
  // Access your API key as a Build Configuration variable
  BuildConfig.apiKey
);

GenerativeModelFutures model = GenerativeModelFutures.from(gm);

// AFTER
import com.google.firebase.ai.FirebaseAI;
import com.google.firebase.ai.GenerativeModel;
import com.google.firebase.ai.java.GenerativeModelFutures;
import com.google.firebase.ai.type.GenerativeBackend;

...

// 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-4-hydrogen");

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

Web

// BEFORE
import { GoogleGenerativeAI } from "@google/generative-ai";

// Fetch your API_KEY and access your API
const API_KEY = "...";
const genAI = new GoogleGenerativeAI(API_KEY);

...

const model = genAI.getGenerativeModel({ model: "MODEL_NAME"});

// AFTER
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-4-hydrogen" });

Dart

// BEFORE
import 'package:google_generative_ai/google_generative_ai.dart';

final apiKey = Platform.environment['API_KEY'];
if (apiKey == null) {
print('No \$API_KEY environment variable');
exit(1);
}

final model = GenerativeModel(model: 'MODEL_NAME', apiKey: apiKey);

// AFTER
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-4-hydrogen');

Unity

Il supporto per Unity non era disponibile dagli SDK client Google AI.

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. Per trasmettere input e output in streaming utilizzando Gemini Live API, crea un'istanza LiveModel.

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

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

  • Gli SDK client Firebase AI Logic non supportano l'esecuzione del codice. Se utilizzi questa funzionalità, assicurati di adattarla alla tua app.

  • Esamina i seguenti elenchi per verificare se devi apportare modifiche al codice per adattarlo alla migrazione agli SDK client Firebase AI Logic.

Obbligatorio per tutte le lingue e le piattaforme

  • Chiamata di funzione
    Se hai implementato questa funzionalità, dovrai aggiornare il modo in cui definisci lo schema. Ti consigliamo di consultare la guida alle chiamate di funzione aggiornata per scoprire come scrivere le dichiarazioni delle funzioni.

  • Generazione di output strutturato (come JSON) utilizzando responseSchema
    Se hai implementato questa funzionalità, dovrai aggiornare il modo in cui definisci lo schema. Ti consigliamo di consultare la nuova guida all'output strutturato per scoprire come scrivere schemi JSON.

  • Timeout

    • Il timeout predefinito per le richieste è stato modificato in 180 secondi.

Obbligatorio in base alla piattaforma o alla lingua

Swift

  • Enumerazioni

    • Sostituzione della maggior parte dei tipi enum 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 i 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.

    • Sono stati rimossi i casi unknown e unspecified dalle seguenti enumerazioni (ora struct): HarmCategory, HarmBlockThreshold, HarmProbability, BlockReason e FinishReason.

    • L'enumerazione ModelContent.Part è stata sostituita con un protocollo denominato Part per consentire l'aggiunta di nuovi tipi in modo compatibile con le versioni precedenti. Questa modifica è descritta in maggiore dettaglio nella sezione Parti dei contenuti.

  • Parti di contenuti

    • Rimosso il protocollo ThrowingPartsRepresentable e semplificati gli inizializzatori per ModelContent per evitare errori occasionali del compilatore. Le immagini che non vengono codificate correttamente genereranno comunque errori se utilizzate in generateContent.

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

    • HarmCategory non è più nidificato nel tipo SafetySetting. Se lo chiami SafetySetting.HarmCategory, puoi sostituirlo con HarmCategory.
  • Feedback sulla sicurezza

    • Rimosso il tipo SafetyFeedback, poiché non era utilizzato in nessuna delle risposte.
  • Metadati delle citazioni

    • La proprietà citationSources è stata rinominata in citations in CitationMetadata.
  • Caratteri fatturabili totali

    • La proprietà totalBillableCharacters in CountTokensResponse è stata modificata in modo da essere facoltativa per riflettere le situazioni in cui non vengono inviati caratteri.
  • Risposta del candidato

    • Il nome di CandidateResponse è stato cambiato in Candidate per renderlo coerente con altre piattaforme.
  • Configurazione della generazione

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

Kotlin

  • Enumerazioni

    • Sostituite enum classi e sealed classi con classi normali. 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 per utilizzare InlineData.
  • Impostazioni di sicurezza

    • Il campo method è stato modificato in modo da poter essere nullo.
  • Classe Duration

    • Sono stati rimossi tutti gli utilizzi della classe Duration di Kotlin e sono stati sostituiti con long. Questa modifica offre una migliore interoperabilità con Java.
  • Metadati delle citazioni

    • Abbiamo inserito tutti i campi dichiarati in precedenza in CitationMetadata in una nuova classe denominata Citation. Le citazioni sono disponibili nell'elenco denominato citations in CitationMetadata. Questa modifica consente un migliore allineamento dei tipi tra le piattaforme.
  • Conta i token

    • Il campo totalBillableCharacters è stato modificato in modo da poter essere nullo.
  • Caratteri fatturabili totali

    • La proprietà totalBillableCharacters in CountTokensResponse è stata modificata in modo da essere facoltativa per 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 l'allineamento con altre piattaforme.

Java

  • Enumerazioni

    • Sostituite enum classi e sealed classi con classi normali. 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 per utilizzare InlineData.
  • Impostazioni di sicurezza

    • Il campo method è stato modificato in modo da poter essere nullo.
  • Classe Duration

    • Sono stati rimossi tutti gli utilizzi della classe Duration di Kotlin e sono stati sostituiti con long. Questa modifica offre una migliore interoperabilità con Java.
  • Metadati delle citazioni

    • Abbiamo inserito tutti i campi dichiarati in precedenza in CitationMetadata in una nuova classe denominata Citation. Le citazioni sono disponibili nell'elenco denominato citations in CitationMetadata. Questa modifica consente un migliore allineamento dei tipi tra le piattaforme.
  • Conta i token

    • Il campo totalBillableCharacters è stato modificato in modo da poter essere nullo.
  • Caratteri fatturabili totali

    • La proprietà totalBillableCharacters in CountTokensResponse è stata modificata in modo da essere facoltativa per 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 l'allineamento con altre piattaforme.

Web

Tieni presente che l'SDK client Google AI per JavaScript ha subito molte modifiche da quando gli SDK client Firebase AI Logic si sono separati. Di seguito sono riportate alcune potenziali modifiche che potresti dover prendere in considerazione durante la migrazione agli SDK client Firebase AI Logic.

  • Enumerazioni

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

    • blockReason in PromptFeedback è stato modificato in facoltativo.
  • Grounding con la Ricerca

    • Sono stati rimossi tutti gli utilizzi di questa funzionalità, poiché non è ancora supportata negli SDK Firebase AI Logic.
  • Errori

    • Rimosso tutti gli utilizzi di GoogleGenerativeAIError e, facoltativamente, eseguito il passaggio a AIError.

Dart

  • Enumerazioni

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

    • DataPart è stato rinominato in InlineDataPart e la funzione data static in inlineData per l'allineamento con altre piattaforme.
  • Opzioni di richiesta

    • Rimosso RequestOptions perché timeout non funzionava. Verrà aggiunta di nuovo nel prossimo futuro, ma verrà spostata 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

    • La proprietà citationSources è stata rinominata 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 sono stati esposti involontariamente: defaultTimeout, CountTokensResponseFields, parseCountTokensResponse, parseEmbedContentResponse, parseGenerateContentResponse, parseContent, BatchEmbedContentsResponse, ContentEmbedding, EmbedContentRequest e EmbedContentResponse.
  • Conta i token

    • 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 l'allineamento con altre piattaforme.
  • Funzionalità di incorporamento

    • È stata rimossa dal modello la funzionalità di embedding non supportata (embedContent e batchEmbedContents).

Unity

Il supporto per Unity non era disponibile dagli SDK client Google AI.

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


Invia un feedback sulla tua esperienza con Firebase AI Logic