Entiende texto con la función ML.UNDERSTAND_TEXT

En este documento, se describe cómo usar la función ML.UNDERSTAND_TEXT con un modelo remoto para realizar una función de análisis de texto de lenguaje natural en texto de una tabla estándar de BigQuery.

Para obtener información sobre la inferencia de modelos en BigQuery ML, consulta Descripción general de la inferencia de modelos.

Para obtener información sobre los tipos de modelos compatibles de cada instrucción y función de SQL, y todas las instrucciones y funciones de SQL admitidas en cada tipo de modelo, consulta Recorrido del usuario de extremo a extremo para cada modelo.

Permisos necesarios

• Para crear una conexión, necesitas membresía en la siguiente función

  • 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 AA, necesitas los siguientes permisos:

  • 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. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

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

4. Enable the BigQuery, BigQuery Connection API, and Cloud Natural Language API APIs.

   Enable the APIs

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

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

7. Enable the BigQuery, BigQuery Connection API, and Cloud Natural Language API APIs.

   Enable the APIs

Crear una conexión

Crea una conexión de recurso en la nube y obtén la cuenta de servicio de la conexión.

Selecciona una de las opciones siguientes:

Console

1. Ve a la página de BigQuery.

   Ir a BigQuery

2. Para crear una conexión, haz clic en Agregar y, luego, en Conexiones a fuentes de datos externas.

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

4. En el campo ID de conexión, escribe un nombre para tu conexión.

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

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

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

Terraform

Usa el recurso google_bigquery_connection.

Nota: Para crear objetos de BigQuery a través de Terraform, debes habilitar la API de Cloud Resource Manager

.

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.

Nota: Por lo general, las muestras de Terraform suponen que las APIs necesarias están habilitadas en tu proyecto de Google Cloud.

Otorga acceso a la cuenta de servicio

Elige una de las opciones siguientes:

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 Seleccionar una función, selecciona Service Usage y, luego, Consumidor de Service Usage.

5. Haz clic en Agregar otra función.

6. En el campo Seleccionar una función, selecciona BigQuery y, luego, Usuario de conexión de BigQuery.

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/serviceusage.serviceUsageConsumer' --condition=None
gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/bigquery.connectionUser' --condition=None

Reemplaza lo siguiente:

• PROJECT_NUMBER: Es el número de tu proyecto.
• MEMBER: Es el ID de la cuenta de servicio que copiaste antes.

Si no se otorga el permiso, se produce un error.

Crear un modelo

Crea un modelo remoto con un REMOTE_SERVICE_TYPE de CLOUD_AI_NATURAL_LANGUAGE_V1:

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

Reemplaza lo siguiente:

• PROJECT_ID: el ID de tu proyecto
• DATASET_ID: El 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 usas.
• MODEL_NAME: el nombre del modelo
• REGION: Es la región que usa la conexión.
• CONNECTION_ID: el ID de conexión, por ejemplo, myconnection.

  Cuando ves los detalles de conexión en la consola de Google Cloud, el ID de conexión 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.

Interpretar texto

Comprende texto con la función ML.UNDERSTAND_TEXT:

SELECT *
FROM ML.UNDERSTAND_TEXT(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  { TABLE PROJECT_ID.DATASET_ID.TABLE_NAME | (QUERY) },
  STRUCT('FEATURE_NAME' AS nlu_option)
);

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
• TABLE_NAME: Es el nombre de la tabla que contiene el texto que se analizará en una columna llamada text_content. Si el texto está en una columna con un nombre diferente, especifica text_content como alias para esa columna.
• QUERY: una consulta que contiene el texto que se describirá en una columna llamada text_content. Si el texto está en una columna con un nombre diferente, especifica text_content como alias para esa columna.
• FEATURE_NAME: Es el nombre de una función de la API de Natural Language compatible.

Ejemplo 1

En el siguiente ejemplo, se inspecciona el texto en la columna text_content de la tabla y se identifica la opinión emocional predominante dentro del texto:

SELECT * FROM ML.UNDERSTAND_TEXT(
  MODEL `mydataset.mynlpmodel`,
  TABLE mydataset.mytable,
  STRUCT('analyze_sentiment' AS nlu_option)
);

Ejemplo 2

En el siguiente ejemplo, se inspecciona el texto en la columna comment de la tabla y se proporciona información sintáctica sobre él:

SELECT * FROM ML.UNDERSTAND_TEXT(
  MODEL `mydataset.mynlpmodel`,
  (SELECT comment AS text_content from mydataset.mytable),
  STRUCT('analyze_syntax' AS nlu_option)
);

¿Qué sigue?

Prueba el notebook Estadísticas de datos no estructurados con BigQuery ML y modelos previamente entrenados de Vertex AI.