适用于 iOS 的文本嵌入指南

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

您可以查看此 Web 演示,了解此任务的实际运作方式。如需详细了解此任务的功能、模型和配置选项,请参阅概览

代码示例

Text Embedder 的示例代码提供了集成此任务的 iOS 应用的基本实现。该示例会评估两段文本之间的语义相似度,并且需要一台实体 iOS 设备或 iOS 模拟器。

您可以将该应用用作您自己的 iOS 应用的起点,也可以在修改现有应用时参考该应用。您可以参阅 GitHub 上的文本嵌入器示例代码。

下载代码

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

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

  1. 使用以下命令克隆 git 代码库:

    git clone https://github.com/google-ai-edge/mediapipe-samples
    
  2. (可选)将您的 Git 实例配置为使用稀疏检出,以便您只保留 Text Embedder 示例应用的文件:

    cd mediapipe
    git sparse-checkout init --cone
    git sparse-checkout set examples/text_embedder/ios/
    

创建示例代码的本地版本后,您可以安装 MediaPipe 任务库,使用 Xcode 打开项目并运行应用。如需了解相关说明,请参阅 适用于 iOS 的设置指南

关键组件

以下文件包含文本嵌入器示例应用的重要代码:

设置

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

依赖项

文本嵌入器使用 MediaPipeTasksText 库,该库必须使用 CocoaPods 安装。该库与 Swift 和 Objective-C 应用兼容,并且无需任何额外的语言专用设置。

如需了解如何在 macOS 上安装 CocoaPods,请参阅 CocoaPods 安装指南。如需了解如何使用应用所需的 Pod 创建 Podfile,请参阅使用 CocoaPods

使用以下代码在 Podfile 中添加 MediaPipeTasksText pod:

target 'MyTextEmbedderApp' do
  use_frameworks!
  pod 'MediaPipeTasksText'
end

如果您的应用包含单元测试目标,请参阅 iOS 设置指南,详细了解如何设置 Podfile

型号

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

选择并下载模型,然后使用 Xcode 将其添加到您的项目目录。 如需了解如何向 Xcode 项目添加文件,请参阅管理 Xcode 项目中的文件和文件夹

使用 BaseOptions.modelAssetPath 属性指定 app bundle 中的模型路径。如需查看代码示例,请参阅下一部分。

创建任务

您可以通过调用其某个初始化程序来创建文本嵌入任务。TextEmbedder(options:) 初始化程序接受配置选项的值。

如果您不需要使用自定义配置选项初始化文本嵌入器,则可以使用 TextEmbedder(modelPath:) 初始化程序使用默认选项创建文本嵌入器。如需详细了解配置选项,请参阅配置概览

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

Swift

import MediaPipeTasksText

let modelPath = Bundle.main.path(forResource: "model",
                                      ofType: "tflite")

let options = TextEmbedderOptions()
options.baseOptions.modelAssetPath = modelPath
options.quantize = true

let textEmbedder = try TextEmbedder(options: options)

Objective-C

@import MediaPipeTasksText;

NSString *modelPath = [[NSBundle mainBundle] pathForResource:@"model"
                                                      ofType:@"tflite"];

MPPTextEmbedderOptions *options = [[MPPTextEmbedderOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.quantize = YES;

MPPTextEmbedder *textEmbedder =
      [[MPPTextEmbedder alloc] initWithOptions:options error:nil];

配置选项

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

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

运行任务

如需嵌入输入文本并获取其嵌入向量,您可以使用 TextEmbedderembed(text:) 方法。

Swift

let result = try textEmbedder.embed(text: text)

Objective-C

MPPTextEmbedderResult *result = [textEmbedder embedText:text
                                                  error:nil];

注意:该任务会阻塞当前线程,直到其完成对文本的推理为止。为避免阻塞当前线程,请使用 iOS DispatchNSOperation 框架在后台线程中执行处理。如果您的应用是使用 Swift 创建的,则您还可以使用 Swift 并发功能在后台线程执行。

在示例代码中,系统会在 TextEmbedderService.swift 文件中调用 embed(text:) 方法。

处理和显示结果

运行推理后,文本嵌入任务会返回一个 TextEmbedderResult 对象,其中包含输入文本的嵌入列表(浮点或标量量化)。

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

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

您可以使用 TextEmbedder.cosineSimilarity 方法比较两个嵌入的语义相似性。

Swift

let similarity = try TextEmbedder.cosineSimilarity(
  embedding1: result.embeddingResult.embeddings[0],
  embedding2: otherResult.embeddingResult.embeddings[0])
    

Objective-C

NSNumber *similarity = [MPPTextEmbedder
      cosineSimilarityBetweenEmbedding1:result.embeddingResult.embeddings[0]
                          andEmbedding2:otherResult.embeddingResult.embeddings[0]
                                  error:nil];
    

在示例代码中,TextEmbedder.cosineSimilarity 方法在 TextEmbedderService.swift 文件中调用。