Gemini 3 Pro & Flash, Gemini 3 Pro Image (nano banana pro), and the latest Gemini Live API native audio models are now available to use with Firebase AI Logic on all platforms!

Gemini 2.0 Flash and Flash-Lite models will be retired on March 31, 2026. To avoid service disruption, update to a newer model like gemini-2.5-flash-lite. Learn more.

Membuat pengalaman campuran dengan model yang dihosting di perangkat dan di cloud

Bangun aplikasi dan fitur web yang didukung AI dengan inferensi hybrid menggunakan Firebase AI Logic. Inferensi hybrid memungkinkan menjalankan inferensi menggunakan model di perangkat jika tersedia dan melakukan penggantian yang lancar ke model yang dihosting di cloud jika tidak tersedia (dan sebaliknya).

Halaman ini menjelaskan cara mulai menggunakan SDK klien, serta menunjukkan 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:

Menggunakan model di perangkat untuk inferensi menawarkan:
- Privasi yang ditingkatkan
- Konteks lokal
- Inferensi tanpa biaya
- Fungsi offline
Menggunakan penawaran fungsi hybrid:
- Menjangkau 100% audiens Anda, terlepas dari ketersediaan model di perangkat atau konektivitas internet

Kemampuan dan fitur yang didukung untuk inferensi di perangkat:

Pembuatan konten satu giliran, streaming, dan non-streaming
Membuat teks dari input khusus teks
Membuat teks dari input teks dan gambar, khususnya jenis gambar input JPEG dan PNG
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 yang Anda pilih (Gemini Developer API atau Vertex AI Gemini API).
Halaman ini menjelaskan cara mulai mengembangkan menggunakan localhost (pelajari lebih lanjut cara menggunakan API di localhost dalam dokumentasi Chrome). Selain itu, lihat opsi dan kemampuan konfigurasi tambahan (seperti output terstruktur) di bagian selanjutnya di halaman ini.
Setelah menerapkan fitur, Anda dapat mengizinkan pengguna akhir mencoba fitur Anda di aplikasi sebenarnya.

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

Pastikan Anda menggunakan Chrome versi terbaru. Update di chrome://settings/help.
Inferensi di perangkat tersedia mulai Chrome v139 dan yang lebih baru.
Aktifkan model multimodal di perangkat dengan menyetel tanda berikut ke Enabled:
- chrome://flags/#prompt-api-for-gemini-nano-multimodal-input
Mulai ulang Chrome.
(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 Anda untuk inferensi di perangkat, permintaan akan otomatis memulai download model di latar belakang.

Catatan: Mendownload model dapat memakan waktu beberapa menit, jadi menunggu download otomatis dengan permintaan pertama dapat menunda penerimaan respons terhadap permintaan tersebut secara signifikan.
Lihat petunjuk untuk mendownload model di perangkat
1. Buka Developer Tools > Console.
2. Jalankan perintah berikut:
```
await LanguageModel.availability();
```
3. Pastikan outputnya 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 memantau progres download dan memastikan model 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

Login ke konsol Firebase, 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 Tambahkan Firebase ke project Google Cloud (di bagian bawah halaman). Pada langkah pertama alur kerja, mulai 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.
Di konsol Firebase, buka halaman Firebase AI Logic.
Klik Mulai untuk meluncurkan alur kerja terpandu yang membantu Anda menyiapkan API dan resource yang diperlukan untuk project Anda.
Siapkan project Anda untuk menggunakan penyedia "Gemini API".

Sebaiknya mulai menggunakan Gemini Developer API. Kapan saja, Anda dapat menyiapkan Vertex AI Gemini API (dan persyaratan penagihannya).

Untuk Gemini Developer API, konsol akan mengaktifkan API yang diperlukan dan membuat kunci API Gemini di project Anda.
Jangan menambahkan kunci API Gemini ini ke codebase aplikasi Anda. Pelajari lebih lanjut.
Jika diminta dalam alur kerja konsol, ikuti petunjuk di layar untuk mendaftarkan aplikasi dan menghubungkannya ke Firebase.
Lanjutkan ke langkah berikutnya dalam panduan ini untuk menambahkan SDK 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.

Instal Firebase JS SDK untuk Web menggunakan npm:
```
npm install firebase
```

Inisialisasi Firebase di aplikasi Anda:

import { initializeApp } from "firebase/app";

// 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: 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.

Lakukan inisialisasi layanan untuk penyedia API pilihan Anda.
Buat instance GenerativeModel. Pastikan untuk melakukan hal berikut:
1. Panggil getGenerativeModel setelah atau saat interaksi pengguna akhir (seperti klik tombol). Ini adalah prasyarat untuk inferenceMode.
2. Setel mode ke salah satu opsi berikut:
  - PREFER_ON_DEVICE: Gunakan model di perangkat jika tersedia; jika tidak, kembali ke 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, kembali ke model di perangkat.
  - ONLY_IN_CLOUD: Gunakan model yang dihosting di cloud jika tersedia; jika tidak, tampilkan pengecualian.
  Catatan: Untuk permintaan yang dikirim ke model di perangkat, pastikan permintaan tersebut didukung oleh inferensi di perangkat.
  Untuk permintaan yang dikirim dari luar perangkat, perangkat harus online. Selain itu, model yang dihosting di cloud secara default adalah gemini-2.5-flash-lite, tetapi Anda dapat mengganti model default.

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
// Call `getGenerativeModel` after or on an end-user interaction
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

Langkah 5: Kirim permintaan perintah ke model

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

Membuat teks dari input khusus teks
Membuat teks dari input teks dan gambar (multimodal)

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

Membuat teks dari input khusus teks

Sebelum mencoba contoh ini, pastikan Anda telah menyelesaikan bagian Mulai 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 Mulai dalam panduan ini.

Anda dapat menggunakan generateContent() untuk membuat teks 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 {
    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).

Memungkinkan pengguna akhir mencoba fitur Anda

Agar pengguna akhir dapat mencoba fitur Anda di aplikasi, Anda harus mendaftar ke Uji Coba Origin Chrome. Perhatikan bahwa uji coba ini memiliki durasi dan penggunaan yang terbatas.

Mendaftar ke Uji Coba Origin Chrome Prompt API. Anda akan diberi token.
Berikan token di setiap halaman web yang ingin Anda aktifkan fitur uji cobanya. Gunakan salah satu opsi berikut:
- Berikan token sebagai tag meta di tag <head>: <meta http-equiv="origin-trial" content="TOKEN">
- Berikan token sebagai header HTTP: Origin-Trial: TOKEN
- Berikan token secara terprogram.

Kamu bisa apa lagi?

Di bagian ini, pelajari cara menetapkan mode inferensi, mengganti model penggantian yang dihosting di cloud secara default, dan menggunakan konfigurasi model untuk mengontrol respons (seperti membuat output terstruktur).

Menetapkan mode inferensi

Contoh dalam penyiapan umum menggunakan mode PREFER_ON_DEVICE, tetapi ini hanyalah salah satu dari empat mode inferensi yang tersedia.

PREFER_ON_DEVICE: Gunakan model di perangkat jika tersedia; jika tidak, kembali ke model yang dihosting di cloud.
```
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });
```
ONLY_ON_DEVICE: Gunakan model di perangkat jika tersedia; jika tidak, tampilkan pengecualian.
```
const model = getGenerativeModel(ai, { mode: InferenceMode.ONLY_ON_DEVICE });
```
PREFER_IN_CLOUD: Gunakan model yang dihosting di cloud jika tersedia; jika tidak, kembali ke model di perangkat.
```
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_IN_CLOUD });
```
ONLY_IN_CLOUD: Gunakan model yang dihosting di cloud jika tersedia; jika tidak, tampilkan pengecualian.
```
const model = getGenerativeModel(ai, { mode: InferenceMode.ONLY_IN_CLOUD });
```

Menentukan apakah inferensi di perangkat atau di cloud digunakan

Jika Anda menggunakan mode inferensi PREFER_ON_DEVICE atau PREFER_IN_CLOUD, mungkin akan berguna untuk mengetahui mode mana yang digunakan untuk permintaan tertentu. Informasi ini diberikan oleh properti inferenceSource dari setiap respons (tersedia mulai JS SDK v12.5.0).

Saat Anda mengakses properti ini, nilai yang ditampilkan akan berupa ON_DEVICE atau IN_CLOUD.

// ...

console.log('You used: ' + result.response.inferenceSource);

console.log(result.response.text());

Mengganti model penggantian default

Model yang dihosting di cloud secara default adalah gemini-2.5-flash-lite (mulai dengan JS SDK v12.8.0).

Model ini adalah model yang dihosting di cloud penggantian saat Anda menggunakan mode PREFER_ON_DEVICE. Model ini juga merupakan model default saat Anda menggunakan mode ONLY_IN_CLOUD atau mode PREFER_IN_CLOUD.

Anda dapat menggunakan opsi konfigurasi inCloudParams untuk menentukan model default alternatif yang dihosting di cloud.

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  inCloudParams: {
    model: "GEMINI_MODEL_NAME"
  }
});

Temukan nama model untuk semua model Gemini yang didukung.

Menggunakan konfigurasi model untuk mengontrol respons

Dalam setiap permintaan ke model, Anda dapat mengirimkan konfigurasi model untuk mengontrol cara model menghasilkan respons. Model yang dihosting di cloud dan model di perangkat menawarkan opsi konfigurasi yang berbeda.

Konfigurasi dipertahankan selama masa aktif instance. Jika Anda ingin menggunakan konfigurasi yang berbeda, buat instance GenerativeModel baru dengan konfigurasi tersebut.

Menetapkan konfigurasi untuk model yang di-hosting di cloud

Gunakan opsi inCloudParams untuk mengonfigurasi model Gemini yang di-hosting di cloud. Pelajari parameter yang tersedia.

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  inCloudParams: {
    model: "GEMINI_MODEL_NAME"
    temperature: 0.8,
    topK: 10
  }
});

Menetapkan konfigurasi untuk model di perangkat

Perhatikan bahwa inferensi menggunakan model di perangkat menggunakan Prompt API dari Chrome.

Gunakan opsi onDeviceParams untuk mengonfigurasi model di perangkat. Pelajari parameter yang tersedia.

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  onDeviceParams: {
    createOptions: {
      temperature: 0.8,
      topK: 8
    }
  }
});

Menetapkan konfigurasi untuk output terstruktur (seperti JSON)

Pembuatan output terstruktur (seperti JSON dan enum) didukung untuk inferensi menggunakan model yang dihosting di cloud dan di perangkat.

Untuk inferensi campuran, gunakan inCloudParams dan onDeviceParams untuk mengonfigurasi model agar merespons dengan output terstruktur. Untuk mode lainnya, gunakan hanya konfigurasi yang berlaku.

Untuk inCloudParams: Tentukan responseMimeType yang sesuai (dalam contoh ini, application/json) serta responseSchema yang Anda inginkan untuk digunakan model.
Untuk onDeviceParams: Tentukan responseConstraint yang Anda inginkan untuk digunakan model.

Output JSON

Contoh berikut mengadaptasi contoh output JSON umum untuk inferensi hybrid:

import {
  getAI,
  getGenerativeModel,
  Schema
} from "firebase/ai";

const jsonSchema = Schema.object({
 properties: {
    characters: Schema.array({
      items: Schema.object({
        properties: {
          name: Schema.string(),
          accessory: Schema.string(),
          age: Schema.number(),
          species: Schema.string(),
        },
        optionalProperties: ["accessory"],
      }),
    }),
  }
});

const model = getGenerativeModel(ai, {
  mode: InferenceMode.INFERENCE_MODE,
  inCloudParams: {
    model: "gemini-2.5-flash"
    generationConfig: {
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});

Output enum

Seperti di atas, tetapi menyesuaikan dokumentasi tentang output enum untuk inferensi hybrid:

// ...

const enumSchema = Schema.enumString({
  enum: ["drama", "comedy", "documentary"],
});

const model = getGenerativeModel(ai, {

// ...

    generationConfig: {
      responseMimeType: "text/x.enum",
      responseSchema: enumSchema
    },

// ...
});

// ...

Fitur yang belum tersedia untuk inferensi di perangkat

Sebagai rilis eksperimental, 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 melakukan penggantian ke model yang di-hosting di cloud; namun, mode ONLY_ON_DEVICE akan memunculkan error.
Membuat teks dari input audio, video, dan dokumen (seperti PDF)
- Dapat melakukan penggantian ke model yang di-hosting di cloud; namun, mode ONLY_ON_DEVICE akan memunculkan error.
Membuat gambar menggunakan model Gemini atau Imagen
- Dapat melakukan penggantian ke model yang di-hosting di cloud; namun, mode ONLY_ON_DEVICE akan memunculkan error.
Menyediakan file menggunakan URL dalam permintaan multimodal. Anda harus menyediakan file sebagai data inline untuk model di perangkat.
Multi-turn chat
- Dapat melakukan penggantian ke model yang di-hosting di cloud; namun, mode ONLY_ON_DEVICE akan memunculkan error.
Streaming dua arah dengan Gemini Live API
Memberi model alat untuk membantunya membuat respons (seperti panggilan fungsi, eksekusi kode, konteks URL, dan perujukan dengan Google Penelusuran)
Menjumlahkan 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 konsol Firebase untuk inferensi di perangkat.
- Perhatikan bahwa inferensi apa pun yang menggunakan model yang dihosting di cloud dapat dipantau seperti inferensi lainnya yang menggunakan SDK klien Firebase AI Logic untuk Web.

Memberikan masukan tentang pengalaman Anda menggunakan Firebase AI Logic