Generar incrustaciones de texto 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. Después, puedes usar ese modelo con la función ML.GENERATE_EMBEDDING para crear representaciones de texto mediante datos de una tabla estándar de BigQuery.

Se admiten los siguientes tipos de modelos remotos:

• Modelos remotos en comparación con modelos de inserción de Vertex AI.
• Modelos remotos sobre modelos abiertos compatibles (Vista previa).

Roles obligatorios

Para crear un modelo remoto y usar la función ML.GENERATE_EMBEDDING, 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.

• 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 un modelo y ejecuta la inferencia:
  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.models.updateMetadata
• Consultar datos de tabla: bigquery.tables.getData

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

Antes de empezar

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

2. Verify that billing is enabled for your Google Cloud project.

3. Enable the BigQuery, BigQuery Connection, 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

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

   Ir a BigQuery

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

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

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

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

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

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

1. Ve a la página BigQuery.

   Ir a BigQuery

2. En el panel Explorador, haga clic en Añadir datos:

   

   Se abrirá el cuadro de diálogo Añadir datos.

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

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

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

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

7. En el campo ID de conexión, introduce un nombre para la conexión.

8. Haga clic en Crear conexión.

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.

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

2. 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": "[e-mail]"}
   

Terraform

Usa el recurso google_bigquery_connection.

Nota: Para crear objetos de BigQuery con Terraform, debes habilitar la API Cloud Resource Manager

.

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

1. Abre Cloud Shell.

2. Define el Google Cloud proyecto 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).

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

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

3. Revisa y modifica los parámetros de ejemplo para aplicarlos a tu entorno.
4. Guarda los cambios.
5. 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

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

2. 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!".

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

Nota: Los ejemplos de Terraform suelen presuponer que las APIs necesarias están habilitadas en tu proyecto. Google Cloud

Conceder un rol a la cuenta de servicio de la conexión del modelo remoto

Debes conceder el rol Usuario de Vertex AI a la cuenta de servicio de la conexión.

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/text-embedding-005', asigne 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 = 'text-embedding-005'), otorga este rol en el mismo proyecto en el que tengas previsto crear el modelo remoto.

Si se asigna el rol en otro proyecto, se produce el error [e-mail] does not have the permission to access resource.

Para conceder el rol, sigue estos pasos:

Consola

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

   Ir a IAM y administración

2. Haz clic en Conceder acceso.

   Se abrirá el cuadro de diálogo Añadir principales.

3. En el campo Nuevos principales, introduce el ID de la cuenta de servicio que has copiado anteriormente.

4. En el campo Selecciona un rol, elige Vertex AI y, a continuación, Usuario de Vertex AI.

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

Haz los cambios siguientes:

• PROJECT_NUMBER: tu número de proyecto
• MEMBER: el ID de la cuenta de servicio que has copiado antes

Elegir un método de implementación de modelos abiertos

Si creas un modelo remoto a partir de un modelo abierto compatible, puedes desplegarlo automáticamente al mismo tiempo que creas el modelo remoto especificando el ID del modelo de Vertex AI Model Garden o de Hugging Face en la instrucción CREATE MODEL. También puedes desplegar manualmente el modelo abierto y, a continuación, usarlo con el modelo remoto especificando el endpoint del modelo en la instrucción CREATE MODEL. Para obtener más información, consulta Implementar modelos abiertos.

Crear un modelo remoto de BigQuery ML

Crea un modelo remoto:

Nuevos modelos abiertos

Vista previa

Este producto o función está sujeto a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Los productos y las funciones previos a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

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

   Ir a BigQuery

2. 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 (
     {HUGGING_FACE_MODEL_ID = 'HUGGING_FACE_MODEL_ID' |
        MODEL_GARDEN_MODEL_NAME = 'MODEL_GARDEN_MODEL_NAME'}
     [, HUGGING_FACE_TOKEN = 'HUGGING_FACE_TOKEN' ]
     [, MACHINE_TYPE = 'MACHINE_TYPE' ]
     [, MIN_REPLICA_COUNT = MIN_REPLICA_COUNT ]
     [, MAX_REPLICA_COUNT = MAX_REPLICA_COUNT ]
     [, RESERVATION_AFFINITY_TYPE = {'NO_RESERVATION' | 'ANY_RESERVATION' | 'SPECIFIC_RESERVATION'} ]
     [, RESERVATION_AFFINITY_KEY = 'compute.googleapis.com/reservation-name' ]
     [, RESERVATION_AFFINITY_VALUES = RESERVATION_AFFINITY_VALUES ]
     [, ENDPOINT_IDLE_TTL = ENDPOINT_IDLE_TTL ]
   );

   Haz los cambios siguientes:

   • PROJECT_ID: tu ID de proyecto.
   • DATASET_ID: ID del conjunto de datos que contendrá el modelo. Este conjunto de datos debe estar en la misma ubicación que la conexión que estés usando.
   • MODEL_NAME: el nombre del modelo.
   • REGION: la región que usa la conexión.
   • CONNECTION_ID: el ID de tu conexión de BigQuery.

     Para obtener este valor, consulta los detalles de la conexión en la consola Google Cloud y copia 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.

   • HUGGING_FACE_MODEL_ID: un valor STRING que especifica el ID del modelo de un modelo de Hugging Face compatible, en el formato provider_name/model_name. Por ejemplo, deepseek-ai/DeepSeek-R1. Para obtener el ID del modelo, haz clic en el nombre del modelo en Hugging Face Model Hub y, a continuación, copia el ID del modelo de la parte superior de la tarjeta del modelo.
   • MODEL_GARDEN_MODEL_NAME: un valor STRING que especifica el ID y la versión del modelo de un modelo de Model Garden de Vertex AI compatible, con el formato publishers/publisher/models/model_name@model_version. Por ejemplo, publishers/openai/models/gpt-oss@gpt-oss-120b. Para obtener el ID del modelo, haz clic en la tarjeta del modelo en Vertex AI Model Garden y, a continuación, copia el ID del modelo del campo ID del modelo. Para obtener la versión predeterminada del modelo, cópiala del campo Versión de la tarjeta del modelo. Para ver otras versiones del modelo que puedes usar, haz clic en Implementar modelo y, a continuación, en el campo ID de recurso.
   • HUGGING_FACE_TOKEN: un valor STRING que especifica el token de acceso de usuario de Hugging Face que se va a usar. Solo puedes especificar un valor para esta opción si también especificas un valor para la opción HUGGING_FACE_MODEL_ID.

     El token debe tener al menos el rol read, pero también se aceptan tokens con un ámbito más amplio. Esta opción es obligatoria cuando el modelo identificado por el valor HUGGING_FACE_MODEL_ID es un modelo cerrado o privado de Hugging Face.

     Algunos modelos con acceso restringido requieren que aceptes explícitamente sus términos del servicio para poder acceder a ellos. Para aceptar estos términos, sigue estos pasos:

     1. Ve a la página del modelo en el sitio web de Hugging Face.
     2. Busca y revisa los términos del servicio del modelo. Normalmente, se incluye un enlace al contrato de servicio en la tarjeta del modelo.
     3. Acepta los términos que se te indiquen en la página.
   • MACHINE_TYPE: un valor STRING que especifica el tipo de máquina que se va a usar al desplegar el modelo en Vertex AI. Para obtener información sobre los tipos de máquinas admitidos, consulta Tipos de máquinas. Si no especifica ningún valor para la opción MACHINE_TYPE, se usará el tipo de máquina predeterminado de Vertex AI Model Garden para el modelo.
   • MIN_REPLICA_COUNT: un valor INT64 que especifica el número mínimo de réplicas de máquinas que se usan al desplegar el modelo en un endpoint de Vertex AI. El servicio aumenta o disminuye el número de réplicas según lo requiera la carga de inferencia en el endpoint. El número de réplicas utilizadas nunca es inferior al valor de MIN_REPLICA_COUNT ni superior al valor de MAX_REPLICA_COUNT. El valor de MIN_REPLICA_COUNT debe estar en el intervalo [1, 4096]. El valor predeterminado es 1.
   • MAX_REPLICA_COUNT: un valor de INT64 que especifica el número máximo de réplicas de máquinas que se utilizan al desplegar el modelo en un endpoint de Vertex AI. El servicio aumenta o disminuye el número de réplicas según lo requiera la carga de inferencia en el endpoint. El número de réplicas utilizadas nunca es inferior al valor de MIN_REPLICA_COUNT ni superior al valor de MAX_REPLICA_COUNT. El valor de MAX_REPLICA_COUNT debe estar en el intervalo [1, 4096]. El valor predeterminado es el valor MIN_REPLICA_COUNT.
   • RESERVATION_AFFINITY_TYPE: determina si el modelo implementado usa reservas de Compute Engine para proporcionar disponibilidad de máquinas virtuales (VM) garantizada al servir predicciones y especifica si el modelo usa VMs de todas las reservas disponibles o solo de una reserva específica. Para obtener más información, consulta Afinidad de las reservas de Compute Engine.

     Solo puedes usar las reservas de Compute Engine que se compartan con Vertex AI. Para obtener más información, consulta Permitir que se consuma una reserva.

     Los valores admitidos son los siguientes:

     • NO_RESERVATION: no se consume ninguna reserva cuando tu modelo se despliega en un endpoint de Vertex AI. Especificar NO_RESERVATION tiene el mismo efecto que no especificar una afinidad de reserva.
     • ANY_RESERVATION: el despliegue del modelo de Vertex AI consume máquinas virtuales (VMs) de las reservas de Compute Engine que están en el proyecto actual o que se comparten con el proyecto y que están configuradas para el consumo automático. Solo se utilizan las máquinas virtuales que cumplen los siguientes requisitos:
       • Usan el tipo de máquina especificado por el valor MACHINE_TYPE.
       • Si el conjunto de datos de BigQuery en el que vas a crear el modelo remoto es de una sola región, la reserva debe estar en la misma región. Si el conjunto de datos está en la US multirregión, la reserva debe estar en la región us-central1. Si el conjunto de datos está en la EUmultirregión, la reserva debe estar en la región europe-west4.

       Si no hay suficiente capacidad en las reservas disponibles o no se encuentran reservas adecuadas, el sistema aprovisiona VMs de Compute Engine bajo demanda para satisfacer los requisitos de recursos.

     • SPECIFIC_RESERVATION: el despliegue del modelo de Vertex AI consume VMs solo de la reserva que especifiques en el valor RESERVATION_AFFINITY_VALUES. Esta reserva debe configurarse para un consumo específicamente segmentado. La implementación falla si la reserva especificada no tiene capacidad suficiente.
   • RESERVATION_AFFINITY_KEY: la cadena. compute.googleapis.com/reservation-name. Debe especificar esta opción cuando el valor de RESERVATION_AFFINITY_TYPE sea SPECIFIC_RESERVATION.
   • RESERVATION_AFFINITY_VALUES: valor ARRAY<STRING> que especifica el nombre completo del recurso de la reserva de Compute Engine, con el siguiente formato:
     
     projects/myproject/zones/reservation_zone/reservations/reservation_name

     Por ejemplo, RESERVATION_AFFINITY_values = ['projects/myProject/zones/us-central1-a/reservations/myReservationName'].

     Puedes obtener el nombre y la zona de la reserva en la página Reservas de la consola de Google Cloud . Para obtener más información, consulta Ver reservas.

     Debe especificar esta opción cuando el valor de RESERVATION_AFFINITY_TYPE sea SPECIFIC_RESERVATION.

   • ENDPOINT_IDLE_TTL: un valor de INTERVAL que especifica la duración de la inactividad tras la cual el modelo abierto se deja de desplegar automáticamente desde el endpoint de Vertex AI.

     Para habilitar la retirada automática, especifica un valor de literal de intervalo entre 390 minutos (6,5 horas) y 7 días. Por ejemplo, especifica INTERVAL 8 HOUR para que el modelo se deje de implementar después de 8 horas de inactividad. El valor predeterminado es de 390 minutos (6,5 horas).

     La inactividad del modelo se define como el tiempo que ha transcurrido desde que se realizó alguna de las siguientes operaciones en el modelo:

     • Ejecutando la sentencia CREATE MODEL.
     • Ejecutar la instrucción ALTER MODEL con el argumento DEPLOY_MODEL definido como TRUE.
     • Envío de una solicitud de inferencia al endpoint del modelo. Por ejemplo, ejecutando la función ML.GENERATE_EMBEDDING o ML.GENERATE_TEXT.

     Cada una de estas operaciones reinicia el temporizador de inactividad a cero. El restablecimiento se activa al inicio de la tarea de BigQuery que realiza la operación.

     Una vez que se haya anulado el despliegue del modelo, las solicitudes de inferencia que se envíen al modelo devolverán un error. El objeto de modelo de BigQuery no cambia, incluidos los metadatos del modelo. Para volver a usar el modelo en la inferencia, debes volver a desplegarlo ejecutando la instrucción ALTER MODEL en el modelo y configurando la opción DEPLOY_MODEL en TRUE.

Modelos abiertos desplegados

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

   Ir a BigQuery

2. 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 = 'https://ENDPOINT_REGION-aiplatform.googleapis.com/v1/projects/ENDPOINT_PROJECT_ID/locations/ENDPOINT_REGION/endpoints/ENDPOINT_ID'
   );

   Haz los cambios siguientes:

   • PROJECT_ID: tu ID de proyecto.
   • DATASET_ID: ID del conjunto de datos que contendrá el modelo. Este conjunto de datos debe estar en la misma ubicación que la conexión que estés usando.
   • MODEL_NAME: el nombre del modelo.
   • REGION: la región que usa la conexión.
   • CONNECTION_ID: el ID de tu conexión de BigQuery.

     Para obtener este valor, consulta los detalles de la conexión en la consola Google Cloud y copia 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_REGION: la región en la que se ha desplegado el modelo abierto.
   • ENDPOINT_PROJECT_ID: el proyecto en el que se ha implementado el modelo abierto.
   • ENDPOINT_ID: el ID del endpoint HTTPS que usa el modelo abierto. Para obtener el ID del endpoint, busca el modelo abierto en la página Predicción online y copia el valor del campo ID.

Todos los demás modelos

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

   Ir a BigQuery

2. 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: ID del conjunto de datos que contendrá el modelo. Este conjunto de datos debe estar en la misma ubicación que la conexión que estés usando.
   • MODEL_NAME: el nombre del modelo.
   • REGION: la región que usa la conexión.
   • CONNECTION_ID: el ID de tu conexión de BigQuery.

     Para obtener este valor, consulta los detalles de la conexión en la consola Google Cloud y copia 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 nombre de un modelo de inserción que se va a usar. Para obtener más información, consulta ENDPOINT.

     El modelo de Vertex AI que especifiques debe estar disponible en la ubicación en la que crees el modelo remoto. Para obtener más información, consulta Ubicaciones.

Generar embeddings de texto

Genera incrustaciones de texto con la función ML.GENERATE_EMBEDDING usando datos de texto de una columna de una tabla o de una consulta.

Normalmente, se usa un modelo de inserciones de texto en los casos prácticos en los que solo se utiliza texto, y un modelo de inserciones multimodal en los casos prácticos de búsqueda entre modalidades, en los que las inserciones de texto y contenido visual se generan en el mismo espacio semántico.

Texto de Vertex AI

Genera inserciones de texto mediante un modelo remoto a través de un modelo de inserciones de texto de Vertex AI:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  {TABLE PROJECT_ID.DATASET_ID.TABLE_NAME | (CONTENT_QUERY)},
  STRUCT(FLATTEN_JSON AS flatten_json_output,
    TASK_TYPE AS task_type,
    OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

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 sobre un modelo de inserción.
• TABLE_NAME: el nombre de la tabla que contiene el texto que se va a insertar. Esta tabla debe tener una columna llamada content. También puedes usar un alias para usar una columna con otro nombre.
• CONTENT_QUERY: una consulta cuyo resultado contiene una columna STRING llamada content.
• FLATTEN_JSON: un valor BOOL que indica si se debe analizar la inserción en una columna independiente. El valor predeterminado es TRUE.
• TASK_TYPE: un literal STRING que especifica la aplicación de destino para ayudar al modelo a producir inserciones de mejor calidad. TASK_TYPE acepta los siguientes valores:
  • RETRIEVAL_QUERY: especifica que el texto proporcionado es una consulta en un ajuste de búsqueda o recuperación.
  • RETRIEVAL_DOCUMENT: especifica que el texto proporcionado es un documento en un contexto de búsqueda o recuperación.

    Cuando se usa este tipo de tarea, es útil incluir el título del documento en la consulta para mejorar la calidad de la inserción. 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)
          );
          

    Si se especifica la columna de título en la consulta de entrada, se rellena el campo title del cuerpo de la solicitud enviada al modelo. Si especifica un valor de title al usar cualquier otro tipo de tarea, esa entrada se ignora y no tiene ningún efecto en los resultados de la inserción.

  • SEMANTIC_SIMILARITY: especifica que el texto proporcionado se usará para la similitud textual semántica (STS).
  • CLASSIFICATION: especifica que las inserciones se usarán para la clasificación.
  • CLUSTERING: especifica que las inserciones se usarán para la creación de clústeres.
  • QUESTION_ANSWERING: especifica que las inserciones se usarán para responder preguntas.
  • FACT_VERIFICATION: especifica que las inserciones se usarán para verificar hechos.
  • CODE_RETRIEVAL_QUERY: especifica que las inserciones se usarán para recuperar código.
• OUTPUT_DIMENSIONALITY: valor INT64 que especifica el número de dimensiones que se deben usar al generar inserciones. Por ejemplo, si especifica 256 AS output_dimensionality, la columna de salida ml_generate_embedding_result contendrá 256 inserciones por cada valor de entrada.

  En el caso de los modelos remotos de más de gemini-embedding-001 modelos, el valor de OUTPUT_DIMENSIONALITY debe estar en el intervalo [1, 3072]. El valor predeterminado es 3072. En los modelos remotos de text-embedding o text-multilingual-embedding, el valor OUTPUT_DIMENSIONALITY debe estar en el intervalo [1, 768]. El valor predeterminado es 768.

  Si usas un modelo remoto a través de un modelo text-embedding, la versión del modelo text-embedding debe ser text-embedding-004 o una posterior. Si usas un modelo remoto con un modelo text-multilingual-embedding, la versión del modelo text-multilingual-embedding debe ser text-multilingual-embedding-002 o posterior.

Ejemplo: insertar texto en una tabla

En el siguiente ejemplo se muestra una solicitud para insertar 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)
  );

Texto abierto

Vista previa

Este producto o función está sujeto a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Los productos y las funciones previos a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

Nota: Para enviar comentarios o solicitar asistencia sobre esta función, ponte en contacto con [e-mail].

Genera incrustaciones de texto usando un modelo remoto en un modelo de incrustaciones abierto:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  {TABLE PROJECT_ID.DATASET_ID.TABLE_NAME | (CONTENT_QUERY)},
  STRUCT(FLATTEN_JSON AS flatten_json_output)
);

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 sobre un modelo de inserción.
• TABLE_NAME: el nombre de la tabla que contiene el texto que se va a insertar. Esta tabla debe tener una columna llamada content. También puedes usar un alias para usar una columna con otro nombre.
• CONTENT_QUERY: una consulta cuyo resultado contiene una columna STRING llamada content.
• FLATTEN_JSON: un valor BOOL que indica si se debe analizar la inserción en una columna independiente. El valor predeterminado es TRUE.

Vertex AI multimodal

Genera representaciones de texto mediante un modelo remoto a través de un modelo de representación multimodal de Vertex AI:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  {TABLE PROJECT_ID.DATASET_ID.TABLE_NAME | (CONTENT_QUERY)},
  STRUCT(FLATTEN_JSON AS flatten_json_output，
  OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

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 que contiene el texto que se va a insertar. Esta tabla debe tener una columna llamada content. También puedes usar un alias para usar una columna con otro nombre.
• CONTENT_QUERY: una consulta cuyo resultado contiene una columna STRING llamada content.
• FLATTEN_JSON: un 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 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: usar las inserciones para clasificar la similitud semántica

En el siguiente ejemplo se inserta una colección de reseñas de películas y se ordenan por distancia de coseno con respecto a la reseña "Esta película era normal" mediante la función VECTOR_SEARCH. Cuanto menor sea la distancia, mayor será la similitud semántica.

Para obtener más información sobre la búsqueda vectorial y el índice vectorial, consulta el artículo Introducción a la búsqueda vectorial.

CREATE TEMPORARY TABLE movie_review_embeddings AS (
  SELECT *
  FROM
    ML.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (
        SELECT "This movie was fantastic" AS content
        UNION ALL
        SELECT "This was the best movie I've ever seen!!" AS content
        UNION ALL
        SELECT "This movie was just okay..." AS content
        UNION ALL
        SELECT "This movie was terrible." AS content
      ),
      STRUCT(TRUE AS flatten_json_output)
    )
);

WITH 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
  base.content AS content,
  distance AS distance_to_average_review
FROM
  VECTOR_SEARCH(
    TABLE movie_review_embeddings,
    "ml_generate_embedding_result",
    (SELECT ml_generate_embedding_result FROM average_review_embedding),
    distance_type=>"COSINE",
    top_k=>-1
  )
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       |
+------------------------------------------+----------------------------+

Siguientes pasos

• Consulta cómo usar las inserciones de texto e imagen para realizar una búsqueda semántica de texto a imagen.
• Consulta cómo usar las incrustaciones de texto para la búsqueda semántica y la generación aumentada de recuperación (RAG).