Guia de incorporação de texto para iOS

A tarefa de incorporador de texto permite criar uma representação numérica de dados de texto para capturar o significado semântico deles. Estas instruções mostram como usar o Text Embedder em apps para iOS.

Confira esta demonstração na Web para ver essa tarefa em ação. 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 Text Embedder fornece uma implementação básica de um app para iOS que integra essa tarefa. O exemplo avalia as semelhanças semânticas entre dois textos e exige um dispositivo iOS físico ou um simulador iOS.

Você pode usar o app como ponto de partida para seu próprio app iOS ou se referir a ele ao modificar um app existente. Consulte o código de exemplo do Text Embedder no GitHub.

Fazer o download do código

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

Para fazer o download do código de exemplo:

  1. Clone o repositório do Git usando o seguinte comando:

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

  2. Opcionalmente, configure sua instância do git para usar o checkout esparso, para que você tenha apenas os arquivos do app de exemplo do Text Embedder:

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

Depois de criar uma versão local do código de exemplo, é possível instalar a biblioteca de tarefas do MediaPipe, abrir o projeto usando o Xcode e executar o app. Para instruções, consulte o Guia de configuração para iOS.

Principais componentes

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

Configuração

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

Dependências

O Text Embedder usa a biblioteca MediaPipeTasksText, que precisa ser instalada usando o CocoaPods. A biblioteca é compatível com apps Swift e Objective-C e não requer nenhuma configuração específica da linguagem.

Para instruções sobre como instalar o CocoaPods no macOS, consulte o guia de instalação do CocoaPods. Para instruções sobre como criar um Podfile com os pods necessários para seu app, consulte Como usar CocoaPods.

Adicione o pod MediaPipeTasksText no Podfile usando o seguinte código:

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

Se o app incluir destinos de teste de unidade, consulte o guia de configuração para iOS para mais informações sobre como configurar o Podfile.

Modelo

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

Selecione e faça o download de um modelo e adicione-o ao diretório do projeto usando o Xcode. Para instruções sobre como adicionar arquivos ao projeto do Xcode, consulte Como gerenciar arquivos e pastas no projeto do Xcode.

Use a propriedade BaseOptions.modelAssetPath para especificar o caminho para o modelo no app bundle. Para conferir um exemplo de código, consulte a próxima seção.

Criar a tarefa

É possível criar a tarefa de incorporação de texto chamando um dos inicializadores dela. O inicializador TextEmbedder(options:) aceita valores para as opções de configuração.

Se você não precisar de um incorporador de texto inicializado com opções de configuração personalizadas, use o inicializador TextEmbedder(modelPath:) para criar um incorporador de texto com as opções padrão. Para mais informações sobre as opções de configuração, consulte Visão geral da configuração.

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

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

Opções de configuração

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

Nome da opção Descrição Intervalo de valor Valor padrão
l2_normalize Se o vetor de recursos retornado vai ser normalizado com a norma L2. Use essa opção somente se o modelo ainda não tiver uma operação TFLite L2_NORMALIZATION nativa. Na maioria dos casos, isso já acontece e a normalização L2 é alcançada pela inferência do TFLite sem a necessidade dessa opção. Boolean False
quantize Define se o embedding retornado precisa ser quantizado em bytes por quantização escalar. As inclusões são implicitamente consideradas como unidade-norm e, portanto, qualquer dimensão tem garantia de ter um valor em [-1,0, 1,0]. Use a opção l2_normalize se não for esse o caso. Boolean False

Executar a tarefa

Para incorporar o texto de entrada e extrair os vetores de incorporação, use o método embed(text:) de TextEmbedder.

Swift

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

Objective-C

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

Observação: a tarefa bloqueia a linha de execução atual até que ela termine de executar a inferência no texto. Para evitar o bloqueio da linha de execução atual, execute o processamento em uma linha de execução em segundo plano usando os frameworks Dispatch ou NSOperation do iOS. Se o app for criado usando Swift, você também poderá usar a concorrência do Swift para a execução de linhas de execução em segundo plano.

No código de exemplo, o método embed(text:) é chamado no arquivo TextEmbedderService.swift.

Gerenciar e exibir resultados

Ao executar a inferência, a tarefa Text Embedder retorna um objeto TextEmbedderResult que contém uma lista de embeddings (ponto flutuante ou quantizada por escala) para o texto de entrada.

Confira a seguir um exemplo dos dados de saída desta 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 duas embeddings usando o método 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];

No código de exemplo, o método TextEmbedder.cosineSimilarity é chamado no arquivo TextEmbedderService.swift.