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


Firebase AI Logic kullanarak hibrit çıkarımla yapay zeka destekli Android uygulamaları ve özellikleri oluşturabilirsiniz. Karma çıkarım, kullanılabildiğinde cihaz üzerinde modelleri kullanarak çıkarım çalıştırmayı ve aksi takdirde (veya tam tersi) sorunsuz bir şekilde bulutta barındırılan modellere geri dönmeyi sağlar.

Bu sayfada, istemci SDK'sını kullanmaya başlama ve ek yapılandırma seçenekleri ile özellikler hakkında bilgiler verilmektedir.

Firebase AI Logic SDK'sının 17.10.0 sürümü veya üzerini (BoM 34.10.0 sürümü veya üzeri) kullanan ve belirli cihazlarda çalışan Android uygulamaları için Firebase AI Logic üzerinden cihaz üzerinde çıkarımın desteklendiğini unutmayın. ML Kit Şartları ve ML Kit'in üretken yapay zeka özelliklerine özgü şartlar geçerlidir.

Önerilen kullanım alanları ve desteklenen özellikler

Önerilen kullanım alanları

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

    • Gelişmiş gizlilik
    • Yerel bağlam
    • Ücretsiz çıkarım
    • Çevrimdışı işlevler

  • Karma işlevselliği tekliflerini kullanma:

    • 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

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

Bu sayfanın alt kısmındaki cihaz üzerinde çıkarım için henüz kullanılamayan özellikler listesini incelemeyi unutmayın.

Başlamadan önce

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

Desteklenen Android cihazlar ve cihaz üzerinde 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, ardından 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ışı 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 kullanmaya başlamanıza olanak tanıyan Gemini Developer API'yi seçmenizi öneririz.

    Daha sonra istediğiniz zaman Agent Platform Gemini API (formerly Vertex AI)'ı ayarlayabilirsiniz (ve faturalandırma için gerekli olan bilgileri girebilirsiniz).

  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 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'sı (firebase-ai-ondevice), üretken modellerle etkileşim kurmaya yönelik 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:17.17.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta05")
  implementation("com.google.firebase:firebase-appcheck-debug:19.4.1")
}

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:17.17.0")
  implementation("com.google.firebase:firebase-ai-ondevice:16.0.0-beta05")
  implementation("com.google.firebase:firebase-appcheck-debug:19.4.1")

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

    uygulayın.

  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 > App Check > Uygulamalar sekmesine gidin.

    2. Uygulamanızı bulun, taşma menüsünü () tıklayın ve 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 hata ayıklama jetonu edinme dahil) için resmi App Check belgeleri inceleyin.

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ılamıyorsa modeli indirin.

İndirildikten sonra AICore, modeli otomatik olarak güncel tutar. AICore ve cihaz üzerindeki model indirme işlemini yönetme hakkında daha fazla bilgi için snippet'in ardından gelen 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 modeli indirme hakkında aşağıdakileri unutmayın:

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

  • 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 sisteme ait 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ı için optimizasyon yapmak üzere 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 başlatın ve model örneği oluşturun

Bu sayfada sağlayıcıya özel içerikleri ve kodu 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 ve mode değerini aşağıdakilerden biri olarak ayarlayın. Buradaki açıklamalar çok üst düzeydir ancak bu modların davranışı hakkında ayrıntılı bilgi edinmek için Çıkarım modu ayarlama bölümüne gidebilirsiniz.

    • 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 modeli kullanmayı deneyin; aksi takdirde bir istisna oluşturun.

    • PREFER_IN_CLOUD: Bulutta barındırılan modeli kullanmayı deneyin. Aksi takdirde cihaz üzerinde modeli kullanı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ı çıkış türleri 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

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

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

Bu örneği denemeden önce bu kılavuzun Başlarken 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 yapabilirsiniz?

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.

Bu bölümde listelenen özellikler henüz cihaz üzerinde çıkarım için kullanılamamaktadır. Bu özelliklerden herhangi birini kullanmak istiyorsanız daha tutarlı bir deneyim için ONLY_IN_CLOUD çıkarım modunu kullanmanızı öneririz.

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

  • Birden fazla resim dosyasından metin oluşturma

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

  • Gemini modellerini kullanarak resim oluşturma

  • Çok formatlı isteklerde URL'ler kullanarak dosya sağlama. Dosyaları, cihaz üzerindeki modellere satır içi veri olarak sağlamanız gerekir.

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

  • Çok aşamalı etkileşimli sohbet

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

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 modeli 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 (daha fazla bilgiyi ML Kit dokümanlarında bulabilirsiniz):

  • 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 çalıştırabilir.

  • 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 sisteme ait 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üklemeyi 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 bildirim verme