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

Firebase AI Logic ile hibrit çıkarım kullanarak yapay zeka destekli web uygulamaları ve özellikleri oluşturun. Karma çıkarım, mümkün olduğunda cihaz üzerinde modelleri kullanarak çıkarım yapmanıza ve aksi takdirde bulutta barındırılan modellere sorunsuz bir şekilde geçiş yapmanıza (veya tam tersi) olanak tanır.

Bu sayfada, istemci SDK'sını kullanmaya nasıl başlayacağınız açıklanmaktadır. Bu standart kurulumu tamamladıktan sonra ek yapılandırma seçeneklerine ve özelliklerine (ör. yapılandırılmış çıkış) göz atın.

Cihaz üzerinde çıkarım, Masaüstü için Chrome'da çalışan web uygulamalarında desteklenir.

Kod örneklerine git

Önerilen kullanım alanları ve desteklenen özellikler

Önerilen kullanım alanları:

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

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

  • Karma işlevsellik sunan teklifleri kullanma:

    • Cihaz üzerinde model kullanılabilirliği veya internet bağlantısı fark etmeksizin kitlenizin% 100'üne ulaşın.

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

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

JSON ve enum'lar dahil olmak üzere yapılandırılmış çıkış da oluşturabilirsiniz.

Başlamadan önce

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

  • Cihaz üzerinde model kullanılarak yapılan çıkarım, Chrome'un Prompt API'sini kullanır. Bulutta barındırılan model kullanılarak yapılan çıkarım ise seçtiğiniz Gemini API sağlayıcısını (Gemini Developer API veya Agent Platform Gemini API (formerly Vertex AI)) kullanır.

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

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

Localhost'u kullanmaya başlama

Bu başlangıç adımları, göndermek istediğiniz desteklenen istem istekleri için gereken genel kurulumu açıklar.

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 sayfasında 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 üzerinde ç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'da yerleşik olarak bulunur ancak cihaz üzerinde model varsayılan olarak kullanılamaz. Cihaz üzerinde çıkarım için ilk isteğinizden önce modeli henüz indirmediyseniz istek, arka planda model indirme işlemini otomatik olarak başlatır.

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.

  2. Firebase konsolunda AI Services (Yapay Zeka Hizmetleri) > AI Logic (Yapay Zeka Mantığı) bölümüne gidin.

  3. Projeniz için gerekli API'leri ve kaynakları ayarlamanıza yardımcı olan rehberli bir iş akışını 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ızı sağlayan Gemini Developer API'yi seçmenizi öneririz.

    Daha sonra dilediğiniz zaman Agent Platform Gemini API (formerly Vertex AI)'i (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.

    İş akışının bu aşaması, AI Logic için Firebase App Check'i otomatik olarak uygular. Bu, doğrudan uygulamanızdan erişildiğinde Gemini API korumaya yardımcı olan kritik bir hizmettir. Başlangıç kapsamında (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 bir 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ına dahildir.

  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

Konsolda AI Logic için sunulan rehberli kurulum iş akışı kapsamında, Gemini API korumak için Firebase App Check otomatik olarak uygulanır. Yerel geliştirme için App Check'un zorunlu kılınmasını sürdürürken onayı atlamak üzere App Check hata ayıklama sağlayıcısını yapılandırmanız gerekir.

Uygulamanızı localhost üzerinden etkileşimli olarak çalıştırırken (ör. yerel geliştirme sırasında) hata ayıklama sağlayıcısını nasıl kullanacağınızı aşağıda bulabilirsiniz:

  1. Hata ayıklama derlemenizde, App Check başlatılmadan ö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(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 Security (Güvenlik) > App Check (Uygulama Kontrolü) > Apps (Uygulamalar) sekmesine gidin.

    2. Uygulamanızı bulun, taşma menüsünü () tıklayın ve ardından 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 belgelerine göz atın.

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

Bu sayfada sağlayıcıya özel içerikleri ve kodları 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 değerini aşağıdakilerden birine ayarladığınızdan emin olun:

    • PREFER_ON_DEVICE: Varsa cihaz üzerinde modeli kullanın. Yoksa bulutta barındırılan modele geçin.

    • ONLY_ON_DEVICE: Varsa cihaz üzerinde modeli kullanın. Aksi takdirde istisna oluşturun.

    • PREFER_IN_CLOUD: Varsa bulutta barındırılan modeli kullanın. Aksi takdirde cihaz üzerinde çalışan modele geçin.

    • ONLY_IN_CLOUD: Varsa bulutta barındırılan modeli 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() yöntemini, son kullanıcı sayfa etkileşiminden (ör. düğme tıklaması) sonra veya bu etkileşim sırasında ve modele istem isteği göndermeden önce çağırmanız gerekir. Chrome belgelerinde 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önderme

Bu bölümde, farklı çıkış türleri oluşturmak için çeşitli giriş türlerini nasıl göndereceğiniz gösterilmektedir. Örneğin:

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

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

Bu örneği denemeden önce bu kılavuzun Başlangıç 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, generateContent yerine generateContentStream kullanarak metin yanıtlarının akışını da destekler.

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

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

Metin ve resim dosyaları içeren bir istemden metin oluşturmak için generateContent() işlevini kullanabilirsiniz. Bu işlev, her giriş dosyasının mimeType değerini ve dosyanın kendisini sağlar.

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

Firebase AI Logic, generateContent yerine generateContentStream kullanarak metin yanıtlarının akışını da destekler.

Başka ne yapabilirsin?

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

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ılabilir).

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

    • Bulutta barındırılan modele geçebilir ancak ONLY_ON_DEVICE modu hata verir.

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

    • Bulutta barındırılan modele yedek olarak kullanılabilir ancak ONLY_ON_DEVICE modu hata verir.

  • Gemini Nano Banana modellerini kullanarak resim oluşturma

    • Bulutta barındırılan modele geçebilir ancak ONLY_ON_DEVICE modu hata verir.

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

  • Çok adımlı sohbet

    • Bulutta barındırılan modele geçebilir ancak ONLY_ON_DEVICE modu hata verir.

  • Gemini Live API ile çift yönlü akış

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

  • Parça sayma

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

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

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


Firebase AI Logic ile ilgili deneyiminiz hakkında geri bildirimde bulunun