Guia de incorporação de texto para Android

Com a tarefa MediaPipe Text Embedder, é possível criar uma representação numérica dos dados de texto para capturar o significado semântico deles. Estas instruções mostram como usar o Incorporador de texto com apps Android.

Para mais informações sobre os recursos, modelos e opções de configuração dessa tarefa, consulte a Visão geral.

Exemplo de código

O código de exemplo do MediaPipe Tasks é uma implementação simples de um app Text Embedder para Android. O exemplo avalia as semelhanças semânticas entre duas partes de texto e requer um dispositivo Android físico ou um Android Emulator.

Use o app como ponto de partida para seu próprio app Android ou consulte-o ao modificar um app já existente. O código de exemplo do Text Embedder está hospedado no GitHub (em inglês).

Fazer o download do código

As instruções a seguir mostram como criar uma cópia local do código de exemplo usando a ferramenta de linha de comando git.

Para fazer o download do código de exemplo:

  1. Clone o repositório git usando o seguinte comando:
    git clone https://github.com/google-ai-edge/mediapipe-samples
    
  2. Como opção, configure sua instância git para usar a finalização da compra esparsa para que você tenha apenas os arquivos do app de exemplo Text Embedder:
    cd mediapipe
    git sparse-checkout init --cone
    git sparse-checkout set examples/text_embedder/android
    

Depois de criar uma versão local do código de exemplo, você poderá importar o projeto para o Android Studio e executar o app. Para conferir instruções, consulte o Guia de configuração para Android.

Principais componentes

Os arquivos a seguir contêm o código essencial para este aplicativo de exemplo de incorporador de texto:

  • TextEmbedderHelper.kt: inicializa o incorporador de texto e processa o modelo e a seleção delegada.
  • MainActivity.kt: implementa o aplicativo e monta os componentes da interface do usuário.

Configuração

Esta seção descreve as principais etapas para configurar seu ambiente de desenvolvimento e projetos de código para usar o Text Embedder. Para ter informações gerais sobre como configurar seu ambiente de desenvolvimento para usar tarefas do MediaPipe, incluindo requisitos de versão da plataforma, consulte o Guia de configuração para Android.

Dependências

O Incorporador de texto usa as bibliotecas com.google.mediapipe:tasks-text. Adicione essa dependência ao arquivo build.gradle do projeto de desenvolvimento do app Android. Importe as dependências necessárias com o seguinte código:

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

Modelo

A tarefa MediaPipe Text Embedder requer um modelo treinado compatível com ela. Para mais informações sobre os modelos treinados disponíveis para o incorporador de texto, consulte a seção Modelos de visão geral da tarefa.

Selecione e faça o download do modelo e armazene-o no diretório do projeto:

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

Especifique o caminho do modelo no parâmetro ModelAssetPath. No código de exemplo, o modelo é definido na função setupTextEmbedder() no arquivo TextEmbedderHelper.kt:

Use a função BaseOptions.Builder.setModelAssetPath() para especificar o caminho usado pelo modelo. Esse método é mencionado no exemplo de código na próxima seção.

Criar a tarefa

Use uma das funções createFrom...() para criar a tarefa. A função createFromOptions() aceita opções de configuração para definir as opções do incorporador. Você também pode inicializar a tarefa usando a função de fábrica createFromFile(). A função createFromFile() aceita um caminho relativo ou absoluto para o arquivo de modelo treinado. Para mais informações sobre as opções de configuração, consulte Opções de configuração.

O código a seguir demonstra como criar e configurar essa tarefa.

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

A implementação de código de exemplo define as opções do incorporador de texto na função setupTextEmbedder() no arquivo TextEmbedderHelper.kt.

Opções de configuração

Esta tarefa tem as seguintes opções de configuração para apps Android:

Nome da opção Descrição Intervalo de valor Valor padrão
l2_normalize Define se o vetor de atributo retornado será normalizado com a norma L2. Use essa opção somente se o modelo ainda não tiver uma operação nativa do TFLite L2_NORMALIZATION. Na maioria dos casos, esse já é o caso, e a normalização L2 é, portanto, feita por meio da inferência TFLite sem precisar dessa opção. Boolean False
quantize Define se o embedding retornado precisa ser quantizado em bytes por meio da quantização escalar. Os embeddings são implicitamente considerados padrão de unidade e, portanto, qualquer dimensão tem um valor em [-1.0, 1.0]. Use a opção l2_normalize se esse não for o caso. Boolean False

preparar dados

O Incorporador de texto funciona com dados de texto (String). A tarefa lida com o pré-processamento de entrada de dados, incluindo a tokenização e o pré-processamento de tensor. Todo o pré-processamento é processado na função embed(). Não é necessário fazer outro pré-processamento do texto de entrada.

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

Executar a tarefa

O Incorporador de texto usa a função embed para acionar inferências. Na incorporação de texto, isso significa retornar os vetores de embedding do texto de entrada.

O código a seguir demonstra como executar o processamento com o modelo de tarefa.

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

No código de exemplo, a função embed é chamada no arquivo TextEmbedderHelper.kt.

Gerenciar e mostrar resultados

Ao executar a inferência, a tarefa "Incorporador de texto" retorna um objeto TextEmbedderResult que contém uma lista de embeddings (ponto flutuante ou quantizados escalares) para o texto de entrada.

Veja a seguir um exemplo dos dados de saída dessa tarefa:

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

É possível comparar a semelhança semântica de dois embeddings usando a função TextEmbedder.cosineSimilarity. Confira um exemplo no código a seguir.

val similarity = TextEmbedder.cosineSimilarity(firstEmbed, secondEmbed)

No código de exemplo, a função TextEmbedder.cosineSimilarity() é chamada no arquivo TextEmbedderHelper.kt.