GenAI Image Description API

此 API 目前处于 Beta 版阶段，不受任何服务等级协议 (SLA) 或弃用政策的约束。此 API 可能会发生破坏向后兼容性的更改。

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

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

主要功能

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

示例结果

输入	输出
	一个外形类似仙人掌的绿色小 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。

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