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 transformer 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, clustering 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
- Use a
CLI do Hugging Face Optimum
para exportar o modelo
sentence-transformers/all-MiniLM-L6-v2para ONNX. - Use a instrução
CREATE MODELpara importar o modelo ONNX para o BigQuery. - Use a
função
ML.PREDICTpara gerar embeddings com o modelo ONNX importado.
Custos
Neste documento, você vai usar os seguintes componentes faturáveis do Google Cloud:
Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.
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
- Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verifique se o faturamento está ativado para o projeto do Google Cloud .
Ative as APIs BigQuery e Cloud Storage.
Funções necessárias para ativar APIs
Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (
roles/serviceusage.serviceUsageAdmin), que contém a permissãoserviceusage.services.enable. Saiba como conceder papéis.- Verifique se você tem as permissões necessárias para realizar as tarefas neste documento.
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:
Verifique se você tem os seguintes papéis no projeto:
- Administrador do BigQuery Studio (
roles/bigquery.studioAdmin) - Criador de objetos do Storage (
roles/storage.objectCreator)
Verificar os papéis
-
No console do Google Cloud , acesse a página IAM.
Acessar IAM - Selecione o projeto.
-
Na coluna Principal, encontre todas as linhas que identificam você ou um grupo no qual você está incluído. Para saber em quais grupos você está incluído, entre em contato com o administrador.
- Em todas as linhas que especificam ou incluem você, verifique a coluna Papel para ver se a lista de papéis inclui os papéis necessários.
Conceder os papéis
-
No console do Google Cloud , acesse a página IAM.
Acessar IAM - Selecione o projeto.
- Clique em Conceder acesso.
-
No campo Novos principais, digite seu identificador de usuário. Normalmente, é o endereço de e-mail de uma Conta do Google.
- Clique em Selecionar um papel e pesquise o papel.
- Para conceder outros papéis, adicione-os clicando em Adicionar outro papel.
- Clique em Salvar.
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:
Instale a CLI do Optimum:
pip install optimum[onnx]Exportar o modelo. O argumento
--modelespecifica o ID do modelo do Hugging Face. O argumento--opsetespecifica a versão da biblioteca ONNXRuntime e é definido como17para 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 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 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:
Instale a CLI do Optimum:
pip install optimum[onnx]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.pyCopie 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())Salve o arquivo
convert-tokenizer.py.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 bucket do Cloud Storage para armazenar os arquivos convertidos.
- Faça upload do modelo de transformação convertido e dos arquivos de tokenizador para seu bucket do Cloud Storage.
crie um conjunto de dados
Crie um conjunto de dados do BigQuery para armazenar seu modelo de ML.Console
No console do Google Cloud , acesse a página BigQuery.
No painel Explorer, clique no nome do seu projeto.
Clique em Conferir ações > Criar conjunto de dados.
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.
Mantenha as configurações padrão restantes e clique em Criar conjunto de dados.
bq
Para criar um conjunto de dados, use o
comando bq mk --dataset.
Crie um conjunto de dados chamado
bqml_tutorialcom o local dos dados definido comoUS.bq mk --dataset \ --location=US \ --description "BigQuery ML tutorial dataset." \ bqml_tutorial
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.
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
No console do Google Cloud , abra o BigQuery Studio.
No editor de consultas, execute a seguinte instrução
CREATE MODELpara criar o modelotokenizer.CREATE OR REPLACE MODEL `bqml_tutorial.tokenizer` OPTIONS (MODEL_TYPE='ONNX', MODEL_PATH='TOKENIZER_BUCKET_PATH')
Substitua
TOKENIZER_BUCKET_PATHpelo caminho para o modelo que você fez upload para o Cloud Storage. Se você estiver usando o modelo de exemplo, substituaTOKENIZER_BUCKET_PATHpelo 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 tokenizerno painel Resultados da consulta.Clique em Acessar modelo para abrir o painel Detalhes.
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.
No editor de consultas, execute a seguinte instrução
CREATE MODELpara criar o modeloall-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_PATHpelo caminho para o modelo que você fez upload para o Cloud Storage. Se você estiver usando o modelo de exemplo, substituaTRANSFORMER_BUCKET_PATHpelo 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-v2no painel Resultados da consulta.Clique em Acessar modelo para abrir o painel Detalhes.
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.
bq
Use o comando query da ferramenta de linha de comando bq para executar a instrução CREATE MODEL.
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_PATHpelo caminho para o modelo que você fez upload para o Cloud Storage. Se você estiver usando o modelo de exemplo, substituaTOKENIZER_BUCKET_PATHpelo 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.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_PATHpelo caminho para o modelo que você fez upload para o Cloud Storage. Se você estiver usando o modelo de exemplo, substituaTRANSFORMER_BUCKET_PATHpelo 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.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.
Use o seguinte valor de parâmetro
querypara criar o modelotokenizer.{ "query": "CREATE MODEL `PROJECT_ID :bqml_tutorial.tokenizer` OPTIONS(MODEL_TYPE='ONNX' MODEL_PATH='TOKENIZER_BUCKET_PATH')" }Substitua:
PROJECT_IDpelo código do projeto;TOKENIZER_BUCKET_PATHcom o caminho para o modelo que você enviou para o Cloud Storage. Se você estiver usando o modelo de exemplo, substituaTOKENIZER_BUCKET_PATHpelo seguinte valor:gs://cloud-samples-data/bigquery/ml/onnx/all-MiniLM-L6-v2/tokenizer.onnx.
Use o seguinte valor de parâmetro
querypara criar o modeloall-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_IDpelo código do projeto;TRANSFORMER_BUCKET_PATHcom o caminho para o modelo que você enviou ao Cloud Storage. Se você estiver usando o modelo de exemplo, substituaTRANSFORMER_BUCKET_PATHpelo 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_IDpelo código do projeto;TOKENIZER_BUCKET_PATHcom o caminho para o modelo que você enviou para o Cloud Storage. Se você estiver usando o modelo de exemplo, substituaTOKENIZER_BUCKET_PATHpelo seguinte valor:gs://cloud-samples-data/bigquery/ml/onnx/all-MiniLM-L6-v2/tokenizer.onnx.TRANSFORMER_BUCKET_PATHcom o caminho para o modelo que você enviou ao Cloud Storage. Se você estiver usando o modelo de exemplo, substituaTRANSFORMER_BUCKET_PATHpelo 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 de transformador 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.PREDICTinterna usa o modelobqml_tutorial.tokenizer. Ela usa a colunatitledo conjunto de dados públicobigquery-public-data.imdb.reviewscomo entradatext. O modelotokenizerconverte as strings de texto bruto nas entradas de token numéricas necessárias para o modelo principal, incluindo as entradasinput_idseattention_mask. - Geração de embeddings (consulta externa): a chamada
ML.PREDICTexterna usa o modelobqml_tutorial.all-MiniLM-L6-v2. A consulta usa as colunasinput_idseattention_maskda 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.
No console do Google Cloud , abra o BigQuery Studio.
No editor de consultas, execute a consulta a seguir.
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.PREDICTinterna usa o modelobqml_tutorial.tokenizer. Ela usa a colunatitledo conjunto de dados públicobigquery-public-data.imdb.reviewscomo entradatext. O modelotokenizerconverte as strings de texto bruto nas entradas de token numéricas necessárias para o modelo principal, incluindo as entradasinput_idseattention_mask. - Geração de embeddings (consulta externa): a chamada
ML.PREDICTexterna usa o modelobqml_tutorial.all-MiniLM-L6-v2. A consulta usa as colunasinput_idseattention_maskda 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:
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
- No console Google Cloud , acesse a página Gerenciar recursos.
- Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
- Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.
gcloud
Excluir um projeto do Google Cloud :
gcloud projects delete PROJECT_ID
Excluir recursos individuais
Como alternativa, para remover os recursos individuais usados neste tutorial, faça o seguinte:
A seguir
- Aprenda a usar embeddings de texto para pesquisa semântica e geração aumentada por recuperação (RAG).
- Para mais informações sobre como converter modelos de transformadores para ONNX, consulte
Exportar um modelo para ONNX com
optimum.exporters.onnx. - Para mais informações sobre como importar modelos ONNX, consulte
A instrução
CREATE MODELpara modelos ONNX. - Para mais informações sobre como fazer previsões, consulte
A função
ML.PREDICT. - Para uma visão geral sobre ML do BigQuery, consulte Introdução ao ML do BigQuery.
- Para começar a usar o BigQuery ML, consulte Criar modelos de machine learning no BigQuery ML.