iOS 文字嵌入指南

文字嵌入器工作可讓您建立文字資料的數值表示法,以便擷取其語意意義。本操作說明說明如何在 iOS 應用程式中使用文字嵌入工具。

您可以查看這個網頁示範,瞭解這項工作的實際運作情形。如要進一步瞭解此任務的功能、模型和設定選項,請參閱總覽

程式碼範例

Text Embedder 的程式碼範例提供 iOS 應用程式的基本實作方式,可整合這項工作。這個範例會評估兩段文字之間的語意相似度,並需要實體 iOS 裝置或 iOS 模擬器。

您可以使用該應用程式做為自有 iOS 應用程式的起點,或是在修改現有應用程式時參考該應用程式。您可以參考 GitHub 上的 Text Embedder 範例程式碼。

下載程式碼

以下操作說明說明如何使用 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 設定指南

重要元件

下列檔案包含 Text Embedder 範例應用程式的重要程式碼:

設定

本節將說明設定開發環境和程式碼專案以使用文字嵌入功能的關鍵步驟。如要進一步瞭解如何設定開發環境以使用 MediaPipe 工作,包括平台版本需求,請參閱 iOS 設定指南

依附元件

Text Embedder 會使用 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 文字嵌入器工作需要與這項工作相容的已訓練模型。如要進一步瞭解適用於文字嵌入器的已訓練模型,請參閱工作總覽模型章節

選取並下載模型,然後使用 Xcode 將模型新增至專案目錄。如需在 Xcode 專案中新增檔案的操作說明,請參閱「管理 Xcode 專案中的檔案和資料夾」。

使用 BaseOptions.modelAssetPath 屬性指定應用程式套件中的模型路徑。如需程式碼範例,請參閱下一節。

建立工作

您可以呼叫其中一個初始化器,建立文字嵌入器工作。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 運算時,才使用這個選項。在大多數情況下,模型都已包含這個運算,因此可透過 TFLite 推論達成 L2 規格化,而不需要使用這個選項。 Boolean False
quantize 是否應透過純量量化,將傳回的嵌入值量化為位元組。默認會假設嵌入為單位非單位,因此所有維度保證都會有 [-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 並行處理執行背景執行緒。

在範例程式碼中,embed(text:) 方法會在 TextEmbedderService.swift 檔案中呼叫。

處理及顯示結果

執行推論時,文字嵌入器工作會傳回 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 檔案中呼叫。