Cihaz üzerinde ve bulutta barındırılan modellerle web uygulamalarında karma deneyimler oluşturma

Firebase AI Logic kullanarak hibrit çıkarımla yapay zeka destekli web uygulamaları ve özellikleri oluşturun. Hibrit çıkarım, cihaz üzerinde modeller kullanılabildiğinde çıkarım çalıştırmayı ve aksi takdirde (veya tam tersi) bulutta barındırılan modellere sorunsuz bir şekilde geri dönmeyi sağlar.

Bu sayfada, istemci SDK'sını kullanmaya başlama hakkında bilgi verilmektedir. Bu standart kurulumu tamamladıktan sonra ek yapılandırma seçeneklerini ve özellikleri (ör. yapılandırılmış çıkış) inceleyin.

Cihaz üzerinde çıkarımın masaüstünde Chrome'da çalışan web uygulamaları için desteklendiğini unutmayın.

Kod örneklerine git

Önerilen kullanım alanları ve desteklenen özellikler

Önerilen kullanım alanları:

  • Çıkarım için cihaz üzerinde bir model kullanmanın avantajları:

    • Gelişmiş gizlilik
    • Local Context
    • Ücretsiz çıkarım
    • Çevrimdışı işlevler

  • Karma işlevsellik tekliflerini kullanma:

    • Cihaz üzerinde model kullanılabilirliğinden veya internet bağlantısından bağımsız olarak kitlenizin% 100'üne ulaşın

Cihaz üzerinde çıkarım için desteklenen özellikler:

Cihaz üzerinde çıkarım yalnızca akışlı veya akışsız çıkışla tek dönüşlü metin oluşturmayı (sohbet değil) destekler. Aşağıdaki metin oluşturma özelliklerini destekler:

Ayrıca, JSON ve enums dahil olmak üzere yapılandırılmış çıkış oluşturabilirsiniz.

Başlamadan önce

Aşağıdakileri göz önünde bulundurun:

  • Cihaz üzerinde model kullanılarak çıkarım yapılırken Chrome'daki istem API'si kullanılır. Bulutta barındırılan model kullanılarak çıkarım yapılırken ise seçtiğiniz Gemini API sağlayıcı (Gemini Developer API veya Agent Platform Gemini API (formerly Vertex AI)) kullanılır.

  • Bu sayfada, localhost kullanarak geliştirmeye başlama (Chrome belgelerinde localhost'ta API kullanma hakkında daha fazla bilgi edinin) açıklanmaktadır.

    Bu standart kurulumu tamamladıktan sonra ek yapılandırma seçeneklerini ve özellikleri (ör. yapılandırılmış çıkış) inceleyin.

localhost'ta kullanmaya başlama

Bu başlangıç adımlarında, göndermek istediğiniz desteklenen tüm istem istekleri için gerekli olan genel kurulum açıklanmaktadır.

1. adım: Cihaz üzerinde çıkarım için Chrome'u ve Prompt API'yi ayarlayın

  1. Chrome'un güncel bir sürümünü kullandığınızdan emin olun. chrome://settings/help adresinden güncelleyin.
    Cihaz üzerinde çıkarım, Chrome 139 ve sonraki sürümlerde kullanılabilir.

  2. Aşağıdaki işareti Enabled olarak ayarlayarak cihaz üzerindeki çok formatlı modeli etkinleştirin:

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

  3. Chrome'u yeniden başlatın.

  4. (İsteğe bağlı) İlk istekten önce cihaz üzerinde modeli indirin.

    Prompt API, Chrome'a yerleşiktir ancak cihaz üzerinde model varsayılan olarak kullanılamaz. Cihaz üzerinde çıkarım için ilk isteğinizi göndermeden önce modeli henüz indirmediyseniz istek, model indirme işlemini arka planda otomatik olarak başlatır.

2. adım: Firebase projesi oluşturma ve uygulamanızı Firebase'e bağlama

  1. Firebase konsolunda oturum açın, ardından Firebase projenizi seçin.

  2. Firebase konsolunda AI Services > AI Logic'e gidin.

  3. Projeniz için gerekli API'leri ve kaynakları ayarlamanıza yardımcı olan rehberli bir iş akışı başlatmak için Başlayın'ı tıklayın.

  4. İstenirse uygulamanızı kaydetmek ve Firebase yapılandırmanızı uygulamanıza eklemek için ekrandaki talimatları uygulayın.

  5. "Gemini API sağlayıcısı" seçmeniz istendiğinde, ücretsiz olarak hızlıca başlamanıza olanak tanıyan Gemini Developer API'yi seçmenizi öneririz.

    Daha sonra istediğiniz zaman Agent Platform Gemini API (formerly Vertex AI)'ı ayarlayabilirsiniz (ve faturalandırma için gerekli olan bilgileri girebilirsiniz).

  6. Firebase AI Logic için gerekli API'leri ve ilişkili hizmetleri ayarlamak üzere iş akışına devam edin.

    Temmuz 2026'nın başlarından itibaren iş akışının bu aşamasında, uygulamanıza doğrudan erişildiğinde Gemini API'ı korumaya yardımcı olan kritik bir hizmet olan AI Logic için otomatik olarak Firebase App Check uygulanacak. Başlarken (bu kılavuzun ilerleyen bölümlerindeki adımlara bakın) App Check uygulandığında yerel geliştirme için App Check hata ayıklama sağlayıcısını yapılandırmanız gerekir.

  7. Gerekli SDK'ları uygulamanıza eklemek için bu kılavuzdaki sonraki adıma geçin.

3. adım: SDK'yı ekleyin

Firebase kitaplığı, üretken modellerle etkileşim kurmak için API'lere erişim sağlar. Kitaplık, web için Firebase JavaScript SDK'sının bir parçası olarak dahil edilir.

  1. npm kullanarak web için Firebase JS SDK'sını yükleyin:

    npm install firebase

  2. Uygulamanızda Firebase'i başlatın:

    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);

4. adım: Yerel geliştirme için App Check hata ayıklama sağlayıcısını yapılandırın

Temmuz 2026'nın başlarından itibaren, konsolda AI Logic için rehberli kurulum iş akışının bir parçası olarak Firebase App Check, Gemini API'yi korumak için otomatik olarak zorunlu kılınacak. Yerel geliştirme için, App Check yaptırımını sürdürürken onaylamayı atlamak üzere App Check hata ayıklama sağlayıcısını yapılandırmanız gerekir.

uygulayın.

Uygulamanızı localhost etkileşimli olarak (ör. yerel geliştirme sırasında) çalıştırırken hata ayıklama sağlayıcısını kullanmak için aşağıdaki adımları uygulayın:

  1. Hata ayıklama derlemenizde, App Check öğesini başlatmadan önce self.FIREBASE_APPCHECK_DEBUG_TOKEN öğesini true olarak ayarlayarak hata ayıklama modunu etkinleştirin. Örneğin:

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

  2. Web uygulamanızı yerel olarak ziyaret edin ve tarayıcının geliştirici araçlarını açın. Hata ayıklama konsolunda bir hata ayıklama jetonu görürsünüz:

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

  3. Hata ayıklama jetonunuzu App Check ile kaydedin:

    1. Firebase konsolunda Güvenlik > Uygulama Kontrolü > Uygulamalar sekmesine gidin.

    2. Uygulamanızı bulun, taşma menüsünü () tıklayın ve Hata ayıklama jetonlarını yönet'i seçin.

    3. Hata ayıklama jetonunuzu kaydetmek için ekrandaki talimatları uygulayın.

Hata ayıklama sağlayıcısı hakkında ayrıntılı bilgi (yeni hata ayıklama jetonu edinme dahil) için resmi App Check belgeleri inceleyin.

5. adım: Hizmeti ilk kullanıma hazırlayın ve model örneği oluşturun

Bu sayfada sağlayıcıya özel içerikleri ve kodu görüntülemek için Gemini API sağlayıcınızı tıklayın.

Modele istem isteği göndermeden önce aşağıdakileri ayarlayın:

  1. Seçtiğiniz API sağlayıcısı için hizmeti başlatın.

  2. GenerativeModel örneği oluşturun. mode özelliğini aşağıdakilerden birine ayarladığınızdan emin olun:

    • PREFER_ON_DEVICE: Cihaz üzerinde model varsa onu kullanın. Aksi takdirde, bulutta barındırılan modele geri dönün.

    • ONLY_ON_DEVICE: Kullanılabiliyorsa cihaz üzerinde modeli kullanın; aksi takdirde istisna oluşturun.

    • PREFER_IN_CLOUD: Bulutta barındırılan model varsa onu kullanın. Aksi takdirde cihaz üzerindeki modele geri dönün.

    • ONLY_IN_CLOUD: Bulutta barındırılan model varsa onu kullanın; aksi takdirde istisna oluşturun.

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 });

6. adım: Cihaz üzerinde modeli başlatın

initializeDeviceModel() işlevini, bir son kullanıcı sayfası etkileşiminden (ör. düğme tıklama) sonra veya bu etkileşim sırasında ve modele bir istem isteği göndermeden önce çağırmanız gerekir. Chrome dokümanlarında kullanıcı etkinleştirme şartı hakkında daha fazla bilgi edinin.

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}%`)
);

7. adım: Bir modele istem isteği gönderin

Bu bölümde, aşağıdakiler de dahil olmak üzere farklı türlerde çıkışlar oluşturmak için çeşitli giriş türlerini nasıl göndereceğiniz gösterilmektedir:

Yapılandırılmış çıkış (ör. JSON veya numaralandırmalar) oluşturmak istiyorsanız aşağıdaki "metin oluştur" örneklerinden birini kullanın ve ek olarak modeli, sağlanan şemaya göre yanıt verecek şekilde yapılandırın.

Yalnızca metin içeren girişlerden metin oluşturma

Bu örneği denemeden önce bu kılavuzun Başlarken bölümünü tamamladığınızdan emin olun.

Metin içeren bir istemden metin oluşturmak için generateContent() kullanabilirsiniz:

// 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();

Firebase AI Logic'nın, generateContentStream kullanarak metin yanıtlarının akışını da desteklediğini unutmayın (generateContent yerine).

Metin ve resim (çok formatlı) girişinden metin oluşturma

Bu örneği denemeden önce bu kılavuzun Başlarken bölümünü tamamladığınızdan emin olun.

Metin ve resim dosyaları içeren bir istemden metin oluşturmak için generateContent() kullanabilirsiniz. Her giriş dosyasının mimeType ve dosyanın kendisi sağlanır.

Cihaz üzerinde çıkarım için desteklenen giriş resmi türleri PNG ve JPEG'dir.

// 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();

Firebase AI Logic'nın, generateContentStream kullanarak metin yanıtlarının akışını da desteklediğini unutmayın (generateContent yerine).

Başka ne yapabilirsiniz?

Hibrit deneyimleriniz için çeşitli ek yapılandırma seçenekleri ve özelliklerinden yararlanabilirsiniz:

Cihaz üzerinde çıkarım için henüz kullanılamayan özellikler

Web SDK'sının tüm özellikleri cihaz üzerinde çıkarım için kullanılamaz. Aşağıdaki özellikler cihaz üzerinde çıkarım için henüz desteklenmemektedir (ancak genellikle bulut tabanlı çıkarım için kullanılabilirler).

  • JPEG ve PNG dışındaki resim dosyası giriş türlerinden oluşturulan metin

    • Bulutta barındırılan modele geri dönebilir ancak ONLY_ON_DEVICE modunda hata oluşur.

  • Ses, video ve doküman (ör. PDF) girişlerinden metin oluşturma

    • Bulutta barındırılan modele geri dönebilir ancak ONLY_ON_DEVICE modunda hata oluşur.

  • Gemini modellerini kullanarak resim oluşturma

    • Bulutta barındırılan modele geri dönebilir ancak ONLY_ON_DEVICE modunda hata oluşur.

  • Çok formatlı isteklerde URL'ler kullanarak dosya sağlama. Dosyaları cihaz üzerinde modellere satır içi veri olarak sağlamanız gerekir.

  • Çok adımlı sohbet

    • Bulutta barındırılan modele geri dönebilir ancak ONLY_ON_DEVICE modunda hata oluşur.

  • Gemini Live API ile çift yönlü yayın

  • Modelin yanıtını oluşturmasına yardımcı olması için araçlar sağlama (ör. işlev çağırma, kod yürütme, URL bağlamı, Google Search ile temellendirme ve Google Maps ile temellendirme)

  • Parça sayma

    • Her zaman hata verir. Sayım, bulutta barındırılan ve cihaz üzerinde modeller arasında farklılık gösterir. Bu nedenle, sezgisel bir geri dönüş yoktur.

  • Cihaz üzerinde çıkarım için Firebase konsolunda yapay zeka kullanım takibi.

    • Bulutta barındırılan modeller kullanılarak yapılan tüm çıkarımların, Firebase AI Logic web için istemci SDK'sı kullanılarak yapılan diğer çıkarımlar gibi izlenebileceğini unutmayın.


Firebase AI Logic ile ilgili deneyiminiz hakkında geri bildirim verme