Esta página se ha traducido con Cloud Translation API.

Generar inserciones de vídeo con la función AI.GENERATE_EMBEDDING

En este documento se explica cómo crear un modelo remoto de BigQuery ML que haga referencia a un modelo fundamental de inserciones de Vertex AI. Después, puedes usar ese modelo con la función AI.GENERATE_EMBEDDING para crear representaciones insertadas de vídeo a partir de datos de una tabla de objetos de BigQuery.

Roles obligatorios

Para crear un modelo remoto y generar inserciones, necesitas los siguientes roles de Gestión de Identidades y Accesos (IAM):

Crear y usar conjuntos de datos, tablas y modelos de BigQuery: Editor de datos de BigQuery (roles/bigquery.dataEditor) en tu proyecto.
Crear, delegar y usar conexiones de BigQuery: Administrador de conexiones de BigQuery (roles/bigquery.connectionsAdmin) en tu proyecto.

Si no tienes una conexión predeterminada configurada, puedes crear una y definirla al ejecutar la instrucción CREATE MODEL. Para ello, debes tener el rol Administrador de BigQuery (roles/bigquery.admin) en tu proyecto. Para obtener más información, consulta Configurar la conexión predeterminada.
Concede permisos a la cuenta de servicio de la conexión: administrador de gestión de identidades y accesos del proyecto (roles/resourcemanager.projectIamAdmin) en el proyecto que contiene el endpoint de Vertex AI. Este es el proyecto actual de los modelos remotos que creas especificando el nombre del modelo como endpoint. Es el proyecto identificado en la URL de los modelos remotos que creas especificando una URL como endpoint.

Si usas el modelo remoto para analizar datos no estructurados de una tabla de objetos y el segmento de Cloud Storage que usas en la tabla de objetos está en un proyecto distinto al de tu endpoint de Vertex AI, también debes tener el rol Administrador de Storage (roles/storage.admin) en el segmento de Cloud Storage que usa la tabla de objetos.
Crear tareas de BigQuery: Usuario de tareas de BigQuery (roles/bigquery.jobUser) en tu proyecto.

Estos roles predefinidos contienen los permisos necesarios para realizar las tareas descritas en este documento. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:

Permisos obligatorios

Crea un conjunto de datos: bigquery.datasets.create
Crea, delega y usa una conexión: bigquery.connections.*
Define los permisos de la cuenta de servicio: resourcemanager.projects.getIamPolicy y resourcemanager.projects.setIamPolicy
Crea una tabla de objetos: bigquery.tables.create y bigquery.tables.update
Crea un modelo y ejecuta la inferencia:
- bigquery.jobs.create
- bigquery.models.create
- bigquery.models.getData
- bigquery.models.updateData
- bigquery.models.updateMetadata

También puedes obtener estos permisos con roles personalizados u otros roles predefinidos.

Antes de empezar

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 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
Verify that billing is enabled for your Google Cloud project.
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

Crear conjunto de datos

Crea un conjunto de datos de BigQuery para que contenga tus recursos:

Consola

En la Google Cloud consola, ve a la página BigQuery.

Ir a BigQuery
En el panel de la izquierda, haz clic en Explorador:

Si no ves el panel de la izquierda, haz clic en Ampliar panel de la izquierda para abrirlo.
En el panel Explorador, haz clic en el nombre de tu proyecto.
Haz clic en Ver acciones > Crear conjunto de datos.
En la página Crear conjunto de datos, haz lo siguiente:
1. En ID del conjunto de datos, escribe un nombre para el conjunto de datos.
2. En Tipo de ubicación, selecciona Región o Multirregión.
  - Si has seleccionado Región, elige una ubicación de la lista Región.
  - Si has seleccionado Multirregión, elige EE. UU. o Europa en la lista Multirregión.
3. Haz clic en Crear conjunto de datos.

bq

Para crear un conjunto de datos, usa el comando bq mk con la marca --location:
```
bq --location=LOCATION mk -d DATASET_ID
```
Haz los cambios siguientes:
- LOCATION: la ubicación del conjunto de datos.
- DATASET_ID es el ID del conjunto de datos que vas a crear.
Confirma que se ha creado el conjunto de datos:
```
bq ls
```

Crear una conexión

Crea una conexión de recursos de Cloud y obtén la cuenta de servicio de la conexión. Crea la conexión en la misma ubicación que el conjunto de datos que has creado en el paso anterior.

Puedes saltarte este paso si tienes una conexión predeterminada configurada o si tienes el rol Administrador de BigQuery.

Selecciona una de las opciones siguientes:

Consola

Ve a la página BigQuery.

Ir a BigQuery
En el panel de la izquierda, haga clic en Explorador:

Si no ves el panel de la izquierda, haz clic en Ampliar panel de la izquierda para abrirlo.
En el panel Explorador, despliega el nombre de tu proyecto y haz clic en Conexiones.
En la página Conexiones, haz clic en Crear conexión.
En Tipo de conexión, elija Modelos remotos de Vertex AI, funciones remotas, BigLake y Spanner (recurso de Cloud).
En el campo ID de conexión, introduce un nombre para la conexión.
En Tipo de ubicación, selecciona una ubicación para tu conexión. La conexión debe estar ubicada en el mismo lugar que tus otros recursos, como los conjuntos de datos.
Haga clic en Crear conexión.
Haz clic en Ir a la conexión.
En el panel Información sobre la conexión, copia el ID de la cuenta de servicio para usarlo en un paso posterior.

bq

En un entorno de línea de comandos, crea una conexión:
```
bq mk --connection --location=REGION --project_id=PROJECT_ID \
    --connection_type=CLOUD_RESOURCE CONNECTION_ID
```
El parámetro --project_id anula el proyecto predeterminado.

Haz los cambios siguientes:
- REGION: tu región de conexión
- PROJECT_ID: tu ID de proyecto Google Cloud
- CONNECTION_ID: un ID para tu conexión
Cuando creas un recurso de conexión, BigQuery crea una cuenta de servicio del sistema única y la asocia a la conexión.

Solución de problemas: si aparece el siguiente error de conexión, actualiza el SDK de Google Cloud:
```
Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
```

Obtén y copia el ID de la cuenta de servicio para usarlo en un paso posterior:

bq show --connection PROJECT_ID.REGION.CONNECTION_ID

El resultado debería ser similar al siguiente:

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

Terraform

Usa el recurso google_bigquery_connection.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configurar la autenticación para bibliotecas de cliente.

En el siguiente ejemplo se crea una conexión de recursos de Cloud llamada my_cloud_resource_connection en la región 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 la configuración de Terraform en un Google Cloud proyecto, sigue los pasos que se indican en las siguientes secciones.

Preparar Cloud Shell

Abre Cloud Shell.
Define el Google Cloud proyecto predeterminado en el que quieras aplicar tus configuraciones de Terraform.

Solo tienes que ejecutar este comando una vez por proyecto y puedes hacerlo en cualquier directorio.
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
Las variables de entorno se anulan si defines valores explícitos en el archivo de configuración de Terraform.

Preparar el directorio

Cada archivo de configuración de Terraform debe tener su propio directorio (también llamado módulo raíz).

En Cloud Shell, crea un directorio y un archivo nuevo en ese directorio. El nombre del archivo debe tener la extensión .tf. Por ejemplo, main.tf. En este tutorial, nos referiremos al archivo como main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
Si estás siguiendo un tutorial, puedes copiar el código de ejemplo de cada sección o paso.

Copia el código de ejemplo en el archivo main.tf que acabas de crear.

También puedes copiar el código de GitHub. Se recomienda cuando el fragmento de Terraform forma parte de una solución integral.
Revisa y modifica los parámetros de ejemplo para aplicarlos a tu entorno.
Guarda los cambios.
Inicializa Terraform. Solo tienes que hacerlo una vez por directorio.
```
terraform init
```
Si quieres usar la versión más reciente del proveedor de Google, incluye la opción -upgrade:
```
terraform init -upgrade
```

Aplica los cambios

Revisa la configuración y comprueba que los recursos que va a crear o actualizar Terraform se ajustan a tus expectativas:
```
terraform plan
```
Haz las correcciones necesarias en la configuración.
Aplica la configuración de Terraform ejecutando el siguiente comando e introduciendo yes en la petición:
```
terraform apply
```
Espera hasta que Terraform muestre el mensaje "Apply complete!".
Abre tu Google Cloud proyecto para ver los resultados. En la Google Cloud consola, ve a tus recursos en la interfaz de usuario para comprobar que Terraform los ha creado o actualizado.

Dar acceso a la cuenta de servicio

Asigna a la cuenta de servicio de la conexión los roles Usuario de Vertex AI y Lector de objetos de Storage.

Si tiene previsto especificar el endpoint como una URL al crear el modelo remoto (por ejemplo, endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/gemini-2.0-flash'), otorgue este rol en el mismo proyecto que especifique en la URL.

Si tienes previsto especificar el endpoint usando el nombre del modelo al crear el modelo remoto (por ejemplo, endpoint = 'gemini-2.0-flash'), concede este rol en el mismo proyecto en el que vayas a crear el modelo remoto.

Si se asigna el rol en otro proyecto, se produce el error bqcx-1234567890-wxyz@gcp-sa-bigquery-condel.iam.gserviceaccount.com does not have the permission to access resource.

Para conceder estos roles, sigue estos pasos:

Consola

Ve a la página IAM y administración.

Ir a IAM y administración
Haz clic en Añadir.

Se abrirá el cuadro de diálogo Añadir principales.
En el campo Nuevos principales, introduce el ID de la cuenta de servicio que has copiado anteriormente.
En el campo Selecciona un rol, elige Vertex AI y, a continuación, Usuario de Vertex AI.
Haz clic en Añadir otro rol.
En el campo Selecciona un rol, elige Cloud Storage y, a continuación, Visor de objetos de Storage.
Haz clic en Guardar.

gcloud

Usa el 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

Haz los cambios siguientes:

PROJECT_NUMBER: número del proyecto en el que se va a conceder el rol.
MEMBER: el ID de la cuenta de servicio que has copiado anteriormente.

Crear una tabla de objetos

Para analizar vídeos sin moverlos de Cloud Storage, crea una tabla de objetos.

Para crear una tabla de objetos, sigue estos pasos:

SQL

Usa la instrucción CREATE EXTERNAL TABLE.

En la Google Cloud consola, ve a la página BigQuery.

Ir a BigQuery
En el editor de consultas, introduce la siguiente instrucción:
```
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');
```
Haz los cambios siguientes:
- PROJECT_ID: tu ID de proyecto.
- DATASET_ID: el ID del conjunto de datos que has creado.
- TABLE_NAME: el nombre de la tabla de objetos.
- REGION: la región o multirregión que contiene la conexión.
- CONNECTION_ID: el ID de la conexión que has creado.
  Cuando consultas los detalles de la conexión en la consola de Google Cloud , este es el valor de la última sección del ID de conexión completo que se muestra en ID de conexión, por ejemplo, projects/myproject/locations/connection_location/connections/myconnection.
  
  Para usar una conexión predeterminada, especifica DEFAULT en lugar de la cadena de conexión que contiene PROJECT_ID.REGION.CONNECTION_ID.
- BUCKET_PATH: la ruta al segmento de Cloud Storage que contiene los vídeos, en el formato ['gs://bucket_name/[folder_name/]*'].
  El segmento de Cloud Storage que utilices debe estar en el mismo proyecto en el que tengas previsto crear el modelo y llamar a la función AI.GENERATE_EMBEDDING. Si quieres llamar a la función AI.GENERATE_EMBEDDING en un proyecto distinto del que contiene el segmento de Cloud Storage que usa la tabla de objetos, debes asignar el rol Administrador de almacenamiento a nivel de segmento a la cuenta de servicio service-A@gcp-sa-aiplatform.iam.gserviceaccount.com.
- STALENESS_INTERVAL: especifica si las operaciones en la tabla de objetos usan metadatos almacenados en caché y cómo de actualizados deben estar los metadatos almacenados en caché para que la operación los use. Para obtener más información sobre las consideraciones relativas al almacenamiento en caché de metadatos, consulta Almacenamiento en caché de metadatos para mejorar el rendimiento.
  Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Este es el valor predeterminado.
  
  Para habilitar el almacenamiento en caché de metadatos, especifica un valor de literal de intervalo entre 30 minutos y 7 días. Por ejemplo, especifica INTERVAL 4 HOUR para un intervalo de obsolescencia de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se han actualizado en las últimas 4 horas. Si los metadatos almacenados en caché son anteriores a ese periodo, la operación recupera los metadatos de Cloud Storage.
- CACHE_MODE: especifica si la caché de metadatos se actualiza automáticamente o manualmente. Para obtener más información sobre las consideraciones relativas al almacenamiento en caché de metadatos, consulta el artículo Almacenamiento en caché de metadatos para mejorar el rendimiento.
  Selecciona AUTOMATIC para que la caché de metadatos se actualice a un intervalo definido por el sistema, normalmente entre 30 y 60 minutos.
  
  Seleccione MANUAL si quiere actualizar la caché de metadatos según la programación que determine. En este caso, puedes llamar al procedimiento del sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para actualizar la caché.
  
  Debes definir CACHE_MODE si STALENESS_INTERVAL tiene un valor superior a 0.
Haz clic en Ejecutar.

Para obtener más información sobre cómo ejecutar consultas, consulta Ejecutar una consulta interactiva.

bq

Usa el 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

Haz los cambios siguientes:

BUCKET_PATH: la ruta al segmento de Cloud Storage que contiene los vídeos, en el formato ['gs://bucket_name/[folder_name/]*'].
El segmento de Cloud Storage que utilices debe estar en el mismo proyecto en el que tengas previsto crear el modelo y llamar a la función AI.GENERATE_EMBEDDING. Si quieres llamar a la función AI.GENERATE_EMBEDDING en un proyecto distinto del que contiene el segmento de Cloud Storage que usa la tabla de objetos, debes asignar el rol Administrador de almacenamiento a nivel de segmento a la cuenta de servicio service-A@gcp-sa-aiplatform.iam.gserviceaccount.com.
REGION: la región o multirregión que contiene la conexión.
CONNECTION_ID: el ID de la conexión que has creado.
Cuando consultas los detalles de la conexión en la consola de Google Cloud , este es el valor de la última sección del ID de conexión completo que se muestra en ID de conexión, por ejemplo, projects/myproject/locations/connection_location/connections/myconnection.
STALENESS_INTERVAL: especifica si las operaciones en la tabla de objetos usan metadatos almacenados en caché y cuánto tiempo deben haber pasado desde la última actualización de los metadatos almacenados en caché para que la operación pueda usarlos. Para obtener más información sobre las consideraciones relativas al almacenamiento en caché de metadatos, consulta Almacenamiento en caché de metadatos para mejorar el rendimiento.
Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Este es el valor predeterminado.

Para habilitar el almacenamiento en caché de metadatos, especifica un valor de literal de intervalo entre 30 minutos y 7 días. Por ejemplo, especifica INTERVAL 4 HOUR para un intervalo de obsolescencia de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se han actualizado en las últimas 4 horas. Si los metadatos almacenados en caché son anteriores a ese periodo, la operación recupera los metadatos de Cloud Storage.
CACHE_MODE: especifica si la caché de metadatos se actualiza automáticamente o manualmente. Para obtener más información sobre las consideraciones relativas al almacenamiento en caché de metadatos, consulta el artículo Almacenamiento en caché de metadatos para mejorar el rendimiento.
Defina el valor AUTOMATIC para que la caché de metadatos se actualice a un intervalo definido por el sistema, normalmente entre 30 y 60 minutos.

Seleccione MANUAL si quiere actualizar la caché de metadatos según la programación que determine. En este caso, puedes llamar al procedimiento del sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para actualizar la caché.

Debes definir CACHE_MODE si STALENESS_INTERVAL tiene un valor superior a 0.
PROJECT_ID: tu ID de proyecto.
DATASET_ID: el ID del conjunto de datos que has creado.
TABLE_NAME: el nombre de la tabla de objetos.

Crear un modelo

En la Google Cloud consola, ve a la página BigQuery.

Ir a BigQuery
En el editor de SQL, crea un modelo remoto:
```
CREATE OR REPLACE MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
OPTIONS (ENDPOINT = 'ENDPOINT');
```
Haz los cambios siguientes:
- PROJECT_ID: tu ID de proyecto.
- DATASET_ID: el ID del conjunto de datos que has creado.
- MODEL_NAME: el nombre del modelo.
- REGION: la región o multirregión que contiene la conexión.
- CONNECTION_ID: el ID de la conexión que has creado.
  Cuando consultas los detalles de la conexión en la consola de Google Cloud , este es el valor de la última sección del ID de conexión completo que se muestra en ID de conexión, por ejemplo, projects/myproject/locations/connection_location/connections/myconnection.
- ENDPOINT: el modelo de inserción que se va a usar. En este caso, multimodalembedding@001.
  Si especificas una URL como endpoint al crear el modelo remoto (por ejemplo, endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/multimodalembedding@001'), asegúrate de que el proyecto que especifiques en la URL sea el proyecto en el que hayas asignado el rol de usuario de Vertex AI a la conexión. cuenta de servicio.
  
  El modelo multimodalembedding@001 debe estar disponible en la ubicación en la que crees el modelo remoto. Para obtener más información, consulta Ubicaciones.

Generar incrustaciones de vídeo

Genera incrustaciones de vídeo con la función AI.GENERATE_EMBEDDING usando datos de vídeo de una tabla de objetos:

SELECT *
FROM AI.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE PROJECT_ID.DATASET_ID.TABLE_NAME,
  STRUCT(
    START_SECOND AS start_second,
    END_SECOND AS end_second,
    INTERVAL_SECONDS AS interval_seconds)
);

Haz los cambios siguientes:

PROJECT_ID: tu ID de proyecto.
DATASET_ID: el ID del conjunto de datos que contiene el modelo.
MODEL_NAME: el nombre del modelo remoto en un modelo multimodalembedding@001.
TABLE_NAME: el nombre de la tabla de objetos que contiene los vídeos que se van a insertar.
START_SECOND: un valor FLOAT64 que especifica el segundo del vídeo en el que se debe empezar a insertar. El valor predeterminado es 0. Este valor debe ser positivo e inferior al valor de end_second.
END_SECOND: un valor FLOAT64 que especifica el segundo del vídeo en el que se debe dejar de insertar. El valor predeterminado es 120. Este valor debe ser positivo y mayor que el valor start_second.
INTERVAL_SECONDS: valor de FLOAT64 que especifica el intervalo que se debe usar al crear las inserciones. Por ejemplo, si defines start_second = 0, end_second = 120 y interval_seconds = 10, el vídeo se dividirá en doce segmentos de 10 segundos ([0, 10), [10, 20), [20, 30)...) y se generarán inserciones para cada segmento. Este valor debe ser mayor que 4 y menor que 120. El valor predeterminado es 16.

Ejemplo

En el siguiente ejemplo se muestra cómo crear inserciones para los vídeos de la tabla de objetos videos. Se crean embeddings para cada intervalo de 5 segundos entre las marcas de 10 y 40 segundos de cada vídeo.

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

Generar inserciones de vídeo con la función AI.GENERATE_EMBEDDING

Roles obligatorios

Permisos obligatorios

Antes de empezar

Crear conjunto de datos

Consola

bq

Crear una conexión

Consola

bq

Terraform

Preparar Cloud Shell

Preparar el directorio

Aplica los cambios

Dar acceso a la cuenta de servicio

Consola

gcloud

Crear una tabla de objetos

SQL

bq

Crear un modelo

Generar incrustaciones de vídeo

Ejemplo

Siguientes pasos