Prompt API'yi kullanmaya başlama

Bu sayfada aşağıdakilerin nasıl yapılacağı açıklanmaktadır:

• Projenizi Prompt API'yi kullanacak şekilde yapılandırma
• Yalnızca metin girişi yapma ve yanıt alma
• İlgili metin girişiyle birlikte bir resim girişi sağlayın ve yanıt alın

Prompt API hakkında daha fazla bilgi için Kotlin (com.google.mlkit.genai.prompt) ve Java (com.google.mlkit.genai.prompt.java, com.google.mlkit.genai.prompt) referans belgelerine bakın.

[İsteğe bağlı] İstemleri Gemma 3n modeliyle test etme

Uygulamadan önce isteminizi AI Studio'da Gemma 3n E4B modeliyle test etmenizi öneririz. Gemma 3n'nin çıkışlarının, nano-v3 çıkışlarına çok benzemesi beklenir.

Projeyi yapılandırma

Not: Bu API için Android API düzeyi 26 veya sonraki sürümler gerekir.

build.gradle yapılandırmanıza bağımlılık olarak ML Kit Prompt API'yi ekleyin:

implementation("com.google.mlkit:genai-prompt:1.0.0-alpha1")

Üretken modeli uygulama

Kodu projenizde uygulamak için aşağıdaki adımları uygulayın:

• generativeModel nesnesi oluşturma:

  Kotlin

  // Get a GenerativeModel instance
  val generativeModel = Generation.getClient()
  

  Java

  // Get a GenerativeModel instance
  GenerativeModelFutures generativeModelFutures = GenerativeModelFutures
      .from(Generation.INSTANCE.getClient());
  

• Gemini Nano'nun AVAILABLE, DOWNLOADABLE veya UNAVAILABLE olup olmadığını kontrol edin. Ardından, indirilebilir bir özellikse indirin:

  Kotlin

  val status = generativeModel.checkStatus()
  when (status) {
      FeatureStatus.UNAVAILABLE -> {
          // Gemini Nano not supported on this device or device hasn't fetched the latest configuration to support it
      }
  
      FeatureStatus.DOWNLOADABLE -> {
          // Gemini Nano can be downloaded on this device, but is not currently downloaded
          generativeModel.download().collect { status ->
              when (status) {
                  is DownloadStatus.DownloadStarted ->
                      Log.d(TAG, "starting download for Gemini Nano")
  
                  is DownloadStatus.DownloadProgress ->
                      Log.d(TAG, "Nano ${status.totalBytesDownloaded} bytes downloaded")
  
                  DownloadStatus.DownloadCompleted -> {
                      Log.d(TAG, "Gemini Nano download complete")
                      modelDownloaded = true
                  }
  
                  is DownloadStatus.DownloadFailed -> {
                      Log.e(TAG, "Nano download failed ${status.e.message}")
                  }
              }
          }
      }
  
      FeatureStatus.DOWNLOADING -> {
          // Gemini Nano currently being downloaded
      }
  
      FeatureStatus.AVAILABLE -> {
          // Gemini Nano currently downloaded and available to use on this device
      }
  }
  

  Java

  ListenableFuture<Integer> status = generativeModelFutures.checkStatus();
  Futures.addCallback(generativeModelFutures.checkStatus(), new FutureCallback<>() {
      @Override
      public void onSuccess(Integer featureStatus) {
          switch (featureStatus) {
              case FeatureStatus.AVAILABLE - > {
                  // Gemini Nano currently downloaded and available to use on this device
              }
              case FeatureStatus.UNAVAILABLE - > {
                  // Gemini Nano not supported on this device or device hasn't fetched the latest configuration to support it
              }
              case FeatureStatus.DOWNLOADING - > {
                  // Gemini Nano currently being downloaded
              }
              case FeatureStatus.DOWNLOADABLE - > {
                  generativeModelFutures.download(new DownloadCallback() {
                      @Override
                      public void onDownloadStarted(long l) {
                          Log.d(TAG, "starting download for Gemini Nano");
                      }
                      @Override
                      public void onDownloadProgress(long l) {
                          Log.d(TAG, "Nano " + l + " bytes downloaded");
                      }
                      @Override
                      public void onDownloadCompleted() {
                          Log.d(TAG, "Gemini Nano download complete");
                      }
                      @Override
                      public void onDownloadFailed(@NonNull GenAiException e) {
                          Log.e(TAG, "Nano download failed: " + e.getMessage());
                      }
                  });
              }
          }
      }
      @Override
      public void onFailure(@NonNull Throwable t) {
          // Failed to check status
      }
  }, ContextCompat.getMainExecutor(context));
  
  

Yalnızca metin girişi sağlama

Kotlin

val response = generativeModel.generateContent("Write a 3 sentence story about a magical dog.")

Java

GenerateContentResponse response = generativeModelFutures.generateContent(
  new GenerateContentRequest.Builder(
    new TextPart("Write a 3 sentence story about a magical dog."))
  .build())
  .get();

Alternatif olarak, isteğe bağlı parametreler ekleyin:

Kotlin

val response = generativeModel.generateContent(
    generateContentRequest(
        TextPart("Write a 3 sentence story about a magical dog."),
    ) {
        // Optional parameters
        temperature = 0.2f
        topK = 10
        candidateCount = 3
    },
)

Java

GenerateContentRequest.Builder requestBuilder =
        new GenerateContentRequest.Builder(
                new TextPart("Write a 3 sentence story about a magical dog."));
requestBuilder.setTemperature(.2f);
requestBuilder.setTopK(10);
requestBuilder.setCandidateCount(3);

GenerateContentResponse response =
        generativeModelFutures.generateContent(requestBuilder.build()).get();

İsteğe bağlı parametreler hakkında daha fazla bilgi için İsteğe bağlı yapılandırmalar başlıklı makaleyi inceleyin.

Çok formatlı (resim ve metin) giriş sağlama

generateContentRequest() işlevinde bir resim ve metin girişini birlikte paketleyin. Metin istemi, resimle ilgili bir soru veya komut olmalıdır:

Kotlin

val response = generativeModel.generateContent(
    generateContentRequest(ImagePart(bitmap), TextPart(textPrompt)) {
        // optional parameters
        ...
    },
)

Java

GenerateContentResponse response = generativeModelFutures.generateContent(
    new GenerateContentRequest.Builder(
        new ImagePart(bitmap),
        new TextPart("textPrompt"))
    // optional parameters
    .build())
.get();

Çıkarım sonucunu işleme

• Çıkarımı çalıştırın ve sonucu alın. Yalnızca metin içeren ve çok formatlı istemler için yanıt oluşturulurken sonucu beklemeyi veya yanıtı yayınlamayı seçebilirsiniz.

  • Bu işlemde, sonuç döndürülmeden önce yapay zeka modelinden tüm sonucun alındığı akışsız çıkarım kullanılır:

  Kotlin

  // Call the AI model to generate content and store the complete
  // in a new variable named 'response' once it's finished
  val response = generativeModel.generateContent("Write a 3 sentence story about a magical dog")
  

  Java

  GenerateContentResponse response = generativeModelFutures.generateContent(
          new GenerateContentRequest.Builder(
                  new TextPart("Write a 3 sentence story about a magical dog."))
                  .build())
          .get();
  

  • Aşağıdaki snippet'ler, sonuç oluşturulurken parçalar halinde alındığı için akış çıkarımı kullanımına örneklerdir:

  Kotlin

  // Streaming inference
  var fullResponse = ""
  generativeModel.generateContentStream("Write a 3 sentence story about a magical dog").collect { chunk ->
      val newChunkReceived = chunk.candidates[0].text
      print(newChunkReceived)
      fullResponse += newChunkReceived
  }
  

  Java

  // Streaming inference
  StringBuilder fullResponse = new StringBuilder();
  generativeModelFutures.generateContent(new GenerateContentRequest.Builder(
      (new TextPart("Write a 3 sentence story about a magical dog"))).build(),
          chunk -> {
              Log.d(TAG, chunk);
              fullResponse.append(chunk);
          });
  

Akışla aktarılan ve akışla aktarılmayan çıkarım hakkında daha fazla bilgi için Akışla aktarma ve akışla aktarmama başlıklı makaleyi inceleyin.

Gecikme optimizasyonu

Uygulamanız, ilk çıkarım çağrısı için optimizasyon yapmak üzere isteğe bağlı olarak warmup() çağrısı yapabilir. Bu işlem, Gemini Nano'yu belleğe yükler ve çalışma zamanı bileşenlerini başlatır.

İsteğe bağlı yapılandırmalar

Her GenerateContentRequest kapsamında aşağıdaki isteğe bağlı parametreleri ayarlayabilirsiniz:

• temperature : Jeton seçimindeki rastgelelik derecesini kontrol eder.
• seed : Kararlı ve kontrollü sonuçlar oluşturulmasını sağlar.
• topK : Sonuçlardaki rastgeleliği ve çeşitliliği kontrol eder.
• candidateCount : Döndürülen benzersiz yanıtların sayısını ister. Yanıtların tam sayısının, yinelenen yanıtlar otomatik olarak kaldırıldığından candidateCount ile aynı olmayabileceğini unutmayın.
• maxOutputTokens : Yanıtta oluşturulabilecek maksimum jeton sayısını tanımlar.

İsteğe bağlı yapılandırmaları ayarlama hakkında daha fazla bilgi için GenerateContentRequest başlıklı makaleyi inceleyin.

Desteklenen özellikler ve sınırlamalar

• Giriş 4.000 jetondan (veya yaklaşık 3.000 İngilizce kelimeden) kısa olmalıdır. Daha fazla bilgi için countTokens referansına bakın.
• Uzun çıktı (256'dan fazla jeton) gerektiren kullanım alanlarından kaçınılmalıdır.
• AICore, uygulama başına çıkarım kotası uygular. Daha fazla bilgi için Uygulama başına kota başlıklı makaleyi inceleyin.
• Prompt API için aşağıdaki diller doğrulanmıştır:
  • İngilizce
  • Korece

Not: Daha fazla dili doğrulama sürecindeyiz. Kalite standartlarınızı karşılayıp karşılamadıklarını görmek için diğer dillerle denemeler yapmanızı ve ilgilendiğiniz diğer dillerle ilgili geri bildirimlerinizi bizimle paylaşmanızı öneririz.

Sık karşılaşılan kurulum sorunları

Not: Bu API, kilidi açılmış önyükleyiciye sahip cihazlarda desteklenmez.

ML Kit üretken yapay zeka API'leri, Gemini Nano'ya erişmek için Android AICore uygulamasına bağlıdır. Bir cihaz yeni kurulduğunda (sıfırlama dahil) veya AICore uygulaması yeni sıfırlandığında (ör. veriler temizlendiğinde, uygulama kaldırılıp yeniden yüklendiğinde) AICore uygulaması başlatma işlemini (sunucudan en son yapılandırmaları indirme dahil) tamamlamak için yeterli zamana sahip olmayabilir. Bu nedenle, ML Kit GenAI API'leri beklendiği gibi çalışmayabilir. Karşılaşabileceğiniz yaygın kurulum hata mesajları ve bunları nasıl ele alacağınız aşağıda açıklanmıştır:

Örnek hata mesajı	Ne yapmalı?
AICore, 4-CONNECTION_ERROR hata türü ve 601-BINDING_FAILURE hata koduyla başarısız oldu: AICore hizmeti bağlanamadı.	Bu durum, cihaz kurulumundan hemen sonra ML Kit GenAI API'lerini kullanarak uygulamayı yüklediğinizde veya uygulamanız yüklendikten sonra AICore kaldırıldığında ortaya çıkabilir. AICore uygulamasını güncelleyip uygulamanızı yeniden yüklemek sorunu düzeltir.
AICore, 3-PREPARATION_ERROR hata türü ve 606-FEATURE_NOT_FOUND hata koduyla başarısız oldu: Özellik ... kullanılamıyor.	Bu durum, AICore en son yapılandırmaları indirmeyi tamamlamadığında meydana gelebilir. Cihaz internete bağlandığında güncelleme işlemi genellikle birkaç dakika ile birkaç saat arasında sürer. Cihazı yeniden başlatmak güncellemeyi hızlandırabilir. Cihazın önyükleyicisi kilidi açılmışsa bu hatayı da göreceğinizi unutmayın. Bu API, önyükleyicisi kilidi açılmış cihazları desteklemez.
AICore, 1-DOWNLOAD_ERROR hata türü ve 0-UNKNOWN hata koduyla başarısız oldu: Feature ... failed with failure status 0 and error esz: UNAVAILABLE: Unable to resolve host ...	Ağ bağlantısını koruyun, birkaç dakika bekleyin ve tekrar deneyin.

Not: Çeşitli sıfırlama işlemleri geliştiriciler için yaygın olsa da kullanıcılar için çok daha az sıklıkta gerçekleşir. Ayrıca, bu kurulum hatası durumlarının tümü checkFeatureStatus() veya checkStatus() API'leri tarafından yakalanabilir. İlgili kullanıcı arayüzünü göstermeden önce checkFeatureStatus() veya checkStatus()'u çağırdığınızdan emin olun. Böylece uygulama kullanıcılarınız bu hataları hiçbir durumda görmez.