Integra Cloud SQL en Vertex AI

En esta página, se describe cómo integrar Cloud SQL en Vertex AI. Esta integración te permite aplicar modelos de lenguaje grande (LLM), que se alojan en Vertex AI, a una base de datos de Cloud SQL para PostgreSQL, versión 12 y posteriores.

Si integras Cloud SQL en Vertex AI, puedes aplicar el poder semántico y predictivo de los modelos de aprendizaje automático (AA) a tus datos. Esta integración extiende la sintaxis de PostgreSQL con dos funciones para consultar modelos:

  • Invoca predicciones para llamar a un modelo mediante SQL dentro de una transacción.
  • Genera incorporaciones para que un LLM traduzca mensajes de texto en vectores numéricos. Luego, puedes aplicar estas incorporaciones de vectores como entradas a las funciones pgvector. Esto incluye métodos para comparar y ordenar muestras de texto según su distancia semántica relativa.

Como resultado, puedes hacer predicciones en tiempo real y obtener estadísticas valiosas directamente en la base de datos, lo que optimiza tus flujos de trabajo y mejora tus capacidades de toma de decisiones.

Para obtener más información sobre Vertex AI, consulta Introducción a Vertex AI.

Antes de comenzar

  1. Accede a tu cuenta de Google Cloud. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

  2. En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.

    Ir al selector de proyectos

  3. Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.

  4. En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.

    Ir al selector de proyectos

  5. Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.

  6. Habilita las APIs de Google Cloud necesarias.

    Console

    1. Ve a la página de APIs y servicios.
    2. Selecciona el proyecto desde la lista de proyectos.
    3. Si la Biblioteca de API no está abierta, selecciona Biblioteca en el menú de navegación.

    4. Haz clic en las APIs que quieras habilitar. Para este procedimiento, habilita la API de Cloud SQL Admin y la API de Vertex AI.

    5. Después de seleccionar cada API, haz clic en Habilitar.

    gcloud

    1. Abre Cloud Shell, que proporciona acceso de línea de comandos a tus recursos de Google Cloud directamente desde el navegador.
    2. Para habilitar las APIs requeridas, usa el comando gcloud services enable: 
      gcloud services enable sqladmin.googleapis.com \
enable aiplatform.googleapis.com
      3. Este comando habilita las siguientes APIs:
      • API de Cloud SQL Admin
      • La API de Vertex AI

  7. Otorga permisos de Identity and Access Management (IAM) a la cuenta de servicio de Cloud SQL para acceder a Vertex AI.

    gcloud

    Si deseas agregar permisos de Vertex AI a la cuenta de servicio de Cloud SQL para el proyecto en el que se encuentra la instancia de Cloud SQL, usa el comando gcloud projects add-iam-policy-binding: 

    gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
  --role="roles/aiplatform.user"

    Realiza los siguientes reemplazos:
    • PROJECT_ID: el ID del proyecto que tiene el extremo de Vertex AI. Cloud SQL usa este extremo para acceder al LLM alojado en Vertex AI.

    • SERVICE_ACCOUNT_EMAIL: la dirección de correo electrónico de la cuenta de servicio de Cloud SQL.

      Para encontrar esta dirección de correo electrónico, usa el comando gcloud sql instances describe INSTANCE_NAME y reemplaza INSTANCE_NAME por el nombre de la instancia de Cloud SQL. El valor que aparece junto al parámetro serviceAccountEmailAddress es la dirección de correo electrónico.

Habilita la integración de bases de datos en Vertex AI

Para habilitar la integración de la base de datos con Vertex AI, completa los siguientes pasos:

  1. Crea o actualiza una instancia de Cloud SQL para que la instancia pueda integrarse en Vertex AI.

    gcloud

    Crea la instancia

    Para crear la instancia de Cloud SQL, usa el comando gcloud sql instances create.

    gcloud sql instances create INSTANCE_NAME \
--database-version=DATABASE_VERSION \
--tier=MACHINE_TYPE \
--region=REGION_NAME \
--enable-google-ml-integration \
--database-flags cloudsql.enable_google_ml_integration=on

    Realiza los siguientes reemplazos:

    • INSTANCE_NAME: Es el nombre de la instancia.
    • DATABASE_VERSION: la versión de la base de datos para la instancia (por ejemplo, POSTGRES_13)
    • MACHINE_TYPE: el tipo de máquina para la instancia
    • REGION_NAME: el nombre de la región para la instancia

    Actualiza la instancia

    Para actualizar la instancia, usa el comando gcloud sql instances patch.

    gcloud sql instances patch INSTANCE_NAME \
--enable-google-ml-integration \
--database-flags cloudsql.enable_google_ml_integration=on

    Si esta actualización modifica un valor que requiere que la instancia se reinicie, recibirás un mensaje para continuar con el cambio o cancelarlo.

    REST v1

    Crea la instancia

    Usa este ejemplo para crear la instancia. Para ver una lista completa de los parámetros de esta llamada, consulta la página instances:insert. Para obtener información sobre la configuración de las instancias, incluidos los valores válidos para una región, consulta Configuración de instancias.

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • PROJECT_ID: el ID o el número del proyecto de Google Cloud que contiene la instancia
    • INSTANCE_NAME: Es el nombre de la instancia.
    • REGION_NAME: el nombre de la región para la instancia
    • DATABASE_VERSION: la cadena de enumeración de la versión de la base de datos (por ejemplo: POSTGRES_13)
    • PASSWORD: la contraseña del usuario root
    • MACHINE_TYPE: la string de enumeración del tipo de máquina (nivel) como: db-custom-[CPUS]-[MEMORY_MBS].
    • EDITION_TYPE: tu edición de Cloud SQL

    También debes incluir el objeto enableGoogleMlIntegration en la solicitud. Configura los siguientes parámetros, según sea necesario:

    • enableGoogleMlIntegration: cuando este parámetro se establece en true, las instancias de Cloud SQL pueden conectarse a Vertex AI para pasar solicitudes de predicciones en tiempo real y estadísticas a la IA
    • cloudsql.enable_google_ml_integration: cuando este parámetro se establece en on, Cloud SQL puede integrarse en Vertex AI.

    HTTP method and URL: 

    POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances

    Cuerpo JSON de la solicitud:

    {
  "name": "INSTANCE_NAME",
  "region": "REGION_NAME",
  "databaseVersion": "DATABASE_VERSION",
  "rootPassword": "PASSWORD",
  "settings": {
    "tier": "MACHINE_TYPE",
    "edition": "EDITION_TYPE",
    "enableGoogleMlIntegration": "true" | "false"
    "databaseFlags":
      {
        "name": "cloudsql.enable_google_ml_integration",
        "value": "on" | "off"
      }
  }
}

    Para enviar tu solicitud, expande una de estas opciones:

    Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2019-09-25T22:19:33.735Z",
  "operationType": "CREATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

    Actualiza la instancia

    Usa este ejemplo para actualizar la instancia. Para ver una lista completa de los parámetros de esta llamada, consulta la página instances.patch.

    Si una actualización modifica un valor que requiere que la instancia se reinicie, recibirás un mensaje para continuar con el cambio o cancelarlo.

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • PROJECT_ID: el ID o el número del proyecto de Google Cloud que contiene la instancia
    • INSTANCE_NAME: Es el nombre de la instancia.

    HTTP method and URL: 

    PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

    Cuerpo JSON de la solicitud:

    {
  "settings": {
    "enableGoogleMlIntegration": true,
    "databaseFlags":
      {
        "name": "cloudsql.enable_google_ml_integration",
        "value": "on"
      }
   }
}

    Para enviar tu solicitud, expande una de estas opciones:

    Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

    REST v1beta4

    Crea la instancia

    Usa este ejemplo para crear la instancia. Para ver una lista completa de los parámetros de esta llamada, consulta la página instances:insert. Para obtener información sobre la configuración de las instancias, incluidos los valores válidos para una región, consulta Configuración de instancias.

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • PROJECT_ID: el ID o el número del proyecto de Google Cloud que contiene la instancia
    • INSTANCE_NAME: Es el nombre de la instancia.
    • REGION_NAME: el nombre de la región para la instancia
    • DATABASE_VERSION: la cadena de enumeración de la versión de la base de datos (por ejemplo: POSTGRES_13)
    • PASSWORD: la contraseña del usuario root
    • MACHINE_TYPE: la string de enumeración del tipo de máquina (nivel) como: db-custom-[CPUS]-[MEMORY_MBS].
    • EDITION_TYPE: tu edición de Cloud SQL

    También debes incluir el objeto enableGoogleMlIntegration en la solicitud. Configura los siguientes parámetros, según sea necesario:

    • enableGoogleMlIntegration: cuando este parámetro se establece en true, las instancias de Cloud SQL pueden conectarse a Vertex AI para pasar solicitudes de predicciones en tiempo real y estadísticas a la IA
    • cloudsql.enable_google_ml_integration: cuando este parámetro se establece en on, Cloud SQL puede integrarse en Vertex AI.

    HTTP method and URL: 

    POST https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances

    Cuerpo JSON de la solicitud:

    {
  "name": "INSTANCE_NAME",
  "region": "REGION_NAME",
  "databaseVersion": "DATABASE_VERSION",
  "rootPassword": "PASSWORD",
  "settings": {
    "tier": "MACHINE_TYPE",
    "edition": "EDITION_TYPE",
    "enableGoogleMlIntegration": "true" | "false"
    "databaseFlags":
      {
        "name": "cloudsql.enable_google_ml_integration",
        "value": "on" | "off"
      }
  }
}

    Para enviar tu solicitud, expande una de estas opciones:

    Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2019-09-25T22:19:33.735Z",
  "operationType": "CREATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

    Actualiza la instancia

    Usa este ejemplo para actualizar la instancia. Para ver una lista completa de los parámetros de esta llamada, consulta la página instances.patch.

    Si una actualización modifica un valor que requiere que la instancia se reinicie, recibirás un mensaje para continuar con el cambio o cancelarlo.

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • PROJECT_ID: el ID o el número del proyecto de Google Cloud que contiene la instancia
    • INSTANCE_NAME: Es el nombre de la instancia.

    HTTP method and URL: 

    PATCH https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

    Cuerpo JSON de la solicitud:

    {
  "settings": {
    "enableGoogleMlIntegration": true,
    "databaseFlags":
      {
        "name": "cloudsql.enable_google_ml_integration",
        "value": "on"
      }
   }
}

    Para enviar tu solicitud, expande una de estas opciones:

    Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}
  2. Instala la extensión google_ml_integration en una base de datos de la instancia principal de Cloud SQL. Esta base de datos contiene datos sobre los que deseas ejecutar predicciones.
    1. Conecta un cliente psql a la instancia principal, como se describe en Conéctate con un cliente psql.
    2. En el símbolo del sistema de psql, conéctate a la base de datos: 
      \c DB_NAME

      Reemplaza DB_NAME por el nombre de la base de datos en la que deseas instalar la extensión.

    3. Instala la extensión: 
      CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;

Solución de problemas

Esta sección contiene información sobre los problemas asociados con la integración de Cloud SQL en Vertex AI, junto con los pasos para solucionar los problemas.

Problema Soluciona problemas
Mensaje de error: Google ML integration API is supported only on Postgres version 12 or above. Para habilitar la integración de Vertex AI en Cloud SQL, debes tener una base de datos de Cloud SQL para PostgreSQL, versión 12 o posterior. Para actualizar tu base de datos a esta versión, consulta Actualiza la versión principal de la base de datos de manera local.
Mensaje de error: Google ML Integration API is not supported on shared core instance. Please upsize your machine type. Si seleccionaste un núcleo compartido para el tipo de máquina de tu instancia, no puedes habilitar la integración de Vertex AI en Cloud SQL. Actualiza tu tipo de máquina a un núcleo dedicado. Para obtener más información, consulta Tipo de máquina.
Mensaje de error: Google ML Integration is unsupported for this maintenance version. Please follow https://cloud.google.com/sql/docs/postgres/self-service-maintenance to update the maintenance version of the instance. Para habilitar la integración de Vertex AI en Cloud SQL, la versión de mantenimiento de tu instancia debe ser R20240130 o posterior. Para actualizar tu instancia a esta versión, consulta Mantenimiento de autoservicio.
Mensaje de error: Cannot invoke ml_predict_row if 'cloudsql.enable_google_ml_integration' is off. La marca de la base de datos cloudsql.enable_google_ml_integration está desactivada. Cloud SQL no se puede integrar en Vertex AI.

Para activar esta marca, usa el comando gcloud sql instances patch:

gcloud sql instances patch INSTANCE_NAME --database-flags cloudsql.enable_google_ml_integration=on

Reemplaza INSTANCE_NAME por el nombre de la instancia principal de Cloud SQL.
Mensaje de error: Failed to connect to remote host: Connection refused. La integración entre Cloud SQL y Vertex AI no está habilitada. Para habilitar esta integración, usa el comandogcloud sql instances patch:

gcloud sql instances patch INSTANCE_NAME
--enable-google-ml-integration

ReemplazarINSTANCE_NAME por el nombre de la instancia principal de Cloud SQL.
Mensaje de error: Vertex AI API has not been used in project PROJECT_ID before or it is disabled. Enable it by visiting /apis/api/aiplatform.googleapis.com/overview?project=PROJECT_ID then retry. La API de Vertex AI no está habilitada. Para obtener más información sobre cómo habilitar esta API, consulta Habilita la integración de la base de datos con Vertex AI.
Mensaje de error: Permission 'aiplatform.endpoints.predict' denied on resource. Los permisos de Vertex AI no se agregan a la cuenta de servicio de Cloud SQL para el proyecto en el que se encuentra la instancia de Cloud SQL. Para obtener más información sobre cómo agregar estos permisos a la cuenta de servicio, consulta Habilita la integración de la base de datos con Vertex AI.
Mensaje de error: Publisher Model `projects/PROJECT_ID/locations/REGION_NAME/publishers/google/models/MODEL_NAME` not found. El modelo de aprendizaje automático o el LLM no existen en Vertex AI.
Mensaje de error: Resource exhausted: grpc: received message larger than max. El tamaño de la solicitud que Cloud SQL pasa a Vertex AI supera el límite de gRPC de 4 MB por solicitud.
Mensaje de error: Cloud SQL attempts to send a request to Vertex AI. However, the instance is in the %s region, but the Vertex AI endpoint is in the %s region. Make sure the instance and endpoint are in the same region. Cloud SQL intenta enviar una solicitud a Vertex AI. Sin embargo, la instancia está en una región, pero el extremo de Vertex AI está en una región diferente. Para resolver este problema, la instancia y el extremo deben estar en la misma región.
Mensaje de error: The Vertex AI endpoint isn't formatted properly. El extremo de Vertex AI no tiene el formato correcto. Si deseas obtener más información, consulta Usa extremos privados para la predicción en línea.
Mensaje de error: Quota exceeded for aiplatform.googleapis.com/online_prediction_requests_per_base_model with base model: textembedding-gecko. La cantidad de solicitudes que Cloud SQL pasa a Vertex AI supera el límite de 1,500 solicitudes por minuto, por región, por modelo y por proyecto.

¿Qué sigue?