Algumas ou todas as informações nesta página podem não se aplicar ao Cloud de Confiance da S3NS. Consulte Diferenças do Google Cloud para saber mais.

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Gerar embeddings com modelos transformadores no formato ONNX

Neste tutorial, você vai usar a CLI Hugging Face Optimum para exportar o modelo sentence-transformers/all-MiniLM-L6-v2 para o formato Open Neural Network Exchange (ONNX). Use a instrução CREATE MODEL para importar o modelo ONNX para o BigQuery. Por fim, use a função ML.PREDICT para gerar embeddings com o modelo ONNX importado.

Neste tutorial, usamos o modelo sentence-transformers/all-MiniLM-L6-v2. Esse modelo de 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, clustering e similaridade de frases, capturando o significado subjacente do texto.

O ONNX fornece um formato uniforme projetado para representar qualquer framework de machine learning (ML). O suporte do BigQuery ML para ONNX permite que você faça o seguinte:

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

Objetivos

Exporte o modelo sentence-transformers/all-MiniLM-L6-v2 para o ONNX.
Importar o modelo ONNX para o BigQuery.
Use a função ML.PREDICT para gerar embeddings com o modelo ONNX importado.

Custos

Neste documento, você vai usar os seguintes componentes faturáveis do Cloud de Confiance by S3NS:

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

In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance 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.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector
Verifique se o faturamento está ativado para o projeto do Cloud de Confiance .

Ative as APIs BigQuery e Cloud Storage, se ainda não estiverem ativadas.
Funções necessárias para ativar APIs
Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.
Ativar as APIs

Verifique se você tem as permissões necessárias para executar as tarefas neste documento.

Funções exigidas

Para conseguir as permissões necessárias para concluir o tutorial, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Criar conjuntos de dados, tabelas e modelos e executar jobs do BigQuery: Administrador do BigQuery Studio (roles/bigquery.studioAdmin)
Criar um bucket do Cloud Storage e objetos de armazenamento (se você estiver convertendo manualmente os arquivos de modelo do transformador para ONNX): Administrador do Storage (roles/storage.admin)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

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

Para mais informações sobre as permissões do IAM no BigQuery, consulte Permissões do IAM.

Opcional: converter manualmente os arquivos do modelo de transformador para ONNX

Se você estiver convertendo manualmente o modelo sentence-transformers/all-MiniLM-L6-v2 e o tokenizador para ONNX, siga as etapas nas seções a seguir. Como alternativa, use os arquivos de amostra no bucket do Cloud Storage gs://cloud-samples-data. Os arquivos neste bucket já foram convertidos. Se você usar os arquivos de amostra, pule para Criar um conjunto de dados.

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 como instalar o Python, consulte Downloads do Python.

Exportar o modelo de transformador para o ONNX

Use a CLI Hugging Face Optimum para exportar o modelo sentence-transformers/all-MiniLM-L6-v2 para o ONNX. Para mais informações sobre como exportar modelos com a CLI 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]
```
Exporte o modelo:
```
optimum-cli export onnx \
    --model sentence-transformers/all-MiniLM-L6-v2 \
    --task sentence-similarity \
    --opset 17 all-MiniLM-L6-v2/
```
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.

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

Aplicar quantização ao modelo de transformador

Use a CLI do Optimum para aplicar a quantização ao modelo de transformador exportado para 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:

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

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

Converter o tokenizador em ONNX

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

Para produzir 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 brutas 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 preferência, crie um arquivo chamado convert-tokenizer.py. O exemplo a seguir usa o editor de texto nano:
```
nano convert-tokenizer.py
```

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())

Salve o arquivo convert-tokenizer.py.
Para converter o tokenizador, execute o script Python:
```
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 de 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 transformador convertido e dos arquivos do tokenizador para o bucket do Cloud Storage.

Criar um conjunto de dados

Para criar um conjunto de dados do BigQuery, selecione uma das seguintes opções:

Console

No console do Cloud de Confiance , acesse a página BigQuery.

Acessar o BigQuery
No painel à esquerda, clique em Explorer:

Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.
No Explorer, expanda o projeto e clique em Conjuntos de dados.
Na página Conjuntos de dados, clique em Criar conjunto de dados.
No painel Criar conjunto de dados, faça o seguinte:
- Para o código do conjunto de dados, insira bqml_tutorial.
- Em Local dos dados, selecione EUA.
Não altere as outras configurações padrão.
Clique em Criar conjunto de dados.

bq

Para criar um novo conjunto de dados, use o comando bq mk --dataset.

Crie um conjunto de dados chamado bqml_tutorial com o local de dados definido como US:

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.

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

No console do Cloud de Confiance , acesse a página do BigQuery Studio.

Acessar Studio
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ê enviou ao Cloud Storage. Se você usar o modelo de amostra, 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, você vai ver uma mensagem no painel Resultados da consulta semelhante a esta: Successfully created model named tokenizer.
Para abrir o painel Detalhes, clique em Ir para o modelo.
Para ver as entradas e a saída do modelo na Coluna de rótulo, consulte a seção Colunas de atributos:
Para criar o modelo all-MiniLM-L6-v2, no editor de consultas, execute a seguinte instrução CREATE MODEL:
```
 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ê enviou para o Cloud Storage. Se você usar o modelo de amostra, 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, você vai ver uma mensagem no painel Resultados da consulta semelhante a esta: Successfully created model named all-MiniLM-L6-v2.
Para abrir o painel Detalhes, clique em Ir para o modelo.
Para ver as entradas e as saídas do modelo na Coluna de rótulo, consulte a seção Colunas de atributos:

bq

Execute a instrução CREATE MODEL usando o comando query da ferramenta de linha de comando bq.

Crie 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ê enviou ao Cloud Storage. Se você usar o modelo de amostra, 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.
Crie 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ê enviou para o Cloud Storage. Se você usar o modelo de amostra, 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.

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.

Para criar o modelo tokenizer, use o seguinte parâmetro query:
```
{
  "query": "CREATE MODEL `PROJECT_ID :bqml_tutorial.tokenizer` OPTIONS(MODEL_TYPE='ONNX' MODEL_PATH='TOKENIZER_BUCKET_PATH')"
}
```
Substitua:
- PROJECT_ID: o ID do projeto.
- TOKENIZER_BUCKET_PATH: o caminho para o modelo que você enviou ao Cloud Storage. Se você usar o modelo de amostra, substitua TOKENIZER_BUCKET_PATH pelo seguinte valor: gs://cloud-samples-data/bigquery/ml/onnx/all-MiniLM-L6-v2/tokenizer.onnx.
Para criar o modelo all-MiniLM-L6-v2, use o seguinte valor de parâmetro query:
```
{
  "query": "CREATE MODEL `PROJECT_ID :bqml_tutorial.all-MiniLM-L6-v2` OPTIONS(MODEL_TYPE='ONNX' MODEL_PATH='TRANSFORMER_BUCKET_PATH')"
}
```
Substitua:
- PROJECT_ID: o ID do projeto.
- TRANSFORMER_BUCKET_PATH: o caminho para o modelo que você enviou ao Cloud Storage. Se você usar o modelo de amostra, substitua TRANSFORMER_BUCKET_PATH pelo seguinte valor: gs://cloud-samples-data/bigquery/ml/onnx/all-MiniLM-L6-v2/model_quantized.onnx.

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 transformador 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: o ID do projeto.
TOKENIZER_BUCKET_PATH: o caminho para o modelo que você enviou ao Cloud Storage. Se você usar o modelo de amostra, substitua TOKENIZER_BUCKET_PATH pelo seguinte valor: gs://cloud-samples-data/bigquery/ml/onnx/all-MiniLM-L6-v2/tokenizer.onnx.
TRANSFORMER_BUCKET_PATH: o caminho para o modelo que você enviou ao Cloud Storage. Se você usar o modelo de amostra, 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 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 o texto bruto diretamente pelo tokenizador e pelo modelo de embedding da seguinte maneira:

Tokenização (consulta interna): a chamada ML.PREDICT interna usa o modelo bqml_tutorial.tokenizer. Ele 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 brutas nas entradas de token numéricas exigidas pelo modelo principal, incluindo as entradas input_ids e attention_mask.
Geração de embedding (consulta externa): a chamada externa ML.PREDICT 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 o embedding semântico do texto.

Para gerar os embeddings, siga estas etapas:

No console do Cloud de Confiance , acesse a página do BigQuery Studio.

Acessar Studio

No editor de consultas, execute esta consulta:

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 o texto bruto diretamente pelo tokenizador e pelo modelo de embedding da seguinte maneira:

Tokenização (consulta interna): a chamada ML.PREDICT interna usa o modelo bqml_tutorial.tokenizer. Ele 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 brutas nas entradas de token numéricas exigidas pelo modelo principal, incluindo as entradas input_ids e attention_mask.
Geração de embedding (consulta externa): a chamada externa ML.PREDICT 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 o embedding semântico do texto.

Na linha de comando, execute o comando a seguir 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

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

No console Cloud de Confiance , acesse a página Gerenciar recursos.
Acessar "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

Exclua um projeto do Cloud de Confiance :

gcloud projects delete PROJECT_ID

Excluir recursos individuais

Como alternativa, para manter o projeto e excluir os recursos usados neste tutorial, siga estas etapas:

No console do Cloud de Confiance , acesse a página do BigQuery Studio.

Acessar Studio
No painel à esquerda, expanda o projeto e clique em Conjuntos de dados.
No conjunto de dados bqml_tutorial, clique em Abrir ações > Excluir.
Na caixa de diálogo Excluir conjunto de dados, clique em Excluir para confirmar.
Se você seguiu as etapas para converter manualmente os arquivos do modelo de transformador em ONNX, exclua o bucket do Cloud Storage.

A seguir

Saiba como 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 MODEL para modelos ONNX.
Para mais informações sobre como realizar previsões, consulte A função ML.PREDICT.
Para uma visão geral do BigQuery ML, consulte Introdução ao BigQuery ML.
Para começar a usar o BigQuery ML, consulte Criar modelos de machine learning no BigQuery ML.