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

Bangun aplikasi dan fitur web berteknologi 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 (seperti output terstruktur).

Perhatikan bahwa inferensi di perangkat didukung untuk aplikasi web yang berjalan di Chrome di Desktop.

Langsung ke contoh kode

Kasus penggunaan yang direkomendasikan dan kemampuan yang didukung

Kasus penggunaan yang direkomendasikan:

• Penggunaan model di perangkat untuk inferensi menawarkan:

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

• Penggunaan fungsi hybrid menawarkan:

  • Menjangkau 100% audiens Anda, terlepas dari ketersediaan model di perangkat atau konektivitas internet

Kemampuan dan fitur yang didukung untuk inferensi di perangkat:

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

• Membuat teks dari input khusus teks

• Membuat teks dari input teks dan gambar, khususnya jenis gambar input JPEG dan PNG

Anda juga dapat membuat output terstruktur, termasuk JSON dan enum.

Sebelum memulai

Perhatikan hal berikut ini:

• Inferensi menggunakan model di perangkat menggunakan Prompt API dari Chrome; sedangkan inferensi menggunakan model yang dihosting di cloud menggunakan penyedia Gemini API pilihan Anda (Gemini Developer API atau Agent Platform Gemini API (formerly Vertex AI)).

• Halaman ini menjelaskan cara mulai mengembangkan menggunakan localhost (pelajari lebih lanjut cara menggunakan API di localhost dalam dokumentasi Chrome).

  Setelah menyelesaikan penyiapan standar ini, lihat opsi dan kemampuan konfigurasi tambahan (seperti output terstruktur).

Mulai di localhost

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

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.

   Lihat petunjuk untuk mendownload model di perangkat

   1. Buka Alat Developer > Konsol.

   2. Jalankan perintah berikut:

      await LanguageModel.availability();
      

   3. Pastikan output-nya adalah available, downloading, atau downloadable.

   4. Jika outputnya adalah downloadable, mulai download model dengan menjalankan:

      await LanguageModel.create();
      

   5. Anda dapat menggunakan callback monitor berikut untuk memproses progres download dan memastikan bahwa model telah available sebelum membuat permintaan:

      const session = await LanguageModel.create({
        monitor(m) {
          m.addEventListener("downloadprogress", (e) => {
            console.log(`Downloaded ${e.loaded * 100}%`);
          });
        },
      });
      

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

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

   Belum memiliki project Firebase?

   Jika Anda belum memiliki project Firebase, klik tombol untuk membuat project Firebase baru, lalu gunakan salah satu opsi berikut:

   • Opsi 1: Buat project Firebase yang benar-benar baru (dan project Google Cloud yang mendasarinya secara otomatis) dengan memasukkan nama project baru di langkah pertama alur kerja.

   • Opsi 2: "Tambahkan Firebase" ke project Google Cloud yang ada dengan mengklik Add Firebase to Google Cloud project (di bagian bawah halaman). Pada langkah pertama alur kerja, masukkan nama project dari project yang ada, lalu pilih project dari daftar yang ditampilkan.

   Selesaikan langkah-langkah alur kerja di layar yang tersisa untuk membuat project Firebase. Perhatikan bahwa saat diminta, Anda tidak perlu menyiapkan Google Analytics untuk menggunakan SDK Firebase AI Logic.

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

3. Klik Mulai 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 "Gemini API provider", 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 (more_vert), 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 App Check resmi.

Langkah 5: Lakukan inisialisasi layanan dan buat instance model

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 di 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:

• Membuat teks yang dihasilkan dari input khusus teks
• Membuat teks dari input teks dan gambar (multimodal)

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

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)

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:

• Menetapkan mode inferensi

• Mengganti model penggantian default yang dihosting di cloud

• Menggunakan konfigurasi model untuk mengontrol respons

• Membuat output terstruktur (seperti JSON)

Fitur yang belum tersedia untuk inferensi di perangkat

Tidak semua kemampuan Web SDK tersedia untuk inferensi di perangkat. Fitur berikut belum didukung untuk inferensi di perangkat (tetapi biasanya tersedia untuk inferensi berbasis cloud).

• 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 audio, video, dan dokumen (seperti PDF)

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

• Membuat gambar menggunakan model Gemini Nano Banana

  • 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.

• Streaming dua arah dengan Gemini Live API

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

• Menghitung token

  • Selalu menampilkan error. Jumlahnya akan berbeda antara model yang dihosting di cloud dan model di perangkat, sehingga tidak ada penggantian yang intuitif.

• Pemantauan AI di Firebase console untuk inferensi di perangkat.

  • Perhatikan bahwa inferensi apa pun yang menggunakan model yang dihosting di cloud dapat dipantau seperti inferensi lainnya menggunakan SDK klien Firebase AI Logic untuk Web.

Berikan masukan tentang pengalaman Anda menggunakan Firebase AI Logic