Cihaz üzerinde ve bulutta barındırılan modellerle karma deneyimler oluşturun

Firebase AI Logic kullanarak hibrit çıkarım ile yapay zeka destekli web uygulamaları ve özellikleri oluşturun. Karma çıkarım, varsa cihazdaki 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 ve yapılandırılmış çıkış gibi ek yapılandırma seçenekleri ve özellikler gösterilmektedir.

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 kullanmanın avantajları:

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

• Tek dönüşlü içerik oluşturma, akış ve akış dışı
• 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)
• JSON ve numaralandırmalar dahil olmak üzere yapılandırılmış çıkış oluşturma

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). Ayrıca, bu sayfanın ilerleyen bölümlerinde ek yapılandırma seçenekleri ve özellikler (ör. yapılandırılmış çıkış) hakkında bilgi edinebilirsiniz.

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

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 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, ardından Firebase projenizi seçin.

   Henüz bir Firebase projeniz yok mu?

   Henüz bir Firebase projeniz yoksa yeni bir Firebase projesi oluşturmak için düğmeyi tıklayın 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: Firebase'i Google Cloud projesine ekle'yi (sayfanın alt kısmında) tıklayarak mevcut bir Google Cloud projesine "Firebase ekleyin". İş 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 kurulumu yapmanız gerekmediğini unutmayın.Google Analytics

2. Firebase konsolunda Firebase AI Logic sayfasına 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. Projenizi "Gemini API" sağlayıcısını kullanacak şekilde ayarlayın.

   Gemini Developer API ile başlamanızı öneririz. Dilediğiniz zaman Vertex AI Gemini API (ve faturalandırma için gerekli olan) ayarlayabilirsiniz.

   Konsol, Gemini Developer API için gerekli API'leri etkinleştirir ve projenizde Gemini API anahtarı oluşturur.
   Bu Gemini API anahtarını uygulamanızın kod tabanına eklemeyin. Daha fazla bilgi edinin.

5. Konsolun iş akışında istenirse uygulamanızı kaydetmek ve Firebase'e bağlamak için ekrandaki talimatları uygulayın.

6. SDK'yı 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";
   
   // 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: 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. Aşağıdakileri yaptığınızdan emin olun:

   1. getGenerativeModel Bir son kullanıcı etkileşiminden sonra veya etkileşim sırasında (ör. düğme tıklaması) çağrılır. Bu, inferenceMode için ön koşuldur.

   2. mode özelliğini aşağıdakilerden birine ayarlayın:

      • PREFER_ON_DEVICE: Cihaz üzerinde 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
// 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 });

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

• 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 bir ş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) kullanılarak metin yanıtlarının aktarılmasını da desteklediğini unutmayın.

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

generateContent() Metin ve resim dosyaları içeren bir istemden metin oluşturmak için 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) kullanılarak 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 Denemesi'ne 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?

Bu bölümde, çıkarım modu ayarlama, varsayılan bulutta barındırılan yedek modeli geçersiz kılma ve yanıtları kontrol etmek için model yapılandırmasını kullanma (ör. yapılandırılmış çıkış oluşturma) hakkında bilgi edineceksiniz.

Çıkarım modu ayarlama

Genel kurulumdaki örneklerde PREFER_ON_DEVICE modu kullanılır ancak bu, mevcut dört çıkarım modundan yalnızca biridir.

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

  const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });
  

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

  const model = getGenerativeModel(ai, { mode: InferenceMode.ONLY_ON_DEVICE });
  

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

  const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_IN_CLOUD });
  

• ONLY_IN_CLOUD: Varsa bulut tabanlı modeli kullanın; aksi takdirde bir istisna oluşturun.

  const model = getGenerativeModel(ai, { mode: InferenceMode.ONLY_IN_CLOUD });
  

Cihaz üzerinde mi yoksa bulutta mı çıkarım yapıldığını belirleme

PREFER_ON_DEVICE veya PREFER_IN_CLOUD çıkarım modlarını kullanıyorsanız belirli istekler için hangi modun kullanıldığını bilmek faydalı olabilir. Bu bilgiler, her yanıtın inferenceSource özelliği tarafından sağlanır (JS SDK v12.5.0'dan itibaren kullanılabilir).

Bu özelliğe eriştiğinizde döndürülen değer ON_DEVICE veya IN_CLOUD olur.

// ...

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

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

Varsayılan yedek modeli geçersiz kılma

Varsayılan bulutta barındırılan model gemini-2.5-flash-lite (JS SDK v12.8.0'dan itibaren)

Bu model, PREFER_ON_DEVICE modunu kullandığınızda yedek Cloud'da barındırılan modeldir. Ayrıca ONLY_IN_CLOUD modunu veya PREFER_IN_CLOUD modunu kullandığınızda varsayılan modeldir.

Alternatif bir varsayılan bulutta barındırılan model belirtmek için inCloudParams yapılandırma seçeneğini kullanabilirsiniz.

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

Desteklenen tüm Gemini modellerinin model adlarını öğrenin.

Yanıtları kontrol etmek için model yapılandırmasını kullanma

Bir modele gönderdiğiniz her istekle birlikte, modelin nasıl yanıt üreteceğini kontrol etmek için bir model yapılandırması gönderebilirsiniz. Cloud tarafından barındırılan modeller ve cihaz üzerinde modeller farklı yapılandırma seçenekleri sunar.

Yapılandırma, örneğin kullanım ömrü boyunca korunur. Farklı bir yapılandırma kullanmak istiyorsanız bu yapılandırmayla yeni bir GenerativeModel örneği oluşturun.

Bulutta barındırılan bir modelin yapılandırmasını ayarlama

Bulutta barındırılan bir Gemini modelini yapılandırmak için inCloudParams seçeneğini kullanın. Kullanılabilir parametreler hakkında bilgi edinin.

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

Cihaz üzerinde model için yapılandırmayı ayarlama

Cihaz üzerinde model kullanılarak yapılan çıkarımlarda Chrome'daki istem API'sinin kullanıldığını unutmayın.

Cihaz üzerinde bir model yapılandırmak için onDeviceParams seçeneğini kullanın. Kullanılabilir parametreler hakkında bilgi edinin.

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

Yapılandırılmış çıkış (ör. JSON) için yapılandırmayı ayarlama

Hem bulutta barındırılan hem de cihaz üzerinde modeller kullanılarak çıkarım için yapılandırılmış çıkış (ör. JSON ve enum) oluşturma desteklenir.

Karma çıkarım için modeli yapılandırılmış çıkışla yanıt verecek şekilde ayarlamak üzere hem inCloudParams hem de onDeviceParams kullanın. Diğer modlar için yalnızca geçerli yapılandırmayı kullanın.

• inCloudParams için: Uygun responseMimeType'ı (bu örnekte application/json) ve modelin kullanmasını istediğiniz responseSchema'ı belirtin.

• onDeviceParams için: Modelin kullanmasını istediğiniz responseConstraint değerini belirtin.

JSON çıkışı

Aşağıdaki örnekte, hibrit çıkarım için genel JSON çıkışı örneği uyarlanmıştır:

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

Enum çıkışı

Yukarıdakiyle aynıdır ancak karma çıkarım için enum çıkışıyla ilgili dokümanlar uyarlanır:

// ...

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

const model = getGenerativeModel(ai, {

// ...

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

// ...
});

// ...

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

Deneysel bir sürüm olduğundan Web SDK'sının tüm özellikleri cihaz üzerinde çıkarım için kullanılamaz. Aşağıdaki özellikler henüz cihaz üzerinde çıkarım için 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 ü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 iki yönlü yayın

• 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ı ve Google Arama 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 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