Cómo establecer permisos para las funciones de IA generativa que llaman a los LLM de Vertex AI

En este documento, se muestra cómo configurar los permisos para ejecutar consultas de IA generativa. Las consultas de IA generativa contienen funciones AI.* que llaman a modelos básicos en Vertex AI, por ejemplo, AI.GENERATE.

Existen dos formas de configurar los permisos para ejecutar consultas que usan funciones AI.*:

• Ejecuta la consulta con tus credenciales de usuario final
• Crea una conexión de BigQuery ML para ejecutar la consulta con una cuenta de servicio

En la mayoría de los casos, puedes usar las credenciales del usuario final y dejar el argumento CONNECTION en blanco. Si se espera que tu trabajo de consulta se ejecute durante 48 horas o más, debes usar una conexión de BigQuery y agregarla al argumento CONNECTION.

Ejecuta consultas de IA generativa con credenciales de usuario final

Para ejecutar consultas de IA generativa con credenciales de usuario final, configura los permisos necesarios con la consola de Google Cloud . Ten en cuenta que, si eres propietario del proyecto, ya tienes todos los permisos necesarios, por lo que no necesitas hacer nada.

Roles obligatorios

Para obtener los permisos que necesitas para ejecutar un trabajo de consulta que llama a un modelo de Vertex AI, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto:

• Ejecutar trabajos de consulta: Usuario de trabajo de BigQuery (roles/bigquery.jobUser)
• Accede a un modelo de base en Vertex AI: Usuario de Vertex AI (roles/aiplatform.user)

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Otorga los roles necesarios al usuario o grupo

Puedes usar la consola de Google Cloud para otorgar los roles necesarios a una principal. La principal es el usuario o el grupo que ejecuta la consulta que usa funciones AI.* para llamar a un modelo de base de Vertex AI.

1. En la consola de Google Cloud , dirígete a la página IAM.

   Ir a IAM

2. Elige tu proyecto.

3. Para otorgar roles a una principal, haz lo siguiente:

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

      Ir a IAM y administración

   2. Haz clic en Otorgar acceso.

      Se abre el cuadro de diálogo Agregar principales.

   3. En el campo Principales nuevas, ingresa el identificador de principal, por ejemplo, [e-mail] o //iam.googleapis.com/locations/global/workforcePools/example-pool/group/[e-mail].

   4. En la sección Asignar roles, haz clic en la flecha del menú desplegable Seleccionar un rol.

   5. Busca el rol Usuario de Vertex AI y selecciónalo.

   6. Haz clic en Agregar otra función.

   7. En la sección Asignar roles, haz clic en la flecha del menú desplegable Seleccionar un rol.

   8. Busca o explora el rol Usuario de trabajo de BigQuery y selecciónalo.

   9. Haz clic en Guardar.

      

Para modificar los roles de una principal que ya tiene roles en el proyecto, consulta Cómo otorgar roles adicionales a la misma principal.

Para obtener información sobre otros métodos para otorgar roles a nivel del proyecto a un principal, consulta Otorga o revoca varios roles de IAM de forma programática.

Ejecuta consultas de IA generativa con una conexión de BigQuery

Para ejecutar consultas de IA generativa con una conexión, crea la conexión y, luego, otorga acceso a la cuenta de servicio que creó la conexión.

Crear una conexión

Puedes configurar una conexión de recursos de Cloud para ejecutar todas las consultas de IA generativa que contengan funciones de AI.*. Cuando creas una conexión, otorgas permisos para ejecutar consultas en una cuenta de servicio.

Selecciona una de las siguientes opciones:

Console

1. Ve a la página de BigQuery.

   Ir a BigQuery

2. En el panel de la izquierda, haz clic en Explorar:

   

   Si no ves el panel izquierdo, haz clic en Expand left pane para abrirlo.

3. En el panel Explorador, expande el nombre de tu proyecto y, luego, haz clic en Conexiones.

4. En la página Connections, haz clic en Create connection.

5. En Tipo de conexión, elige Modelos remotos de Vertex AI, funciones remotas, BigLake y Spanner (Cloud Resource).

6. En el campo ID de conexión, ingresa un nombre para tu conexión.

7. En Tipo de ubicación, selecciona una ubicación para tu conexión. La conexión debe estar ubicada junto con tus otros recursos, como los conjuntos de datos.

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

   Reemplaza lo siguiente:

   • REGION: tu región de conexión
   • PROJECT_ID: El ID de tu 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 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 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 .

Para obtener más información, consulta Crea y configura una conexión de recursos de Cloud.

Otorga acceso a la cuenta de servicio

Para ejecutar consultas que usan funciones de AI.* generativas que llaman a modelos de Vertex AI, debes otorgar los permisos adecuados a la cuenta de servicio que se creó cuando creaste la conexión. Para ejecutar funciones que llaman a un modelo de base de Vertex AI, se requiere el rol de usuario de Vertex AI (roles/aiplatform.user).

Selecciona una de las siguientes opciones:

Console

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

   Ir a IAM y administración

2. Haz clic en Otorgar acceso.

   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 la sección Asignar roles, haz clic en Agregar roles.

5. Busca el rol Usuario de Vertex AI, selecciónalo y, luego, haz clic en Aplicar.

6. Haz clic en Guardar.

gcloud

Usa el comando gcloud projects add-iam-policy-binding:

gcloud projects add-iam-policy-binding gs://PROJECT_ID \
--member="serviceAccount:$(bq show --format=prettyjson --connection $PROJECT_ID.$REGION.$CONNECTION_ID | jq -r .cloudResource.serviceAccountId)"
--role=roles/aiplatform.user

Reemplaza lo siguiente:

• PROJECT_ID: nombre del proyecto.
• REGION: Es la ubicación en la que se creó la conexión.
• CONNECTION_ID: Es el nombre de la conexión que creaste.

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 otorga acceso al rol de IAM a la cuenta de servicio de la conexión de recursos de Cloud:

# 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 {}
}

## This grants IAM role access to the service account of the connection created in the previous step.
resource "google_project_iam_member" "connectionPermissionGrant" {
  project = data.google_project.default.project_id
  role    = "roles/storage.objectViewer"
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

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