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 a um modelo de incorporação. 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.

Os seguintes tipos de modelos remotos são compatíveis:

• Modelos remotos sobre modelos de embedding da Vertex AI.
• Modelos remotos em modelos abertos compatíveis (pré-lançamento).

Funções exigidas

Para criar um modelo remoto e usar a função ML.GENERATE_EMBEDDING, você precisa dos seguintes papéis do Identity and Access Management (IAM):

• Criar e usar conjuntos de dados, tabelas e modelos do BigQuery: Editor de dados do BigQuery (roles/bigquery.dataEditor) no seu projeto.

• Crie, delegue e use conexões do BigQuery: administrador de conexões do BigQuery (roles/bigquery.connectionsAdmin) no seu projeto.

  Se você não tiver uma conexão padrão configurada, crie e defina uma como parte da execução da instrução CREATE MODEL. Para isso, você precisa ter a função de administrador do BigQuery (roles/bigquery.admin) no seu projeto. Para mais informações, consulte Configurar a conexão padrão.

• Conceda permissões à conta de serviço da conexão: Administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin) no projeto que contém o endpoint da Vertex AI. Este é o projeto atual para modelos remotos que você cria especificando o nome do modelo como um endpoint. Esse é o projeto identificado no URL para modelos remotos que você cria especificando um URL como endpoint.

• Criar jobs do BigQuery: usuário de jobs do BigQuery (roles/bigquery.jobUser) no seu projeto.

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 as permissões da conta de serviço: resourcemanager.projects.getIamPolicy e resourcemanager.projects.setIamPolicy
• Crie um modelo e execute a inferência:
  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.models.updateMetadata
• Consultar dados da tabela: bigquery.tables.getData

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

Antes de começar

1. 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 (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

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

3. Enable the BigQuery, BigQuery Connection, and Vertex AI 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

crie um conjunto de dados

Crie um conjunto de dados do BigQuery para conter seus recursos:

Console

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

   Acessar o BigQuery

2. No painel à esquerda, clique em Explorer:

   

   Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.

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

4. Clique em Conferir ações > Criar conjunto de dados.

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

   1. Em ID do conjunto de dados, digite um nome para o conjunto de dados.

   2. Em Tipo de local, selecione Região ou Multirregião.

      • Se você selecionou Região, escolha um local na lista Região.
      • Se você selecionou Multirregião, escolha EUA ou Europa na lista Multirregião.

   3. Clique em Criar conjunto de dados.

bq

1. Para criar um conjunto de dados, use o comando bq mk com a flag --location:

   bq --location=LOCATION mk -d DATASET_ID

   Substitua:

   • LOCATION: o local do conjunto de dados.
   • DATASET_ID é o ID do conjunto de dados que você está criando.

2. Confirme se o conjunto de dados foi criado:

   bq ls

Crie uma conexão

Pule esta etapa se você tiver uma conexão padrão configurada ou a função de administrador do BigQuery.

Crie uma Conexão de recursos do Cloud para o modelo remoto usar 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. No painel Explorer, clique em Adicionar dados:

   

   A caixa de diálogo Adicionar dados é aberta.

3. No painel Filtrar por, na seção Tipo de fonte de dados, selecione Aplicativos comerciais.

   Como alternativa, no campo Pesquisar fontes de dados, insira Vertex AI.

4. Na seção Fontes de dados em destaque, clique em Vertex AI.

5. Clique no card da solução Modelos da Vertex AI: federação do BigQuery.

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

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

8. Clique em Criar conexão.

9. Clique em Ir para conexão.

10. 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 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": "[e-mail]"}
   

Terraform

Use o recurso google_bigquery_connection.

Observação: para criar objetos do BigQuery usando o Terraform, é necessário ativar a API Cloud Resource Manager.

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 Google 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 Google Cloud , siga as etapas nas seções a seguir.

Preparar o Cloud Shell

1. Inicie o Cloud Shell.

2. Defina o projeto Google Cloud padrão 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 Google Cloud projeto para conferir os resultados. No console do Google Cloud , navegue até seus recursos na UI para verificar se foram criados ou atualizados pelo Terraform.

Observação:as amostras do Terraform geralmente presumem que as APIs necessárias estejam ativadas no seu Google Cloud projeto.

Conceder um papel à conta de serviço da conexão do modelo remoto

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-005', 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-005', conceda essa função no mesmo projeto em que planeja criar o modelo remoto.

Conceder a função em um projeto diferente resulta no erro [e-mail] 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

Escolher um método de implantação de modelo aberto

Se você estiver criando um modelo remoto em um modelo aberto compatível, é possível implantar automaticamente o modelo aberto ao mesmo tempo em que cria o modelo remoto especificando o ID do modelo do Model Garden da Vertex AI ou da Hugging Face na instrução CREATE MODEL. Outra opção é implantar manualmente o modelo aberto primeiro e depois usar esse modelo com o modelo remoto especificando o endpoint do modelo na instrução CREATE MODEL. Para mais informações, consulte Implantar modelos abertos.

Criar um modelo remoto do BigQuery ML

Crie um modelo remoto:

Novos modelos abertos

Pré-lançamento

Este produto ou recurso está sujeitos aos "Termos das Soluções Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis no estado em que se encontram e podem ter suporte limitado. Você encontra mais detalhes nas descrições das fases de lançamento.

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 {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
   OPTIONS (
     {HUGGING_FACE_MODEL_ID = 'HUGGING_FACE_MODEL_ID' |
        MODEL_GARDEN_MODEL_NAME = 'MODEL_GARDEN_MODEL_NAME'}
     [, HUGGING_FACE_TOKEN = 'HUGGING_FACE_TOKEN' ]
     [, MACHINE_TYPE = 'MACHINE_TYPE' ]
     [, MIN_REPLICA_COUNT = MIN_REPLICA_COUNT ]
     [, MAX_REPLICA_COUNT = MAX_REPLICA_COUNT ]
     [, RESERVATION_AFFINITY_TYPE = {'NO_RESERVATION' | 'ANY_RESERVATION' | 'SPECIFIC_RESERVATION'} ]
     [, RESERVATION_AFFINITY_KEY = 'compute.googleapis.com/reservation-name' ]
     [, RESERVATION_AFFINITY_VALUES = RESERVATION_AFFINITY_VALUES ]
     [, ENDPOINT_IDLE_TTL = ENDPOINT_IDLE_TTL ]
   );

   Substitua:

   • PROJECT_ID: o ID do projeto.
   • DATASET_ID: o ID do conjunto de dados para conter o modelo. Esse conjunto de dados precisa estar no mesmo local que a conexão que você está usando.
   • MODEL_NAME: o nome do modelo
   • REGION: a região usada pela conexão.
   • CONNECTION_ID: o ID da conexão do BigQuery

     Para conseguir esse valor, veja os detalhes da conexão no console do Google Cloud e copie 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.

   • HUGGING_FACE_MODEL_ID: um valor STRING que especifica o ID de um modelo compatível do Hugging Face, no formato provider_name/model_name. Por exemplo, deepseek-ai/DeepSeek-R1. Para conseguir o ID do modelo, clique no nome dele no Hub de modelos do Hugging Face e copie o ID na parte de cima do card.
   • MODEL_GARDEN_MODEL_NAME: um valor STRING que especifica o ID e a versão de um modelo compatível do Model Garden da Vertex AI, no formato publishers/publisher/models/model_name@model_version. Exemplo: publishers/openai/models/gpt-oss@gpt-oss-120b. Para conseguir o ID do modelo, clique no card dele no Model Garden da Vertex AI e copie o ID no campo ID do modelo. Para copiar a versão padrão do modelo, acesse o campo Versão no card do modelo. Para ver outras versões de modelo que podem ser usadas, clique em Implantar modelo e depois no campo ID do recurso.
   • HUGGING_FACE_TOKEN: um valor STRING que especifica o token de acesso do usuário do Hugging Face a ser usado. Só é possível especificar um valor para essa opção se você também especificar um valor para a opção HUGGING_FACE_MODEL_ID.

     O token precisa ter pelo menos a função read, mas tokens com um escopo mais amplo também são aceitos. Essa opção é obrigatória quando o modelo identificado pelo valor HUGGING_FACE_MODEL_ID é um modelo restrito ou particular do Hugging Face.

     Alguns modelos restritos exigem concordância explícita com os Termos de Serviço antes de conceder o acesso. Para concordar com estes termos, siga estas etapas:

     1. Acesse a página do modelo no site do Hugging Face.
     2. Localize e leia os Termos de Serviço do modelo. Normalmente, um link para o contrato de serviço é encontrado no card do modelo.
     3. Aceite os termos conforme solicitado na página.
   • MACHINE_TYPE: um valor STRING que especifica o tipo de máquina a ser usado ao implantar o modelo na Vertex AI. Para informações sobre tipos de máquinas compatíveis, consulte Tipos de máquinas. Se você não especificar um valor para a opção MACHINE_TYPE, será usado o tipo de máquina padrão do Model Garden da Vertex AI para o modelo.
   • MIN_REPLICA_COUNT: um valor INT64 que especifica o número mínimo de réplicas de máquina usadas ao implantar o modelo em um endpoint da Vertex AI. O serviço aumenta ou diminui a contagem de réplicas conforme necessário para a carga de inferência no endpoint. O número de réplicas usadas nunca é menor que o valor MIN_REPLICA_COUNT nem maior que o valor MAX_REPLICA_COUNT. O valor MIN_REPLICA_COUNT precisa estar no intervalo [1, 4096]. O valor padrão é 1.
   • MAX_REPLICA_COUNT: um valor INT64 que especifica o número máximo de réplicas de máquina usadas ao implantar o modelo em um endpoint da Vertex AI. O serviço aumenta ou diminui a contagem de réplicas conforme necessário para a carga de inferência no endpoint. O número de réplicas usadas nunca é menor que o valor MIN_REPLICA_COUNT nem maior que o valor MAX_REPLICA_COUNT. O valor MAX_REPLICA_COUNT precisa estar no intervalo [1, 4096]. O valor padrão é o valor MIN_REPLICA_COUNT.
   • RESERVATION_AFFINITY_TYPE: determina se o modelo implantado usa reservas do Compute Engine para garantir a disponibilidade de máquina virtual (VMs) ao veicular previsões e especifica se o modelo usa VMs de todas as reservas disponíveis ou apenas de uma reserva específica. Para mais informações, consulte Afinidade de reserva do Compute Engine.

     Só é possível usar reservas do Compute Engine compartilhadas com a Vertex AI. Para mais informações, consulte Permitir o consumo de uma reserva.

     Confira os valores compatíveis:

     • NO_RESERVATION: nenhuma reserva é consumida quando o modelo é implantado em um endpoint da Vertex AI. Especificar NO_RESERVATION tem o mesmo efeito que não especificar uma afinidade de reserva.
     • ANY_RESERVATION: a implantação do modelo da Vertex AI consome máquinas virtuais (VMs) de reservas do Compute Engine que estão no projeto atual ou que são compartilhadas com o projeto e que estão configuradas para consumo automático. Somente as VMs que atendem às seguintes qualificações são usadas:
       • Eles usam o tipo de máquina especificado pelo valor MACHINE_TYPE.
       • Se o conjunto de dados do BigQuery em que você está criando o modelo remoto for de uma única região, a reserva precisará estar na mesma região. Se o conjunto de dados estiver na multirregião US, a reserva precisará estar na região us-central1. Se o conjunto de dados estiver na multirregião EU, a reserva precisará estar na região europe-west4.

       Se não houver capacidade suficiente nas reservas disponíveis ou se nenhuma reserva adequada for encontrada, o sistema vai provisionar VMs do Compute Engine sob demanda para atender aos requisitos de recursos.

     • SPECIFIC_RESERVATION: a implantação do modelo da Vertex AI consome VMs apenas da reserva especificada no valor RESERVATION_AFFINITY_VALUES. Essa reserva precisa ser configurada para consumo segmentado especificamente. A implantação falha se a reserva especificada não tiver capacidade suficiente.
   • RESERVATION_AFFINITY_KEY: a string compute.googleapis.com/reservation-name. É necessário especificar essa opção quando o valor de RESERVATION_AFFINITY_TYPE for SPECIFIC_RESERVATION.
   • RESERVATION_AFFINITY_VALUES: um valor ARRAY<STRING> que especifica o nome completo do recurso da reserva do Compute Engine, no seguinte formato:
     
     projects/myproject/zones/reservation_zone/reservations/reservation_name

     Por exemplo, RESERVATION_AFFINITY_values = ['projects/myProject/zones/us-central1-a/reservations/myReservationName'].

     É possível conferir o nome e a zona da reserva na página Reservas do console do Google Cloud . Para mais informações, consulte Conferir reservas.

     Você precisa especificar essa opção quando o valor de RESERVATION_AFFINITY_TYPE é SPECIFIC_RESERVATION.

   • ENDPOINT_IDLE_TTL: um valor INTERVAL que especifica a duração da inatividade após a qual o modelo aberto é automaticamente removido do endpoint da Vertex AI.

     Para ativar a remoção automática, especifique um valor de literal de intervalo entre 390 minutos (6,5 horas) e 7 dias. Por exemplo, especifique INTERVAL 8 HOUR para que o modelo seja removido após 8 horas de inatividade. O valor padrão é 390 minutos (6,5 horas).

     A inatividade do modelo é definida como o período que passou desde que uma das seguintes operações foi realizada no modelo:

     • Executar a instrução CREATE MODEL.
     • Executar a instrução ALTER MODEL com o argumento DEPLOY_MODEL definido como TRUE.
     • Enviar uma solicitação de inferência para o endpoint do modelo. Por exemplo, executando a função ML.GENERATE_EMBEDDING ou ML.GENERATE_TEXT.

     Cada uma dessas operações redefine o timer de inatividade para zero. A redefinição é acionada no início do job do BigQuery que realiza a operação.

     Depois que o modelo é removido da implantação, as solicitações de inferência enviadas a ele retornam um erro. O objeto do modelo do BigQuery permanece inalterado, incluindo os metadados do modelo. Para usar o modelo novamente para inferência, é necessário implantá-lo novamente executando a instrução ALTER MODEL no modelo e definindo a opção DEPLOY_MODEL como TRUE.

Modelos abertos implantados

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 {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
   OPTIONS (
     ENDPOINT = 'https://ENDPOINT_REGION-aiplatform.googleapis.com/v1/projects/ENDPOINT_PROJECT_ID/locations/ENDPOINT_REGION/endpoints/ENDPOINT_ID'
   );

   Substitua:

   • PROJECT_ID: o ID do projeto.
   • DATASET_ID: o ID do conjunto de dados para conter o modelo. Esse conjunto de dados precisa estar no mesmo local que a conexão que você está usando.
   • MODEL_NAME: o nome do modelo
   • REGION: a região usada pela conexão.
   • CONNECTION_ID: o ID da conexão do BigQuery

     Para conseguir esse valor, veja os detalhes da conexão no console do Google Cloud e copie 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_REGION: a região em que o modelo aberto está implantado.
   • ENDPOINT_PROJECT_ID: o projeto em que o modelo aberto está 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.

Todos os outros modelos

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 {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
   OPTIONS (ENDPOINT = 'ENDPOINT');

   Substitua:

   • PROJECT_ID: o ID do projeto.
   • DATASET_ID: o ID do conjunto de dados para conter o modelo. Esse conjunto de dados precisa estar no mesmo local que a conexão que você está usando.
   • MODEL_NAME: o nome do modelo
   • REGION: a região usada pela conexão.
   • CONNECTION_ID: o ID da conexão do BigQuery

     Para conseguir esse valor, veja os detalhes da conexão no console do Google Cloud e copie 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 de um modelo de embedding a ser usado. Para mais informações, consulte ENDPOINT.

     O modelo da Vertex AI especificado precisa estar disponível no local em que você está criando o modelo remoto. Para mais informações, consulte Locais.

Gerar embeddings de texto

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

Normalmente, você usaria um modelo de embedding de texto para casos de uso somente de texto e um modelo de embedding multimodal 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.

Texto da Vertex AI

Gere embeddings de texto usando um modelo remoto em vez de um modelo de embedding de texto da Vertex AI:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  {TABLE PROJECT_ID.DATASET_ID.TABLE_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.
• 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.
• 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. 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)
          );
          

    Especificar a coluna de título na consulta de entrada preenche o campo title do corpo da solicitação enviado ao modelo. Se você especificar um valor de title ao usar qualquer outro tipo de tarefa, essa entrada será ignorada e não terá efeito nos resultados do embedding.

  • 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.
  • QUESTION_ANSWERING: especifica que os embeddings serão usados para responder a perguntas.
  • FACT_VERIFICATION: especifica que os embeddings serão usados para verificação de fatos.
  • CODE_RETRIEVAL_QUERY: especifica que os embeddings serão usados para recuperação de código.
• 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, a coluna de saída ml_generate_embedding_result vai conter 256 embeddings para cada valor de entrada.

  Para modelos remotos em relação a modelos gemini-embedding-001, o valor OUTPUT_DIMENSIONALITY precisa estar no intervalo [1, 3072]. O valor padrão é 3072. Para modelos remotos de text-embedding ou text-multilingual-embedding o valor de OUTPUT_DIMENSIONALITY precisa estar no intervalo [1, 768]. O valor padrão é 768.

  Se você estiver usando um modelo remoto em vez de um modelo text-embedding, a versão do modelo text-embedding precisa ser text-embedding-004 ou mais recente. Se você estiver usando um modelo remoto em vez de um modelo text-multilingual-embedding, a versão do modelo text-multilingual-embedding precisa ser text-multilingual-embedding-002 ou mais recente.

Exemplo: 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)
  );

Texto livre

Pré-lançamento

Este produto ou recurso está sujeitos aos "Termos das Soluções Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis no estado em que se encontram e podem ter suporte limitado. Você encontra mais detalhes nas descrições das fases de lançamento.

Observação :para enviar feedback ou solicitar suporte sobre esse recurso, entre em contato com [e-mail].

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

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  {TABLE PROJECT_ID.DATASET_ID.TABLE_NAME | (CONTENT_QUERY)},
  STRUCT(FLATTEN_JSON AS flatten_json_output)
);

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

Multimodal da Vertex AI

Gere embeddings de texto usando um modelo remoto em um modelo de embedding multimodal da Vertex AI:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  {TABLE PROJECT_ID.DATASET_ID.TABLE_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.
• 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.
• 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.

Exemplo: usar embeddings para classificar a similaridade 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 VECTOR_SEARCH. Uma distância menor indica mais semelhança semântica.

Para mais informações sobre pesquisa e índice vetorial, consulte Introdução à pesquisa vetorial.

CREATE TEMPORARY TABLE movie_review_embeddings AS (
  SELECT *
  FROM
    ML.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (
        SELECT "This movie was fantastic" AS content
        UNION ALL
        SELECT "This was the best movie I've ever seen!!" AS content
        UNION ALL
        SELECT "This movie was just okay..." AS content
        UNION ALL
        SELECT "This movie was terrible." AS content
      ),
      STRUCT(TRUE AS flatten_json_output)
    )
);

WITH 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
  base.content AS content,
  distance AS distance_to_average_review
FROM
  VECTOR_SEARCH(
    TABLE movie_review_embeddings,
    "ml_generate_embedding_result",
    (SELECT ml_generate_embedding_result FROM average_review_embedding),
    distance_type=>"COSINE",
    top_k=>-1
  )
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       |
+------------------------------------------+----------------------------+

A seguir

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