Guida all'incorporamento del testo per iOS

L'attività Incorporatore di testo consente di creare una rappresentazione numerica dei dati di testo per acquisirne il significato semantico. Queste istruzioni mostrano come utilizzare Text Embedder nelle app per iOS.

Puoi vedere questa attività in azione visualizzando questa demo web. Per ulteriori informazioni sulle funzionalità, sui modelli e sulle opzioni di configurazione di questa attività, consulta la Panoramica.

Esempio di codice

Il codice di esempio per Text Embedder fornisce un'implementazione di base di un'app per iOS che integra questa attività. L'esempio valuta le somiglianze semantiche tra due parti di testo e richiede un dispositivo iOS fisico o un simulatore iOS.

Puoi utilizzare l'app come punto di partenza per la tua app per iOS o farvi riferimento quando modifichi un'app esistente. Puoi consultare il codice di esempio di Text Embedder su GitHub.

Scarica il codice

Le istruzioni riportate di seguito mostrano come creare una copia locale del codice di esempio utilizzando lo strumento a riga di comando git.

Per scaricare il codice di esempio:

  1. Clona il repository Git utilizzando il seguente comando:

    git clone https://github.com/google-ai-edge/mediapipe-samples

  2. Se vuoi, configura l'istanza Git in modo da utilizzare il controllo sparse, in modo da avere solo i file per l'app di esempio Text Embedder:

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

Dopo aver creato una versione locale del codice di esempio, puoi installare la libreria di attività MediaPipe, aprire il progetto utilizzando Xcode ed eseguire l'app. Per le istruzioni, consulta la Guida alla configurazione per iOS.

Componenti chiave

I seguenti file contengono il codice fondamentale per l'applicazione di esempio Text Embedder:

Configurazione

In questa sezione vengono descritti i passaggi chiave per la configurazione dell'ambiente di sviluppo e dei progetti di codice per l'utilizzo di Incorporatore di testo. Per informazioni generali sulla configurazione dell'ambiente di sviluppo per l'utilizzo delle attività MediaPipe, inclusi i requisiti della versione della piattaforma, consulta la Guida alla configurazione per iOS.

Dipendenze

Text Embedder utilizza la libreria MediaPipeTasksText, che deve essere installata utilizzando CocoaPods. La libreria è compatibile con le app Swift e Objective-C e non richiede alcuna configurazione aggiuntiva specifica per il linguaggio.

Per istruzioni su come installare CocoaPods su macOS, consulta la guida all'installazione di CocoaPods. Per istruzioni su come creare un Podfile con i pod necessari per la tua app, consulta Utilizzare CocoaPods.

Aggiungi il pod MediaPipeTasksText in Podfile utilizzando il seguente codice:

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

Se la tua app include target dei test delle unità, consulta la Guida alla configurazione per iOS per ulteriori informazioni sulla configurazione di Podfile.

Modello

L'attività MediaPipe Text Embedder richiede un modello addestrato compatibile con questa attività. Per saperne di più sui modelli addestrati disponibili per Text Embedder, consulta la sezione Modelli della panoramica delle attività.

Seleziona e scarica un modello e aggiungilo alla directory del progetto utilizzando Xcode. Per istruzioni su come aggiungere file al progetto Xcode, consulta la sezione Gestione di file e cartelle nel progetto Xcode.

Utilizza la proprietà BaseOptions.modelAssetPath per specificare il percorso del modello nell'app bundle. Per un esempio di codice, consulta la sezione successiva.

Crea l'attività

Puoi creare l'attività di incorporamento di testo chiamando uno dei relativi inizializzatori. L'inizializzatore TextEmbedder(options:) accetta i valori per le opzioni di configurazione.

Se non hai bisogno di un inserzionista di testo inizializzato con opzioni di configurazione personalizzate, puoi utilizzare l'inizializzatore TextEmbedder(modelPath:) per creare un inserzionista di testo con le opzioni predefinite. Per ulteriori informazioni sulle opzioni di configurazione, consulta Panoramica della configurazione.

Il codice seguente mostra come creare e configurare questa attività.

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];

Opzioni di configurazione

Questa attività offre le seguenti opzioni di configurazione per le app per iOS:

Nome opzione Descrizione Intervallo di valori Valore predefinito
l2_normalize Indica se normalizzare il vettore di caratteristiche restituito con la norma L2. Utilizza questa opzione solo se il modello non contiene già un'operazione L2_NORMALIZATION TFLite nativa. Nella maggior parte dei casi, è già così e la normalizzazione L2 viene quindi raggiunta tramite l'inferenza TFLite senza bisogno di questa opzione. Boolean False
quantize Indica se l'embedding restituito deve essere quantizzato in byte tramite la quantizzazione scalare. Si presume implicitamente che gli incorporamenti siano di norma unitaria e quindi qualsiasi dimensione abbia un valore garantito compreso tra -1,0 e 1,0. In caso contrario, utilizza l'opzione l2_normalize. Boolean False

Esegui l'attività

Per incorporare il testo di input e ottenere i relativi vettori di embedding, puoi utilizzare il metodo embed(text:) di TextEmbedder.

Swift

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

Objective-C

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

Nota: l'attività blocca il thread corrente fino al completamento dell'esecuzione dell'inferenza sul testo. Per evitare di bloccare il thread attuale, esegui l'elaborazione in un thread in background utilizzando i framework Dispatch o NSOperation di iOS. Se l'app è stata creata utilizzando Swift, puoi anche utilizzare Swift Concurrency per l'esecuzione di thread in background.

Nel codice di esempio, il metodo embed(text:) viene chiamato nel file TextEmbedderService.swift.

Gestire e visualizzare i risultati

Dopo l'esecuzione dell'inferenza, l'attività di inserimento di testo restituisce un oggetto TextEmbedderResult che contiene un elenco di embedding (a virgola mobile o quantizzati scalari) per il testo di input.

Di seguito è riportato un esempio dei dati di output di questa attività:

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

Puoi confrontare la somiglianza semantica di due incorporamenti utilizzando il metodo 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];

Nel codice di esempio, il metodo TextEmbedder.cosineSimilarity viene chiamato nel file TextEmbedderService.swift.