Como gerar incorporações de vídeo usando a função ML.GENERATE_EMBEDDING

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 vídeo usando dados de uma tabela de objetos do BigQuery.

Funções exigidas

Para criar um modelo remoto e gerar incorporações, você precisa das seguintes funções 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.

    Se você usar o modelo remoto para analisar dados não estruturados de uma tabela de objetos e o bucket do Cloud Storage usado na tabela estiver em um projeto diferente do seu endpoint da Vertex AI, também será necessário ter o papel de administrador do Storage (roles/storage.admin) no bucket do Cloud Storage usado pela tabela de objetos.

  • 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 uma tabela de objetos: bigquery.tables.create e bigquery.tables.update
  • 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.

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.

    Go to project selector

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

  3. Enable the BigQuery, BigQuery Connection, Cloud Storage, 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:

    Botão destacado para o painel "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:

    O elemento da interface "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": "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 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.

Conceder acesso à conta de serviço

Conceda à conta de serviço da conexão as funções de usuário da Vertex AI e leitor de objetos do Storage.

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/gemini-2.0-flash', 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 = 'gemini-2.0-flash', 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 bqcx-1234567890-wxyz@gcp-sa-bigquery-condel.iam.gserviceaccount.com does not have the permission to access resource.

Para conceder esses papéis, siga estas etapas:

Console

  1. Acesse a página IAM e administrador.

    Acessar IAM e administrador

  2. Clique em Adicionar.

    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 Adicionar outro papel.

  6. No campo Selecionar papel, escolha Cloud Storage e, em seguida, Visualizador de objetos do Storage.

  7. Clique em Salvar.

gcloud

Use o comando gcloud projects add-iam-policy-binding.

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

Substitua:

  • PROJECT_NUMBER: o número do projeto em que a função será concedida.
  • MEMBER: o ID da conta de serviço que você copiou anteriormente.

criar uma tabela de objetos

Para analisar vídeos sem movê-los do Cloud Storage, crie uma tabela de objetos.

Para criar uma tabela de objetos:

SQL

Use a instrução CREATE EXTERNAL TABLE.

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

    Acessar o BigQuery

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

    CREATE EXTERNAL TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME`
WITH CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID`| DEFAULT}
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['BUCKET_PATH'[,...]],
  max_staleness = STALENESS_INTERVAL,
  metadata_cache_mode = 'CACHE_MODE');

    Substitua:

    • PROJECT_ID: o ID do projeto.
    • DATASET_ID: o ID do conjunto de dados que você criou.
    • TABLE_NAME: o nome da tabela de objetos.
    • REGION: a região ou multirregião que contém a conexão.
    • CONNECTION_ID: o ID da conexão que você criou.

      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.

      Para usar uma conexão padrão, especifique DEFAULT em vez da string de conexão que contém PROJECT_ID.REGION.CONNECTION_ID.

    • BUCKET_PATH: o caminho para o bucket do Cloud Storage que contém os vídeos, no formato ['gs://bucket_name/[folder_name/]*'].

      O bucket do Cloud Storage usado precisa estar no mesmo projeto em que você planeja criar o modelo e chamar a função ML.GENERATE_EMBEDDING. Se você quiser chamar a função ML.GENERATE_EMBEDDING em um projeto diferente daquele que contém o bucket do Cloud Storage usado pela tabela de objetos, é preciso conceder o papel de Administrador do Storage no nível do bucket para a conta de serviço service-A@gcp-sa-aiplatform.iam.gserviceaccount.com.

    • STALENESS_INTERVAL: especifica se os metadados em cache são usados pelas operações na tabela de objetos e se eles precisam ser atualizados para que possam ser usados pela operação. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

      Para desativar o armazenamento em cache de metadados, especifique 0. Esse é o padrão.

      Para ativar o armazenamento em cache de metadados, especifique um valor de literal de intervalo entre 30 minutos e 7 dias. Por exemplo, especifique INTERVAL 4 HOUR para um intervalo de inatividade de 4 horas. Com esse valor, as operações na tabela usarão metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados em cache forem anteriores a isso, a operação recuperará os metadados do Cloud Storage.

    • CACHE_MODE: especifica se o cache de metadados é atualizado de forma automática ou manual. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

      Defina como AUTOMATIC para que o cache de metadados seja atualizado em um intervalo definido pelo sistema, geralmente entre 30 e 60 minutos.

      Defina como MANUAL se quiser atualizar o cache de metadados com uma programação que você determinar. Nesse caso, chame o procedimento do sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar o cache.

      Defina CACHE_MODE se STALENESS_INTERVAL estiver definido como um valor maior que 0.

  3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Use o comando bq mk.

bq mk --table \
--external_table_definition=BUCKET_PATH@REGION.CONNECTION_ID \
--object_metadata=SIMPLE \
--max_staleness=STALENESS_INTERVAL \
--metadata_cache_mode=CACHE_MODE \
PROJECT_ID:DATASET_ID.TABLE_NAME

Substitua:

  • BUCKET_PATH: o caminho para o bucket do Cloud Storage que contém os vídeos, no formato ['gs://bucket_name/[folder_name/]*'].

    O bucket do Cloud Storage usado precisa estar no mesmo projeto em que você planeja criar o modelo e chamar a função ML.GENERATE_EMBEDDING. Se você quiser chamar a função ML.GENERATE_EMBEDDING em um projeto diferente daquele que contém o bucket do Cloud Storage usado pela tabela de objetos, é preciso conceder o papel de Administrador do Storage no nível do bucket para a conta de serviço service-A@gcp-sa-aiplatform.iam.gserviceaccount.com.

  • REGION: a região ou multirregião que contém a conexão.
  • CONNECTION_ID: o ID da conexão que você criou.

    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.

  • STALENESS_INTERVAL: especifica se os metadados em cache são usados pelas operações na tabela de objetos e se eles precisam ser atualizados para que possam ser usados pela operação. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

    Para desativar o armazenamento em cache de metadados, especifique 0. Esse é o padrão.

    Para ativar o armazenamento em cache de metadados, especifique um valor de literal de intervalo entre 30 minutos e 7 dias. Por exemplo, especifique INTERVAL 4 HOUR para um intervalo de inatividade de 4 horas. Com esse valor, as operações na tabela usarão metadados em cache se tiverem sido atualizados nas últimas 4 horas. Se os metadados em cache forem anteriores a isso, a operação recuperará os metadados do Cloud Storage.

  • CACHE_MODE: especifica se o cache de metadados é atualizado de forma automática ou manual. Para mais informações sobre considerações de armazenamento em cache de metadados, consulte Armazenamento em cache de metadados para desempenho.

    Defina como AUTOMATIC para que o cache de metadados seja atualizado em um intervalo definido pelo sistema, geralmente entre 30 e 60 minutos.

    Defina como MANUAL se quiser atualizar o cache de metadados com uma programação que você determinar. Nesse caso, chame o procedimento do sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para atualizar o cache.

    Defina CACHE_MODE se STALENESS_INTERVAL estiver definido como um valor maior que 0.

  • PROJECT_ID: o ID do projeto.
  • DATASET_ID: o ID do conjunto de dados que você criou.
  • TABLE_NAME: o nome da tabela de objetos.

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

    Substitua:

    • PROJECT_ID: o ID do projeto.
    • DATASET_ID: o ID do conjunto de dados que você criou.
    • MODEL_NAME: o nome do modelo
    • REGION: a região ou multirregião que contém a conexão.
    • CONNECTION_ID: o ID da conexão que você criou.

      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 modelo de embedding a ser usado. Neste caso, multimodalembedding@001.

      Se você especificar um URL como o endpoint ao criar o modelo remoto, por exemplo, endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/multimodalembedding@001', verifique se o projeto especificado no URL é aquele em que você concedeu o função do usuário da Vertex AI à conexão. conta de serviço.

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

Gerar embeddings de vídeo

Gere embeddings de vídeo com a função ML.GENERATE_EMBEDDING usando dados de vídeo de uma tabela de objetos:

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,
    START_SECOND AS start_second,
    END_SECOND AS end_second,
    INTERVAL_SECONDS AS interval_seconds)
);

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 de objetos que contém os vídeos a serem incorporados.
  • FLATTEN_JSON: um valor BOOL que indica se é necessário analisar a incorporação em uma coluna separada. O valor padrão é TRUE.
  • START_SECOND: um valor de FLOAT64 que especifica o segundo em que a incorporação deve ser iniciada no vídeo. O valor padrão é 0. Esse valor precisa ser positivo e menor que o valor de end_second.
  • END_SECOND: um valor de FLOAT64 que especifica o segundo em que a incorporação deve ser concluída no vídeo. O valor padrão é 120. Esse valor precisa ser positivo e maior que o valor de start_second.
  • INTERVAL_SECONDS: um valor de FLOAT64 que especifica o intervalo a ser usado ao criar incorporações. Por exemplo, se você definir start_second = 0, end_second = 120 e interval_seconds = 10, o vídeo será dividido em 12 segmentos de 10 segundos ([0, 10), [10, 20), [20, 30)...) e as incorporações serão geradas para cada segmento. Esse valor precisa ser maior que 4 e menor que 120. O valor padrão é 16.

Exemplo

O exemplo a seguir mostra como criar incorporações para os vídeos na tabela de objetos videos: As incorporações são criadas para cada intervalo de 5 segundos entre as marcas de 10 e 40 segundos em cada vídeo.

SELECT *
FROM
  ML.GENERATE_EMBEDDING(
    MODEL `mydataset.embedding_model`,
    TABLE `mydataset.videos`,
    STRUCT(TRUE AS flatten_json_output,
    10 AS start_second,
    40 AS end_second,
    5 AS interval_seconds)
  );

A seguir