Como gerar embeddings de texto usando a função ML.GENERATE_CoordinateDING

Neste tutorial, mostramos como criar um modelo remoto do BigQuery ML que faz referência ao modelo de fundação de incorporação da Vertex AI. Em seguida, use esse modelo com a função ML.GENERATE_EMBEDDING para criar embeddings de texto usando dados de uma tabela padrão do BigQuery.

Funções exigidas

  • Para criar uma conexão, você precisa da associação no seguinte papel do Identity and Access Management (IAM):

    • roles/bigquery.connectionAdmin

  • Para conceder permissões à conta de serviço da conexão, você precisa da seguinte permissão:

    • resourcemanager.projects.setIamPolicy

  • Para criar o modelo usando o BigQuery ML, você precisa das seguintes permissões do IAM:

    • bigquery.jobs.create
    • bigquery.models.create
    • bigquery.models.getData
    • bigquery.models.updateData
    • bigquery.models.updateMetadata

  • Para executar a inferência, você precisa das seguintes permissões:

    • bigquery.tables.getData na tabela
    • bigquery.models.getData no modelo
    • bigquery.jobs.create

Antes de começar

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

    Go to project selector

  2. Make sure that billing is enabled for your Google Cloud project.

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

    Enable the APIs

Criar um conjunto de dados

Crie um conjunto de dados do BigQuery para armazenar o modelo de ML:

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

    Acesse 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.

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

      Os conjuntos de dados públicos são armazenados na multirregião US. Para simplificar, armazene seus conjuntos de dados no mesmo local.

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

      Página Criar conjunto de dados.

Criar uma conexão

Crie uma Conexão de recursos do Cloud e tenha acesso à conta de serviço da conexão. Crie a conexão no mesmo local do conjunto de dados criado na etapa anterior.

Selecione uma das seguintes opções:

Console

  1. Acessar a página do BigQuery.

    Acessar o BigQuery

  2. Para criar uma conexão, clique em Adicionar e em Conexões com fontes de dados externas.

  3. Na lista Tipo de conexão, selecione Modelos remotos da Vertex AI, funções remotas e BigLake (Cloud Resource).

  4. No campo ID da conexão, insira um nome para a conexão.

  5. Clique em Criar conexão.

  6. Clique em Ir para conexão.

  7. No painel Informações da conexão, copie o ID da conta de serviço para uso em uma etapa posterior.

bq

  1. Em um ambiente de linha de comando, crie uma conexão:

    bq mk --connection --location=REGION --project_id=PROJECT_ID \
    --connection_type=CLOUD_RESOURCE CONNECTION_ID

    O parâmetro --project_id substitui o projeto padrão.

    Substitua:

    • REGION: sua região de conexão
    • PROJECT_ID: o ID do projeto do Google Cloud
    • CONNECTION_ID: um ID para sua conexão

    Quando você cria um recurso de conexão, o BigQuery cria uma conta de serviço do sistema exclusiva e a associa à conexão.

    Solução de problemas: se você receber o seguinte erro de conexão, atualize o SDK Google Cloud:

    Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...

  2. Recupere e copie o ID da conta de serviço para uso em uma etapa posterior:

    bq show --connection PROJECT_ID.REGION.CONNECTION_ID

    O resultado será assim:

    name                          properties
1234.REGION.CONNECTION_ID     {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}

Terraform

Use o recurso google_bigquery_connection.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

O exemplo a seguir cria uma conexão de recurso do Cloud chamada my_cloud_resource_connection na região US:


# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Para aplicar a configuração do Terraform em um projeto do Google Cloud, conclua as etapas nas seções a seguir.

Preparar o Cloud Shell

  1. Inicie o Cloud Shell.

  2. Defina o projeto padrão do Google Cloud em que você quer aplicar as configurações do Terraform.

    Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

  1. No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

    Copie o exemplo de código no main.tf recém-criado.

    Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.

  3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
  4. Salve as alterações.
  5. Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório. 
    terraform init

    Opcionalmente, para usar a versão mais recente do provedor do Google, inclua a opção -upgrade: 

    terraform init -upgrade

Aplique as alterações

  1. Revise a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expectativas: 
    terraform plan

    Faça as correções necessárias na configuração.

  2. Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt: 
    terraform apply

    Aguarde até que o Terraform exiba a mensagem "Apply complete!".

  3. Abra seu projeto do Google Cloud para ver os resultados. No console do Google Cloud, navegue até seus recursos na IU para verificar se foram criados ou atualizados pelo Terraform.

Conceder acesso à conta de serviço

Conceda à conta de serviço da conexão a função de usuário da Vertex AI.

Se você planeja especificar o endpoint como um URL ao criar o modelo remoto, por exemplo, endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/text-embedding-004', conceda essa função no mesmo projeto especificado no URL.

Se você planeja especificar o endpoint usando o nome do modelo ao criar o modelo remoto, por exemplo, endpoint = 'text-embedding-004', conceda esse papel no mesmo projeto em que planeja criar o modelo remoto.

Conceder o papel em um projeto diferente resulta no erro bqcx-1234567890-xxxx@gcp-sa-bigquery-condel.iam.gserviceaccount.com does not have the permission to access resource.

Para conceder o papel, siga estas etapas:

Console

  1. Acesse a página IAM e administrador.

    Acessar IAM e administrador

  2. Clique em CONCEDER ACESSO.

    A caixa de diálogo Adicionar principais é aberta.

  3. No campo Novos principais, digite o ID da conta de serviço que você copiou anteriormente.

  4. No campo Selecionar um papel, selecione Vertex AI e, em seguida, selecione Usuário da Vertex AI.

  5. Clique em Salvar.

gcloud

Use o comando gcloud projects add-iam-policy-binding (em inglês).

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/aiplatform.user' --condition=None

Substitua:

  • PROJECT_NUMBER: o ID do seu projeto
  • MEMBER: o ID da conta de serviço que você copiou anteriormente

Criar um modelo

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

    Acessar o BigQuery

  2. Usando o editor de SQL, crie um modelo remoto:

    CREATE OR REPLACE MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION `CONNECTION_ID`
OPTIONS (ENDPOINT = 'ENDPOINT');

    Substitua:

    • PROJECT_ID: ID do projeto
    • DATASET_ID: o ID do conjunto de dados para conter o modelo
    • MODEL_NAME: o nome do modelo
    • CONNECTION_ID: o ID da conexão do BigQuery

      Quando você visualiza os detalhes da conexão no console do Google Cloud, esse é o valor na última seção do ID da conexão totalmente qualificado, mostrado em ID da conexão, por exemplo projects/myproject/locations/connection_location/connections/myconnection

    • ENDPOINT: o nome do modelo de embedding a ser usado. Precisa ser um modelo text-embedding, text-multilingual-embedding ou multimodalembedding. Para mais informações sobre versões e aliases de modelos compatíveis, consulte ENDPOINT.

Gerar embeddings de texto usando dados de uma tabela

Gere embeddings de texto com a função ML.GENERATE_EMBEDDING usando dados de texto de uma coluna da tabela.

Normalmente, você quer usar um modelo text-embedding ou text-multilingual-embedding para casos de uso somente de texto e um modelo multimodalembedding para casos de uso de pesquisa multimodal, em que os embeddings para conteúdo de texto e visual são gerados no mesmo espaço semântico.

embedding de texto

Gere embeddings de texto usando um modelo remoto em um modelo de embedding:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE PROJECT_ID.DATASET_ID.TABLE_NAME,
  STRUCT(FLATTEN_JSON AS flatten_json_output,
    TASK_TYPE AS task_type,
    OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

Substitua:

  • PROJECT_ID: o ID do projeto.
  • DATASET_ID: o ID do conjunto de dados que contém o modelo.
  • MODEL_NAME: o nome do modelo remoto sobre um modelo de embedding.
  • TABLE_NAME: o nome da tabela que contém o texto a ser incorporado. Essa tabela precisa ter uma tabela chamada content ou é possível utilizar um alias para usar uma coluna com um nome diferente.
  • FLATTEN_JSON: um valor BOOL que indica se é necessário analisar a incorporação em uma coluna separada. O valor padrão é TRUE.
  • TASK_TYPE: um literal STRING que especifica o aplicativo downstream pretendido para ajudar o modelo a produzir embeddings de melhor qualidade. TASK_TYPE aceita os seguintes valores:
    • RETRIEVAL_QUERY: especifica que o texto é uma consulta em uma configuração de pesquisa ou recuperação.
    • RETRIEVAL_DOCUMENT: especifica que o texto é um documento em uma configuração de pesquisa ou recuperação.

      Ao usar esse tipo de tarefa, vale a pena incluir o título do documento na declaração de consulta para melhorar a qualidade da incorporação. Você pode usar a opção title para especificar o nome da coluna que contém o título do documento. Caso contrário, o título do documento precisa estar em uma coluna chamada title ou com o alias como title, por exemplo: 

            SELECT *
      FROM
        ML.GENERATE_EMBEDDING(
          MODEL mydataset.embedding_model,
          (SELECT abstract as content, header as title, publication_number
          FROM mydataset.publications),
          STRUCT(TRUE AS flatten_json_output, 'RETRIEVAL_DOCUMENT' as task_type)
      );
    • SEMANTIC_SIMILARITY: especifica o texto a ser usado para similaridade textual semântica (STS).
    • CLASSIFICATION: especifica que os embeddings serão usados para classificação.
    • CLUSTERING: especifica que os embeddings serão usados para clustering.
  • OUTPUT_DIMENSIONALITY: um INT64 valor que especifica o número de dimensões a serem usadas ao gerar os embeddings de vários tipos. Por exemplo, se você especificar 256 AS output_dimensionality, o ml_generate_embedding_result a coluna de saída contém 256 embeddings para cada valor de entrada.

    Esse argumento só poderá ser usado se o modelo remoto que você especificar no argumento model usa um dos seguintes modelos como um endpoint:

    • text-embedding-004 ou posterior
    • text-multilingual-embedding-002 ou posterior

embedding multimodal

Gere embeddings de texto usando um modelo remoto no LLM multimodalembedding:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE PROJECT_ID.DATASET_ID.TABLE_NAME,
  STRUCT(FLATTEN_JSON AS flatten_json_output，
  OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

Substitua:

  • PROJECT_ID: o ID do projeto.
  • DATASET_ID: o ID do conjunto de dados que contém o modelo.
  • MODEL_NAME: o nome do modelo remoto em um modelo multimodalembedding@001.
  • TABLE_NAME: o nome da tabela que contém o texto a ser incorporado. Essa tabela precisa ter uma tabela chamada content ou é possível utilizar um alias para usar uma coluna com um nome diferente.
  • FLATTEN_JSON: um BOOL que indica se é necessário analisar a incorporação em uma coluna separada. O valor padrão é TRUE.
  • OUTPUT_DIMENSIONALITY: um INT64 valor que especifica o número de dimensões a serem usadas ao gerar os embeddings de vários tipos. Os valores válidos são: 128, 256, 512 e 1408. O valor padrão é 1408. Por exemplo, se você especificar 256 AS output_dimensionality, o ml_generate_embedding_result a coluna de saída contém 256 embeddings para cada valor de entrada.

Gerar embeddings de texto usando dados de uma consulta

Gerar embeddings de texto com a função ML.GENERATE_EMBEDDING usando dados de texto fornecidos por uma consulta e um modelo remoto em vez de estar incorporado.

Normalmente, você quer usar um modelo text-embedding ou text-multilingual-embedding para casos de uso somente de texto e um modelo multimodalembedding para casos de uso de pesquisa multimodal, em que os embeddings para conteúdo de texto e visual são gerados no mesmo espaço semântico.

embedding de texto

Gere embeddings de texto usando um modelo remoto em vez de incorporado:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  (CONTENT_QUERY),
  STRUCT(FLATTEN_JSON AS flatten_json_output,
    TASK_TYPE AS task_type,
    OUTPUT_DIMENSIONALITY AS output_dimensionality)
  );

Substitua:

  • PROJECT_ID: o ID do projeto.
  • DATASET_ID: o ID do conjunto de dados que contém o modelo.
  • MODEL_NAME: o nome do modelo remoto sobre um modelo de embedding.
  • CONTENT_QUERY: uma consulta cujo resultado contém uma coluna STRING chamada content.
  • FLATTEN_JSON: um valor BOOL que indica se é necessário analisar a incorporação em uma coluna separada. O valor padrão é TRUE.
  • TASK_TYPE: um literal STRING que especifica o aplicativo downstream pretendido para ajudar o modelo a produzir embeddings de melhor qualidade. TASK_TYPE aceita os seguintes valores:
    • RETRIEVAL_QUERY: especifica que o texto é uma consulta em uma configuração de pesquisa ou recuperação.
    • RETRIEVAL_DOCUMENT: especifica que o texto é um documento em uma configuração de pesquisa ou recuperação.

      Ao usar esse tipo de tarefa, vale a pena incluir o título do documento na declaração de consulta para melhorar a qualidade da incorporação. Você pode usar a opção title para especificar o nome da coluna que contém o título do documento. Caso contrário, o título do documento precisa estar em uma coluna chamada title ou com o alias como title, por exemplo: 

                SELECT *
          FROM
            ML.GENERATE_EMBEDDING(
              MODEL mydataset.embedding_model,
              (SELECT abstract as content, header as title, publication_number
              FROM mydataset.publications),
              STRUCT(TRUE AS flatten_json_output, 'RETRIEVAL_DOCUMENT' as task_type)
          );
    • SEMANTIC_SIMILARITY: especifica o texto a ser usado para similaridade textual semântica (STS).
    • CLASSIFICATION: especifica que os embeddings serão usados para classificação.
    • CLUSTERING: especifica que os embeddings serão usados para clustering.
  • OUTPUT_DIMENSIONALITY: um INT64 que especifica o número de dimensões a serem usadas ao gerar os embeddings de vários tipos. Por exemplo, se você especificar 256 AS output_dimensionality, o ml_generate_embedding_result a coluna de saída contém 256 embeddings para cada valor de entrada.

    Esse argumento só poderá ser usado se o modelo remoto que você especificar no argumento model usa um dos seguintes modelos como um endpoint:

    • text-embedding-004 ou posterior
    • text-multilingual-embedding-002 ou posterior

embedding multimodal

Gere embeddings de texto usando um modelo remoto no LLM multimodalembedding:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  (CONTENT_QUERY),
  STRUCT(FLATTEN_JSON AS flatten_json_output,
  OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

Substitua:

  • PROJECT_ID: o ID do projeto.
  • DATASET_ID: o ID do conjunto de dados que contém o modelo.
  • MODEL_NAME: o nome do modelo remoto em um modelo multimodalembedding@001.
  • CONTENT_QUERY: uma consulta cujo resultado contém uma coluna STRING chamada content.
  • FLATTEN_JSON: um BOOL que indica se é necessário analisar a incorporação em uma coluna separada. O valor padrão é TRUE.
  • OUTPUT_DIMENSIONALITY: um INT64 valor que especifica o número de dimensões a serem usadas ao gerar os embeddings de vários tipos. Os valores válidos são: 128, 256, 512 e 1408. O valor padrão é 1408. Por exemplo, se você especificar 256 AS output_dimensionality, o ml_generate_embedding_result a coluna de saída contém 256 embeddings para cada valor de entrada.

Exemplos

Os exemplos a seguir mostram como chamar a função ML.GENERATE_EMBEDDING em uma tabela e uma consulta.

Incorporar texto em uma tabela

O exemplo a seguir mostra uma solicitação para incorporar a coluna content da tabela text_data:

SELECT *
FROM
  ML.GENERATE_EMBEDDING(
    MODEL `mydataset.embedding_model`,
    TABLE mydataset.text_data,
    STRUCT(TRUE AS flatten_json_output, 'CLASSIFICATION' AS task_type)
  );

Usar incorporações para classificar semelhança semântica

O exemplo a seguir incorpora uma coleção de avaliações de filmes e as ordena pela distância do cosseno à avaliação "Este filme foi médio" usando a função ML.DISTANCE. Uma distância menor indica mais semelhança semântica.

WITH movie_review_embeddings AS (
  SELECT *
  FROM
    ML.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (
        SELECT "Movie 1" AS title, "This movie was fantastic" AS content
        UNION ALL
        SELECT "Movie 2" AS title, "This was the best movie I've ever seen!!" AS content
        UNION ALL
        SELECT "Movie 3" AS title, "This movie was just okay..." AS content
        UNION ALL
        SELECT "Movie 4" AS title, "This movie was terrible." AS content
      ),
      STRUCT(TRUE AS flatten_json_output)
    )
),
average_review_embedding AS (
  SELECT ml_generate_embedding_result
  FROM
    ML.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (SELECT "This movie was average" AS content),
      STRUCT(TRUE AS flatten_json_output)
    )
)
SELECT
  content,
  ML.DISTANCE(
    (SELECT ml_generate_embedding_result FROM average_review_embedding),
    ml_generate_embedding_result,
    'COSINE'
  ) AS distance_to_average_review
FROM
  movie_review_embeddings
ORDER BY distance_to_average_review;

O resultado é o seguinte:

+------------------------------------------+----------------------------+
| content                                  | distance_to_average_review |
+------------------------------------------+----------------------------+
| This movie was just okay...              | 0.062789813467745592       |
| This movie was fantastic                 |  0.18579561313064263       |
| This movie was terrible.                 |  0.35707466240930985       |
| This was the best movie I've ever seen!! |  0.41844932504542975       |
+------------------------------------------+----------------------------+