Intégrer Cloud SQL à Vertex AI

Cette page explique comment intégrer Cloud SQL à Vertex AI. Cette intégration vous permet d'appliquer de grands modèles de langage (LLM), hébergés dans Vertex AI, à une base de données Cloud SQL pour PostgreSQL, version 12 et ultérieure.

En intégrant Cloud SQL à Vertex AI, vous pouvez appliquer la puissance sémantique et prédictive des modèles de machine learning (ML) à vos données. Cette intégration étend la syntaxe PostgreSQL avec deux fonctions permettant d'interroger des modèles :

  • Appelez des prédictions pour appeler un modèle à l'aide de SQL dans une transaction.
  • Générez des embeddings pour qu'un modèle d'embedding traduit des requêtes de texte en vecteurs numériques. Vous pouvez ensuite appliquer ces embeddings en tant qu'entrées aux fonctions pgvector. Cela inclut des méthodes permettant de comparer et de trier des échantillons de texte en fonction de leur distance sémantique relative.

Ainsi, vous pouvez faire des prédictions en temps réel et obtenir de précieuses informations directement depuis la base de données, en rationalisant vos workflows et en améliorant vos capacités de prise de décision.

Pour en savoir plus sur Vertex AI, consultez la Présentation de Vertex AI.

Avant de commencer

  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.

    Go to project selector

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

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

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

  6. Activez les API Google Cloud nécessaires.

    Console

    1. Accédez à la page API et services.
    2. Dans la liste des projets, sélectionnez un projet.
    3. Si la bibliothèque d'API n'est pas ouverte, sélectionnez Bibliothèque dans le menu de navigation.

    4. Cliquez sur les API que vous souhaitez activer. Pour cette procédure, activez l'API Cloud SQL Admin et l'API Vertex AI.

    5. Après avoir sélectionné chaque API, cliquez sur Activer.

    gcloud

    1. Ouvrez Cloud Shell, qui fournit un accès en ligne de commande à vos ressources Google Cloud, directement depuis votre navigateur.
    2. Pour activer les API requises, utilisez la commande gcloud services enable : 
      gcloud services enable sqladmin.googleapis.com \
enable aiplatform.googleapis.com
      3. Cette commande active les API suivantes :
      • API Cloud SQL Admin
      • API Vertex AI

  7. Accordez au compte de service Cloud SQL les autorisations IAM (Identity and Access Management) pour accéder à Vertex AI.

    gcloud

    Pour ajouter des autorisations Vertex AI au compte de service Cloud SQL pour le projet où se trouve l'instance Cloud SQL, utilisez la commande gcloud projects add-iam-policy-binding: 

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

    Effectuez les remplacements suivants :
    • PROJECT_ID: ID du projet contenant le point de terminaison Vertex AI. Cloud SQL utilise ce point de terminaison pour accéder au LLM hébergé dans Vertex AI.

    • SERVICE_ACCOUNT_EMAIL : adresse e-mail associée au compte de service Cloud SQL.

      Pour trouver cette adresse e-mail, utilisez la commande gcloud sql instances describe INSTANCE_NAME et remplacez INSTANCE_NAME par le nom de l'instance Cloud SQL. La valeur qui s'affiche à côté du paramètre serviceAccountEmailAddress est l'adresse e-mail.

Activer l'intégration de la base de données avec Vertex AI

Pour activer l'intégration de la base de données avec Vertex AI, procédez comme suit :

  1. Créez ou mettez à jour une instance Cloud SQL afin que l'instance puisse s'intégrer à Vertex AI.

    gcloud

    Créer l'instance

    Pour créer l'instance Cloud SQL, utilisez la commande 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

    Effectuez les remplacements suivants :

    • INSTANCE_NAME : nom de l'instance
    • DATABASE_VERSION : version de la base de données pour l'instance (par exemple, POSTGRES_13).
    • MACHINE_TYPE : type de machine de l'instance.
    • REGION_NAME : nom de la région pour l'instance.

    Mettre à jour l'instance

    Pour mettre à jour l'instance, utilisez la commande gcloud sql instances patch.

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

    Si cette mise à jour modifie une valeur dont la modification nécessite un redémarrage de l'instance, un message vous invite à procéder à la modification ou à annuler l'opération.

    REST v1

    Créer l'instance

    Utilisez cet exemple pour créer l'instance. Pour obtenir la liste complète des paramètres de cet appel, consultez la page instances:insert. Pour en savoir plus sur les paramètres des instances, y compris sur les valeurs valides pour la région, consultez la page Paramètres des instances.

    Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

    • PROJECT_ID : ID ou numéro de projet du projet Google Cloud contenant l'instance.
    • INSTANCE_NAME : nom de l'instance
    • REGION_NAME : nom de la région pour l'instance.
    • DATABASE_VERSION : chaîne d'énumération de la version de base de données (par exemple, POSTGRES_13).
    • PASSWORD : mot de passe de l'utilisateur root
    • MACHINE_TYPE : chaîne d'énumération du type (niveau) de machine, comme suit : db-custom-[CPUS]-[MEMORY_MBS].
    • EDITION_TYPE : votre édition Cloud SQL

    Vous devez également inclure l'objet enableGoogleMlIntegration dans la requête. Définissez les paramètres suivants, si nécessaire :

    • enableGoogleMlIntegration : lorsque ce paramètre est défini sur true, les instances Cloud SQL peuvent se connecter à Vertex AI pour transmettre des requêtes de prédictions en temps réel et des insights à l'IA.
    • cloudsql.enable_google_ml_integration : lorsque ce paramètre est défini sur on, Cloud SQL peut s'intégrer à Vertex AI.

    Méthode HTTP et URL : 

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

    Corps JSON de la requête :

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

    Pour envoyer votre requête, développez l'une des options suivantes :

    Vous devriez recevoir une réponse JSON de ce type :

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

    Mettre à jour l'instance

    Utilisez cet exemple pour mettre à jour l'instance. Pour obtenir la liste complète des paramètres de cet appel, consultez la page instances.patch.

    Si cette mise à jour modifie une valeur dont la modification nécessite un redémarrage de l'instance, un message vous invite à procéder à la modification ou à annuler l'opération.

    Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

    • PROJECT_ID : ID ou numéro de projet du projet Google Cloud contenant l'instance.
    • INSTANCE_NAME : nom de l'instance

    Méthode HTTP et URL : 

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

    Corps JSON de la requête :

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

    Pour envoyer votre requête, développez l'une des options suivantes :

    Vous devriez recevoir une réponse JSON de ce type :

    {
  "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

    Créer l'instance

    Utilisez cet exemple pour créer l'instance. Pour obtenir la liste complète des paramètres de cet appel, consultez la page instances:insert. Pour en savoir plus sur les paramètres des instances, y compris sur les valeurs valides pour la région, consultez la page Paramètres des instances.

    Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

    • PROJECT_ID : ID ou numéro de projet du projet Google Cloud contenant l'instance.
    • INSTANCE_NAME : nom de l'instance
    • REGION_NAME : nom de la région pour l'instance.
    • DATABASE_VERSION : chaîne d'énumération de la version de base de données (par exemple, POSTGRES_13).
    • PASSWORD : mot de passe de l'utilisateur root
    • MACHINE_TYPE : chaîne d'énumération du type (niveau) de machine, comme suit : db-custom-[CPUS]-[MEMORY_MBS].
    • EDITION_TYPE : votre édition Cloud SQL

    Vous devez également inclure l'objet enableGoogleMlIntegration dans la requête. Définissez les paramètres suivants, si nécessaire :

    • enableGoogleMlIntegration : lorsque ce paramètre est défini sur true, les instances Cloud SQL peuvent se connecter à Vertex AI pour transmettre des requêtes de prédictions en temps réel et des insights à l'IA.
    • cloudsql.enable_google_ml_integration : lorsque ce paramètre est défini sur on, Cloud SQL peut s'intégrer à Vertex AI.

    Méthode HTTP et URL : 

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

    Corps JSON de la requête :

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

    Pour envoyer votre requête, développez l'une des options suivantes :

    Vous devriez recevoir une réponse JSON de ce type :

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

    Mettre à jour l'instance

    Utilisez cet exemple pour mettre à jour l'instance. Pour obtenir la liste complète des paramètres de cet appel, consultez la page instances.patch.

    Si cette mise à jour modifie une valeur dont la modification nécessite un redémarrage de l'instance, un message vous invite à procéder à la modification ou à annuler l'opération.

    Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

    • PROJECT_ID : ID ou numéro de projet du projet Google Cloud contenant l'instance.
    • INSTANCE_NAME : nom de l'instance

    Méthode HTTP et URL : 

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

    Corps JSON de la requête :

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

    Pour envoyer votre requête, développez l'une des options suivantes :

    Vous devriez recevoir une réponse JSON de ce type :

    {
  "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. Installez l'extension google_ml_integration dans une base de données de l'instance Cloud SQL principale. Cette base de données contient les données sur lesquelles vous souhaitez effectuer des prédictions.
    1. Connectez un client psql à l'instance principale, comme décrit dans la section Se connecter à l'aide d'un client psql.
    2. Lorsque l'invite de commande psql s'affiche, connectez-vous à la base de données : 
      \c DB_NAME

      Remplacez DB_NAME par le nom de la base de données sur laquelle vous souhaitez installer l'extension.

    3. Installez l'extension : 
      CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;

Résoudre les problèmes

Cette section contient des informations sur les problèmes associés à l'intégration de Cloud SQL à Vertex AI, ainsi que la procédure à suivre pour les résoudre.

Problème Dépannage
Message d'erreur : Google ML integration API is supported only on Postgres version 12 or above. Pour activer l'intégration de Vertex AI dans Cloud SQL, vous devez disposer d'une base de données Cloud SQL pour PostgreSQL version 12 ou ultérieure. Pour mettre à niveau votre base de données vers cette version, consultez la page Mettre à niveau la version majeure de la base de données sur place.
Message d'erreur : Google ML Integration API is not supported on shared core instance. Please upsize your machine type. Si vous avez sélectionné un cœur partagé pour le type de machine de votre instance, vous ne pouvez pas activer l'intégration de Vertex AI dans Cloud SQL. Mettez à niveau votre type de machine pour utiliser un cœur dédié. Pour en savoir plus, consultez la section Type de machine.
Message d'erreur : 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. Pour activer l'intégration de Vertex AI dans Cloud SQL, la version de maintenance de votre instance doit être une version R20240130 ou ultérieure. Pour mettre à niveau votre instance vers cette version, consultez la section Maintenance en libre-service.
Message d'erreur : Cannot invoke ml_predict_row if 'cloudsql.enable_google_ml_integration' is off. L'option de base de données cloudsql.enable_google_ml_integration est désactivée. Cloud SQL ne peut pas intégrer Vertex AI.

Pour activer cette option, utilisez la commande gcloud sql instances patch :

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

Remplacez INSTANCE_NAME par le nom de l'instance Cloud SQL principale.
Message d'erreur : Failed to connect to remote host: Connection refused. L'intégration entre Cloud SQL et Vertex AI n'est pas activée. Pour activer cette intégration, utilisez la commande gcloud sql instances patch :

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

Remplacez INSTANCE_NAME par le nom de l'instance Cloud SQL principale.
Message d'erreur : 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. L'API Vertex AI n'est pas activée. Pour en savoir plus sur l'activation de cette API, consultez la section Activer l'intégration de base de données avec Vertex AI.
Message d'erreur : Permission 'aiplatform.endpoints.predict' denied on resource. Les autorisations Vertex AI ne sont pas ajoutées au compte de service Cloud SQL pour le projet où se trouve l'instance Cloud SQL. Pour en savoir plus sur l'ajout de ces autorisations au compte de service, consultez la section Activer l'intégration de base de données avec Vertex AI.
Message d'erreur : Publisher Model `projects/PROJECT_ID/locations/REGION_NAME/publishers/google/models/MODEL_NAME` not found. Le modèle de machine learning ou le LLM n'existe pas dans Vertex AI.
Message d'erreur : Resource exhausted: grpc: received message larger than max. La taille de la requête que Cloud SQL transmet à Vertex AI dépasse la limite gRPC de 4 Mo par requête.
Message d'erreur : 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 tente d'envoyer une requête à Vertex AI. Cependant, l'instance se trouve dans une région, mais le point de terminaison Vertex AI se trouve dans une région différente. Pour résoudre ce problème, l'instance et le point de terminaison doivent se trouver dans la même région.
Message d'erreur : The Vertex AI endpoint isn't formatted properly. Le format du point de terminaison Vertex AI n'est pas correct. Pour en savoir plus, consultez la section Utiliser des points de terminaison privés pour la prédiction en ligne.
Message d'erreur : Quota exceeded for aiplatform.googleapis.com/online_prediction_requests_per_base_model with base model: textembedding-gecko. Le nombre de requêtes que Cloud SQL transmet à Vertex AI dépasse la limite de 1 500 requêtes par minute par région par modèle par projet.

Étapes suivantes