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

Firebase AI Logic kullanarak karma çıkarım ile yapay zeka destekli web uygulamaları ve özellikleri oluşturabilirsiniz. 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 özelliklere göz atın.

Firebase AI Logic üzerinden cihaz üzerinde çıkarım, Firebase AI Logic SDK 12.5.0 ve sonraki sürümlerini kullanan ve masaüstünde Chrome'da (139 veya sonraki sürümler) çalışan web uygulamaları için desteklenir.

Kod örneklerini görüntülemek için atlayın

Kullanım alanları ve desteklenen özellikler

Uygulamanızın kullanım alanlarına bağlı olarak cihaz üzerinde veya karma deneyimlerin çeşitli avantajlarından yararlanabilirsiniz:

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

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

  • Karma yaklaşım kullanmanın avantajları:

    • Son kullanıcının cihazından bağımsız olarak benzer bir uygulama deneyimi sunma
    • İnternet bağlantısı, kota sınırlamaları veya cihaz özelliklerinden bağımsız olarak üretken yapay zeka özelliklerinin kullanılabilirliğini artırma

Desteklenen cihaz üzerinde çıkarım özellikleri

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

Bu sayfanın alt kısmında yer alan karma veya cihaz üzerinde çıkarım için henüz desteklenmeyen özellikler listesini inceleyin.

Desteklenen API'ler ve platformlar

Aşağıdaki bölümlerde, desteklenen API'lerin yanı sıra desteklenen platformlar ve tarayıcılar açıklanmaktadır.

Bulutta ve cihaz üzerinde çıkarım için desteklenen API'ler

  • Bulutta çıkarım, seçtiğiniz Gemini API sağlayıcısını (Gemini Developer API veya Agent Platform Gemini API (formerly Vertex AI)) kullanır.

  • Cihaz üzerinde çıkarım, Chrome'un Prompt API'sini kullanır.

Desteklenen platformlar ve tarayıcılar

Cihaz üzerinde çıkarım (Chrome'daki Prompt API'yi kullanır) için uygulamanızın son kullanıcısının masaüstünde Chrome (139 veya sonraki sürüm) kullanması gerekir. Chrome belgelerinde daha fazla bilgi edinebilirsiniz.

Localhost'u kullanmaya başlama

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

Localhost'ta API'leri kullanma hakkında daha fazla bilgiyi Chrome belgelerinde bulabilirsiniz.

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, uygulamanızdan doğrudan erişildiğinde Gemini API'i 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 yaptırımı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. Aksi takdirde 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 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() yöntemini kullanabilirsiniz. Bu yöntemde her giriş dosyasının mimeType değerini ve dosyanın kendisini sağlamanız gerekir.

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?

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

Henüz desteklenmeyen özellikler

Web SDK'sının veya bulutta barındırılan modellerin tüm özellikleri karma ya da cihaz üzerinde çıkarım için kullanılamaz.

Karma uygulamalar için henüz desteklenmeyen özellikler

Aşağıdaki özellikler, karma uygulamalarla (cihaz üzerinde veya bulut yedekleme aracılığıyla) kullanılamaz:

  • Gemini Live API: Çift yönlü gerçek zamanlı akış desteklenmez.

  • Sunucu istem şablonları: Yönetilen sunucu istem şablonları desteklenmez.

  • Jetonları sayma: Jeton sayısı, bulutta barındırılan ve cihaz üzerinde çalışan modeller arasında farklılık göstereceğinden jeton sayısına güvenilmemelidir. Bu nedenle, sezgisel bir yedek yoktur.

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

Aşağıdaki özellikler cihaz üzerinde çıkarım için henüz desteklenmemektedir ancak bulutta barındırılan modellerde kullanılabilir.

  • Gemini Nano Banana modelleri kullanılarak resim üretme

    • Bulutta barındırılan modele geri dönebilir ancak ONLY_ON_DEVICE modu hata verir.

  • 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 modu hata verir.

  • Ses, video ve doküman (PDF) gibi çok formatlı girişlerden oluşturulan metin

    • Bulutta barındırılan modele geri dönebilir 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 geri dönebilir ancak ONLY_ON_DEVICE modu hata verir.

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

  • Firebase konsolundaki yapay zeka kullanım takibi, cihaz üzerinde çıkarım (cihaz günlükleri dahil) ile ilgili verileri göstermez. Ancak bulutta barındırılan bir model kullanan tüm çıkarımlar, diğer çıkarımlar gibi Firebase AI Logic üzerinden izlenebilir.

Ek sınırlamalar

Yukarıdakilere ek olarak, cihaz üzerinde çıkarım aşağıdaki sınırlamalara sahiptir:

  • Uygulamanızın son kullanıcısı, gerekli işaretler etkinleştirilmiş şekilde masaüstünde Chrome (sürüm 139 veya daha yeni) kullanıyor olmalıdır.

  • Cihaz üzerinde model, ilk model indirme işlemi için kullanıcının cihazında yeterli depolama alanı gerektirir.


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