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

Firebase AI Logic kullanarak hibrit çıkarım ile yapay zeka destekli web uygulamaları ve özellikleri oluşturun. Karma çıkarım, varsa cihaz üzerinde modelleri kullanarak çıkarım yapmaya ve aksi takdirde bulutta barındırılan modellere sorunsuz bir şekilde geri dönmeye (veya tam tersi) olanak tanır.

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

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 teklifleri için cihaz üzerinde model kullanma:

  • Gelişmiş gizlilik
  • Yerel bağlam
  • Ücretsiz çıkarım
  • Çevrimdışı işlevler

• Karma işlev tekliflerini kullanma:

  • Cihaz modeli 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:

• Yalnızca metin içeren girişten metin oluşturma

• Metin ve resim girişinden metin oluşturma (özellikle JPEG ve PNG giriş resim türleri)

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 Prompt API 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 Vertex AI Gemini API) kullanılır.

• Bu sayfada, localhost kullanarak geliştirmeye nasıl başlayacağınız açıklanmaktadır (Chrome dokümanlarında localhost'ta API kullanma hakkında daha fazla bilgi edinin).

  Bu standart kurulumu tamamladıktan sonra ek yapılandırma seçeneklerine ve özelliklere (ör. yapılandırılmış çıkış) göz atın.

• Özelliğinizi uyguladıktan sonra, gerçek uygulamanızda son kullanıcıların özelliğinizi denemesine olanak tanıyabilirsiniz.

localhost'ta çalışmaya 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 Etkin 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.

   İstem API'si Chrome'a yerleştirilmiştir 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, modelin arka planda indirilmesini otomatik olarak başlatır.

   Cihaz üzerinde modeli indirme talimatlarını görüntüleme

   1. Geliştirici Araçları > Konsol'u açın.

   2. Aşağıdaki komutu çalıştırın:

      await LanguageModel.availability();
      

   3. Çıkışın available, downloading veya downloadable olduğundan emin olun.

   4. Çıkış downloadable ise şu komutu çalıştırarak model indirme işlemini başlatın:

      await LanguageModel.create();
      

   5. İndirme ilerleme durumunu dinlemek ve istekte bulunmadan önce modelin available olduğundan emin olmak için aşağıdaki monitor geri çağırmayı kullanabilirsiniz:

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

2. adım: Firebase projesi oluşturun ve uygulamanızı Firebase'e bağlayın

1. Firebase konsolunda oturum açın ve Firebase projenizi seçin.

   Henüz bir Firebase projeniz yok mu?

   Henüz bir Firebase projeniz yoksa düğmeyi tıklayarak yeni bir Firebase projesi oluşturun ve ardından aşağıdaki seçeneklerden birini kullanın:

   • 1. seçenek: İş akışının ilk adımında yeni bir proje adı girerek tamamen yeni bir Firebase projesi (ve temelindeki Google Cloud projesi) otomatik olarak oluşturun.

   • 2. seçenek: Google Cloud projesine "Firebase eklemek" için Firebase'i Google Cloud projesine ekle'yi (sayfanın alt kısmında) tıklayın. İş akışının ilk adımında, mevcut projenin proje adını girmeye başlayın ve ardından görüntülenen listeden projeyi seçin.

   Firebase projesi oluşturmak için ekrandaki iş akışının kalan adımlarını tamamlayın. İstendiğinde Firebase AI Logic SDK'larını kullanmak için kurulum yapmanız gerekmediğini unutmayın.Google Analytics

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

3. Projeniz için gerekli API'leri ve kaynakları ayarlamanıza yardımcı olacak 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 Vertex AI Gemini API'ı (ve faturalandırma şartını) ayarlayabilirsiniz.

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, AI Logic için otomatik olarak Firebase App Check zorunlu kılınacak. Bu, Gemini API doğrudan uygulamanızdan erişildiğinde korunmasına yardımcı olan kritik bir hizmettir. Başlangıç sürecinin bir parçası olarak (bu kılavuzun ilerleyen bölümlerindeki adımlara bakın), App Check zorunlu kılındığı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, DebugProvider } 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);
   

3. 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'nın zorunlu kılınmasını sürdürürken onaylamayı atlamak üzere App Check hata ayıklama sağlayıcısını yapılandırmanız gerekir.

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:

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

   self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
   initializeAppCheck(app, { /* 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 > App Check > Uygulamalar sekmesine gidin.

   2. Uygulamanızı bulun, taşma menüsünü (more_vert) 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 bir hata ayıklama jetonunun nasıl alınacağı dahil) için resmi App Check belgelerini inceleyin.

4. adım: Hizmeti başlatın ve model örneği oluşturun

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 değerini aşağıdakilerden birine ayarladığınızdan emin olun:

   • PREFER_ON_DEVICE: Cihazdaki model varsa onu kullanın; yoksa bulutta barındırılan modele geri dönün.

   • ONLY_ON_DEVICE: Varsa cihazdaki modeli kullanın; aksi takdirde istisna oluşturun.

   • PREFER_IN_CLOUD: Varsa bulutta barındırılan modeli kullanın; aksi takdirde cihazdaki modele geri dönün.

   • ONLY_IN_CLOUD: Varsa bulut tabanlı modeli kullanın; aksi takdirde bir 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 });

5. 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ından 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}%`)
);

6. adım: Bir modele istem isteği gönderme

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:

• Yalnızca metin içeren girişlerden metin oluşturma
• Metin ve resim (çok formatlı) girişinden metin oluşturma

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

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 (generateContent yerine) kullanarak metin yanıtlarının aktarılmasını da desteklediğini unutmayın.

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

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 (generateContent yerine) kullanarak metin yanıtlarının aktarılmasını da desteklediğini unutmayın.

Son kullanıcıların özelliğinizi denemesine olanak tanıma

Son kullanıcıların uygulamanızdaki özelliğinizi denemesi için Chrome Origin Trials'a kaydolmanız gerekir. Bu denemelerin sınırlı bir süre ve kullanım için geçerli olduğunu unutmayın.

1. Prompt API Chrome kaynak denemesine kaydolun. Size bir jeton verilir.

2. Deneme özelliğinin etkinleştirilmesini istediğiniz her web sayfasında jetonu sağlayın. Aşağıdaki seçeneklerden birini kullanın:

   • Jetonu <head> etiketinde meta etiketi olarak sağlayın: <meta http-equiv="origin-trial" content="TOKEN">

   • Jetonu HTTP üst bilgisi olarak sağlayın: Origin-Trial: TOKEN

   • Jetonu programatik olarak sağlayın.

Başka ne yapabilirsin?

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

• Çıkarım modu ayarlama

• Varsayılan bulutta barındırılan yedek modeli geçersiz kılma

• Yanıtları kontrol etmek için model yapılandırmasını kullanma (ör. sıcaklık)

• Yapılandırılmış çıkış (ör. JSON) oluşturma

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

Önizleme sürümü olduğundan Web SDK'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ılabilir).

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

  • 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 veya Imagen 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 üzerindeki 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

• Modele yanıtını oluşturmasına yardımcı olacak 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 veriyor. 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 izleme.

  • Bulutta barındırılan modeller kullanılarak yapılan tüm çıkarımların, Firebase AI Logic 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