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
Accedi alla console Firebase, quindi seleziona il tuo progetto Firebase.
Nella console Firebase, vai a AI Services > AI Logic.
Fai clic su Inizia per avviare un workflow guidato che ti aiuta a configurare le API e le risorse richieste per il tuo progetto.
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ù.Se richiesto nel workflow della console, segui le istruzioni sullo schermo per registrare l'app e collegarla a Firebase.
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.
In Xcode, con il progetto dell'app aperto, vai a File > Add Package Dependencies (File > Aggiungi dipendenze pacchetto).
Quando richiesto, aggiungi il repository dell'SDK Firebase per le piattaforme Apple:
https://github.com/firebase/firebase-ios-sdkSeleziona l'ultima versione dell'SDK.
Seleziona la libreria
FirebaseAILogice la libreriaFirebaseAppCheck.
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.
Installa l'SDK Firebase JS per il web utilizzando npm:
npm install firebaseInizializza 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.
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_checkNel 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';Inoltre, nel file
lib/main.dart, assicurati di aver inizializzato Firebase utilizzando l'oggettoDefaultFirebaseOptionsesportato dal file di configurazione:await Firebase.initializeApp( options: DefaultFirebaseOptions.currentPlatform, );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:
In Xcode, con il progetto dell'app aperto, vai al riquadro Packages Dependencies (Dipendenze pacchetti).
Seleziona il pacchetto
generative-ai-swiftdall'elenco delle dipendenze dei pacchetti.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
// BEFOREimport 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
// BEFOREimport 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
// BEFOREimport 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
// BEFOREimport { 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
// BEFOREimport '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
enumconstructcon variabili statiche. Questa modifica consente una maggiore flessibilità per l'evoluzione dell'API in modo compatibile con le versioni precedenti. Quando utilizzi le istruzioniswitch, ora devi includere un casodefault:per coprire i valori sconosciuti o non gestiti, inclusi i nuovi valori che verranno aggiunti all'SDK in futuro.L'enumerazione
BlockThresholdè stata rinominata inHarmBlockThreshold; questo tipo è ora unstruct.Sono stati rimossi i casi
unknowneunspecifieddalle seguenti enumerazioni (orastruct):HarmCategory,HarmBlockThreshold,HarmProbability,BlockReasoneFinishReason.L'enumerazione
ModelContent.Partè stata sostituita con un protocollo denominatoPartper 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
ThrowingPartsRepresentablee semplificati gli inizializzatori perModelContentper evitare errori occasionali del compilatore. Le immagini che non vengono codificate correttamente genereranno comunque errori se utilizzate ingenerateContent.Sostituzione dei casi
ModelContent.Partcon i seguenti tipistructconformi al protocolloPart:- Da
.textaTextPart - Da
.dataaInlineDataPart - Da
.fileDataaFileDataPart - Da
.functionCallaFunctionCallPart - Da
.functionResponseaFunctionResponsePart
- Da
Categoria di danno
HarmCategorynon è più nidificato nel tipoSafetySetting. Se lo chiamiSafetySetting.HarmCategory, puoi sostituirlo conHarmCategory.
Feedback sulla sicurezza
- Rimosso il tipo
SafetyFeedback, poiché non era utilizzato in nessuna delle risposte.
- Rimosso il tipo
Metadati delle citazioni
- La proprietà
citationSourcesè stata rinominata incitationsinCitationMetadata.
- La proprietà
Caratteri fatturabili totali
- La proprietà
totalBillableCharactersinCountTokensResponseè stata modificata in modo da essere facoltativa per riflettere le situazioni in cui non vengono inviati caratteri.
- La proprietà
Risposta del candidato
- Il nome di
CandidateResponseè stato cambiato inCandidateper renderlo coerente con altre piattaforme.
- Il nome di
Configurazione della generazione
- Modificate le proprietà pubbliche di
GenerationConfigininternal. Rimangono tutti configurabili nell'inizializzatore.
- Modificate le proprietà pubbliche di
Kotlin
Enumerazioni
Sostituite
enumclassi esealedclassi 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 inHarmBlockThreshold.Valori rimossi dalle seguenti enumerazioni:
HarmBlockThreshold,HarmProbability,HarmSeverity,BlockReasoneFinishReason.
Metodi blob
- Tutti i metodi che includevano
Blobnel nome sono stati rinominati per utilizzareInlineData.
- Tutti i metodi che includevano
Impostazioni di sicurezza
- Il campo
methodè stato modificato in modo da poter essere nullo.
- Il campo
Classe Duration
- Sono stati rimossi tutti gli utilizzi della classe
Durationdi Kotlin e sono stati sostituiti conlong. Questa modifica offre una migliore interoperabilità con Java.
- Sono stati rimossi tutti gli utilizzi della classe
Metadati delle citazioni
- Abbiamo inserito tutti i campi dichiarati in precedenza in
CitationMetadatain una nuova classe denominataCitation. Le citazioni sono disponibili nell'elenco denominatocitationsinCitationMetadata. Questa modifica consente un migliore allineamento dei tipi tra le piattaforme.
- Abbiamo inserito tutti i campi dichiarati in precedenza in
Conta i token
- Il campo
totalBillableCharactersè stato modificato in modo da poter essere nullo.
- Il campo
Caratteri fatturabili totali
- La proprietà
totalBillableCharactersinCountTokensResponseè stata modificata in modo da essere facoltativa per riflettere le situazioni in cui non vengono inviati caratteri.
- La proprietà
Creazione di un'istanza di un modello
- Il parametro
requestOptionsè stato spostato alla fine dell'elenco dei parametri per l'allineamento con altre piattaforme.
- Il parametro
Java
Enumerazioni
Sostituite
enumclassi esealedclassi 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 inHarmBlockThreshold.Valori rimossi dalle seguenti enumerazioni:
HarmBlockThreshold,HarmProbability,HarmSeverity,BlockReasoneFinishReason.
Metodi blob
- Tutti i metodi che includevano
Blobnel nome sono stati rinominati per utilizzareInlineData.
- Tutti i metodi che includevano
Impostazioni di sicurezza
- Il campo
methodè stato modificato in modo da poter essere nullo.
- Il campo
Classe Duration
- Sono stati rimossi tutti gli utilizzi della classe
Durationdi Kotlin e sono stati sostituiti conlong. Questa modifica offre una migliore interoperabilità con Java.
- Sono stati rimossi tutti gli utilizzi della classe
Metadati delle citazioni
- Abbiamo inserito tutti i campi dichiarati in precedenza in
CitationMetadatain una nuova classe denominataCitation. Le citazioni sono disponibili nell'elenco denominatocitationsinCitationMetadata. Questa modifica consente un migliore allineamento dei tipi tra le piattaforme.
- Abbiamo inserito tutti i campi dichiarati in precedenza in
Conta i token
- Il campo
totalBillableCharactersè stato modificato in modo da poter essere nullo.
- Il campo
Caratteri fatturabili totali
- La proprietà
totalBillableCharactersinCountTokensResponseè stata modificata in modo da essere facoltativa per riflettere le situazioni in cui non vengono inviati caratteri.
- La proprietà
Creazione di un'istanza di un modello
- Il parametro
requestOptionsè stato spostato alla fine dell'elenco dei parametri per l'allineamento con altre piattaforme.
- Il parametro
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,BlockReasoneFinishReason.
- Valori rimossi dalle seguenti enumerazioni:
Motivo del blocco
blockReasoninPromptFeedbackè 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
GoogleGenerativeAIErrore, facoltativamente, eseguito il passaggio aAIError.
- Rimosso tutti gli utilizzi di
Dart
Enumerazioni
- Sono stati rimossi i valori dalle seguenti enumerazioni:
HarmCategory,HarmProbability,BlockReasoneFinishReason.
- Sono stati rimossi i valori dalle seguenti enumerazioni:
Parte dei dati
DataPartè stato rinominato inInlineDataParte la funzionedatastaticininlineDataper l'allineamento con altre piattaforme.
Opzioni di richiesta
- Rimosso
RequestOptionsperchétimeoutnon funzionava. Verrà aggiunta di nuovo nel prossimo futuro, ma verrà spostata nel tipoGenerativeModelper corrispondere ad altre piattaforme.
- Rimosso
Sequenze di interruzioni
- Il parametro
stopSequencesinGenerationConfigè stato modificato in modo che sia facoltativo e che il valore predefinito sianullanziché un array vuoto.
- Il parametro
Citazioni
- La proprietà
citationSourcesè stata rinominata incitationsinCitationMetadata. Il tipoCitationSourceè stato rinominato inCitationper corrispondere ad altre piattaforme.
- La proprietà
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,EmbedContentRequesteEmbedContentResponse.
- Sono stati rimossi i seguenti tipi, metodi e proprietà che sono stati esposti involontariamente:
Conta i token
- Sono stati rimossi i campi aggiuntivi dalla funzione
countTokensche non sono più necessari. È necessario solocontents.
- Sono stati rimossi i campi aggiuntivi dalla funzione
Creazione di un'istanza di un modello
- Il parametro
systemInstructionè stato spostato alla fine dell'elenco dei parametri per l'allineamento con altre piattaforme.
- Il parametro
Funzionalità di incorporamento
- È stata rimossa dal modello la funzionalità di embedding non supportata (
embedContentebatchEmbedContents).
- È stata rimossa dal modello la funzionalità di embedding non supportata (
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