全新推出：LiteRT：Google 专为设备端 AI 打造的高性能运行时，以前称为 TensorFlow Lite。

此页面由 Cloud Translation API 翻译。

适用于 Android 的图片嵌入指南

借助 MediaPipe 图片嵌入任务，您可以将图片数据转换为数字表示法，以执行与机器学习相关的图片处理任务，例如比较两张图片的相似性。以下说明介绍了如何将图片嵌入器与 Android 应用搭配使用。

如需详细了解此任务的功能、模型和配置选项，请参阅概览。

代码示例

MediaPipe Tasks 示例代码是对 Android 图片嵌入器应用的简单实现。该示例使用实体 Android 设备上的摄像头持续嵌入图片，还可以在设备上存储的图片文件上运行嵌入器。

您可以将该应用用作您自己的 Android 应用的起点，也可以在修改现有应用时参考该应用。图片嵌入器示例代码托管在 GitHub 上。

下载代码

以下说明介绍了如何使用 git 命令行工具创建示例代码的本地副本。

如需下载示例代码，请执行以下操作：

使用以下命令克隆 Git 代码库：

git clone https://github.com/google-ai-edge/mediapipe-samples

（可选）将您的 Git 实例配置为使用稀疏检出，以便您只保留 Image Embedder 示例应用的文件：
```
cd mediapipe
git sparse-checkout init --cone
git sparse-checkout set examples/image_embedder/android
```

创建示例代码的本地版本后，您可以将项目导入 Android Studio 并运行应用。如需了解相关说明，请参阅 Android 设置指南。

关键组件

以下文件包含此图片嵌入器示例应用的重要代码：

ImageEmbedderHelper.kt：初始化图片嵌入器，并处理模型和代理选择。
MainActivity.kt：实现应用并组装界面组件。

设置

本部分介绍了设置开发环境和代码项目以使用图片嵌入工具的关键步骤。如需了解如何设置开发环境以使用 MediaPipe 任务（包括平台版本要求）的一般信息，请参阅 Android 设置指南。

依赖项

图片嵌入器使用 com.google.mediapipe:tasks-vision 库。将此依赖项添加到 Android 应用开发项目的 build.gradle 文件中。使用以下代码导入所需的依赖项：

dependencies {
    ...
    implementation 'com.google.mediapipe:tasks-vision:latest.release'
}

型号

MediaPipe 图片嵌入任务需要与此任务兼容的训练模型。如需详细了解适用于图片嵌入器的可用训练模型，请参阅任务概览中的“模型”部分。

选择并下载模型，然后将其存储在项目目录中：

<dev-project-root>/src/main/assets

在 ModelAssetPath 参数中指定模型的路径。在示例代码中，模型在 ImageEmbedderHelper.kt 文件的 setupImageEmbedder() 函数中定义：

使用 BaseOptions.Builder.setModelAssetPath() 方法指定模型使用的路径。下一部分的代码示例中会提及此方法。

创建任务

您可以使用 createFromOptions 函数创建任务。createFromOptions 函数接受配置选项来设置嵌入选项。如需详细了解配置选项，请参阅配置概览。

图片嵌入任务支持 3 种输入数据类型：静态图片、视频文件和实时视频直播。创建任务时，您需要指定与输入数据类型对应的运行模式。选择与输入数据类型对应的标签页，了解如何创建任务和运行推理。

Image

ImageEmbedderOptions options =
  ImageEmbedderOptions.builder()
    .setBaseOptions(
      BaseOptions.builder().setModelAssetPath("model.tflite").build())
    .setQuantize(true)
    .setRunningMode(RunningMode.IMAGE)
    .build();
imageEmbedder = ImageEmbedder.createFromOptions(context, options);

视频

ImageEmbedderOptions options =
  ImageEmbedderOptions.builder()
    .setBaseOptions(
      BaseOptions.builder().setModelAssetPath("model.tflite").build())
    .setQuantize(true)
    .setRunningMode(RunningMode.VIDEO)
    .build();
imageEmbedder = ImageEmbedder.createFromOptions(context, options);

直播

ImageEmbedderOptions options =
  ImageEmbedderOptions.builder()
    .setBaseOptions(
      BaseOptions.builder().setModelAssetPath("model.tflite").build())
    .setQuantize(true)
    .setRunningMode(RunningMode.LIVE_STREAM)
    .setResultListener((result, inputImage) -> {
         // Process the embedding result here.
    })
    .build();
imageEmbedder = ImageEmbedder.createFromOptions(context, options);

示例代码实现允许用户在处理模式之间切换。这种方法会使任务创建代码变得更加复杂，可能不适合您的用例。您可以在 ImageEmbedderHelper.kt 文件的 setupImageEmbedder() 函数中看到此代码。

配置选项

此任务针对 Android 应用提供了以下配置选项：

选项名称	说明	值范围	默认值
`runningMode`	设置任务的运行模式。共有三种模式： IMAGE：适用于单张图片输入的模式。视频：视频的解码帧的模式。 LIVE_STREAM：输入数据（例如来自摄像头）的直播模式。在此模式下，必须调用 resultListener 以设置监听器以异步接收结果。	{`IMAGE, VIDEO, LIVE_STREAM`}	`IMAGE`
`l2_normalize`	是否使用 L2 范数对返回的特征向量进行归一化。仅当模型尚不包含原生 L2_NORMALIZATION TFLite 运算时，才应使用此选项。在大多数情况下，已经是这种情况，因此 L2 归一化是通过 TFLite 推理实现的，而无需此选项。	`Boolean`	`False`
`quantize`	是否应通过标量量化将返回的嵌入量化为字节。系统会隐式假定嵌入的范数为 1，因此任何维度的值都保证在 [-1.0, 1.0] 之间。如果不是这种情况，请使用 l2_normalize 选项。	`Boolean`	`False`
`resultListener`	设置结果监听器，以便在图片嵌入器处于直播模式时异步接收嵌入结果。仅当运行模式设置为 `LIVE_STREAM` 时才能使用	不适用	未设置
`errorListener`	设置可选的错误监听器。	不适用	未设置

准备数据

图片嵌入工具可处理图片、视频文件和直播视频。该任务会处理数据输入预处理，包括调整大小、旋转和值归一化。

您需要先将输入图片或帧转换为 com.google.mediapipe.framework.image.MPImage 对象，然后才能将其传递给图片嵌入任务。

Image

import com.google.mediapipe.framework.image.BitmapImageBuilder;
import com.google.mediapipe.framework.image.MPImage;

// Load an image on the user’s device as a Bitmap object using BitmapFactory.

// Convert an Android’s Bitmap object to a MediaPipe’s Image object.
Image mpImage = new BitmapImageBuilder(bitmap).build();

视频

import com.google.mediapipe.framework.image.BitmapImageBuilder;
import com.google.mediapipe.framework.image.MPImage;

// Load a video file on the user's device using MediaMetadataRetriever

// From the video’s metadata, load the METADATA_KEY_DURATION and
// METADATA_KEY_VIDEO_FRAME_COUNT value. You’ll need them
// to calculate the timestamp of each frame later.

// Loop through the video and load each frame as a Bitmap object.

// Convert the Android’s Bitmap object to a MediaPipe’s Image object.
Image mpImage = new BitmapImageBuilder(frame).build();

直播

import com.google.mediapipe.framework.image.MediaImageBuilder;
import com.google.mediapipe.framework.image.MPImage;

// Create a CameraX’s ImageAnalysis to continuously receive frames
// from the device’s camera. Configure it to output frames in RGBA_8888
// format to match with what is required by the model.

// For each Android’s ImageProxy object received from the ImageAnalysis,
// extract the encapsulated Android’s Image object and convert it to
// a MediaPipe’s Image object.
android.media.Image mediaImage = imageProxy.getImage()
Image mpImage = new MediaImageBuilder(mediaImage).build();

在示例代码中，数据准备是在 ImageEmbedderHelper.kt 文件中处理的。

运行任务

您可以调用与运行模式对应的 embed 函数来触发推理。Image Embedder API 会返回输入图片或帧的嵌入向量。

Image

ImageEmbedderResult embedderResult = imageEmbedder.embed(image);

视频

// Calculate the timestamp in milliseconds of the current frame.
long frame_timestamp_ms = 1000 * video_duration * frame_index / frame_count;

// Run inference on the frame.
ImageEmbedderResult embedderResult =
    imageEmbedder.embedForVideo(image, frameTimestampMs);

直播

// Run inference on the frame. The embedding results will be available
// via the `resultListener` provided in the `ImageEmbedderOptions` when
// the image embedder was created.
imageEmbedder.embedAsync(image, frameTimestampMs);

请注意以下几点：

在视频模式或直播模式下运行时，您还必须向图片嵌入任务提供输入帧的时间戳。
在图片或视频模式下运行时，图片嵌入任务将阻塞当前线程，直到其处理完输入图片或帧。为避免阻塞当前线程，请在后台线程中执行处理。
在直播模式下运行时，图片嵌入程序任务不会阻塞当前线程，而是会立即返回。每当它处理完输入帧后，都会调用其结果监听器并传递检测结果。如果在图片嵌入任务忙于处理其他帧时调用 embedAsync 函数，该任务会忽略新的输入帧。

在示例代码中，embed 函数在 ImageEmbedderHelper.kt 文件中定义。

处理和显示结果

运行推理后，图片嵌入任务会返回一个 ImageEmbedderResult 对象，其中包含输入图片的嵌入列表（浮点或标量量化）。

以下是此任务的输出数据示例：

ImageEmbedderResult:
  Embedding #0 (sole embedding head):
    float_embedding: {0.0, 0.0, ..., 0.0, 1.0, 0.0, 0.0, 2.0}
    head_index: 0

此结果是通过嵌入以下图片获得的：

异国猫的中景镜头

您可以使用 ImageEmbedder.cosineSimilarity 函数比较两个嵌入的类似程度。如需查看示例，请参阅以下代码。

// Compute cosine similarity.
double similarity = ImageEmbedder.cosineSimilarity(
  result.embeddingResult().embeddings().get(0),
  otherResult.embeddingResult().embeddings().get(0));