GenAI Image Description API

Bu API beta sürümünde sunulur ve herhangi bir HDS veya kullanımdan kaldırma politikasına tabi değildir. Bu API'de, geriye dönük uyumluluğu bozan değişiklikler yapılabilir.

ML Kit'in GenAI Resim Açıklaması API'si ile resimler için kısa içerik açıklamaları oluşturabilirsiniz. Bu, aşağıdaki kullanım alanlarında yararlı olabilir:

• Resim başlıkları oluşturma
• Görme engelli kullanıcıların görsellerin içeriğini daha iyi anlamasına yardımcı olmak için alternatif metin (alt metin) oluşturma
• Kullanıcıların resimleri aramasına veya düzenlemesine yardımcı olmak için oluşturulan açıklamaları meta veri olarak kullanma
• Kullanıcı ekranına bakamadığında (ör. araç kullanırken veya podcast dinlerken) resimlerin kısa açıklamalarını kullanma

Temel özellikler

• Giriş resmi için kısa bir açıklama döndürme

Örnek sonuçlar

Giriş	Çıkış
	Kaktüse benzeyen bir tasarıma sahip küçük, yeşil bir Android robot siyah bir yüzeyin üzerinde duruyor.
	Siyah burunlu ve pembe dilli küçük, beyaz bir köpek, arka planda köprü bulunan çimenlik bir alanda koşuyor.

Başlarken

Not: Bu API için Android API düzeyi 26 veya daha yeni bir sürüm gerekir.

GenAI Image Description API'yi kullanmaya başlamak için bu bağımlılığı projenizin derleme dosyasına ekleyin.

implementation("com.google.mlkit:genai-image-description:1.0.0-beta1")

Görüntü Açıklaması API'sini uygulamanıza entegre etmek için bir ImageDescriber istemcisi edinerek başlarsınız. Ardından, gerekli cihaz üzerindeki model özelliklerinin durumunu kontrol etmeniz ve cihazda yoksa modeli indirmeniz gerekir. Görüntü girişinizi ImageDescriptionRequest olarak hazırladıktan sonra, görüntü açıklaması metnini almak için istemciyi kullanarak çıkarım işlemini çalıştırın ve son olarak, kaynakları serbest bırakmak için istemciyi kapatmayı unutmayın.

Kotlin

// Create an image describer
val options = ImageDescriberOptions.builder(context).build()
val imageDescriber = ImageDescription.getClient(options)

suspend fun prepareAndStartImageDescription(
    bitmap: Bitmap
) {
  // Check feature availability, status will be one of the following:
  // UNAVAILABLE, DOWNLOADABLE, DOWNLOADING, AVAILABLE
  val featureStatus = imageDescriber.checkFeatureStatus().await()

  if (featureStatus == FeatureStatus.DOWNLOADABLE) {
      // Download feature if necessary.
      // If downloadFeature is not called, the first inference request
      // will also trigger the feature to be downloaded if it's not
      // already downloaded.
      imageDescriber.downloadFeature(object : DownloadCallback {
          override fun onDownloadStarted(bytesToDownload: Long) { }

          override fun onDownloadFailed(e: GenAiException) { }

          override fun onDownloadProgress(totalBytesDownloaded: Long) {}

          override fun onDownloadCompleted() {
              startImageDescriptionRequest(bitmap, imageDescriber)
          }
      })
  } else if (featureStatus == FeatureStatus.DOWNLOADING) {
      // Inference request will automatically run once feature is
      // downloaded.
      // If Gemini Nano is already downloaded on the device, the
      // feature-specific LoRA adapter model will be downloaded
      // very quickly. However, if Gemini Nano is not already
      // downloaded, the download process may take longer.
      startImageDescriptionRequest(bitmap, imageDescriber)
  } else if (featureStatus == FeatureStatus.AVAILABLE) {
      startImageDescriptionRequest(bitmap, imageDescriber)
  }
}

fun startImageDescriptionRequest(
    bitmap: Bitmap,
    imageDescriber: ImageDescriber
) {
    // Create task request
    val imageDescriptionRequest = ImageDescriptionRequest
        .builder(bitmap)
        .build()
}

  // Run inference with a streaming callback
  val imageDescriptionResultStreaming =
      imageDescriber.runInference(imageDescriptionRequest) { outputText ->
          // Append new output text to show in UI
          // This callback is called incrementally as the description
          // is generated
      }

  // You can also get a non-streaming response from the request
  // val imageDescription = imageDescriber.runInference(
  //        imageDescriptionRequest).await().description
}

// Be sure to release the resource when no longer needed
// For example, on viewModel.onCleared() or activity.onDestroy()
imageDescriber.close()

Java

// Create an image describer
ImageDescriberOptions options = ImageDescriberOptions.builder(context).build();
ImageDescriber imageDescriber = ImageDescription.getClient(options);

void prepareAndStartImageDescription(
      Bitmap bitmap
) throws ExecutionException, InterruptedException {
  // Check feature availability, status will be one of the following:
  // UNAVAILABLE, DOWNLOADABLE, DOWNLOADING, AVAILABLE
  try {
      int featureStatus = imageDescriber.checkFeatureStatus().get();
      if (featureStatus == FeatureStatus.DOWNLOADABLE) {
          // Download feature if necessary.
          // If downloadFeature is not called, the first inference request
          // will also trigger the feature to be downloaded if it's not
          // already downloaded.
          imageDescriber.downloadFeature(new DownloadCallback() {
              @Override
              public void onDownloadCompleted() {
                  startImageDescriptionRequest(bitmap, imageDescriber);
              }

              @Override
              public void onDownloadFailed(GenAIException e) {}

              @Override
              public void onDownloadProgress(long totalBytesDownloaded) {}

              @Override
              public void onDownloadStarted(long bytesDownloaded) {}
          });
      } else if (featureStatus == FeatureStatus.DOWNLOADING) {
          // Inference request will automatically run once feature is
          // downloaded.
          // If Gemini Nano is already downloaded on the device, the
          // feature-specific LoRA adapter model will be downloaded
          // very quickly. However, if Gemini Nano is not already
          // downloaded, the download process may take longer.
          startImageDescriptionRequest(bitmap, imageDescriber);
      } else if (featureStatus == FeatureStatus.AVAILABLE) {
          startImageDescriptionRequest(bitmap, imageDescriber);
      }
  } catch (ExecutionException | InterruptedException e) {
      e.printStackTrace();
  }
}

void startImageDescriptionRequest(
     Bitmap bitmap,
     ImageDescriber imageDescriber
) {
  // Create task request
  ImageDescriptionRequest imageDescriptionRequest =
          ImageDescriptionRequest.builder(bitmap).build();

  // Start image description request with streaming response
  imageDescriber.runInference(imageDescriptionRequest, newText -> {
      // Append new output text to show in UI
      // This callback is called incrementally as the description
      // is generated
  });

  // You can also get a non-streaming response from the request
  // String imageDescription = imageDescriber.runInference(
  //        imageDescriptionRequest).get().getDescription();
}

// Be sure to release the resource when no longer needed
// For example, on viewModel.onCleared() or activity.onDestroy()
imageDescriber.close();

Desteklenen özellikler ve sınırlamalar

GenAI Image Description API, İngilizce'yi destekler. Gelecekte daha fazla dil için destek eklenecektir. API, resmin kısa bir açıklamasını döndürür.

Belirli özellik yapılandırmasının (ImageDescriberOptions ile belirtilir) kullanılabilirliği, ilgili cihazın yapılandırmasına ve cihaza indirilen modellere bağlı olarak değişiklik gösterebilir.

Geliştiricilerin, istenen ImageDescriberOptions özelliğine sahip bir cihazda istenen API özelliğinin desteklenip desteklenmediğini kontrol etmenin en güvenilir yolu checkFeatureStatus() yöntemini çağırmaktır. Bu yöntem, çalışma zamanında cihazda özellik kullanılabilirliğinin kesin durumunu sağlar.

Not: Farklı cihaz türlerindeki donanım farklılıkları, Gemini Nano temel model sürümlerinde ve dolayısıyla ML Kit GenAI API çıkışlarında farklılıklara neden olabilir. Farklılıkları azaltmak için LoRA adaptörleri uygulanır.

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

Not: Bu API, kilidi açık önyükleyici olan cihazlarda desteklenmez.

ML Kit GenAI API'leri, Gemini Nano'ya erişmek için Android AICore uygulamasından yararlanır. Bir cihaz yeni kurulduğunda (sıfırlama dahil) veya AICore uygulaması yeni sıfırlandığında (ör. veriler temizlenir, uygulama kaldırılır ve yeniden yüklenir), AICore uygulamasının ilklendirmeyi tamamlaması (sunucudan en son yapılandırmaların indirilmesi dahil) için yeterli zamanı olmayabilir. Sonuç olarak ML Kit GenAI API'leri beklendiği gibi çalışmayabilir. Karşılaşabileceğiniz yaygın kurulum hata mesajları ve bunların nasıl ele alınacağı aşağıda açıklanmıştır:

Örnek hata mesajı	Nasıl ele alınır?
AICore, 4-CONNECTION_ERROR hata türü ve 601-BINDING_FAILURE hata koduyla başarısız oldu: AICore hizmeti bağlanamadı.	Bu durum, uygulamayı cihaz kurulumundan hemen sonra ML Kit GenAI API'lerini kullanarak yüklediğinizde veya uygulamanız yüklendikten sonra AICore'un kaldırıldığı durumlarda ortaya çıkabilir. AICore uygulamasını güncelleyip uygulamanızı yeniden yüklediğinizde sorun düzelecektir.
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 ortaya çıkabilir. Ağ bağlantısını koruyun ve birkaç dakika ila birkaç saat bekleyin. Cihazın önyükleyicisinin kilidi açıksa bu hatayı da göreceğinizi unutmayın. Bu API, önyükleyicisinin kilidi açık 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 hatasıyla başarısız oldu: UNAVAILABLE: Unable to resolve host ...	Ağ bağlantısını koruyun, birkaç dakika bekleyip tekrar deneyin.

Not: Çeşitli sıfırlamalar geliştiriciler için yaygın olsa da kullanıcılar için çok daha seyrektir. Ayrıca, tüm bu kurulum hatası durumları checkFeatureStatus() API tarafından yakalanabilir. Uygulama kullanıcılarınızın bu hataları hiçbir durumda görmemesi için ilgili kullanıcı arayüzünü göstermeden önce checkFeatureStatus() işlevini çağırdığınızdan emin olun.