适用于 Android 的文本嵌入指南

借助 MediaPipe Text Embedder 任务,您可以创建文本数据的数字表示形式,以捕获其语义含义。以下说明介绍了如何在 Android 应用中使用文本嵌入器。

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

代码示例

MediaPipe Tasks 示例代码是 Android 版文本嵌入器应用的简单实现。该示例评估了两段文本之间的语义相似度,因此需要使用实体 Android 设备或 Android 模拟器。

您可以使用该应用作为基础来开发自己的 Android 应用,也可以在修改现有应用时参考该应用。文本嵌入器示例代码托管在 GitHub 上。

下载代码

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

如需下载示例代码,请执行以下操作:

  1. 使用以下命令克隆 Git 代码库:
    git clone https://github.com/google-ai-edge/mediapipe-samples
    
  2. (可选)将您的 Git 实例配置为使用稀疏检出,以便只有文本嵌入器示例应用的文件:
    cd mediapipe
    git sparse-checkout init --cone
    git sparse-checkout set examples/text_embedder/android
    

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

关键组件

以下文件包含此文本嵌入器示例应用的关键代码:

初始设置

本部分介绍了专门针对使用文本嵌入器而设置开发环境和代码项目的关键步骤。如需了解如何为使用 MediaPipe 任务设置开发环境的一般信息(包括平台版本要求),请参阅 Android 设置指南

依赖项

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

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

模型

MediaPipe Text Embedder 任务需要一个与此任务兼容的经过训练的模型。如需详细了解文本嵌入器可用的经过训练的模型,请参阅任务概览“模型”部分

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

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

ModelAssetPath 参数中指定模型的路径。在示例代码中,模型在 TextEmbedderHelper.kt 文件中的 setupTextEmbedder() 函数中定义:

使用 BaseOptions.Builder.setModelAssetPath() 函数指定模型使用的路径。下一部分的代码示例将引用此方法。

创建任务

您可以使用其中一个 createFrom...() 函数来创建任务。createFromOptions() 函数接受配置选项来设置嵌入器选项。您还可以使用 createFromFile() 工厂函数初始化任务。createFromFile() 函数接受经过训练的模型文件的相对或绝对路径。如需详细了解配置选项,请参阅配置选项

以下代码演示了如何构建和配置此任务。

val baseOptions = baseOptionsBuilder.build()
val optionsBuilder =
    TextEmbedderOptions.builder().setBaseOptions(baseOptions)
val options = optionsBuilder.build()
textEmbedder = TextEmbedder.createFromOptions(context, options)

示例代码实现在 TextEmbedderHelper.kt 文件的 setupTextEmbedder() 函数中设置文本嵌入器选项。

配置选项

此任务具有以下 Android 应用的配置选项:

选项名称 说明 值范围 默认值
l2_normalize 是否以 L2 范数归一化返回的特征向量。 仅当模型尚未包含原生 L2_NORMALIZATION TFLite 运算时,才可使用此选项。在大多数情况下,情况都是如此,L2 归一化是通过 TFLite 推断实现的,因此无需使用此选项。 Boolean False
quantize 是否应通过标量量化将返回的嵌入量化为字节。嵌入被隐式假定为单位范数,因此任何维度的值都必须在 [-1.0, 1.0] 之间。如果不属于这种情况,请使用 l2_normalize 选项。 Boolean False

准备数据

文本嵌入器可处理文本 (String) 数据。该任务会处理数据输入预处理,包括标记化和张量预处理。所有预处理都在 embed() 函数中处理。无需事先对输入文本进行额外的预处理。

val inputText = "The input text to be embedded."

运行任务

Text Embedder 使用 embed 函数来触发推断。对于文本嵌入,这意味着返回输入文本的嵌入向量。

以下代码演示了如何使用任务模型执行处理。

textEmbedder?.let {
    val firstEmbed =
        it.embed(firstText).embeddingResult().embeddings().first()
    val secondEmbed =
        it.embed(secondText).embeddingResult().embeddings().first()
    ...
}

在示例代码中,embed 函数在 TextEmbedderHelper.kt 文件中调用。

处理和显示结果

运行推断时,Text Embedder 任务会返回一个 TextEmbedderResult 对象,该对象包含输入文本的一系列嵌入(浮点数或标量量化)。

下面显示了此任务的输出数据示例:

TextEmbedderResult:
  Embedding #0 (sole embedding head):
    float_embedding: {0.2345f, 0.1234f, ..., 0.6789f}
    head_index: 0

您可以使用 TextEmbedder.cosineSimilarity 函数比较两个嵌入的语义相似度。有关示例,请参阅以下代码。

val similarity = TextEmbedder.cosineSimilarity(firstEmbed, secondEmbed)

在示例代码中,TextEmbedder.cosineSimilarity() 函数在 TextEmbedderHelper.kt 文件中调用。