iOS 向けテキスト エンベディング ガイド

テキスト エンベディング タスクを使用すると、テキストデータの数値表現を作成して、その意味を取得できます。以下の手順では、iOS アプリでテキスト埋め込みツールを使用する方法について説明します。

このタスクの動作を確認するには、こちらのウェブデモをご覧ください。このタスクの機能、モデル、構成オプションの詳細については、概要をご覧ください。

サンプルコード

Text Embedder のサンプルコードには、このタスクを統合する iOS 用アプリの基本的な実装が用意されています。この例では、2 つのテキスト間の意味的な類似性を評価します。そのためには、物理的な 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 用セットアップガイドをご覧ください。

主要コンポーネント

次のファイルには、Text Embedder サンプル アプリケーションの重要なコードが含まれています。

セットアップ

このセクションでは、Text Embedder を使用する開発環境とコード プロジェクトをセットアップするための主な手順について説明します。プラットフォーム バージョンの要件など、MediaPipe タスクを使用するための開発環境の設定に関する一般的な情報については、iOS の設定ガイドをご覧ください。

依存関係

Text Embedder は MediaPipeTasksText ライブラリを使用します。このライブラリは CocoaPods を使用してインストールする必要があります。このライブラリは Swift アプリと Objective-C アプリの両方と互換性があり、言語固有の追加設定は必要ありません。

macOS に CocoaPods をインストールする手順については、CocoaPods インストール ガイドをご覧ください。アプリに必要な Pod を使用して Podfile を作成する方法については、CocoaPods の使用をご覧ください。

次のコードを使用して、PodfileMediaPipeTasksText Pod を追加します。

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

アプリに単体テスト ターゲットが含まれている場合は、iOS のセットアップ ガイドPodfile のセットアップの詳細をご確認ください。

モデル

MediaPipe Text Embedder タスクには、このタスクと互換性のあるトレーニング済みモデルが必要です。テキスト埋め込みで使用可能なトレーニング済みモデルの詳細については、タスクの概要のモデル セクションをご覧ください。

モデルを選択してダウンロードし、Xcode を使用してプロジェクト ディレクトリに追加します。Xcode プロジェクトにファイルを追加する方法については、Xcode プロジェクト内のファイルとフォルダの管理をご覧ください。

BaseOptions.modelAssetPath プロパティを使用して、アプリバンドルのモデルのパスを指定します。コード例については、次のセクションをご覧ください。

タスクを作成する

Text Embedder タスクを作成するには、いずれかの初期化子を呼び出します。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 Dispatch フレームワークまたは NSOperation フレームワークを使用して、バックグラウンド スレッドで処理を実行します。Swift を使用してアプリを作成している場合は、バックグラウンド スレッドの実行に Swift 同時実行を使用することもできます。

このサンプルコードでは、TextEmbedderService.swift ファイルで embed(text:) メソッドが呼び出されています。

結果を処理して表示する

推論を実行すると、テキスト エンベディング タスクは、入力テキストのエンベディング(浮動小数点数またはスカラー量子化)のリストを含む TextEmbedderResult オブジェクトを返します。

このタスクからの出力データの例を次に示します。

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

2 つのエンベディングの意味的類似性を比較するには、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];
    

このサンプルコードでは、TextEmbedderService.swift ファイルで TextEmbedder.cosineSimilarity メソッドが呼び出されています。