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

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

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

サンプルコード

テキスト埋め込みのサンプルコードは、このタスクを統合する 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 タスクには、このタスクに対応したトレーニング済みモデルが必要です。Text Embedder で使用可能なトレーニング済みモデルの詳細については、タスクの概要のモデルセクションをご覧ください。

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

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

タスクを作成する

Text Embedder タスクを作成するには、いずれかの初期化子を呼び出します。TextEmbedder(options:) イニシャライザは、構成オプションの値を受け入れます。

カスタマイズされた構成オプションで初期化された Text Embedder が不要な場合は、TextEmbedder(modelPath:) イニシャライザを使用して、デフォルト オプションで Text Embedder を作成できます。構成オプションの詳細については、構成の概要をご覧ください。

次のコードは、このタスクをビルドして構成する方法を示しています。

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 同時実行を使用することもできます。

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

結果を処理して表示する

推論を実行すると、Text Embedder タスクは、入力テキストのエンベディングのリスト(浮動小数点数またはスカラー量子化)を含む 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];
    

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