Guida all'incorporamento del testo per Android

L'attività Incorporamento di testo MediaPipe consente di creare una rappresentazione numerica dei dati di testo per acquisirne il significato semantico. Queste istruzioni mostrano come usare l'incorporamento di testo con le app per Android.

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 di MediaPipe Tasks è una semplice implementazione di un'app di incorporamento di testo per Android. L'esempio valuta le somiglianze semantiche tra due parti di testo e richiede un dispositivo Android fisico o un emulatore Android.

Puoi utilizzare l'app come punto di partenza per la tua app per Android o farvi riferimento quando modifichi un'app esistente. Il codice di esempio di incorporamento di testo è ospitato su GitHub.

Scarica il codice

Le seguenti istruzioni 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. Facoltativamente, configura la tua istanza Git in modo da utilizzare un pagamento sparse, in modo da avere solo i file per l'app di esempio di incorporamento di testo:
    cd mediapipe
    git sparse-checkout init --cone
    git sparse-checkout set examples/text_embedder/android
    

Dopo aver creato una versione locale del codice di esempio, puoi importare il progetto in Android Studio ed eseguire l'app. Per le istruzioni, consulta la Guida alla configurazione per Android.

Componenti chiave

I seguenti file contengono il codice fondamentale per questa applicazione di esempio di incorporamento di testo:

  • TextEmbedderHelper.kt: inizializza l'incorporamento del testo e gestisce il modello e la selezione del delegato.
  • MainActivity.kt: implementa l'applicazione e assembla i componenti dell'interfaccia utente.

Configurazione

In questa sezione vengono descritti i passaggi chiave per configurare l'ambiente di sviluppo e i progetti di codice in modo specifico per l'utilizzo di Text Embedder. Per informazioni generali sulla configurazione dell'ambiente di sviluppo per l'utilizzo delle attività di MediaPipe, inclusi i requisiti di versione della piattaforma, consulta la Guida alla configurazione per Android.

Dipendenze

L'incorporamento di testo utilizza le librerie com.google.mediapipe:tasks-text. Aggiungi questa dipendenza al file build.gradle del tuo progetto di sviluppo di app Android. Puoi importare le dipendenze richieste con il seguente codice:

dependencies {
    implementation 'com.google.mediapipe:tasks-text:latest.release'
}

Modello

L'attività Incorporamento di testo MediaPipe richiede un modello addestrato compatibile con questa attività. Per ulteriori informazioni sui modelli addestrati disponibili per l'incorporamento di testo, consulta la sezione Modelli della panoramica dell'attività.

Seleziona e scarica il modello, quindi archivialo all'interno della directory del progetto:

<dev-project-root>/src/main/assets

Specifica il percorso del modello all'interno del parametro ModelAssetPath. Nel codice di esempio, il modello è definito nella funzione setupTextEmbedder() del file TextEmbedderHelper.kt:

Utilizza la funzione BaseOptions.Builder.setModelAssetPath() per specificare il percorso utilizzato dal modello. Questo metodo è indicato nell'esempio di codice nella sezione successiva.

Creare l'attività

Puoi utilizzare una delle funzioni createFrom...() per creare l'attività. La funzione createFromOptions() accetta le opzioni di configurazione per impostare le opzioni di incorporamento. Puoi anche inizializzare l'attività utilizzando la funzione di fabbrica di createFromFile(). La funzione createFromFile() accetta un percorso relativo o assoluto al file del modello addestrato. Per ulteriori informazioni sulle opzioni di configurazione, consulta Opzioni di configurazione.

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

val baseOptions = baseOptionsBuilder.build()
val optionsBuilder =
    TextEmbedderOptions.builder().setBaseOptions(baseOptions)
val options = optionsBuilder.build()
textEmbedder = TextEmbedder.createFromOptions(context, options)

L'implementazione del codice di esempio imposta le opzioni per l'incorporamento del testo nella funzione setupTextEmbedder() del file TextEmbedderHelper.kt.

Opzioni di configurazione

Questa attività prevede le seguenti opzioni di configurazione per le app per Android:

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'operatività TFLite L2_NORMALIZATION nativa. Nella maggior parte dei casi, è già così e la normalizzazione L2 viene quindi ottenuta tramite l'inferenza TFLite senza necessità di questa opzione. Boolean False
quantize Indica se l'incorporamento restituito deve essere quantizzato in byte tramite la quantizzazione scalare. Gli incorporamenti si presume implicitamente come unità-norm, pertanto è garantito che ogni dimensione abbia un valore in [-1.0, 1.0]. In caso contrario, utilizza l'opzione l2_normalize. Boolean False

Preparazione dei dati

L'incorporamento di testo funziona con i dati di testo (String). L'attività gestisce la pre-elaborazione dell'input dei dati, tra cui la tokenizzazione e la pre-elaborazione tensor. L'intera pre-elaborazione viene gestita all'interno della funzione embed(). Non è necessaria ulteriore pre-elaborazione del testo di input.

val inputText = "The input text to be embedded."

Esegui l'attività

L'incorporamento di testo utilizza la funzione embed per attivare le inferenze. Per l'incorporamento del testo, ciò significa restituire i vettori di incorporamento per il testo di input.

Il seguente codice mostra come eseguire l'elaborazione con il modello di attività.

textEmbedder?.let {
    val firstEmbed =
        it.embed(firstText).embeddingResult().embeddings().first()
    val secondEmbed =
        it.embed(secondText).embeddingResult().embeddings().first()
    ...
}

Nel codice di esempio, la funzione embed viene chiamata nel file TextEmbedderHelper.kt.

Gestire e visualizzare i risultati

Dopo l'esecuzione dell'inferenza, l'attività Incorporamento di testo restituisce un oggetto TextEmbedderResult che contiene un elenco di incorporamenti (in virgola mobile o quantitativi 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 la funzione TextEmbedder.cosineSimilarity. Puoi vedere un esempio nel codice che segue.

val similarity = TextEmbedder.cosineSimilarity(firstEmbed, secondEmbed)

Nel codice di esempio, la funzione TextEmbedder.cosineSimilarity() viene chiamata nel file TextEmbedderHelper.kt.