Genera incorporaciones de imágenes con la función ML.GENERATE_OPTIMIDING

En este documento, se muestra cómo crear un modelo remoto de BigQuery ML que hace referencia a un modelo de incorporación de Vertex AI. Luego, usa ese modelo con la función ML.GENERATE_EMBEDDING para crear incorporaciones de imágenes con los datos de una tabla de objetos de BigQuery.

Roles obligatorios

  • Para crear una conexión, necesitas membresía en el siguiente rol de Identity and Access Management (IAM):

    • roles/bigquery.connectionAdmin

  • Para otorgar permisos a la cuenta de servicio de la conexión, necesitas el siguiente permiso:

    • resourcemanager.projects.setIamPolicy

  • Para crear una tabla de objetos, necesitas los siguientes permisos:

    • bigquery.tables.create
    • bigquery.tables.update
    • bigquery.connections.delegate

  • Para crear el modelo con BigQuery ML, necesitas los siguientes permisos de IAM:

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

  • Para ejecutar inferencias, necesitas los siguientes permisos:

    • bigquery.tables.getData en la tabla
    • bigquery.models.getData en el modelo
    • bigquery.jobs.create

Antes de comenzar

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

    Go to project selector

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

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

    Enable the APIs

Crea un conjunto de datos

Crea un conjunto de datos de BigQuery para almacenar tu modelo y tabla de objetos.

Console

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

    Ir a la página de BigQuery

  2. En el panel Explorador, haz clic en el nombre de tu proyecto.

  3. Haz clic en Ver acciones > Crear conjunto de datos.

  4. En la página Crear conjunto de datos, haz lo siguiente:

    • En ID de conjunto de datos, escribe un nombre para el conjunto de datos.

    • En Tipo de ubicación, selecciona una ubicación para el conjunto de datos.

    • Haz clic en Crear conjunto de datos.

bq

  1. Para crear un conjunto de datos nuevo, usa el comando bq mk con la marca --location:

    bq --location=LOCATION mk -d DATASET_ID

    Reemplaza lo siguiente:

    • LOCATION: la ubicación del conjunto de datos.
    • DATASET_ID es el ID del conjunto de datos que crearás.

  2. Confirma que se haya creado el conjunto de datos:

    bq ls

Crear una conexión

Crea una conexión de recurso 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 creaste en el paso anterior.

Selecciona una de las opciones siguientes:

Console

  1. Ve a la página de BigQuery.

    Ir a BigQuery

  2. En el panel Explorador, haz clic en Agregar datos.

    Se abrirá el diálogo Agregar datos.

  3. En el panel Filtrar por, en la sección Tipo de fuente de datos, selecciona Bases de datos.

    Como alternativa, en el campo Buscar fuentes de datos, puedes ingresar Vertex AI.

  4. En la sección Fuentes de datos destacadas, haz clic en Vertex AI.

  5. Haz clic en la tarjeta de solución Modelos de Vertex AI: BigQuery Federation.

  6. En la lista Tipo de conexión, selecciona Modelos remotos de Vertex AI, funciones remotas y BigLake (Cloud Resource).

  7. En el campo ID de conexión, ingresa un nombre para tu conexión.

  8. Haz clic en Crear conexión (Create connection).

  9. Haz clic en Ir a la conexión.

  10. En el panel Información de conexión, copia el ID de la cuenta de servicio para usarlo en un paso posterior.

bq

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

    Reemplaza lo siguiente:

    • REGION: tu región de conexión
    • PROJECT_ID: El ID del proyecto de Google Cloud.
    • CONNECTION_ID: Es 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 con la conexión.

    Solución de problemas: Si recibes 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...

  2. Recupera y copia el ID de cuenta de servicio para usarlo en un paso posterior:

    bq show --connection PROJECT_ID.REGION.CONNECTION_ID

    El resultado es similar a este:

    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. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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 tu configuración de Terraform en un proyecto de Google Cloud, completa los pasos de las siguientes secciones.

Prepara Cloud Shell

  1. Inicia Cloud Shell

  2. Establece el proyecto de Google Cloud predeterminado en el que deseas aplicar tus configuraciones de Terraform.

    Solo necesitas ejecutar este comando una vez por proyecto y puedes ejecutarlo en cualquier directorio.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Las variables de entorno se anulan si configuras valores explícitos en el archivo de configuración de Terraform.

Prepara el directorio

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

  1. En Cloud Shell, crea un directorio y un archivo nuevo dentro de ese directorio. El nombre del archivo debe tener la extensión .tf, por ejemplo, main.tf. En este instructivo, el archivo se denomina main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Si sigues un instructivo, puedes copiar el código de muestra en cada sección o paso.

    Copia el código de muestra en el main.tf recién creado.

    De manera opcional, copia el código de GitHub. Esto se recomienda cuando el fragmento de Terraform es parte de una solución de extremo a extremo.

  3. Revisa y modifica los parámetros de muestra que se aplicarán a tu entorno.
  4. Guarda los cambios.
  5. Inicializa Terraform. Solo debes hacerlo una vez por directorio. 
    terraform init

    De manera opcional, incluye la opción -upgrade para usar la última versión del proveedor de Google: 

    terraform init -upgrade

Aplica los cambios

  1. Revisa la configuración y verifica que los recursos que creará o actualizará Terraform coincidan con tus expectativas: 
    terraform plan

    Corrige la configuración según sea necesario.

  2. Para aplicar la configuración de Terraform, ejecuta el siguiente comando y, luego, escribe yes cuando se te solicite: 
    terraform apply

    Espera hasta que Terraform muestre el mensaje “¡Aplicación completa!”.

  3. Abre tu proyecto de Google Cloud para ver los resultados. En la consola de Google Cloud, navega a tus recursos en la IU para asegurarte de que Terraform los haya creado o actualizado.

Otorga acceso a la cuenta de servicio

Otorga a la cuenta de servicio de la conexión los roles de usuario de Vertex AI y de Visualizador de objetos de almacenamiento.

Para otorgar los roles, sigue estos pasos:

Console

  1. Ir a la página IAM y administración

    Ir a IAM y administración

  2. Haga clic en Agregar.

    Se abre el cuadro de diálogo Agregar principales.

  3. En el campo Principales nuevas (New principals), ingresa el ID de la cuenta de servicio que copiaste antes.

  4. En el campo Selecciona un rol, selecciona Vertex AI y, luego, Usuario de Vertex AI.

  5. Haz clic en Agregar otra función.

  6. En el campo Elige un rol, elige Cloud Storage y, luego,Visualizador de objetos de Storage.

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

Reemplaza lo siguiente:

  • PROJECT_NUMBER: Es el número del proyecto en el que se otorgará el rol.
  • MEMBER: Es el ID de la cuenta de servicio que copiaste antes.

Crea una tabla de objetos

Para analizar imágenes sin transferirlas desde Cloud Storage, crea una tabla de objetos.

Para crear una tabla de objetos, sigue estos pasos:

SQL

Usa la sentencia CREATE EXTERNAL TABLE.

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

    Ve a BigQuery Studio

  2. En el editor de consultas, escribe la siguiente sentencia:

    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');

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID de tu proyecto
    • DATASET_ID: Es el ID del conjunto de datos que creaste.
    • TABLE_NAME: el nombre de la tabla de objetos.
    • REGION: la región o multirregión que contiene la conexión.
    • CONNECTION_ID: Es el ID de la conexión que creaste.

      Cuando ves los detalles de conexión en la consola de Google Cloud, este es el valor en la última sección del ID de conexión completamente calificado 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 bucket de Cloud Storage que contiene las imágenes, en el formato ['gs://bucket_name/[folder_name/]*'].

      El bucket de Cloud Storage que uses debe estar en el mismo proyecto en el que planeas crear el modelo y llamar a la función ML.GENERATE_EMBEDDING. Si deseas llamar a la función ML.GENERATE_EMBEDDING en un proyecto diferente al que contiene el bucket de Cloud Storage que usa la tabla de objetos, debes otorgar el rol de administrador de almacenamiento a nivel del bucket a la cuenta de servicio service-A@gcp-sa-aiplatform.iam.gserviceaccount.com.

    • STALENESS_INTERVAL: especifica si las operaciones que se usan en la tabla de objetos usan los metadatos almacenados en caché, y qué tan actuales deben ser los metadatos almacenados en caché para que la operación los use. Si quieres obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.

      Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Esta es la opción predeterminada.

      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 inactividad de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se actualizaron en las últimas 4 horas. Si los metadatos almacenados en caché son más antiguos, la operación recupera metadatos de Cloud Storage.

    • CACHE_MODE: especifica si la caché de metadatos se actualiza de forma automática o manual. Si quieres obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.

      Configúralo como AUTOMATIC para que la caché de metadatos se actualice a un intervalo definido por el sistema, por lo general, entre 30 y 60 minutos.

      Configúralo como MANUAL si deseas actualizar la caché de metadatos en un programa que determines. En este caso, puedes llamar al procedimiento del sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para actualizar la caché.

      Debes configurar CACHE_MODE si STALENESS_INTERVAL está configurado en un valor mayor que 0.

  3. Haz clic en Ejecutar.

Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta 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

Reemplaza lo siguiente:

  • BUCKET_PATH: La ruta al bucket de Cloud Storage que contiene las imágenes, en el formato ['gs://bucket_name/[folder_name/]*'].

    El bucket de Cloud Storage que uses debe estar en el mismo proyecto en el que planeas crear el modelo y llamar a la función ML.GENERATE_EMBEDDING. Si deseas llamar a la función ML.GENERATE_EMBEDDING en un proyecto diferente al que contiene el bucket de Cloud Storage que usa la tabla de objetos, debes otorgar el rol de administrador de almacenamiento a nivel del bucket 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: Es el ID de la conexión que creaste.

    Cuando ves los detalles de conexión en la consola de Google Cloud, este es el valor en la última sección del ID de conexión completamente calificado que se muestra en ID de conexión, por ejemplo, projects/myproject/locations/connection_location/connections/myconnection.

  • STALENESS_INTERVAL: especifica si las operaciones que se usan en la tabla de objetos usan los metadatos almacenados en caché, y qué tan actuales deben ser los metadatos almacenados en caché para que la operación los use. Si quieres obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.

    Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Esta es la opción predeterminada.

    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 inactividad de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se actualizaron en las últimas 4 horas. Si los metadatos almacenados en caché son más antiguos, la operación recupera metadatos de Cloud Storage.

  • CACHE_MODE: especifica si la caché de metadatos se actualiza de forma automática o manual. Si quieres obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.

    Configúralo como AUTOMATIC para que la caché de metadatos se actualice a un intervalo definido por el sistema, por lo general, entre 30 y 60 minutos.

    Configúralo como MANUAL si deseas actualizar la caché de metadatos en un programa que determines. En este caso, puedes llamar al procedimiento del sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para actualizar la caché.

    Debes configurar CACHE_MODE si STALENESS_INTERVAL está configurado en un valor mayor que 0.

  • PROJECT_ID: el ID de tu proyecto
  • DATASET_ID: Es el ID del conjunto de datos que creaste.
  • TABLE_NAME: el nombre de la tabla de objetos.

Crear un modelo

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

    Ir a BigQuery

  2. Crea un modelo remoto con el editor de SQL:

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

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID de tu proyecto
    • DATASET_ID: Es el ID del conjunto de datos que creaste anteriormente.
    • MODEL_NAME: el nombre del modelo
    • REGION: la región o multirregión que contiene la conexión.
    • CONNECTION_ID: Es el ID de la conexión que creaste.

      Cuando ves los detalles de conexión en la consola de Google Cloud, este es el valor en la última sección del ID de conexión completamente calificado que se muestra en ID de conexión, por ejemplo, projects/myproject/locations/connection_location/connections/myconnection.

    • ENDPOINT: El modelo de incorporación que se usará, en este caso, multimodalembedding@001.

      Si especificas una URL como el extremo cuando creas el modelo remoto, por ejemplo, endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/text-embedding-004', asegúrate de que el proyecto que especifiques en la URL sea el proyecto en el que otorgaste el rol de usuario de Vertex AI a la conexión. en particular.

      El modelo multimodalembedding@001 debe estar disponible en la ubicación en la que creas el modelo remoto. Para obtener más información, consulta Ubicaciones.

Genera incorporaciones de imágenes

Genera incorporaciones de imágenes con la función ML.GENERATE_EMBEDDINGmediante los datos de imagen de una tabla de objetos:

  SELECT *
  FROM ML.GENERATE_EMBEDDING(
    MODEL <var>PROJECT_ID</var>.<var>DATASET_ID</var>.<var>MODEL_NAME</var>,
    TABLE <var>PROJECT_ID</var>.<var>DATASET_ID</var>.<var>TABLE_NAME</var>,
    STRUCT(FLATTEN_JSON AS flatten_json_output,
    OUTPUT_DIMENSIONALITY AS output_dimensionality)
  );

Reemplaza lo siguiente:

  • PROJECT_ID: el ID de tu proyecto
  • DATASET_ID: El ID del conjunto de datos que contiene el modelo.
  • MODEL_NAME: el nombre del modelo remoto sobre un modelo multimodalembedding@001.
  • TABLE_NAME: el nombre de la tabla de objetos que contiene las imágenes que se incorporarán.
  • FLATTEN_JSON: un valor BOOL que indica si se debe analizar la incorporación en una columna separada. El valor predeterminado es TRUE.
  • OUTPUT_DIMENSIONALITY: Un valor INT64 que especifica la cantidad de dimensiones que se usarán cuando se generen incorporaciones. Los valores válidos son 128, 256, 512 y 1408. El valor predeterminado es 1408. Por ejemplo, si especificas 256 AS output_dimensionality, la columna de salida ml_generate_embedding_result contiene 256 incorporaciones para cada valor de entrada.

Ejemplo

En el siguiente ejemplo, se muestra cómo crear incorporaciones para las imágenes en 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)
  );