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, kullanılabildiğinde cihaz üzerinde modelleri kullanarak çıkarım yapmaya ve aksi takdirde sorunsuz bir şekilde bulutta barındırılan modellere geri dönmeye (veya tam tersi) olanak tanır.

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şlevsellik tekliflerini kullanma:

    • Cihaz üzerinde model kullanılabilirliğini ve internet bağlantısını dikkate alarak 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 üzerinde modellerinin listesini ML Kit dokümanlarında bulabilirsiniz.

Başlayın

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: 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 > AI Logic'e 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şlarından itibaren iş akışının bu aşamasında, uygulamanıza doğrudan erişildiğinde Gemini API'ı korumaya yardımcı olan kritik bir hizmet olan AI Logic için otomatik olarak Firebase App Check uygulanacak. Başlarken (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.0.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta06")
  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.0.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta06")
  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ı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 yaptırımını sürdürürken onaylamayı 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 kopyalayın (örneğin, 123a4567-b89c-12d3-e456-789012345678).

  3. Hata ayıklama jetonunuzu App Check ile kaydedin:

    1. Firebase konsolunda Güvenlik > Uygulama Kontrolü > 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 mevcut olup olmadığını kontrol edin ve mevcut değilse modeli indirin.

İndirildikten sonra AICore, 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 notları inceleyin.

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 modeli indirme hakkında aşağıdakileri göz önünde bulundurun:

  • Cihaz üzerinde modeli indirme 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, son kullanıcılarınız uygulamanızdaki kodla karşılaşmadan önce cihaz üzerinde model 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 sizin için yönetir, modeli güncel tutar vb. Cihazda yalnızca bir model indirileceğini unutmayın. Bu nedenle, cihazdaki başka bir uygulama daha önce cihaz üzerindeki modeli başarıyla indirdiyse bu kontrol, modelin kullanılabilir olduğunu gösterir.

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 üzerindeki 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 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 modeli kullanmayı deneyin; aksi takdirde bulutta barındırılan modele geri dönün.

    • ONLY_ON_DEVICE: Cihaz üzerinde model kullanmayı deneyin. Aksi takdirde istisna oluşturun.

    • PREFER_IN_CLOUD: Bulutta barındırılan modeli kullanmaya çalışın. Aksi takdirde cihaz üzerinde modele geri dönün.

    • ONLY_IN_CLOUD: Bulutta barındırılan modeli kullanmayı deneyin. Aksi takdirde bir 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, 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şten metin oluşturma

Bu örneği denemeden önce bu kılavuzun Başlarken 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 bitmap) içeren bir istemden metin oluşturmak için generateContent()'ı kullanabilirsiniz. Her giriş dosyasının mimeType ve dosyanın kendisi sağlanır.

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'nın, generateContentStream kullanarak metin yanıtlarının akışını da desteklediğini unutmayın (generateContent yerine).

Başka ne yapabilirsin?

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

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 modunda istisna hatası verilir.

  • 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 modunda istisna hatası verilir.

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

    • Bulutta barındırılan modele geri dönebilir ancak ONLY_ON_DEVICE modunda istisna hatası verilir.

  • 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 metin istemine 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 modunda istisna hatası verilir.

  • Çok adımlı sohbet

    • Bulutta barındırılan modele otomatik olarak geri dönmez (Cihaz üzerinde çıkarım, istem geçmişini tek bir metin isteminde 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ğırma, kod yürütme, URL bağlamı, Google Search ile temellendirme ve Google Maps ile temellendirme)

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

Firebase konsolundaki yapay zeka izleme özelliği, cihaz üzerinde çıkarım (cihaz üzerinde günlükler dahil) ile ilgili herhangi bir veri 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 planda olduğunda 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. İsteklerinizin bu sınırı aşabileceğini düşünüyorsanız bulutta barındırılan bir modeli kullanabilen bir çıkarım modu yapılandırdığınızdan emin olun.

  • Uzun çıktı (256'dan fazla jeton) gerektiren cihaz üzerinde çıkarım kullanım alanlarından kaçınmanızı öneririz.

  • AICore (cihaz üzerindeki modelleri yöneten bir Android sistem hizmeti), uygulama başına çıkarım kotası uygular. Kısa süre içinde çok fazla API isteği göndermek 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