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

Generar inserciones de imágenes con la función ML.GENERATE_EMBEDDING

En este documento se explica cómo crear un modelo remoto de BigQuery ML que haga referencia a un modelo de inserciones de Vertex AI. A continuación, usa ese modelo con la función ML.GENERATE_EMBEDDING para crear representaciones de imágenes mediante 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 tiene configurada una conexión predeterminada, puede 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
Crear, delegar y usar 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 (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 la página de BigQuery
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:
- En ID del conjunto de datos, escribe un nombre para el conjunto de datos.
- En Tipo de ubicación, seleccione una ubicación para el conjunto de datos.
- 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

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

Crea una conexión de recursos de Cloud para que la use el modelo remoto 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.

Selecciona una de las opciones siguientes:

Consola

Ve a la página BigQuery.

Ir a BigQuery
En el panel Explorador, haga clic en Añadir datos:

Se abrirá el cuadro de diálogo Añadir datos.
En el panel Filtrar por, en la sección Tipo de fuente de datos, selecciona Aplicaciones empresariales.

También puede introducir Vertex AI en el campo Buscar fuentes de datos.
En la sección Fuentes de datos destacadas, haga clic en Vertex AI.
Haz clic en la tarjeta de solución Modelos de Vertex AI: federación de BigQuery.
En la lista Tipo de conexión, selecciona Modelos remotos, funciones remotas y BigLake (recurso de Cloud) de Vertex AI.
En el campo ID de conexión, introduce un nombre para la conexión.
Haga clic en Crear conexión.
Haz clic en Ir a la conexión.
En el panel Información de 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 proyecto, sigue los pasos que se indican en las siguientes secciones. Google Cloud

Preparar Cloud Shell

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

Solo tiene que ejecutar este comando una vez por proyecto y puede 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
```
Haga 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 asegurarte de 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 estos roles 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 estos roles 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 imágenes sin moverlas 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 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 las imágenes, 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 ML.GENERATE_EMBEDDING. Si quieres llamar a la función ML.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 cuánto tiempo deben haber pasado desde la última actualización de los metadatos almacenados en caché para que la operación los pueda usar. 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 esa fecha, 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, que suele ser de entre 30 y 60 minutos.
  
  Seleccione MANUAL si quiere actualizar la caché de metadatos según la programación que determine. En ese caso, puedes llamar al BQ.REFRESH_EXTERNAL_METADATA_CACHEprocedimiento del sistema 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 las imágenes, 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 ML.GENERATE_EMBEDDING. Si quieres llamar a la función ML.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 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 los pueda usar. 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 esa fecha, 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, que suele ser de entre 30 y 60 minutos.

Seleccione MANUAL si quiere actualizar la caché de metadatos según la programación que determine. En ese caso, puedes llamar al BQ.REFRESH_EXTERNAL_METADATA_CACHEprocedimiento del sistema 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 anteriormente.
- 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 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 concedido 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 imágenes

Genera incrustaciones de imágenes con la función ML.GENERATE_EMBEDDING usando datos de imagen de una tabla 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,
    OUTPUT_DIMENSIONALITY AS output_dimensionality)
  );

Haz los cambios siguientes:

PROJECT_ID: el proyecto que contiene el modelo o la tabla.
DATASET_ID: el conjunto de datos que contiene el modelo o la tabla.
MODEL_NAME: el nombre del modelo remoto en un modelo multimodalembedding@001.
TABLE_NAME: nombre de la tabla de objetos que contiene las imágenes que se van a insertar.
FLATTEN_JSON: un valor BOOL que indica si se debe analizar la inserción en una columna independiente. El valor predeterminado es TRUE.
OUTPUT_DIMENSIONALITY: valor INT64 que especifica el número de dimensiones que se deben usar al generar las inserciones. Los valores válidos son 128, 256, 512 y 1408. El valor predeterminado es 1408. Por ejemplo, si especifica 256 AS output_dimensionality, la columna de salida ml_generate_embedding_result contiene 256 inserciones por cada valor de entrada.

Ejemplo

En el siguiente ejemplo se muestra cómo crear las inserciones de las imágenes de la tabla de objetos images:

SELECT *
FROM
  ML.GENERATE_EMBEDDING(
    MODEL `mydataset.embedding_model`,
    TABLE `mydataset.images`,
    STRUCT(TRUE AS flatten_json_output, 512 AS output_dimensionality)
  );

Generar inserciones de imágenes con la función ML.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 imágenes

Ejemplo

Siguientes pasos