GenAI Image Description API

此 API 以 Beta 版形式提供，不受任何服务等级协议 (SLA) 或弃用政策的约束。此 API 可能会发生不向后兼容的更改。

借助 ML Kit 的 GenAI Image Description API，您可以为图片生成简短的内容说明。这在以下使用场景中非常有用：

• 生成图片标题
• 生成替代文字（图片替代文本），帮助视障用户更好地理解图片内容
• 使用生成的说明作为元数据，帮助用户搜索或整理图片
• 当用户无法查看屏幕时（例如在驾驶或收听播客时），利用简短的图片说明

主要功能

• 返回输入图片的简短说明

示例结果

输入	输出
	一个小型绿色 Android 机器人，外形像仙人掌，坐在黑色表面上。
	一只白色的小狗，黑色的鼻子，粉色的舌头，在草地上奔跑，背景是一座桥。

使用入门

注意： 此 API 需要 Android API 级别 26 或更高级别。

如需开始使用 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();

支持的功能和限制

GenAI Image Description API 支持英语，未来将支持更多语言。该 API 会返回一张图片的简短说明。

特定功能配置（由 ImageDescriberOptions 指定）的可用性可能因特定设备的配置和已下载到设备的模型而异。

对于开发者而言，确保设备支持具有所请求 ImageDescriberOptions 的预期 API 功能的最可靠方法是调用 checkFeatureStatus() 方法。此方法可在运行时提供设备上功能可用性的确定状态。

注意： 不同设备类型的硬件差异可能会导致 Gemini Nano 基本模型版本有所不同，进而导致 ML Kit GenAI API 输出有所不同。应用 LoRA 适配器来缓解这些差异。

常见设置问题

注意： 此 API 不受引导加载程序已解锁的设备支持。

机器学习套件生成式 AI 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()，然后再显示任何相关界面，这样您的应用用户在任何情况下都不会看到这些错误。