Genera incorporaciones de texto con la función ML.GENERATE_OPTIMIDING
En este documento, se muestra cómo crear un modelo remoto de BigQuery ML que hace referencia al modelo de base de incorporación de Vertex AI.
Luego, usa ese modelo con la función ML.GENERATE_EMBEDDING
para crear incorporaciones de texto con los datos de una tabla estándar 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 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 tablabigquery.models.getData
en el modelobigquery.jobs.create
Antes de comenzar
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.
Crea un conjunto de datos
Crea un conjunto de datos de BigQuery para almacenar tu modelo de AA:
En la consola de Google Cloud, ve 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, ingresa
bqml_tutorial
.En Tipo de ubicación, selecciona Multirregión y, luego, EE.UU. (varias regiones en Estados Unidos).
Los conjuntos de datos públicos se almacenan en la multirregión
US
. Para que sea más simple, almacena tu conjunto de datos en la misma ubicación.Deja la configuración predeterminada restante como está y haz clic en Crear conjunto de datos.
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
Ve a la página de BigQuery.
Para crear una conexión, haz clic en
Agregar y, luego, en Conexiones a fuentes de datos externas.En la lista Tipo de conexión, selecciona Modelos remotos de Vertex AI, funciones remotas y BigLake (Cloud Resource).
En el campo ID de conexión, escribe un nombre para tu 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.Reemplaza lo siguiente:
REGION
: tu región de conexiónPROJECT_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...
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 al siguiente:
name properties 1234.REGION.CONNECTION_ID {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}
Terraform
Agrega la siguiente sección a tu archivo main.tf
.
## This creates a cloud resource connection. ## Note: The cloud resource nested object has only one output only field - serviceAccountId. resource "google_bigquery_connection" "connection" { connection_id = "CONNECTION_ID" project = "PROJECT_ID" location = "REGION" cloud_resource {} }Reemplaza lo siguiente:
CONNECTION_ID
: Es un ID para tu conexión.PROJECT_ID
: El ID del proyecto de Google Cloud.REGION
: tu región de conexión
Otorga acceso a la cuenta de servicio
Otorga permiso a tu cuenta de servicio para usar la conexión. Si no se otorga permiso, se produce un error. Selecciona una de las opciones siguientes:
Console
Ir a la página IAM y administración
Haz clic en
Otorgar acceso.Se abre el cuadro de diálogo Agregar principales.
En el campo Principales nuevas (New principals), ingresa el ID de la cuenta de servicio que copiaste antes.
En el campo Selecciona un rol, selecciona Vertex AI y, luego, Usuario de Vertex AI.
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
Reemplaza lo siguiente:
PROJECT_NUMBER
: Es el número de tu proyecto.MEMBER
: el ID de la cuenta de servicio que copiaste antes
Crear un modelo
En la consola de Google Cloud, ve a la página de BigQuery.
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 proyectoDATASET_ID
: el ID del conjunto de datos que contendrá el modeloMODEL_NAME
: Es el nombre del modelo.REGION
: la región que usa la conexión.CONNECTION_ID
: el ID de tu conexión de BigQueryCuando 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 Conexión ID, por ejemplo,
projects/myproject/locations/connection_location/connections/myconnection
.ENDPOINT
: el LLM de la incorporación que se usará. Por ejemplo,ENDPOINT='multimodalembedding'
.Para algunos tipos de modelos, puedes especificar una versión particular del modelo si agregas
@version
al nombre del modelo. Por ejemplo,textembedding-gecko@001
. A fin de obtener información sobre las versiones de modelo compatibles para diferentes tipos de modelos, consultaENDPOINT
.
Genera incorporaciones de texto con datos de una tabla
Generar incorporaciones de texto con la función ML.GENERATE_EMBEDDING
mediante datos de texto de una columna de tabla.
Por lo general, deseas usar un modelo textembedding-gecko
o textembedding-gecko-multilingual
para casos de uso de solo texto y un modelo multimodalembedding
para casos de uso de búsqueda multimodal, en los que lo siguiente: las incorporaciones para texto y contenido visual se generan en el mismo espacio semántico.
textembedding-gecko*
Genera incorporaciones de texto con un modelo remoto sobre el LLM textembedding-gecko
o textembedding-gecko-multilingual
:
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, TASK_TYPE AS task_type) );
Reemplaza lo siguiente:
PROJECT_ID
: el ID de tu proyectoDATASET_ID
: El ID del conjunto de datos que contiene el modelo.MODEL_NAME
: el nombre del modelo remoto sobre un modelotextembedding-gecko
otextembedding-gecko-multilingual
.TABLE_NAME
: es el nombre de la tabla que contiene el texto que se incorporará. Esta tabla debe tener una columna llamadacontent
, o puedes usar un alias para usar una columna con nombre diferente.FLATTEN_JSON
: un valorBOOL
que indica si se debe analizar la incorporación en una columna separada. El valor predeterminado esTRUE
.TASK_TYPE
: un literal deSTRING
que especifica la aplicación descendente deseada para ayudar al modelo a producir incorporaciones de mejor calidad.TASK_TYPE
acepta los siguientes valores:RETRIEVAL_QUERY
: especifica que el texto dado es una consulta en un parámetro de configuración de búsqueda o recuperación.RETRIEVAL_DOCUMENT
: especifica que el texto dado de un documento en un parámetro de configuración de búsqueda o recuperación.Cuando se usa este tipo de tarea, es útil incluir el título del documento en la declaración de consulta para mejorar la calidad de la incorporación. Puedes usar la opción
title
para especificar el nombre de la columna que contiene el título del documento; de lo contrario, el título del documento debe estar en una columna con el nombretitle
o con un alias comotitle
, por ejemplo:SELECT * FROM ML.GENERATE_EMBEDDING( MODEL
mydataset.embedding_model
, (SELECT abstract as content, header as title, publication_number FROMmydataset.publications
), STRUCT(TRUE AS flatten_json_output, 'RETRIEVAL_DOCUMENT' as task_type) );SEMANTIC_SIMILARITY
: especifica que el texto dado se usará para la similitud textual semántica (STS).CLASSIFICATION
: especifica que las incorporaciones se usarán para la clasificación.CLUSTERING
: especifica que las incorporaciones se usarán para el agrupamiento en clústeres.
multimodalembedding
Genera incorporaciones de texto con un modelo remoto sobre el LLM multimodalembedding
:
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) );
Reemplaza lo siguiente:
PROJECT_ID
: el ID de tu proyectoDATASET_ID
: El ID del conjunto de datos que contiene el modelo.MODEL_NAME
: el nombre del modelo remoto sobre un modelomultimodalembedding@001
.TABLE_NAME
: es el nombre de la tabla que contiene el texto que se incorporará. Esta tabla debe tener una columna llamadacontent
, o puedes usar un alias para usar una columna con nombre diferente.FLATTEN_JSON
: unaBOOL
que indica si se debe analizar la incorporación en una columna separada. El valor predeterminado esTRUE
.
Genera incorporaciones de texto con datos de una consulta
Genera incorporaciones de texto con elML.GENERATE_EMBEDDING
función mediante datos de texto proporcionados por una consulta y un modelo remoto sobre el LLM textembedding-gecko
o textembedding-gecko-multilingual
:
Por lo general, deseas usar un modelo textembedding-gecko
o textembedding-gecko-multilingual
para casos de uso de solo texto y un modelo multimodalembedding
para casos de uso de búsqueda multimodal, en los que lo siguiente: las incorporaciones para texto y contenido visual se generan en el mismo espacio semántico.
textembedding-gecko*
Genera incorporaciones de texto con un modelo remoto sobre el LLM textembedding-gecko
o textembedding-gecko-multilingual
:
SELECT * FROM ML.GENERATE_EMBEDDING( MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`, (CONTENT_QUERY), STRUCT(FLATTEN_JSON AS flatten_json_output, TASK_TYPE AS task_type );
Reemplaza lo siguiente:
PROJECT_ID
: el ID de tu proyectoDATASET_ID
: El ID del conjunto de datos que contiene el modelo.MODEL_NAME
: el nombre del modelo remoto sobre un modelotextembedding-gecko
otextembedding-gecko-multilingual
.CONTENT_QUERY
: una consulta cuyo resultado contiene una columnaSTRING
llamadacontent
.FLATTEN_JSON
: un valorBOOL
que indica si se debe analizar la incorporación en una columna separada. El valor predeterminado esTRUE
.TASK_TYPE
: un literal deSTRING
que especifica la aplicación descendente deseada para ayudar al modelo a producir incorporaciones de mejor calidad.TASK_TYPE
Acepta los siguientes valores:RETRIEVAL_QUERY
: especifica que el texto dado es una consulta en un parámetro de configuración de búsqueda o recuperación.RETRIEVAL_DOCUMENT
: especifica que el texto dado de un documento en un parámetro de configuración de búsqueda o recuperación.Cuando se usa este tipo de tarea, es útil incluir el título del documento en la declaración de consulta para mejorar la calidad de la incorporación. Puedes usar la opción
title
para especificar el nombre de la columna que contiene el título del documento; de lo contrario, el título del documento debe estar en una columna con el nombretitle
o con un alias comotitle
, por ejemplo:SELECT * FROM ML.GENERATE_EMBEDDING( MODEL
mydataset.embedding_model
, (SELECT abstract as content, header as title, publication_number FROMmydataset.publications
), STRUCT(TRUE AS flatten_json_output, 'RETRIEVAL_DOCUMENT' as task_type) );SEMANTIC_SIMILARITY
: especifica que el texto dado se usará para la similitud textual semántica (STS).CLASSIFICATION
: especifica que las incorporaciones se usarán para la clasificación.CLUSTERING
: especifica que las incorporaciones se usarán para el agrupamiento en clústeres.
multimodalembedding
Genera incorporaciones de texto con un modelo remoto sobre el LLM multimodalembedding
:
SELECT * FROM ML.GENERATE_EMBEDDING( MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`, (CONTENT_QUERY), STRUCT(FLATTEN_JSON AS flatten_json_output) );
Reemplaza lo siguiente:
PROJECT_ID
: el ID de tu proyectoDATASET_ID
: El ID del conjunto de datos que contiene el modelo.MODEL_NAME
: el nombre del modelo remoto sobre un modelomultimodalembedding@001
.CONTENT_QUERY
: una consulta cuyo resultado contiene una columnaSTRING
llamadacontent
.FLATTEN_JSON
: unaBOOL
que indica si se debe analizar la incorporación en una columna separada. El valor predeterminado esTRUE
.
Ejemplos
En los siguientes ejemplos, se muestra cómo llamar a la función ML.GENERATE_EMBEDDING
en una tabla y una consulta.
Cómo incorporar texto en una tabla
En el siguiente ejemplo, se muestra una solicitud para incorporar la columna content
de la tabla text_data
:
SELECT * FROM ML.GENERATE_EMBEDDING( MODEL `mydataset.embedding_model`, TABLE mydataset.text_data, STRUCT(TRUE AS flatten_json_output) );
Usa incorporaciones para clasificar la similitud semántica
En el siguiente ejemplo, se incorpora una colección de reseñas de películas y las ordena por distancia de coseno a la opinión “Esta película fue promedio” mediante la función ML.DISTANCE
.
Una distancia menor indica una similitud semántica más semántica.
WITH movie_review_embeddings AS ( SELECT * FROM ML.GENERATE_EMBEDDING( MODEL `bqml_tutorial.embedding_model`, ( SELECT "Movie 1" AS title, "This movie was fantastic" AS content UNION ALL SELECT "Movie 2" AS title, "This was the best movie I've ever seen!!" AS content UNION ALL SELECT "Movie 3" AS title, "This movie was just okay..." AS content UNION ALL SELECT "Movie 4" AS title, "This movie was terrible." AS content ), STRUCT(TRUE AS flatten_json_output) ) ), 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 content, ML.DISTANCE( (SELECT ml_generate_embedding_result FROM average_review_embedding), ml_generate_embedding_result, 'COSINE' ) AS distance_to_average_review FROM movie_review_embeddings ORDER BY distance_to_average_review;
El resultado es el siguiente:
+------------------------------------------+----------------------------+ | content | distance_to_average_review | +------------------------------------------+----------------------------+ | This movie was fantastic | 0.10028859431058901 | | This movie was terrible. | 0.142427236973374 | | This was the best movie I've ever seen!! | 0.46742391210381995 | | This movie was just okay... | 0.47399255715360622 | +------------------------------------------+----------------------------+