Traducir texto con la función ML.TRANSLATE

En este documento se describe cómo usar la función ML.TRANSLATE con un modelo remoto para traducir texto de una tabla estándar de BigQuery.

Roles obligatorios

Para crear un modelo remoto y traducir texto, necesitas los siguientes roles de Gestión de Identidades y Accesos (IAM) a nivel de proyecto:

• Crear y usar conjuntos de datos, tablas y modelos de BigQuery: Editor de datos de BigQuery (roles/bigquery.dataEditor)

• Crear, delegar y usar conexiones de BigQuery: Administrador de conexión de BigQuery (roles/bigquery.connectionsAdmin)

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

• Crear tareas de BigQuery: usuario de tareas de BigQuery (roles/bigquery.jobUser)

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
• Crear, delegar y usar 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

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

Antes de empezar

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.

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

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery, BigQuery Connection API, and Cloud Translation 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

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

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery, BigQuery Connection API, and Cloud Translation 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 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 del conjunto de datos, escribe un nombre para el conjunto de datos.

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

   • 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, funciones remotas y BigLake (recurso de Cloud) de Vertex AI.

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 Google Cloud 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 acceso a la cuenta de servicio

Selecciona una de las opciones siguientes:

Consola

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

   Ir a IAM y administración

2. Haz clic en Añadir.

   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 Uso del servicio y, a continuación, Consumidor de uso del servicio.

5. Haz clic en Añadir otro rol.

6. En el campo Seleccionar un rol, selecciona BigQuery y, a continuación, Usuario de conexión de BigQuery.

7. Haz clic en Añadir otro rol.

8. En el campo Selecciona un rol, elige Cloud Translation y, a continuación, Usuario de la API Cloud Translation.

9. 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
gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/cloudtranslate.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 anteriormente.

Si no se concede el permiso, se producirá un error.

Crear un modelo

Crea un modelo remoto con un REMOTE_SERVICE_TYPE de CLOUD_AI_TRANSLATE_V3:

CREATE OR REPLACE MODEL
`PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
OPTIONS (REMOTE_SERVICE_TYPE = 'CLOUD_AI_TRANSLATE_V3');

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 la conexión. Por ejemplo, myconnection.

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

Traducir texto

Para traducir texto con la función ML.TRANSLATE, sigue estos pasos:

SELECT *
FROM ML.TRANSLATE(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  { TABLE PROJECT_ID.DATASET_ID.TABLE_NAME | (QUERY) },
  STRUCT('MODE' AS translate_mode, ['LANGUAGE' AS target_language_code])
);

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.
• TABLE_NAME: el nombre de la tabla que contiene el texto que se va a traducir en una columna llamada text_content. Si el texto está en una columna con otro nombre, especifica text_content como alias de esa columna.
• QUERY: una consulta que contiene el texto que se va a traducir en una columna llamada text_content. Si el texto está en una columna con otro nombre, especifica text_content como alias de esa columna.
• MODE: el nombre de un modo de traducción admitido.
• LANGUAGE: el nombre de un código de idioma admitido. Este argumento solo es obligatorio cuando se usa el modo de traducción TRANSLATE_TEXT.

Ejemplo 1

En el siguiente ejemplo se traduce el texto de la columna text_content de la tabla al hindi:

SELECT * FROM ML.TRANSLATE(
  MODEL `mydataset.mytranslatemodel`,
  TABLE mydataset.mytable,
  STRUCT('translate_text' AS translate_mode, 'hi' AS target_language_code)
);

Ejemplo 2

En el siguiente ejemplo se detecta el idioma del texto de la columna comment de la tabla:

SELECT * FROM ML.TRANSLATE(
  MODEL `mydataset.mytranslatemodel`,
  (SELECT comment AS text_content from mydataset.mytable),
  STRUCT('detect_language' AS translate_mode)
);

Siguientes pasos

• Para obtener más información sobre la inferencia de modelos en BigQuery ML, consulta el resumen de la inferencia de modelos.
• Para obtener más información sobre cómo usar las APIs de IA de Cloud para realizar tareas de IA, consulta el artículo Descripción general de las aplicaciones de IA.
• Para obtener más información sobre las instrucciones y funciones de SQL admitidas en los modelos de IA generativa, consulta Recorridos de usuario completos de los modelos de IA generativa.
• Prueba el cuaderno Analíticas de datos sin estructurar con BigQuery ML y modelos preentrenados de Vertex AI.