Gerar embeddings com modelos transformadores no formato ONNX

Neste tutorial, mostramos como exportar um modelo de transformador para o formato Open Neural Network Exchange (ONNX), importar o modelo ONNX para um conjunto de dados do BigQuery e usar o modelo para gerar embeddings com base em uma consulta SQL.

Este tutorial usa o modelo sentence-transformers/all-MiniLM-L6-v2. Esse modelo transformador de frases é conhecido pelo desempenho rápido e eficaz na geração de embeddings de frases. O embedding de frases permite tarefas como pesquisa semântica, agrupamento e similaridade de frases, capturando o significado implícito do texto.

O ONNX fornece um formato uniforme projetado para representar qualquer framework de machine learning (ML). Com o suporte do BigQuery ML para ONNX, você pode fazer o seguinte:

  • Treine um modelo usando seu framework favorito.
  • Converta o modelo no formato ONNX.
  • Importe o modelo ONNX para o BigQuery e faça previsões usando o BigQuery ML.

Objetivos

Custos

Neste documento, você vai usar os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custo baseada na sua projeção de uso, utilize a calculadora de preços.

Novos usuários do Google Cloud podem estar qualificados para um teste sem custo financeiro.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Para mais informações, consulte Limpeza.

Antes de começar

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  4. Verify that billing is enabled for your Google Cloud project.

  5. Enable the BigQuery and Cloud Storage APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  6. Verifique se você tem as permissões necessárias para realizar as tarefas neste documento.
  7. Funções exigidas

    Se você criar um projeto, será o proprietário dele e terá todas as permissões necessárias do Identity and Access Management (IAM) para concluir este tutorial.

    Se você estiver usando um projeto atual, faça o seguinte:

    Make sure that you have the following role or roles on the project:

    Check for the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Google Cloud console, go to the IAM page.

      Acessar o IAM
    2. Selecione o projeto.
    3. Clique em Conceder acesso.
    4. No campo Novos principais, digite seu identificador de usuário. Normalmente, é o endereço de e-mail de uma Conta do Google.

    5. Na lista Selecionar papel, escolha um.
    6. Para conceder outros papéis, adicione-os clicando em Adicionar outro papel.
    7. Clique em Salvar.
    8. Para mais informações sobre as permissões do IAM no BigQuery, consulte Permissões do IAM.

      Converter os arquivos do modelo de transformador para ONNX

      Se quiser, siga as etapas desta seção para converter manualmente o modelo sentence-transformers/all-MiniLM-L6-v2 e o tokenizador para ONNX. Caso contrário, use arquivos de amostra do bucket público do Cloud Storage gs://cloud-samples-data que já foram convertidos.

      Se você optar por converter os arquivos manualmente, precisará ter um ambiente de linha de comando local com o Python instalado. Para mais informações sobre a instalação do Python, consulte Downloads do Python.

      Exportar o modelo Transformer para ONNX

      Use a CLI do Hugging Face Optimum para exportar o modelo sentence-transformers/all-MiniLM-L6-v2 para ONNX. Para mais informações sobre como exportar modelos com a CLI do Optimum, consulte Exportar um modelo para ONNX com optimum.exporters.onnx.

      Para exportar o modelo, abra um ambiente de linha de comando e siga estas etapas:

      1. Instale a CLI do Optimum:

        pip install optimum[onnx]
        
      2. Exportar o modelo. O argumento --model especifica o ID do modelo do Hugging Face. O argumento --opset especifica a versão da biblioteca ONNXRuntime e é definido como 17 para manter a compatibilidade com a biblioteca ONNXRuntime compatível com o BigQuery.

        optimum-cli export onnx \
          --model sentence-transformers/all-MiniLM-L6-v2 \
          --task sentence-similarity \
          --opset 17 all-MiniLM-L6-v2/
        

      O arquivo do modelo é exportado para o diretório all-MiniLM-L6-v2 como model.onnx.

      Aplicar quantização ao modelo Transformer

      Use a CLI do Optimum para aplicar a quantização ao modelo de transformador exportado e reduzir o tamanho do modelo e acelerar a inferência. Para mais informações, consulte Quantização.

      Para aplicar a quantização ao modelo, execute o seguinte comando na linha de comando:

      optimum-cli onnxruntime quantize \
        --onnx_model all-MiniLM-L6-v2/ \
        --avx512_vnni -o all-MiniLM-L6-v2_quantized
      

      O arquivo do modelo quantizado é exportado para o diretório all-MiniLM-L6-v2_quantized como model_quantized.onnx.

      Converter o tokenizador para ONNX

      Para gerar embeddings usando um modelo transformador no formato ONNX, normalmente você usa um tokenizador para produzir duas entradas para o modelo, input_ids e attention_mask.

      Para gerar essas entradas, converta o tokenizador do modelo sentence-transformers/all-MiniLM-L6-v2 para o formato ONNX usando a biblioteca onnxruntime-extensions. Depois de converter o tokenizador, é possível realizar a tokenização diretamente em entradas de texto bruto para gerar previsões do ONNX.

      Para converter o tokenizador, siga estas etapas na linha de comando:

      1. Instale a CLI do Optimum:

        pip install optimum[onnx]
        
      2. Usando o editor de texto de sua escolha, crie um arquivo chamado convert-tokenizer.py. O exemplo a seguir usa o editor de texto nano:

        nano convert-tokenizer.py
        
      3. Copie e cole o seguinte script Python no arquivo convert-tokenizer.py:

        from onnxruntime_extensions import gen_processing_models
        
        # Load the Huggingface tokenizer
        tokenizer = AutoTokenizer.from_pretrained("sentence-transformers/all-MiniLM-L6-v2")
        
        # Export the tokenizer to ONNX using gen_processing_models
        onnx_tokenizer_path = "tokenizer.onnx"
        
        # Generate the tokenizer ONNX model, and set the maximum token length.
        # Ensure 'max_length' is set to a value less than the model's maximum sequence length, failing to do so will result in error during inference.
        tokenizer_onnx_model = gen_processing_models(tokenizer, pre_kwargs={'max_length': 256})[0]
        
        # Modify the tokenizer ONNX model signature.
        # This is because certain tokenizers don't support batch inference.
        tokenizer_onnx_model.graph.input[0].type.tensor_type.shape.dim[0].dim_value = 1
        
        # Save the tokenizer ONNX model
        with open(onnx_tokenizer_path, "wb") as f:
          f.write(tokenizer_onnx_model.SerializeToString())
        
      4. Salve o arquivo convert-tokenizer.py.

      5. Execute o script Python para converter o tokenizador:

        python convert-tokenizer.py
        

      O tokenizador convertido é exportado para o diretório all-MiniLM-L6-v2_quantized como tokenizer.onnx.

      Fazer upload dos arquivos de modelo convertidos para o Cloud Storage

      Depois de converter o modelo transformador e o tokenizador, faça o seguinte:

      crie um conjunto de dados

      Crie um conjunto de dados do BigQuery para armazenar seu modelo de ML.

      Console

      1. No console do Google Cloud , acesse a página BigQuery.

        Acessar a página do BigQuery

      2. No painel Explorer, clique no nome do seu projeto.

      3. Clique em Ver ações > Criar conjunto de dados.

      4. Na página Criar conjunto de dados, faça o seguinte:

        • Para o código do conjunto de dados, insira bqml_tutorial.

        • Em Tipo de local, selecione Multirregião e EUA (várias regiões nos Estados Unidos).

        • Mantenha as configurações padrão restantes e clique em Criar conjunto de dados.

      bq

      Para criar um novo conjunto de dados, utilize o comando bq mk com a sinalização --location. Para obter uma lista completa de parâmetros, consulte a referência comando bq mk --dataset.

      1. Crie um conjunto de dados chamado bqml_tutorial com o local dos dados definido como US e uma descrição de BigQuery ML tutorial dataset:

        bq --location=US mk -d \
         --description "BigQuery ML tutorial dataset." \
         bqml_tutorial

        Em vez de usar a flag --dataset, o comando usa o atalho -d. Se você omitir -d e --dataset, o comando vai criar um conjunto de dados por padrão.

      2. Confirme se o conjunto de dados foi criado:

        bq ls

      API

      Chame o método datasets.insert com um recurso de conjunto de dados definido.

      {
        "datasetReference": {
           "datasetId": "bqml_tutorial"
        }
      }

      BigQuery DataFrames

      Antes de testar esta amostra, siga as instruções de configuração dos BigQuery DataFrames no Guia de início rápido do BigQuery: como usar os BigQuery DataFrames. Para mais informações, consulte a documentação de referência do BigQuery DataFrames.

      Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local.

      import google.cloud.bigquery
      
      bqclient = google.cloud.bigquery.Client()
      bqclient.create_dataset("bqml_tutorial", exists_ok=True)

      Importar os modelos ONNX para o BigQuery

      Importe o tokenizador convertido e os modelos de transformador de frases como modelos do BigQuery ML.

      Selecione uma das seguintes opções:

      Console

      1. No console do Google Cloud , abra o BigQuery Studio.

        Acessar o BigQuery Studio

      2. No editor de consultas, execute a seguinte instrução CREATE MODEL para criar o modelo tokenizer.

         CREATE OR REPLACE MODEL `bqml_tutorial.tokenizer`
          OPTIONS (MODEL_TYPE='ONNX',
           MODEL_PATH='TOKENIZER_BUCKET_PATH')

        Substitua TOKENIZER_BUCKET_PATH pelo caminho para o modelo que você fez upload para o Cloud Storage. Se você estiver usando o modelo de exemplo, substitua TOKENIZER_BUCKET_PATH pelo seguinte valor: gs://cloud-samples-data/bigquery/ml/onnx/all-MiniLM-L6-v2/tokenizer.onnx.

        Quando a operação for concluída, uma mensagem semelhante a esta vai aparecer: Successfully created model named tokenizer no painel Resultados da consulta.

      3. Clique em Acessar modelo para abrir o painel Detalhes.

      4. Analise a seção Colunas de atributos para conferir as entradas do modelo e a Coluna de rótulo para ver as saídas do modelo.

        O painel **Detalhes** do `tokenizer model

      5. No editor de consultas, execute a seguinte instrução CREATE MODEL para criar o modelo all-MiniLM-L6-v2.

         CREATE OR REPLACE MODEL `bqml_tutorial.all-MiniLM-L6-v2`
          OPTIONS (MODEL_TYPE='ONNX',
           MODEL_PATH='TRANSFORMER_BUCKET_PATH')

        Substitua TRANSFORMER_BUCKET_PATH pelo caminho para o modelo que você fez upload para o Cloud Storage. Se você estiver usando o modelo de exemplo, substitua TRANSFORMER_BUCKET_PATH pelo seguinte valor: gs://cloud-samples-data/bigquery/ml/onnx/all-MiniLM-L6-v2/model_quantized.onnx.

        Quando a operação for concluída, uma mensagem semelhante a esta vai aparecer: Successfully created model named all-MiniLM-L6-v2 no painel Resultados da consulta.

      6. Clique em Acessar modelo para abrir o painel Detalhes.

      7. Analise a seção Colunas de atributos para conferir as entradas do modelo e a Coluna de rótulo para ver as saídas do modelo.

        O painel **Detalhes** do modelo `all-MiniLM-L6-v2`

      bq

      Use o comando query da ferramenta de linha de comando bq para executar a instrução CREATE MODEL.

      1. Na linha de comando, execute o comando a seguir para criar o modelo tokenizer.

        bq query --use_legacy_sql=false \
        "CREATE OR REPLACE MODEL
        `bqml_tutorial.tokenizer`
        OPTIONS
        (MODEL_TYPE='ONNX',
        MODEL_PATH='TOKENIZER_BUCKET_PATH')"

        Substitua TOKENIZER_BUCKET_PATH pelo caminho para o modelo que você fez upload para o Cloud Storage. Se você estiver usando o modelo de exemplo, substitua TOKENIZER_BUCKET_PATH pelo seguinte valor: gs://cloud-samples-data/bigquery/ml/onnx/all-MiniLM-L6-v2/tokenizer.onnx.

        Quando a operação for concluída, uma mensagem semelhante a esta será exibida: Successfully created model named tokenizer.

      2. Na linha de comando, execute o comando a seguir para criar o modelo all-MiniLM-L6-v2.

        bq query --use_legacy_sql=false \
        "CREATE OR REPLACE MODEL
        `bqml_tutorial.all-MiniLM-L6-v2`
        OPTIONS
        (MODEL_TYPE='ONNX',
          MODEL_PATH='TRANSFORMER_BUCKET_PATH')"

        Substitua TRANSFORMER_BUCKET_PATH pelo caminho para o modelo que você fez upload para o Cloud Storage. Se você estiver usando o modelo de exemplo, substitua TRANSFORMER_BUCKET_PATH pelo seguinte valor: gs://cloud-samples-data/bigquery/ml/onnx/all-MiniLM-L6-v2/model_quantized.onnx.

        Quando a operação for concluída, uma mensagem semelhante a esta será exibida: Successfully created model named all-MiniLM-L6-v2.

      3. Depois de importar os modelos, verifique se eles aparecem no conjunto de dados.

        bq ls -m bqml_tutorial

        O resultado será o seguinte:

        tableId            Type
        ------------------------
        tokenizer          MODEL
        all-MiniLM-L6-v2   MODEL

      API

      Use o método jobs.insert para importar os modelos.Preencha o parâmetro query do recurso QueryRequest no corpo da solicitação com a instrução CREATE MODEL.

      1. Use o seguinte valor de parâmetro query para criar o modelo tokenizer.

        {
        "query": "CREATE MODEL `PROJECT_ID :bqml_tutorial.tokenizer` OPTIONS(MODEL_TYPE='ONNX' MODEL_PATH='TOKENIZER_BUCKET_PATH')"
        }

        Substitua:

        • PROJECT_ID pelo código do projeto;
        • TOKENIZER_BUCKET_PATH com o caminho para o modelo que você enviou para o Cloud Storage. Se você estiver usando o modelo de exemplo, substitua TOKENIZER_BUCKET_PATH pelo seguinte valor: gs://cloud-samples-data/bigquery/ml/onnx/all-MiniLM-L6-v2/tokenizer.onnx.
      2. Use o seguinte valor de parâmetro query para criar o modelo all-MiniLM-L6-v2.

        {
        "query": "CREATE MODEL `PROJECT_ID :bqml_tutorial.all-MiniLM-L6-v2` OPTIONS(MODEL_TYPE='ONNX' MODEL_PATH='TRANSFORMER_BUCKET_PATH')"
        }

        Substitua:

        • PROJECT_ID pelo código do projeto;
        • TRANSFORMER_BUCKET_PATH com o caminho para o modelo que você enviou ao Cloud Storage. Se você estiver usando o modelo de exemplo, substitua TRANSFORMER_BUCKET_PATH pelo seguinte valor: gs://cloud-samples-data/bigquery/ml/onnx/all-MiniLM-L6-v2/model_quantized.onnx.

      BigQuery DataFrames

      Antes de testar esta amostra, siga as instruções de configuração dos BigQuery DataFrames no Guia de início rápido do BigQuery: como usar os BigQuery DataFrames. Para mais informações, consulte a documentação de referência do BigQuery DataFrames.

      Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local.

      Importe os modelos de tokenizador e Transformer de frases usando o objeto ONNXModel.

      import bigframes
      from bigframes.ml.imported import ONNXModel
      
      bigframes.options.bigquery.project = PROJECT_ID
      
      bigframes.options.bigquery.location = "US"
      
      tokenizer = ONNXModel(
        model_path= "TOKENIZER_BUCKET_PATH"
      )
      imported_onnx_model = ONNXModel(
        model_path="TRANSFORMER_BUCKET_PATH"
      )

      Substitua:

      • PROJECT_ID pelo código do projeto;
      • TOKENIZER_BUCKET_PATH com o caminho para o modelo que você enviou para o Cloud Storage. Se você estiver usando o modelo de exemplo, substitua TOKENIZER_BUCKET_PATH pelo seguinte valor: gs://cloud-samples-data/bigquery/ml/onnx/all-MiniLM-L6-v2/tokenizer.onnx.
      • TRANSFORMER_BUCKET_PATH com o caminho para o modelo que você enviou ao Cloud Storage. Se você estiver usando o modelo de exemplo, substitua TRANSFORMER_BUCKET_PATH pelo seguinte valor: gs://cloud-samples-data/bigquery/ml/onnx/all-MiniLM-L6-v2/model_quantized.onnx.

      Gerar embeddings com os modelos ONNX importados

      Use o tokenizador importado e os modelos transformadores de frases para gerar embeddings com base nos dados do conjunto de dados público bigquery-public-data.imdb.reviews.

      Selecione uma das seguintes opções:

      Console

      Use a função ML.PREDICT para gerar embeddings com os modelos.

      A consulta usa uma chamada ML.PREDICT aninhada para processar texto bruto diretamente pelo tokenizador e pelo modelo de incorporação, da seguinte maneira:

      • Tokenização (consulta interna): a chamada ML.PREDICT interna usa o modelo bqml_tutorial.tokenizer. Ela usa a coluna title do conjunto de dados público bigquery-public-data.imdb.reviews como entrada text. O modelo tokenizer converte as strings de texto bruto nas entradas de token numéricas necessárias para o modelo principal, incluindo as entradas input_ids e attention_mask.
      • Geração de embeddings (consulta externa): a chamada ML.PREDICT externa usa o modelo bqml_tutorial.all-MiniLM-L6-v2. A consulta usa as colunas input_ids e attention_mask da saída da consulta interna como entrada.

      A instrução SELECT recupera a coluna sentence_embedding, que é uma matriz de valores FLOAT que representam a incorporação semântica do texto.

      1. No console do Google Cloud , abra o BigQuery Studio.

        Acessar o BigQuery Studio

      2. No editor de consultas, execute a consulta abaixo.

        SELECT
        sentence_embedding
        FROM
        ML.PREDICT (MODEL `bqml_tutorial.all-MiniLM-L6-v2`,
          (
          SELECT
            input_ids, attention_mask
          FROM
            ML.PREDICT(MODEL `bqml_tutorial.tokenizer`,
              (
              SELECT
                title AS text
              FROM
                `bigquery-public-data.imdb.reviews` limit 10))))

        O resultado será semelhante ao seguinte:

        +-----------------------+
        | sentence_embedding    |
        +-----------------------+
        | -0.02361682802438736  |
        | 0.02025664784014225   |
        | 0.005168713629245758  |
        | -0.026361213997006416 |
        | 0.0655381828546524    |
        | ...                   |
        +-----------------------+
        

      bq

      Use o comando query da ferramenta de linha de comando bq para executar uma consulta. A consulta usa a função ML.PREDICT para gerar embeddings com os modelos.

      A consulta usa uma chamada ML.PREDICT aninhada para processar texto bruto diretamente pelo tokenizador e pelo modelo de incorporação, da seguinte maneira:

      • Tokenização (consulta interna): a chamada ML.PREDICT interna usa o modelo bqml_tutorial.tokenizer. Ela usa a coluna title do conjunto de dados público bigquery-public-data.imdb.reviews como entrada text. O modelo tokenizer converte as strings de texto bruto nas entradas de token numéricas necessárias para o modelo principal, incluindo as entradas input_ids e attention_mask.
      • Geração de embeddings (consulta externa): a chamada ML.PREDICT externa usa o modelo bqml_tutorial.all-MiniLM-L6-v2. A consulta usa as colunas input_ids e attention_mask da saída da consulta interna como entrada.

      A instrução SELECT recupera a coluna sentence_embedding, que é uma matriz de valores FLOAT que representam a incorporação semântica do texto.

      Na linha de comando, execute o seguinte comando para executar a consulta.

      bq query --use_legacy_sql=false \
      'SELECT
      sentence_embedding
      FROM
      ML.PREDICT (MODEL `bqml_tutorial.all-MiniLM-L6-v2`,
        (
        SELECT
          input_ids, attention_mask
        FROM
          ML.PREDICT(MODEL `bqml_tutorial.tokenizer`,
            (
            SELECT
              title AS text
            FROM
              `bigquery-public-data.imdb.reviews` limit 10))))'

      O resultado será semelhante ao seguinte:

      +-----------------------+
      | sentence_embedding    |
      +-----------------------+
      | -0.02361682802438736  |
      | 0.02025664784014225   |
      | 0.005168713629245758  |
      | -0.026361213997006416 |
      | 0.0655381828546524    |
      | ...                   |
      +-----------------------+
      

      BigQuery DataFrames

      Antes de testar esta amostra, siga as instruções de configuração dos BigQuery DataFrames no Guia de início rápido do BigQuery: como usar os BigQuery DataFrames. Para mais informações, consulte a documentação de referência do BigQuery DataFrames.

      Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local.

      Use o método predict para gerar embeddings usando os modelos ONNX.

      import bigframes.pandas as bpd
      
      df = bpd.read_gbq("bigquery-public-data.imdb.reviews", max_results=10)
      df_pred = df.rename(columns={"title": "text"})
      tokens = tokenizer.predict(df_pred)
      predictions = imported_onnx_model.predict(tokens)
      predictions.peek(5)
      

      O resultado será o seguinte:

      Saída do modelo de transformador.

      Limpar

      Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

      Excluir o projeto

      Console

      1. In the Google Cloud console, go to the Manage resources page.

        Go to Manage resources

      2. In the project list, select the project that you want to delete, and then click Delete.
      3. In the dialog, type the project ID, and then click Shut down to delete the project.

      gcloud

      1. In the Google Cloud console, go to the Manage resources page.

        Go to Manage resources

      2. In the project list, select the project that you want to delete, and then click Delete.
      3. In the dialog, type the project ID, and then click Shut down to delete the project.

      Excluir recursos individuais

      Como alternativa, para remover os recursos individuais usados neste tutorial, faça o seguinte:

      1. Exclua os modelos importados.

      2. Opcional: exclua o conjunto de dados.

      A seguir