Membangun pengalaman hybrid di aplikasi Web dengan model yang dihosting di perangkat dan cloud

Anda dapat membangun aplikasi dan fitur Web yang didukung AI dengan inferensi hibrid menggunakan Firebase AI Logic. Inferensi hybrid memungkinkan menjalankan inferensi menggunakan model di perangkat jika tersedia dan beralih dengan lancar ke model yang dihosting di cloud jika tidak tersedia (dan sebaliknya).

Halaman ini menjelaskan cara mulai menggunakan SDK klien. Setelah menyelesaikan penyiapan standar ini, lihat opsi dan kemampuan konfigurasi tambahan.

Perhatikan bahwa inferensi di perangkat melalui Firebase AI Logic didukung untuk aplikasi web yang menggunakan Firebase AI Logic SDK v12.5.0+ dan berjalan di Chrome di Desktop (versi 139 atau yang lebih tinggi).

Langsung ke contoh kode tampilan

Kasus penggunaan dan kemampuan yang didukung

Bergantung pada kasus penggunaan aplikasi, Anda dapat memanfaatkan beberapa manfaat pengalaman di perangkat atau hybrid:

  • Manfaat menggunakan model di perangkat untuk inferensi:

    • Privasi yang ditingkatkan
    • Konteks lokal
    • Inferensi tanpa biaya
    • Fungsi offline

  • Manfaat menggunakan pendekatan hybrid:

    • Memberikan pengalaman aplikasi yang serupa, apa pun perangkat pengguna akhir
    • Meningkatkan ketersediaan fitur AI generatif, terlepas dari konektivitas internet, batasan kuota, atau kemampuan perangkat

Kemampuan inferensi di perangkat yang didukung

Inferensi di perangkat hanya mendukung pembuatan teks satu giliran (bukan chat) (dengan output streaming atau non-streaming), khususnya kemampuan berikut:

Pastikan untuk meninjau daftar fitur yang belum didukung untuk inferensi hybrid atau di perangkat di bagian bawah halaman ini.

API dan platform yang didukung

Bagian berikut menjelaskan API yang didukung, serta platform dan browser yang didukung.

API yang didukung untuk inferensi di cloud vs di perangkat

  • Inferensi dalam cloud menggunakan penyedia Gemini API yang Anda pilih (Gemini Developer API atau Agent Platform Gemini API (formerly Vertex AI)).

  • Inferensi di perangkat menggunakan Prompt API dari Chrome.

Platform dan browser yang didukung

Untuk inferensi di perangkat (yang menggunakan Prompt API dari Chrome), pengguna akhir aplikasi Anda harus menjalankan Chrome di Desktop (versi 139 atau yang lebih tinggi). Pelajari lebih lanjut di dokumentasi Chrome.

Mulai di localhost

Langkah-langkah memulai ini menjelaskan penyiapan umum yang diperlukan untuk setiap permintaan perintah yang didukung yang ingin Anda kirim.

Anda dapat mempelajari lebih lanjut penggunaan API di localhost dalam dokumentasi Chrome.

Langkah 1: Siapkan Chrome dan Prompt API untuk inferensi di perangkat

  1. Pastikan Anda menggunakan Chrome versi terbaru. Update di chrome://settings/help.
    Inferensi di perangkat tersedia mulai Chrome v139 dan yang lebih baru.

  2. Aktifkan model multimodal di perangkat dengan menyetel flag berikut ke Enabled:

    • chrome://flags/#prompt-api-for-gemini-nano-multimodal-input

  3. Mulai ulang Chrome.

  4. (Opsional) Download model di perangkat sebelum permintaan pertama.

    Prompt API disertakan dalam Chrome; namun, model di perangkat tidak tersedia secara default. Jika Anda belum mendownload model sebelum permintaan pertama untuk inferensi di perangkat, permintaan tersebut akan otomatis memulai download model di latar belakang.

Langkah 2: Siapkan project Firebase dan hubungkan aplikasi Anda ke Firebase

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

  2. Di konsol Firebase, buka AI Services > AI Logic.

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

  4. Jika diminta, ikuti petunjuk di layar untuk mendaftarkan aplikasi dan menambahkan konfigurasi Firebase ke aplikasi Anda.

  5. Saat diminta untuk memilih "Penyedia Gemini API", sebaiknya pilih Gemini Developer API, yang memungkinkan Anda memulai dengan cepat tanpa biaya.

    Kapan pun, Anda dapat menyiapkan Agent Platform Gemini API (formerly Vertex AI) (dan persyaratannya untuk penagihan).

  6. Lanjutkan dalam alur kerja untuk menyiapkan API yang diperlukan dan layanan terkait untuk Firebase AI Logic.

    Tahap alur kerja ini otomatis menerapkan Firebase App Check untuk AI Logic, yang merupakan layanan penting untuk membantu melindungi Gemini API saat diakses langsung dari aplikasi Anda. Sebagai bagian dari langkah awal (lihat langkah-langkah selanjutnya dalam panduan ini), Anda harus mengonfigurasi penyedia debug App Check untuk pengembangan lokal saat App Check diterapkan.

  7. Lanjutkan ke langkah berikutnya dalam panduan ini untuk menambahkan SDK yang diperlukan ke aplikasi Anda.

Langkah 3: Tambahkan SDK

Library Firebase menyediakan akses ke API untuk berinteraksi dengan model generatif. Library ini disertakan sebagai bagian dari Firebase JavaScript SDK untuk Web.

  1. Instal Firebase JS SDK untuk Web menggunakan npm:

    npm install firebase

  2. Inisialisasi Firebase di aplikasi Anda:

    import { initializeApp } from "firebase/app";
import { initializeAppCheck } 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);

Langkah 4: Konfigurasi penyedia debug App Check untuk pengembangan lokal

Sebagai bagian dari alur kerja penyiapan terpandu untuk AI Logic di konsol, Firebase App Check otomatis diterapkan untuk melindungi Gemini API. Untuk pengembangan lokal, Anda perlu mengonfigurasi penyedia debug App Check untuk mengabaikan pengesahan sambil tetap mempertahankan penerapan App Check.

Berikut cara menggunakan penyedia debug saat menjalankan aplikasi Anda dari localhost secara interaktif (misalnya, selama pengembangan lokal):

  1. Dalam build debug, aktifkan mode debug dengan menetapkan self.FIREBASE_APPCHECK_DEBUG_TOKEN ke true sebelum Anda melakukan inisialisasi App Check. Contoh:

    self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
initializeAppCheck(firebaseApp, { /* App Check options */ });

  2. Buka aplikasi web Anda secara lokal, lalu buka alat developer browser. Di konsol debug, Anda akan melihat token debug:

    AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678".
You will need to safelist it in the Firebase console for it to work.

  3. Daftarkan token debug Anda ke App Check:

    1. Di Firebase console, buka tab Security > App Check > Apps.

    2. Temukan aplikasi Anda, klik menu tambahan (), lalu pilih Manage debug tokens.

    3. Ikuti petunjuk di layar untuk mendaftarkan token debug Anda.

Untuk mengetahui detail tentang penyedia debug (termasuk cara mendapatkan token debug baru), lihat dokumentasi resmi App Check.

Langkah 5: Lakukan inisialisasi layanan dan buat instance model

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

Siapkan hal berikut sebelum Anda mengirim permintaan perintah ke model:

  1. Lakukan inisialisasi layanan untuk penyedia API yang Anda pilih.

  2. Buat instance GenerativeModel. Pastikan untuk menetapkan mode ke salah satu dari:

    • PREFER_ON_DEVICE: Gunakan model di perangkat jika tersedia; jika tidak, gunakan model yang dihosting di cloud.

    • ONLY_ON_DEVICE: Gunakan model di perangkat jika tersedia; jika tidak, tampilkan pengecualian.

    • PREFER_IN_CLOUD: Gunakan model yang dihosting di cloud jika tersedia; jika tidak, gunakan model di perangkat.

    • ONLY_IN_CLOUD: Gunakan model yang dihosting di cloud jika tersedia; jika tidak, tampilkan pengecualian.

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, InferenceMode } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

Langkah 6: Lakukan inisialisasi model di perangkat

Anda harus memanggil initializeDeviceModel() setelah atau pada interaksi halaman pengguna akhir (seperti klik tombol) dan sebelum Anda mengirim permintaan perintah ke model. Pelajari lebih lanjut persyaratan aktivasi pengguna dalam dokumentasi Chrome.

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, InferenceMode } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

// `initializeDeviceModel` must be called:
// (1) after or on an end-user page interaction such as a button click
// and
// (2) before any queries to the model (such as `generateContent()`)
// You may want to `await` this promise if using `ONLY_ON_DEVICE` (see note below).
model.initializeDeviceModel((val) =>
  // Example: "Download progress: 72.62%""
  console.log(`Download progress: ${Math.round(val*10000) / 100}%`)
);

Langkah 7: Mengirim permintaan perintah ke model

Bagian ini menunjukkan cara mengirim berbagai jenis input untuk menghasilkan berbagai jenis output, termasuk:

Jika Anda ingin menghasilkan output terstruktur (seperti JSON atau enum), gunakan salah satu contoh "teks yang dihasilkan" berikut dan konfigurasikan model untuk merespons sesuai dengan skema yang disediakan.

Membuat teks dari input khusus teks

Sebelum mencoba contoh ini, pastikan Anda telah menyelesaikan bagian Memulai dalam panduan ini.

Anda dapat menggunakan generateContent() untuk membuat teks dari perintah yang berisi teks:

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Wrap in an async function so you can use await
async function run() {
  // Provide a prompt that contains text
  const prompt = "Write a story about a magic backpack."

  // To generate text output, call `generateContent` with the text input
  const result = await model.generateContent(prompt);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

Perhatikan bahwa Firebase AI Logic juga mendukung streaming respons teks menggunakan generateContentStream (bukan generateContent).

Membuat teks dari input teks dan gambar (multimodal)

Sebelum mencoba contoh ini, pastikan Anda telah menyelesaikan bagian Memulai dalam panduan ini.

Anda dapat menggunakan generateContent() untuk membuat teks yang dihasilkan dari perintah yang berisi file teks dan gambar—dengan memberikan mimeType setiap file input dan file itu sendiri.

Jenis gambar input yang didukung untuk inferensi di perangkat adalah PNG dan JPEG.

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Converts a File object to a Part object.
async function fileToGenerativePart(file) {
  const base64EncodedDataPromise = new Promise((resolve) => {
    const reader = new FileReader();
    reader.onloadend = () => resolve(reader.result.split(',')[1]);
    reader.readAsDataURL(file);
  });
  return {
    type: "inlineData",
    inlineData: { data: await base64EncodedDataPromise, mimeType: file.type },
  };
}

async function run() {
  // Provide a text prompt to include with the image
  const prompt = "Write a poem about this picture:";

  const fileInputEl = document.querySelector("input[type=file]");
  const imagePart = await fileToGenerativePart(fileInputEl.files[0]);

  // To generate text output, call `generateContent` with the text and image
  const result = await model.generateContent([prompt, imagePart]);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

Perhatikan bahwa Firebase AI Logic juga mendukung streaming respons teks menggunakan generateContentStream (bukan generateContent).

Kamu bisa apa lagi?

Anda dapat menggunakan berbagai opsi dan kemampuan konfigurasi tambahan untuk pengalaman hybrid:

Fitur yang belum didukung

Tidak semua kemampuan Web SDK atau model yang dihosting di cloud tersedia untuk inferensi hybrid atau di perangkat.

Fitur yang belum didukung untuk penerapan hybrid

Fitur berikut tidak dapat digunakan dengan penerapan hybrid (baik di perangkat maupun melalui penggantian cloud):

  • Gemini Live API: Streaming real-time dua arah tidak didukung.

  • Template perintah server: Template perintah server terkelola tidak didukung.

  • Menghitung token: Penghitungan token tidak boleh diandalkan karena jumlahnya akan berbeda antara model yang dihosting di cloud dan model di perangkat, sehingga tidak ada penggantian yang intuitif.

Fitur yang belum didukung untuk inferensi di perangkat

Fitur berikut belum didukung untuk inferensi di perangkat, tetapi tersedia untuk model yang dihosting di cloud.

  • Membuat gambar menggunakan model Gemini Nano Banana

    • Dapat beralih ke model yang dihosting di cloud; namun, mode ONLY_ON_DEVICE akan menampilkan error.

  • Membuat teks dari jenis input file gambar selain JPEG dan PNG

    • Dapat beralih ke model yang dihosting di cloud; namun, mode ONLY_ON_DEVICE akan menampilkan error.

  • Membuat teks dari input multimodal audio, video, dan dokumen (PDF)

    • Dapat beralih ke model yang dihosting di cloud; namun, mode ONLY_ON_DEVICE akan menampilkan error.

  • Menyediakan file menggunakan URL dalam permintaan multimodal. Anda harus menyediakan file sebagai data inline ke model di perangkat.

  • Multi-turn chat

    • Dapat beralih ke model yang dihosting di cloud; namun, mode ONLY_ON_DEVICE akan menampilkan error.

  • Menyediakan alat untuk membantu model menghasilkan responsnya (seperti pemanggilan fungsi, eksekusi kode, konteks URL, Grounding dengan Google Search, dan Grounding dengan Google Maps)

  • Pemantauan AI di Firebase konsol tidak menampilkan data apa pun untuk inferensi di perangkat (termasuk log perangkat). Namun, inferensi apa pun yang menggunakan model yang dihosting di cloud dapat dipantau seperti inferensi lainnya melalui Firebase AI Logic.

Batasan tambahan

Selain hal di atas, inferensi di perangkat memiliki batasan berikut:

  • Pengguna akhir aplikasi Anda harus menjalankan Chrome di Desktop (versi 139 atau yang lebih baru) dengan flag yang diperlukan diaktifkan.

  • Model di perangkat memerlukan ruang penyimpanan yang cukup di perangkat pengguna untuk download model awal.


Berikan masukan tentang pengalaman Anda menggunakan Firebase AI Logic