Gerar embeddings de texto usando um modelo aberto e a função ML.GENERATE_EMBEDDING

Neste tutorial, mostramos como criar um modelo remoto baseado no modelo de embedding de texto de código aberto Qwen3-Embedding-0.6B e como usar esse modelo com a função ML.GENERATE_EMBEDDING para incorporar resenhas de filmes da tabela pública bigquery-public-data.imdb.reviews.

Permissões necessárias

Para seguir este tutorial, você precisa dos seguintes papéis do Identity and Access Management (IAM):

• Criar e usar conjuntos de dados, conexões e modelos do BigQuery: administrador do BigQuery (roles/bigquery.admin).
• Conceda permissões à conta de serviço da conexão: administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin).
• Implantar e remover a implantação de modelos na Vertex AI: administrador da Vertex AI (roles/aiplatform.admin).

Esses papéis predefinidos contêm as permissões necessárias para executar as tarefas neste documento. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

• Criar um conjunto de dados: bigquery.datasets.create
• Criar, delegar e usar uma conexão: bigquery.connections.*
• Defina a conexão padrão: bigquery.config.*
• Defina as permissões da conta de serviço: resourcemanager.projects.getIamPolicy e resourcemanager.projects.setIamPolicy
• Implantar e remover a implantação de um modelo da Vertex AI:
  • aiplatform.endpoints.deploy
  • aiplatform.endpoints.undeploy
• Crie um modelo e execute a inferência:
  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.models.updateMetadata

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

Custos

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

• BigQuery ML: You incur costs for the data that you process in BigQuery.
• Vertex AI: You incur costs for calls to the Vertex AI model that's represented by the remote model.

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.

Novos usuários do Google Cloud podem estar qualificados para um teste gratuito.

Para mais informações, consulte Preços do BigQuery na documentação do BigQuery.

Os modelos abertos implantados na Vertex AI são cobrados por hora de máquina. Isso significa que o faturamento começa assim que o endpoint é totalmente configurado e continua até que você o remova. Para mais informações sobre preços da Vertex AI, consulte esta página.

Antes de começar

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

   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

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

3. Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.

   Enable the APIs

Implantar um modelo Qwen3-Embedding-0.6B na Vertex AI

Implante o modelo Qwen/Qwen3-Embedding-0.6B do Hugging Face na Vertex AI seguindo as instruções em Implantar modelos do Hugging Face. Durante a implantação, selecione Público (endpoint compartilhado) como o valor do campo Acesso ao endpoint no fluxo de trabalho de implantação.

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

Criar o modelo remoto

Crie um modelo remoto que represente um modelo da Vertex AI:

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

   Acessar o BigQuery

2. No editor de consultas, execute a seguinte instrução:

CREATE OR REPLACE MODEL `bqml_tutorial.qwen3_embedding_model`
REMOTE WITH CONNECTION DEFAULT
OPTIONS (ENDPOINT = 'https://ENDPOINT_REGION-aiplatform.googleapis.com/v1/projects/ENDPOINT_PROJECT_ID/locations/ENDPOINT_REGION/endpoints/ENDPOINT_ID');

Substitua:

• ENDPOINT_REGION: a região em que o modelo aberto está implantado.
• ENDPOINT_PROJECT_ID: o projeto em que o modelo aberto é implantado.
• ENDPOINT_ID: o ID do endpoint HTTPS usado pelo modelo aberto. Para conseguir o ID do endpoint, localize o modelo aberto na página Previsão on-line e copie o valor no campo ID.

O exemplo a seguir mostra o formato de um endpoint HTTP válido:

https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/endpoints/1234.

A consulta leva alguns segundos para ser concluída. Depois disso, o modelo qwen3_embedding_model aparece no conjunto de dados bqml_tutorial no painel Explorer. Como a consulta usa uma instrução CREATE MODEL para criar um modelo, não há resultados de consulta.

Realizar incorporação de texto

Realize o embedding de texto em avaliações de filmes do IMDB usando o modelo remoto e a função ML.GENERATE_EMBEDDING:

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

   Acessar o BigQuery

2. No editor de consultas, insira a seguinte instrução para realizar a incorporação de texto em cinco avaliações de filmes:

   SELECT
     *
   FROM
     ML.GENERATE_EMBEDDING(
       MODEL `bqml_tutorial.qwen3_embedding_model`,
       (
         SELECT
           review AS content,
           *
         FROM
           `bigquery-public-data.imdb.reviews`
         LIMIT 5
       )
     );

   Os resultados incluem as seguintes colunas:

   • ml_generate_embedding_result: uma matriz de números de ponto flutuante de precisão dupla para representar os embeddings gerados.
   • ml_generate_embedding_status: o status da resposta da API sobre a linha correspondente. Se a operação tiver sido bem-sucedida, esse valor estará vazio.
   • content: o texto de entrada de que os embeddings serão extraídos.
   • Todas as colunas da tabela bigquery-public-data.imdb.reviews.

Cancelar a implantação do modelo

Se você optar por não excluir o projeto conforme recomendado, cancele a implantação do modelo de incorporação Qwen3 na Vertex AI para evitar cobranças contínuas.

Limpar

Cuidado: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para as tarefas neste documento, a exclusão dele vai resultar na exclusão de outros trabalhos feitos nele.
• Os IDs de projeto personalizados são perdidos. É possível que, ao criar o projeto, você tenha criado um ID de projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja explorar várias arquiteturas, tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda limites da cota.

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.

A seguir

• Aprenda a usar embeddings de texto para pesquisa semântica e geração aumentada de recuperação (RAG).