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


Firebase AI Logic kullanarak karma çıkarım ile yapay zeka destekli Android uygulamaları ve özellikleri geliştirebilirsiniz. Karma çıkarım, mümkün olduğunda cihaz üzerinde modelleri kullanarak çıkarım yapmayı ve aksi takdirde bulutta barındırılan modellere sorunsuz bir şekilde geri dönmeyi (veya tam tersini) sağlar.

Bu sayfada, istemci SDK'sını kullanmaya nasıl başlayacağınız açıklanmakta ve ek yapılandırma seçenekleri ile özellikler gösterilmektedir.

Firebase AI Logic üzerinden cihaz üzerinde çıkarım, Firebase AI Logic SDK 17.10.0 ve sonraki sürümlerini (BoM 34.10.0 ve sonraki sürümleri) kullanan ve belirli cihazlarda çalışan Android uygulamaları için desteklenir. ML Kiti şartlarına ve ML Kiti'nin üretken yapay zeka özelliklerine özgü şartlara tabidir.

Ö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şlevselliği kullanmanın avantajları:

    • Cihaz üzerinde model kullanılabilirliğini ve internet bağlantısını destekleyerek kitlenizin daha büyük bir kısmına 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:

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

Başlamadan önce

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

Desteklenen Android cihazlar ve cihaz üzerindeki modelleri

Cihaz üzerinde çıkarım (ML Kit'teki Prompt API'yi kullanır) için desteklenen cihazların ve cihaz üzerindeki modellerinin listesini ML Kit belgelerinde bulabilirsiniz.

Başlayın

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

1. 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.

    Temmuz 2026'nın başından itibaren iş 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.

2. adım: Gerekli SDK'ları ekleyin

Firebase AI Logic Android için SDK (firebase-ai) ve Firebase AI Logic On-Device SDK (firebase-ai-ondevice), üretken modellerle etkileşim kurmak için API'lere erişim sağlar.

Modülünüzün (uygulama düzeyinde) Gradle dosyasında (ör. <project>/<app-module>/build.gradle.kts), Android için Firebase AI Logic ve App Check kitaplıklarının bağımlılıklarını ekleyin:

Kotlin 

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic and App Check libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:18.1.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta07")
  implementation("com.google.firebase:firebase-appcheck-debug:20.0.0")
}

Java

Java için iki ek kitaplık eklemeniz gerekir.

dependencies {
  // ... other androidx dependencies

  // Add the dependencies for the Firebase AI Logic and App Check libraries
  // Note that the on-device SDK is not yet included in the Firebase Android BoM
  implementation("com.google.firebase:firebase-ai:18.1.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta07")
  implementation("com.google.firebase:firebase-appcheck-debug:20.0.0")

  // Required for one-shot operations (to use `ListenableFuture` from Guava Android)
  implementation("com.google.guava:guava:31.0.1-android")

  // Required for streaming operations (to use `Publisher` from Reactive Streams)
  implementation("org.reactivestreams:reactive-streams:1.0.4")
}

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

Temmuz 2026'nın başından itibaren, Console'da AI Logic için rehberli kurulum iş akışı kapsamında, Gemini API korumak için Firebase App Check otomatik olarak uygulanacak. 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.

  1. Hata ayıklama derlemenizde App Check öğesini, hata ayıklama sağlayıcı fabrikasını kullanacak şekilde yapılandırın:

    Kotlin

    Firebase.initialize(context = this)
Firebase.appCheck.installAppCheckProviderFactory(
    DebugAppCheckProviderFactory.getInstance(),
)

    Java

    FirebaseApp.initializeApp(/*context=*/ this);
FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
firebaseAppCheck.installAppCheckProviderFactory(
        DebugAppCheckProviderFactory.getInstance());

  2. Hata ayıklama jetonunuzu alın:

    1. Uygulamanızı emülatörde veya test cihazınızda çalıştırın.

    2. Günlüklerinizde App Check hata ayıklama jetonunu bulun. Örneğin:

      D DebugAppCheckProvider: Enter this debug secret into the allow list
in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678

    3. Jetonu (ör. 123a4567-b89c-12d3-e456-789012345678) kopyalayın.

  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.

4. adım: Cihaz üzerinde modelin kullanılabilir olup olmadığını kontrol edin

FirebaseAIOnDevice kullanarak cihaz üzerinde modelin kullanılabilir olup olmadığını kontrol edin ve kullanılabilir değilse modeli indirin.

AICore, indirildikten sonra modeli otomatik olarak güncel tutar. AICore ve cihaz üzerinde model indirme işlemini yönetme hakkında daha fazla bilgi için snippet'ten sonraki notlara göz atın.

Kotlin 

val status = FirebaseAIOnDevice.checkStatus()
when (status) {
  OnDeviceModelStatus.UNAVAILABLE -> {
    Log.w(TAG, "On-device model is unavailable")
  }

  OnDeviceModelStatus.DOWNLOADABLE -> {
    FirebaseAIOnDevice.download().collect { status ->
      when (status) {
        is DownloadStatus.DownloadStarted ->
          Log.w(TAG, "Starting download - ${status.bytesToDownload}")

        is DownloadStatus.DownloadInProgress ->
          Log.w(TAG, "Download in progress ${status.totalBytesDownloaded} bytes downloaded")

        is DownloadStatus.DownloadCompleted ->
          Log.w(TAG, "On-device model download complete")

        is DownloadStatus.DownloadFailed ->
          Log.e(TAG, "Download failed ${status}")
      }
    }
  }
  OnDeviceModelStatus.DOWNLOADING -> {
    Log.w(TAG, "On-device model is being downloaded")
  }

  OnDeviceModelStatus.AVAILABLE -> {
    Log.w(TAG, "On-device model is available")
  }
}

Java 

Checking for, downloading, and warming up the model is not yet available for Java.

However, all other APIs and interactions in this guide are available for Java.

Cihaz üzerinde model indirmeyle ilgili aşağıdaki noktalara dikkat edin:

  • Cihaz üzerinde modelin indirilme süresi, ağınız da dahil olmak üzere birçok faktöre bağlıdır.

  • Kodunuz, birincil veya yedek çıkarımı için cihaz üzerinde bir model kullanıyorsa modelin uygulamanızın yaşam döngüsünün başlarında indirildiğinden emin olun. Böylece, cihaz üzerinde model, son kullanıcılarınız uygulamanızdaki kodla karşılaşmadan önce kullanılabilir olur.

  • Cihaz üzerinde çıkarım isteği yapıldığında cihaz üzerinde model kullanılamıyorsa SDK, cihaz üzerinde modelin indirilmesini otomatik olarak tetiklemez. SDK, bulutta barındırılan modele geri döner veya bir istisna oluşturur (çıkarım modlarının davranışı hakkında ayrıntılı bilgi edinin).

  • AICore (bir Android sistem hizmeti), hangi modelin ve sürümün indirileceğini yönetir, modeli güncel tutar vb. Cihaza yalnızca bir model indirilir. Bu nedenle, cihazdaki başka bir uygulama daha önce cihaz üzerinde modeli başarıyla indirdiyse bu kontrol, modelin kullanılabilir olduğunu döndürür.

Gecikme optimizasyonu

İlk çıkarım çağrısını optimize etmek için uygulamanızın onDeviceExtension?.warmUp() çağrısı yapmasını sağlayabilirsiniz (şu anda yalnızca Kotlin için kullanılabilir). Bu işlem, cihaz üzerinde modeli belleğe yükler ve çalışma zamanı bileşenlerini başlatır.

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. Bir GenerativeModel örneği oluşturun ve mode değerini aşağıdakilerden birine ayarlayın. Buradaki açıklamalar çok geneldir ancak bu modların davranışıyla ilgili ayrıntıları Çıkarım modu ayarlama bölümünde bulabilirsiniz.

    • PREFER_ON_DEVICE: Cihaz üzerinde model kullanmaya çalışır. Aksi takdirde bulutta barındırılan modele geri döner.

    • ONLY_ON_DEVICE: Cihaz üzerinde model kullanmaya çalışın. Aksi takdirde istisna oluşturun.

    • PREFER_IN_CLOUD: Bulutta barındırılan modeli kullanmayı deneyin. Aksi takdirde cihaz üzerinde modele geçin.

    • ONLY_IN_CLOUD: Bulutta barındırılan modeli kullanmayı deneyin. Aksi takdirde istisna oluşturun.

Kotlin 

// Using this SDK to access on-device inference is an Experimental release and requires opt-in
@OptIn(PublicPreviewAPI::class)

// ...

// Initialize the Gemini Developer API backend service
// Create a GenerativeModel instance with a model that supports your use case
// Set the inference mode (like PREFER_ON_DEVICE to use the on-device model if available)
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
    .generativeModel(
        modelName = "CLOUD_MODEL_NAME",
        onDeviceConfig = OnDeviceConfig(mode = InferenceMode.PREFER_ON_DEVICE)
    )

Java 

// Initialize the Gemini Developer API backend service
// Create a GenerativeModel instance with a model that supports your use case
// Set the inference mode (like PREFER_ON_DEVICE to use the on-device model if available)
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
    .generativeModel(
        "CLOUD_MODEL_NAME",
        new OnDeviceConfig(InferenceMode.PREFER_ON_DEVICE)
    );

// Use the GenerativeModelFutures Java compatibility layer which offers
// support for ListenableFuture and Publisher APIs
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

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

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:

Kotlin 

// Imports + initialization of Gemini API backend service + creation of model instance

// Provide a prompt that contains text
val prompt = "Write a story about a magic backpack."

// To generate text output, call generateContent with the text input
val response = model.generateContent(prompt)
print(response.text)

Java 

// Imports + initialization of Gemini API backend service + creation of model instance

// Provide a prompt that contains text
Content prompt = new Content.Builder()
    .addText("Write a story about a magic backpack.")
    .build();

// To generate text output, call generateContent with the text input
ListenableFuture<GenerateContentResponse> response = model.generateContent(prompt);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        String resultText = result.getText();
        System.out.println(resultText);
    }

    @Override
    public void onFailure(Throwable t) {
        t.printStackTrace();
    }
}, executor);

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 en fazla bir resim dosyası (yalnızca bit eşlem) 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.

Kotlin 

// Imports + initialization of Gemini API backend service + creation of model instance

// Loads an image from the app/res/drawable/ directory
val bitmap: Bitmap = BitmapFactory.decodeResource(resources, R.drawable.sparky)

// Provide a prompt that includes the image specified above and text
val prompt = content {
  image(bitmap)
  text("What developer tool is this mascot from?")
}

// To generate text output, call generateContent with the prompt
val response = model.generateContent(prompt)
print(response.text)

Java 

// Imports + initialization of Gemini API backend service + creation of model instance

Bitmap bitmap = BitmapFactory.decodeResource(getResources(), R.drawable.sparky);

// Provide a prompt that includes the image specified above and text
Content content = new Content.Builder()
        .addImage(bitmap)
        .addText("What developer tool is this mascot from?")
        .build();

// To generate text output, call generateContent with the prompt
ListenableFuture<GenerateContentResponse> response = model.generateContent(content);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        String resultText = result.getText();
        System.out.println(resultText);
    }

    @Override
    public void onFailure(Throwable t) {
        t.printStackTrace();
    }
}, executor);

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

Deneysel bir sürüm olduğundan, bulut modellerinin tüm özellikleri cihaz üzerinde çıkarım için kullanılamaz. Aşağıdaki özellikler cihaz üzerinde çıkarım için henüz kullanılamamaktadır (ancak genellikle bulut tabanlı çıkarım için kullanılabilir).

  • Resimler oluşturuluyor

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

  • Bitmap (belleğe yüklenen resim) dışındaki resim dosyası giriş türlerinden metin oluşturma

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

  • Yalnızca resim içeren dosya girişinden metin oluşturma Cihaz üzerinde çıkarım için çok formatlı isteğin bir parçası olarak metin sağlamanız gerekir.

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

  • Birden fazla resim dosyası girişinden metin oluşturma

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

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

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

  • Çok formatlı isteklerde URL'leri kullanarak dosya sağlama Cihaz üzerinde çıkarım için tek bir resmi Bitmap olarak sağlamanız gerekir.

    • fileData (FileDataPart) kullanarak bir dosya URL'si sağlarsanız bulutta barındırılan modele geri dönebilir (ONLY_ON_DEVICE modu bir istisna oluşturur).
    • Bir URL'yi doğrudan yazılı isteme yerleştirirseniz otomatik olarak bulutta barındırılan modele geri dönmez (yerleştirilmiş URL'ler cihaz üzerinde model tarafından yoksayılır).

  • 4.000 jetonu (veya yaklaşık 3.000 İngilizce kelimeyi) aşan istekler gönderme

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

  • Çok adımlı sohbet

    • Otomatik olarak bulutta barındırılan modele geri dönmez (cihaz üzerinde çıkarım, istem geçmişini tek bir yazılı istemde birleştirir. Cihaz üzerinde model, roller arasında ayrım yapmadığı ve geçmişi tek bir mesaj olarak gördüğü için bulutta barındırılan bir model kadar hassas olmaz).
    • Çok turlu sohbet kullanmak istiyorsanız ONLY_IN_CLOUD modunu kullanmanızı öneririz.

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

    • Otomatik olarak bulutta barındırılan modele geri dönmez. Araçları kullanmak istiyorsanız ONLY_IN_CLOUD modunu kullanmanızı öneririz.

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, Firebase AI Logic aracılığıyla diğer çıkarımlar gibi izlenebilir.

Ek sınırlamalar

Yukarıdakilere ek olarak, cihaz üzerinde çıkarım aşağıdaki sınırlamalara sahiptir (ML Kit belgelerinde daha fazla bilgi edinin):

  • Uygulamanızın son kullanıcısı, cihaz üzerinde çıkarım için desteklenen bir cihaz kullanmalıdır.

  • Uygulamanız, yalnızca ön plandayken cihaz üzerinde çıkarım yapabilir.

  • Cihaz üzerinde çıkarım için yalnızca İngilizce ve Korece dilleri doğrulanmıştır.

  • Cihaz üzerinde çıkarım isteğinin tamamı için maksimum jeton sınırı 4.000 jetondur. İstekleriniz bu sınırı aşabilirse bulutta barındırılan bir modeli kullanabilen bir çıkarım modu yapılandırdığınızdan emin olun.

  • Uzun çıkış (256 jetondan fazla) gerektiren cihaz üzerinde çıkarım kullanım alanlarından kaçınmanızı öneririz.

  • Cihaz üzerindeki modelleri yöneten bir Android sistem hizmeti olan AICore, uygulama başına bir çıkarım kotası uygular. Kısa bir süre içinde çok fazla API isteği gönderilmesi ErrorCode.BUSY yanıtına neden olur. Bu hatayı alıyorsanız isteği yeniden denemek için eksponansiyel geri yükleme kullanabilirsiniz. Ayrıca, bir uygulama uzun süreli bir kotayı (ör. günlük kota) aşarsa ErrorCode.PER_APP_BATTERY_USE_QUOTA_EXCEEDED döndürülebilir.


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