GenAI Image Description API

באמצעות GenAI Image Description API של ML Kit, אפשר ליצור תיאורי תוכן קצרים לתמונות. אפשר להשתמש באפשרות הזו בתרחישי השימוש הבאים:

  • יצירת שמות של תמונות
  • יצירת טקסט חלופי (טקסט alt) שיעזור למשתמשים עם ליקויי ראייה להבין טוב יותר את התוכן של התמונות
  • שימוש בתיאורים שנוצרו כמטא-נתונים כדי לעזור למשתמשים לחפש או לארגן תמונות
  • שימוש בתיאורים קצרים של תמונות כשהמשתמש לא יכול להסתכל במסך, למשל כשהוא נוהג או מאזין לפודקאסט

יכולות עיקריות

  • החזרת תיאור קצר של תמונה להזנה

תוצאות לדוגמה

קלט פלט
רובוט קטן וירוק של Android עם עיצוב של קקטוס, יושב על משטח שחור. רובוט קטן וירוק של Android עם עיצוב של קקטוס, ניצב על משטח שחור.
כלב לבן קטן עם אף שחור ולשון ורודה רץ בשדה דשא עם גשר ברקע. כלב לבן קטן עם אף שחור ולשון ורודה רץ בשדה דשא עם גשר ברקע.

תחילת העבודה

כדי להתחיל להשתמש ב-GenAI Image Description API, מוסיפים את התלות הזו לקובץ ה-build של הפרויקט.

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

כדי לשלב את Image Description API באפליקציה, צריך קודם ליצור לקוח ImageDescriber. לאחר מכן צריך לבדוק את הסטטוס של תכונות המודל הנדרשות במכשיר ולהוריד את המודל אם הוא עדיין לא נמצא במכשיר. אחרי שמכינים את קלט התמונה ב-ImageDescriptionRequest, מפעילים את ההסקה באמצעות הלקוח כדי לקבל את טקסט תיאור התמונה, ולבסוף, חשוב לזכור לסגור את הלקוח כדי לשחרר את המשאבים.

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();

תכונות נתמכות ומגבלות

ה-API לתיאור תמונות של GenAI תומך באנגלית, ובעתיד נוסיף תמיכה בשפות נוספות. ה-API מחזיר תיאור קצר אחד של התמונה.

הזמינות של הגדרת התכונה הספציפית (שצוינה על ידי ImageDescriberOptions) עשויה להשתנות בהתאם לתצורה של המכשיר הספציפי ולדגמים שהורדתם למכשיר.

הדרך הבטוחה ביותר למפתחים לוודא שתכונה מסוימת של ה-API נתמכת במכשיר עם ImageDescriberOptions המבוקש היא לבצע קריאה ל-method‏ checkFeatureStatus(). השיטה הזו מספקת את הסטטוס המוחלט של זמינות התכונה במכשיר בזמן הריצה.

בעיות נפוצות בהגדרה

ממשקי ה-API של ML Kit GenAI מסתמכים על אפליקציית Android AICore כדי לגשת ל-Gemini Nano. כשמכשיר מוגדר זה עתה (כולל איפוס), או שאפליקציית AICore אופסה זה עתה (למשל, ניקוי הנתונים, הסרה והתקנה מחדש), יכול להיות שלא יהיה לאפליקציית AICore מספיק זמן לסיים את האיפוס (כולל הורדת ההגדרות האחרונות מהשרת). כתוצאה מכך, יכול להיות ש-ML Kit GenAI APIs לא יפעלו כמצופה. ריכזנו כאן את הודעות השגיאה הנפוצות במהלך ההגדרה ואת הדרכים לטיפול בהן:

דוגמה להודעת שגיאה איך מטפלים
AICore נכשל עם סוג השגיאה 4-CONNECTION_ERROR וקוד השגיאה 601-BINDING_FAILURE: שירות AICore נכשל בקישור. זה יכול לקרות אם מתקינים את האפליקציה באמצעות ממשקי ה-API של ML Kit GenAI מיד אחרי הגדרת המכשיר, או אם מסירים את AICore אחרי התקנת האפליקציה. כדי לפתור את הבעיה, צריך לעדכן את אפליקציית AICore ולאחר מכן להתקין מחדש את האפליקציה.
AICore נכשל עם שגיאת מסוג 3-PREPARATION_ERROR וקוד השגיאה 606-FEATURE_NOT_FOUND: התכונה ... לא זמינה. המצב הזה יכול לקרות אם AICore לא סיים להוריד את ההגדרות האחרונות. שומרים על חיבור לרשת ומחכים כמה דקות עד כמה שעות.

שימו לב: אם נעילת האתחול של המכשיר לא נעולה, תופיע גם השגיאה הזו – ממשק ה-API הזה לא תומך במכשירים עם נעילת אתחול לא נעולה.
AICore נכשל עם סוג השגיאה 1-DOWNLOAD_ERROR וקוד השגיאה 0-UNKNOWN: Feature ... failed with failure status 0 and error esz: UNAVAILABLE: Unable to resolve host ... שומרים על החיבור לרשת, ממתינים כמה דקות ומנסים שוב.