Bermigrasi ke Firebase AI Logic SDK dari Vertex AI in Firebase SDK versi Pratinjau


Firebase AI Logic dan SDK kliennya sebelumnya disebut "Vertex AI in Firebase". Untuk lebih mencerminkan layanan dan fitur yang diperluas (misalnya, kami kini mendukung Gemini Developer API!), kami mengganti nama dan mengemas ulang layanan kami menjadi Firebase AI Logic.

Untuk mengakses model AI generatif Google secara aman langsung dari aplikasi seluler atau web Anda, Anda kini dapat memilih penyedia "Gemini API" — baik Vertex AI Gemini API yang sudah lama tersedia maupun Gemini Developer API yang kini tersedia. Artinya, kini Anda memiliki opsi untuk menggunakan Gemini Developer API, yang menyediakan tingkat tanpa biaya dengan batas tarif dan kuota yang wajar.

Ringkasan langkah-langkah untuk bermigrasi ke SDK Firebase AI Logic

  • Langkah 1: Pilih penyedia "Gemini API" terbaik untuk aplikasi dan kasus penggunaan Anda.

  • Langkah 2: Aktifkan API yang diperlukan.

  • Langkah 3: Perbarui pustaka yang digunakan di aplikasi Anda.

  • Langkah 4: Perbarui inisialisasi di aplikasi Anda.

  • Langkah 5: Perbarui kode Anda, bergantung pada fitur yang Anda gunakan.

Langkah 1: Pilih penyedia "Gemini API" terbaik untuk aplikasi Anda

Dengan migrasi ini, Anda dapat memilih penyedia "Gemini API":

  • SDK "Vertex AI in Firebase" lama hanya dapat menggunakan Vertex AI Gemini API.

  • SDK Firebase AI Logic baru memungkinkan Anda memilih penyedia "Gemini API" yang ingin dipanggil langsung dari aplikasi seluler atau web Anda – baik Gemini Developer API maupun Vertex AI Gemini API.

Tinjau perbedaan antara penggunaan dua penyedia Gemini API, terutama dalam hal fitur yang didukung, harga, dan batas kecepatan. Sebagai contoh, Gemini Developer API tidak mendukung penyediaan file menggunakan URL Cloud Storage, tetapi mungkin merupakan pilihan yang baik jika Anda ingin memanfaatkan tingkat tanpa biaya dan kuota yang wajar.

Langkah 2: Aktifkan API yang diperlukan

Pastikan semua API yang diperlukan diaktifkan di project Firebase Anda untuk menggunakan penyedia "Gemini API" yang Anda pilih.

Perhatikan bahwa Anda dapat mengaktifkan kedua penyedia API di project Anda secara bersamaan.

  1. Login ke konsol Firebase, lalu pilih project Firebase Anda.

  2. Di konsol Firebase, buka halaman Firebase AI Logic.

  3. Klik Mulai untuk meluncurkan alur kerja terpandu yang membantu Anda menyiapkan API dan resource yang diperlukan untuk project Anda.

  4. Pilih penyedia "Gemini API" yang ingin Anda gunakan dengan SDK Firebase AI Logic. Anda dapat menyiapkan dan menggunakan penyedia API lain nanti, jika Anda mau.

    • Gemini Developer APIpenagihan opsional (tersedia di paket harga Spark tanpa biaya)
      Alur kerja konsol akan mengaktifkan API yang diperlukan dan membuat kunci API Gemini di project Anda.
      Jangan tambahkan kunci API Gemini ini ke codebase aplikasi Anda. Pelajari lebih lanjut.

    • Vertex AI Gemini APIpenagihan diperlukan (memerlukan paket harga Blaze bayar sesuai penggunaan)
      Alur kerja konsol akan mengaktifkan API yang diperlukan di project Anda.

  5. Lanjutkan di panduan migrasi ini untuk memperbarui library dan inisialisasi di aplikasi Anda.

Langkah 3: Perbarui library yang digunakan di aplikasi Anda

Perbarui codebase aplikasi Anda untuk menggunakan library Firebase AI Logic.

Swift

  1. Di Xcode, dengan project aplikasi Anda dalam keadaan terbuka, update paket Firebase ke v11.13.0 atau yang lebih baru menggunakan salah satu opsi berikut:

    • Opsi 1: Update semua paket: Buka File > Packages > Update to Latest Package Versions.

    • Opsi 2: Perbarui Firebase satu per satu: Buka paket Firebase di bagian yang disebut Package Dependencies. Klik kanan paket Firebase, lalu pilih Update Package.

  2. Pastikan paket Firebase kini menampilkan v11.13.0 atau yang lebih baru. Jika tidak, pastikan Persyaratan Paket yang Anda tentukan mengizinkan update ke v11.13.0 atau yang lebih baru.

  3. Pilih target aplikasi Anda di Project Editor, lalu buka bagian Frameworks, Libraries, and Embedded Content.

  4. Tambahkan library baru: Pilih tombol +, lalu tambahkan FirebaseAI dari paket Firebase.

  5. Setelah Anda selesai memigrasikan aplikasi (lihat bagian lainnya dalam panduan ini), pastikan untuk menghapus library lama:
    Pilih FirebaseVertexAI-Preview, lalu tekan tombol .

Kotlin

  1. Dalam file Gradle modul (level aplikasi) (biasanya <project>/<app-module>/build.gradle.kts atau <project>/<app-module>/build.gradle), ganti dependensi lama (jika berlaku) dengan yang berikut.

    Perhatikan bahwa mungkin lebih mudah untuk memigrasikan codebase aplikasi Anda (lihat bagian lainnya dalam panduan ini) sebelum menghapus dependensi lama.

    // 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.16.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. Sinkronkan project Android Anda dengan file Gradle.

Perhatikan bahwa jika Anda memilih untuk tidak menggunakan Firebase Android BoM, cukup tambahkan dependensi untuk library firebase-ai dan setujui versi terbaru yang disarankan oleh Android Studio.

Java

  1. Dalam file Gradle modul (level aplikasi) (biasanya <project>/<app-module>/build.gradle.kts atau <project>/<app-module>/build.gradle), ganti dependensi lama (jika berlaku) dengan yang berikut.

    Perhatikan bahwa mungkin lebih mudah untuk memigrasikan codebase aplikasi Anda (lihat bagian lainnya dalam panduan ini) sebelum menghapus dependensi lama.

    // 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.16.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. Sinkronkan project Android Anda dengan file Gradle.

Perhatikan bahwa jika Anda memilih untuk tidak menggunakan Firebase Android BoM, cukup tambahkan dependensi untuk library firebase-ai dan setujui versi terbaru yang disarankan oleh Android Studio.

Web

  1. Dapatkan Firebase JS SDK untuk Web versi terbaru menggunakan npm:

    npm i firebase@latest

    ATAU

    yarn add firebase@latest
  2. Di mana pun Anda mengimpor library, perbarui pernyataan impor untuk menggunakan firebase/ai.

    Perhatikan bahwa mungkin lebih mudah untuk memigrasikan codebase aplikasi Anda (lihat bagian lainnya dalam panduan ini) sebelum menghapus impor lama.

    // 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. Perbarui untuk menggunakan paket firebase_ai dalam file pubspec.yaml Anda dengan menjalankan perintah berikut dari direktori project Flutter Anda:

    flutter pub add firebase_ai
  2. Build ulang project Flutter Anda:

    flutter run
  3. Setelah Anda selesai memigrasikan aplikasi (lihat bagian yang tersisa dalam panduan ini), pastikan untuk menghapus paket lama:

    flutter pub remove firebase_vertexai

Unity

Dukungan untuk Unity tidak tersedia dari "Vertex AI in Firebase".

Pelajari cara memulai Firebase AI Logic SDK untuk Unity.

Langkah 4: Perbarui inisialisasi di aplikasi Anda

Klik penyedia Gemini API untuk melihat konten dan kode khusus penyedia di halaman ini.

Perbarui cara Anda menginisialisasi layanan untuk penyedia API yang Anda pilih dan buat instance 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

Dukungan untuk Unity tidak tersedia sejak "Vertex AI in Firebase".

Pelajari cara memulai Firebase AI Logic SDK untuk Unity.

Perhatikan bahwa bergantung pada kemampuan yang Anda gunakan, Anda mungkin tidak selalu membuat instance GenerativeModel.

Langkah 5: Perbarui kode Anda, bergantung pada fitur yang Anda gunakan

Langkah ini menjelaskan perubahan yang mungkin diperlukan, bergantung pada fitur yang Anda gunakan.

  • Jika Anda menggunakan URL Cloud Storage dan beralih menggunakan Gemini Developer API dalam migrasi ini, Anda harus memperbarui permintaan multimodal untuk menyertakan file sebagai data inline (atau menggunakan URL YouTube untuk video).

  • Beberapa perubahan diperkenalkan untuk SDK "Vertex AI in Firebase" versi GA. Perubahan yang sama ini diperlukan untuk menggunakan SDK Firebase AI Logic. Tinjau daftar berikut untuk mengetahui perubahan yang mungkin perlu Anda lakukan pada kode untuk mengakomodasi penggunaan SDK Firebase AI Logic.

Wajib untuk semua bahasa dan platform

  • Panggilan fungsi
    Jika Anda menerapkan fitur ini sebelum GA, Anda harus memperbarui cara Anda menentukan skema. Sebaiknya tinjau panduan panggilan fungsi yang telah diperbarui untuk mempelajari cara menulis deklarasi fungsi.

  • Membuat output terstruktur (seperti JSON) menggunakan responseSchema
    Jika Anda menerapkan fitur ini sebelum GA, Anda harus memperbarui cara Anda menentukan skema. Sebaiknya tinjau panduan output terstruktur yang baru untuk mempelajari cara menulis skema JSON.

  • Waktu tunggu

    • Mengubah waktu tunggu default untuk permintaan menjadi 180 detik.

Wajib diisi berdasarkan platform atau bahasa

Swift

  • Enumerations

    • Mengganti sebagian besar jenis enum dengan struct dengan variabel statis. Perubahan ini memungkinkan fleksibilitas yang lebih besar untuk mengembangkan API secara kompatibel mundur. Saat menggunakan pernyataan switch, Anda kini harus menyertakan kasus default: untuk mencakup nilai yang tidak diketahui atau tidak ditangani, termasuk nilai baru yang ditambahkan ke SDK pada masa mendatang.

    • Mengganti nama enumerasi BlockThreshold menjadi HarmBlockThreshold; jenis ini sekarang menjadi struct.

    • Kasus unknown dan unspecified telah dihapus dari enumerasi berikut (sekarang struct): HarmCategory, HarmBlockThreshold, HarmProbability, BlockReason, dan FinishReason.

    • Mengganti enumerasi ModelContent.Part dengan protokol bernama Part untuk memungkinkan jenis baru ditambahkan dengan cara yang kompatibel mundur. Perubahan ini dijelaskan secara lebih mendetail di bagian Bagian konten.

  • Bagian konten

    • Menghapus protokol ThrowingPartsRepresentable, dan menyederhanakan penginisialisasi untuk ModelContent guna menghindari error compiler sesekali. Gambar yang tidak dienkode dengan benar akan tetap memunculkan error saat digunakan di generateContent.

    • Mengganti kasus ModelContent.Part dengan jenis struct berikut yang sesuai dengan protokol Part:

      • .text ke TextPart
      • .data ke InlineDataPart
      • .fileData ke FileDataPart
      • .functionCall ke FunctionCallPart
      • .functionResponse ke FunctionResponsePart
  • Kategori bahaya

    • Mengubah HarmCategory agar tidak lagi bertingkat dalam jenis SafetySetting. Jika Anda menyebutnya sebagai SafetySetting.HarmCategory, SafetySetting.HarmCategory tersebut dapat diganti dengan HarmCategory.
  • Masukan keselamatan

    • Menghapus jenis SafetyFeedback, karena tidak digunakan dalam respons apa pun.
  • Metadata kutipan

    • Mengganti nama properti citationSources menjadi citations di CitationMetadata.
  • Total karakter yang dapat ditagih

    • Mengubah properti totalBillableCharacters di CountTokensResponse menjadi opsional untuk mencerminkan situasi saat tidak ada karakter yang dikirim.
  • Respons kandidat

    • Mengganti nama CandidateResponse menjadi Candidate agar sesuai dengan platform lain.
  • Konfigurasi pembuatan

    • Mengubah properti publik GenerationConfig menjadi internal. Semuanya tetap dapat dikonfigurasi di penginisialisasi.

Kotlin

  • Enumerations

    • Mengganti class enum dan class sealed dengan class reguler. Perubahan ini memungkinkan fleksibilitas yang lebih besar untuk mengembangkan API dengan cara yang kompatibel mundur.

    • Mengganti nama enumerasi BlockThreshold menjadi HarmBlockThreshold.

    • Nilai dihapus dari enumerasi berikut: HarmBlockThreshold, HarmProbability, HarmSeverity, BlockReason, dan FinishReason.

  • Metode blob

    • Mengganti nama semua metode yang menyertakan Blob sebagai bagian dari namanya untuk menggunakan InlineData sebagai gantinya.
  • Setelan keamanan

    • Mengubah kolom method menjadi nullable.
  • Class durasi

    • Menghapus semua penggunaan class Duration Kotlin, dan menggantinya dengan long. Perubahan ini memberikan interoperabilitas yang lebih baik dengan Java.
  • Metadata kutipan

    • Membungkus semua kolom yang sebelumnya dideklarasikan di CitationMetadata ke dalam class baru yang disebut Citation. Kutipan dapat ditemukan dalam daftar yang disebut citations di CitationMetadata. Perubahan ini memungkinkan penyelarasan jenis yang lebih baik di seluruh platform.
  • Menghitung token

    • Mengubah kolom totalBillableCharacters menjadi nullable.
  • Total karakter yang dapat ditagih

    • Mengubah properti totalBillableCharacters di CountTokensResponse menjadi opsional untuk mencerminkan situasi saat tidak ada karakter yang dikirim.
  • Membuat instance model

    • Memindahkan parameter requestOptions ke akhir daftar parameter agar selaras dengan platform lain.
  • Live API

    • Menghapus nilai UNSPECIFIED untuk class enum ResponseModality. Sebagai gantinya, gunakan null.

    • Mengganti nama LiveGenerationConfig.setResponseModalities menjadi LiveGenerationConfig.setResponseModality.

    • Menghapus class LiveContentResponse.Status, dan sebagai gantinya, menyusun kolom status sebagai properti LiveContentResponse.

    • Menghapus class LiveContentResponse, dan sebagai gantinya, menyediakan subkelas LiveServerMessage yang cocok dengan respons dari model.

    • Mengubah LiveModelFutures.connect agar menampilkan ListenableFuture<LiveSessionFutures>, bukan ListenableFuture<LiveSession>.

Java

  • Enumerations

    • Mengganti class enum dan class sealed dengan class reguler. Perubahan ini memungkinkan fleksibilitas yang lebih besar untuk mengembangkan API dengan cara yang kompatibel mundur.

    • Mengganti nama enumerasi BlockThreshold menjadi HarmBlockThreshold.

    • Nilai dihapus dari enumerasi berikut: HarmBlockThreshold, HarmProbability, HarmSeverity, BlockReason, dan FinishReason.

  • Metode blob

    • Mengganti nama semua metode yang menyertakan Blob sebagai bagian dari namanya untuk menggunakan InlineData sebagai gantinya.
  • Setelan keamanan

    • Mengubah kolom method menjadi nullable.
  • Class durasi

    • Menghapus semua penggunaan class Duration Kotlin, dan menggantinya dengan long. Perubahan ini memberikan interoperabilitas yang lebih baik dengan Java.
  • Metadata kutipan

    • Membungkus semua kolom yang sebelumnya dideklarasikan di CitationMetadata ke dalam class baru yang disebut Citation. Kutipan dapat ditemukan dalam daftar yang disebut citations di CitationMetadata. Perubahan ini memungkinkan penyelarasan jenis yang lebih baik di seluruh platform.
  • Menghitung token

    • Mengubah kolom totalBillableCharacters menjadi nullable.
  • Total karakter yang dapat ditagih

    • Mengubah properti totalBillableCharacters di CountTokensResponse menjadi opsional untuk mencerminkan situasi saat tidak ada karakter yang dikirim.
  • Membuat instance model

    • Memindahkan parameter requestOptions ke akhir daftar parameter agar selaras dengan platform lain.
  • Live API

    • Menghapus nilai UNSPECIFIED untuk class enum ResponseModality. Sebagai gantinya, gunakan null.

    • Mengganti nama LiveGenerationConfig.setResponseModalities menjadi LiveGenerationConfig.setResponseModality.

    • Menghapus class LiveContentResponse.Status, dan sebagai gantinya, menyusun kolom status sebagai properti LiveContentResponse.

    • Menghapus class LiveContentResponse, dan sebagai gantinya, menyediakan subkelas LiveServerMessage yang cocok dengan respons dari model.

    • Mengubah LiveModelFutures.connect agar menampilkan ListenableFuture<LiveSessionFutures>, bukan ListenableFuture<LiveSession>.

  • Mengubah berbagai metode builder Java agar kini menampilkan instance classnya dengan benar, bukan void.

Web

  • Enumerations

    • Nilai dihapus dari enumerasi berikut: HarmCategory, BlockThreshold, HarmProbability, HarmSeverity, BlockReason, dan FinishReason.
  • Alasan pemblokiran

    • Mengubah blockReason di PromptFeedback menjadi opsional.

Perubahan hanya diperlukan jika Anda mulai menggunakan Gemini Developer API (bukan Vertex AI Gemini API):

  • Setelan keamanan

    • Menghapus penggunaan SafetySetting.method yang tidak didukung.
  • Data inline

    • Menghapus penggunaan InlineDataPart.videoMetadata yang tidak didukung.

Dart

  • Enumerations

    • Nilai dihapus dari enumerasi berikut: HarmCategory, HarmProbability, BlockReason, dan FinishReason.
  • Bagian data

    • Mengganti nama DataPart menjadi InlineDataPart, dan fungsi static data menjadi inlineData agar selaras dengan platform lain.
  • Opsi permintaan

    • Menghapus RequestOptions karena timeout tidak berfungsi. Fitur ini akan ditambahkan kembali dalam waktu dekat, tetapi akan dipindahkan ke jenis GenerativeModel agar sesuai dengan platform lain.
  • Urutan penghentian

    • Mengubah parameter stopSequences di GenerationConfig agar bersifat opsional dan ditetapkan secara default ke null, bukan array kosong.
  • Kutipan

    • Mengganti nama properti citationSources menjadi citations di CitationMetadata. Jenis CitationSource diganti namanya menjadi Citation agar sesuai dengan platform lain.
  • Jenis, metode, dan properti publik yang tidak diperlukan

    • Jenis, metode, dan properti berikut yang tidak sengaja diekspos telah dihapus: defaultTimeout, CountTokensResponseFields, parseCountTokensResponse, parseEmbedContentResponse, parseGenerateContentResponse, parseContent, BatchEmbedContentsResponse, ContentEmbedding, EmbedContentRequest, dan EmbedContentResponse.
  • Menghitung token

    • Menghapus kolom tambahan dari fungsi countTokens yang tidak lagi diperlukan. Hanya contents yang diperlukan.
  • Membuat instance model

    • Memindahkan parameter systemInstruction ke akhir daftar parameter agar selaras dengan platform lain.
  • Fungsi penyematan

    • Menghapus fungsi penyematan yang tidak didukung (embedContent dan batchEmbedContents) dari model.

Unity

Dukungan untuk Unity tidak tersedia dari "Vertex AI in Firebase".

Pelajari cara memulai Firebase AI Logic SDK untuk Unity.

Kemungkinan error terkait migrasi

Saat bermigrasi untuk menggunakan Firebase AI Logic versi GA, Anda mungkin mengalami error jika belum menyelesaikan semua perubahan yang diperlukan seperti yang dijelaskan dalam panduan migrasi ini.

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

Jika Anda menerima error 403 yang menyatakan Requests to this API firebasevertexai.googleapis.com ... are blocked., biasanya berarti kunci API Firebase di file atau objek konfigurasi Firebase Anda tidak memiliki API yang diperlukan dalam daftar yang diizinkannya untuk produk yang sedang Anda coba gunakan.

Pastikan kunci Firebase API yang digunakan oleh aplikasi Anda memiliki semua API yang diperlukan yang disertakan dalam daftar yang diizinkan "pembatasan API" kunci. Untuk Firebase AI Logic, kunci API Firebase Anda minimal harus memiliki Firebase AI Logic API dalam daftar yang diizinkannya. API ini seharusnya telah otomatis ditambahkan ke daftar yang diizinkan untuk kunci API Anda saat Anda mengaktifkan API yang diperlukan di konsol Firebase.

Anda dapat melihat semua kunci API di panel APIs & Services > Credentials di Google Cloud console.


Memberikan masukan tentang pengalaman Anda dengan Firebase AI Logic