Se usó la API de Cloud Translation para traducir esta página.

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 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 tabla
- bigquery.models.getData en el modelo
- bigquery.jobs.create

Antes de comenzar

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

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
Make sure that billing is enabled for your Google Cloud project.
Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.
Enable the 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.

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

Ir a 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.
Haz clic en Crear conexión (Create connection).
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ó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...
```

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

Inicia Cloud Shell
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).

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
```
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.
Revisa y modifica los parámetros de muestra que se aplicarán a tu entorno.
Guarda los cambios.
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

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.
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!”.
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 el rol de usuario de Vertex AI.

Si planeas especificar el extremo como una URL cuando crees el modelo remoto, por ejemplo, endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/text-embedding-004', otorga este rol en el mismo proyecto que especifiques en la URL.

Si planeas especificar el extremo con el nombre del modelo cuando crees el modelo remoto, por ejemplo, endpoint = 'text-embedding-004', otorga este rol en el mismo proyecto en el que planeas crear el modelo remoto.

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

Para otorgar el rol, sigue estos pasos:

Console

Ir a la página IAM y administración

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

Ir a BigQuery
Crea un modelo remoto con el editor de SQL:
```
CREATE OR REPLACE MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION `CONNECTION_ID`
OPTIONS (ENDPOINT = 'ENDPOINT');
```
Reemplaza lo siguiente:
- PROJECT_ID: el ID de tu proyecto
- DATASET_ID: el ID del conjunto de datos que contendrá el modelo
- MODEL_NAME: Es el nombre del modelo.
- CONNECTION_ID: el ID de tu conexión de BigQuery
  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 Conexión ID, por ejemplo, projects/myproject/locations/connection_location/connections/myconnection.
- ENDPOINT: El nombre del modelo de incorporación que se usará. Debe ser un modelo text-embedding, text-multilingual-embedding o multimodalembedding. Para obtener más información sobre las versiones de modelos y los alias compatibles, consulta ENDPOINT.
Importante: La compatibilidad de BigQuery ML con el modelo textembedding-gecko@002 se eliminará gradualmente. Si tienes modelos remotos que usan este modelo, migra a un modelo text-embedding-004 o a otra versión de modelo compatible lo antes posible.

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 text-embedding o text-multilingual-embedding para casos de uso de solo texto y un modelo multimodalembedding para casos de uso de búsqueda multimodal, en los que las incorporaciones para texto y contenido visual se generan en el mismo espacio semántico.

embedding de texto

Genera embedding de texto con un modelo remoto sobre un modelo de embedding:

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,
    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 de embedding.
TABLE_NAME: el nombre de la tabla que contiene el texto que se incorporará. Esta tabla debe tener una columna llamada content, o puedes usar un alias para usar una columna con nombre diferente.
FLATTEN_JSON: Un valor BOOL que indica si se debe analizar la incorporación en una columna separada. El valor predeterminado es TRUE.
TASK_TYPE: Es una literal STRING que especifica la aplicación descendente prevista 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 usas este tipo de tarea, es útil incluir el título del documento en la sentencia 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 llamada title o con el alias title, por ejemplo:
```
      SELECT *
      FROM
        ML.GENERATE_EMBEDDING(
          MODEL mydataset.embedding_model,
          (SELECT abstract as content, header as title, publication_number
          FROM mydataset.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.
OUTPUT_DIMENSIONALITY: Un valor INT64 que especifica la cantidad de dimensiones que se usarán cuando se generen embedding. Por ejemplo, si especificas 256 AS output_dimensionality, la columna de salida ml_generate_embedding_result contiene 256 incorporaciones para cada valor de entrada.
Solo puedes usar este argumento si el modelo remoto que especificas en el argumento model usa uno de los siguientes modelos como extremo:
- text-embedding-004 o posterior
- text-multilingual-embedding-002 o posterior

embedding multimodal

Genera embeddings de texto con un modelo remoto sobre el modelo 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，
  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 que contiene el texto que se incorporará. Esta tabla debe tener una columna llamada content, o puedes usar un alias para usar una columna con nombre diferente.
FLATTEN_JSON: Un 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 embeddings. 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 embeddings para cada valor de entrada.

Genera incorporaciones de texto con datos de una consulta

Genera embeddings de texto con la función ML.GENERATE_EMBEDDING mediante datos de texto proporcionados por una consulta y un modelo remoto sobre un modelo de embeddings.

embedding de texto

Genera embeddings de texto con un modelo remoto sobre el modelo de embedding:

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,
    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 de embedding.
CONTENT_QUERY: una consulta cuyo resultado contiene una columna STRING llamada content.
FLATTEN_JSON: un valor BOOL que indica si se debe analizar la incorporación en una columna separada. El valor predeterminado es TRUE.
TASK_TYPE: Es una literal STRING que especifica la aplicación descendente prevista 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 usas este tipo de tarea, es útil incluir el título del documento en la sentencia 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 llamada title o con el alias title, por ejemplo:
```
          SELECT *
          FROM
            ML.GENERATE_EMBEDDING(
              MODEL mydataset.embedding_model,
              (SELECT abstract as content, header as title, publication_number
              FROM mydataset.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.
OUTPUT_DIMENSIONALITY: un valor INT64 que especifica la cantidad de dimensiones que se usarán cuando se generen incorporaciones. Por ejemplo, si especificas 256 AS output_dimensionality, la columna de salida ml_generate_embedding_result contiene 256 embeddings para cada valor de entrada.
Solo puedes usar este argumento si el modelo remoto que especificas en el argumento model usa uno de los siguientes modelos como extremo:
- text-embedding-004 o posterior
- text-multilingual-embedding-002 o posterior

embedding multimodal

Genera embeddings de texto con un modelo remoto sobre el modelo multimodalembedding:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  (CONTENT_QUERY),
  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.
CONTENT_QUERY: una consulta cuyo resultado contiene una columna STRING llamada content.
FLATTEN_JSON: Un 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 embeddings. 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 embeddings para cada valor de entrada.

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, 'CLASSIFICATION' AS task_type)
  );

Usa incorporaciones para clasificar la similitud semántica

En el siguiente ejemplo, se incorpora una colección de opiniones sobre películas y se ordenan por distancia cosencial a la opinión "Esta película fue promedio" con la función ML.DISTANCE. Una distancia menor indica una mayor similitud 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 just okay...              | 0.062789813467745592       |
| This movie was fantastic                 |  0.18579561313064263       |
| This movie was terrible.                 |  0.35707466240930985       |
| This was the best movie I've ever seen!! |  0.41844932504542975       |
+------------------------------------------+----------------------------+