GenAI Image Description API

這個 API 目前仍在測試階段，不適用任何服務水準協議或廢止政策。這個 API 可能會變更，導致回溯相容性中斷。

您可以使用 ML Kit 的 GenAI 圖片說明 API，為圖片產生簡短內容說明。這項功能可用於下列用途：

• 產生圖片標題
• 產生替代文字，協助視障使用者更容易理解圖片內容
• 使用產生的說明做為中繼資料，協助使用者搜尋或整理圖片
• 在使用者無法看著螢幕時使用圖片的簡短說明，例如在開車或收聽 Podcast 時

主要功能

• 傳回輸入圖片的簡短說明

搜尋結果範例

輸入功率	輸出內容
	一個小型綠色 Android 機器人，外型類似仙人掌，放在黑色表面上。
	一隻小白狗，黑鼻子和粉紅舌頭，在草地上跑來跑去，背景是一座橋。

開始使用

注意： 此 API 需要 Android API 級別 26 以上。

如要開始使用 GenAI Image Description API，請將這個依附元件新增至專案的建構檔案。

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

支援的功能和限制

GenAI 圖片說明 API 支援英文，日後將支援更多語言。API 會傳回圖片的簡短說明。

特定功能設定 (由 ImageDescriberOptions 指定) 是否可用，可能會因特定裝置的設定和已下載至裝置的型號而異。

開發人員如要確保裝置支援指定 API 功能，並提供所要求的 ImageDescriberOptions，最可靠的方法就是呼叫 checkFeatureStatus() 方法。這個方法會在執行階段提供裝置上功能可用性的確切狀態。

注意： 不同裝置類型的硬體可能有所差異，因此 Gemini Nano 基本模型版本也會有所不同，進而影響 ML Kit GenAI API 的輸出結果。我們會套用 LoRA 轉接器來減輕差異。

常見的設定問題

注意： 裝置的解鎖式引導程序不支援此 API。

ML Kit GenAI API 需要透過 Android AICore 應用程式存取 Gemini Nano。裝置剛設定完畢 (包括重設)，或 AICore 應用程式剛重設 (例如清除資料、解除安裝再重新安裝)，AICore 應用程式可能沒有足夠的時間完成初始化程序 (包括從伺服器下載最新設定)。因此，ML Kit GenAI API 可能無法正常運作。以下是您可能會看到的常見設定錯誤訊息，以及如何處理：

錯誤訊息示例	如何處理
AICore 發生錯誤，錯誤類型為 4-CONNECTION_ERROR，錯誤代碼為 601-BINDING_FAILURE：AICore 服務繫結失敗。	當您在裝置設定完成後立即使用 ML Kit GenAI API 安裝應用程式，或是在應用程式安裝完成後解除安裝 AICore 時，就可能發生這種情況。更新 AICore 應用程式，然後重新安裝應用程式，應該就能解決問題。
AICore 失敗，錯誤類型為 3-PREPARATION_ERROR，錯誤代碼為 606-FEATURE_NOT_FOUND：無法使用功能...。	當 AICore 尚未完成下載最新設定時，就可能發生這種情況。保持網路連線，並等待幾分鐘到幾小時。 請注意，如果裝置的系統啟動載入程式已解鎖，您也會看到這則錯誤訊息，因為這個 API 不支援裝置的系統啟動載入程式已解鎖。
AICore 失敗，錯誤類型為 1-DOWNLOAD_ERROR，錯誤代碼為 0-UNKNOWN：功能 ... 失敗，失敗狀態為 0，錯誤 esz：UNAVAILABLE：無法解析主機 ...	保持網路連線，稍待幾分鐘後再重試。

注意： 雖然各種重設作業對開發人員來說很常見，但對使用者來說則較為罕見。此外，所有設定失敗的情況都會由 checkFeatureStatus() API 偵測到。請務必先呼叫 checkFeatureStatus()，再顯示任何相關 UI，這樣應用程式使用者在任何情況下都不會看到這些錯誤。