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 resim girişleri sağlama ve yanıt alma

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 belgelerini inceleyin.

Projeyi yapılandırma

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

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

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

Structured Output API'yi kullanarak yanıtlarınızı belirli bir biçimde almanız gerekiyorsa KSP'yi yapılandırmanız ve ek bağımlılıklar eklemeniz gerekir. Ayrıntılar için Yapılandırılmış çıkış oluşturma başlıklı makaleyi inceleyin.

Üretken modeli uygulama

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

• generativeModel nesnesi oluşturun:

  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, indirilebiliyorsa özelliği 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 bölümüne bakın.

Çok formatlı (görüntü ve metin) giriş sağlama

generateContentRequest() işlevinde birden fazla resim ve bir metin girişini bir araya getirin. Metin istemi, resimle ilgili bir soru veya komut olmalıdır. Aynı istekte en fazla 10 resim ekleyebilirsiniz.

Kotlin

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

Java

GenerateContentResponse response = generativeModelFutures.generateContent(
    new GenerateContentRequest.Builder(
        new Content.Builder()
            .addPart(new ImagePart(bitmap1))
            .addPart(new ImagePart(bitmap2))
            .addPart(new TextPart("textPrompt"))
            .build())
    // optional parameters
    .build())
.get();

Çıkarım sonucunu işleme

• Çıkarımı çalıştırıp sonucu alın. Hem yalnızca metin içeren hem de çok formatlı istemlerde, sonucun tamamını bekleyebilir veya yanıtı oluşturulurken akış olarak alabilirsiniz.

  • Bu örnekte, sonucu döndürmeden önce yapay zeka modelinden tüm sonucu alan, akış dışı çı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, oluşturulurken sonucu parçalar halinde alan akış çıkarımının kullanımına örnek olarak verilmiştir:

  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ışlı ve akışsız çıkarım hakkında daha fazla bilgi için Akışlı ve akışsız başlıklı makaleyi inceleyin.

Gecikme optimizasyonu

İlk çıkarım çağrısını optimize etmek için uygulamanız isteğe bağlı olarak warmup() çağrısını 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 kesin 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. Yinelenen yanıtlar otomatik olarak kaldırıldığından, tam yanıt sayısının candidateCount ile aynı olmayabileceğini unutmayın.
• maxOutputTokens : Yanıtta oluşturulabilecek maksimum parça 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) az olmalıdır. Daha fazla bilgi için countTokens referansına bakın.
• Uzun çıkış (4.000'den fazla jeton) gerektiren kullanım alanlarından kaçınılmalıdır.
• AICore, uygulama başına bir çıkarım kotası uygular. Daha fazla bilgi için Uygulama başına kota bölümüne bakın.

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

Not: Bu API, bootloader'ın kilidi açılmış cihazlarda desteklenmez.

ML Kit GenAI API'leri, Gemini Nano'ya erişmek için Android AICore uygulamasını kullanır. Bir cihaz yeni kurulduğunda (sıfırlama dahil) veya AICore uygulaması yeni sıfırlandığında (ör. veriler temizlendiğinde, kaldırılıp yeniden yüklendiğinde) AICore uygulamasının başlatma işlemini (sunucudan en son yapılandırmaları indirme dahil) tamamlamak için yeterli zamanı 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ı	İtirazı yanıtlama
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üklediğinizde sorun çözülecektir.
AICore, 3-PREPARATION_ERROR hata türü ve 606-FEATURE_NOT_FOUND hata koduyla başarısız oldu: ... özelliği kullanılamıyor.	Bu durum, AICore en son yapılandırmaları indirmeyi tamamlamadığında gerçekleşebilir. Cihaz internete bağlıyken 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 bootloader'ının kilidi açıksa da bu hatayı görürsünüz. Bu API, bootloader'ının kilidi açık olan cihazları desteklemez.
AICore, 1-DOWNLOAD_ERROR hata türü ve 0-UNKNOWN hata koduyla başarısız oldu: ... özelliği, 0 hata durumu ve esz: UNAVAILABLE: ... ana makinesi çözümlenemiyor hatasıyla başarısız oldu.	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, tüm bu kurulum hatası durumları checkFeatureStatus() veya checkStatus() API'leri tarafından yakalanabilir. İlgili kullanıcı arayüzünü göstermeden önce checkFeatureStatus() veya checkStatus() yöntemini çağırdığınızdan emin olun. Böylece uygulama kullanıcılarınız bu hataları hiçbir durumda görmez.