Integrare Cloud SQL con Vertex AI

Questa pagina descrive come integrare Cloud SQL con Vertex AI. Questa integrazione ti consente di applicare modelli linguistici di grandi dimensioni (LLM), ospitati in Vertex AI, a un database Cloud SQL per PostgreSQL, versione 12 e successive.

Se integri Cloud SQL con Vertex AI, puoi applicare la potenza semantica e predittiva dei modelli di machine learning (ML) ai tuoi dati. Questa integrazione estende la sintassi di PostgreSQL con due funzioni per eseguire query sui modelli:

  • Esegui previsioni per chiamare un modello utilizzando SQL all'interno di una transazione.
  • Genera incorporamenti per fare in modo che un modello di incorporamento traduca i prompt di testo in vettori numerici. Puoi quindi applicare questi vettori di incorporamento come input alle funzioni pgvector. Sono inclusi metodi per confrontare e ordinare esempi di testo in base alla relativa distanza semantica.

Di conseguenza, puoi fare previsioni in tempo reale e ottenere informazioni preziose direttamente nel database, semplificando i flussi di lavoro e migliorando le tue capacità decisionali.

Per ulteriori informazioni su Vertex AI, consulta Introduzione a Vertex AI.

Prima di iniziare

  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. Abilita le API Google Cloud necessarie.

    Console

    1. Vai alla pagina API e servizi.
    2. Seleziona il tuo progetto dall'elenco.
    3. Se la libreria API non è aperta, seleziona Libreria dal menu di navigazione.

    4. Fai clic sulle API che vuoi attivare. Per questa procedura, abilita l'API Cloud SQL Admin e l'API Vertex AI.

    5. Dopo aver selezionato ogni API, fai clic su Attiva.

    gcloud

    1. Apri Cloud Shell, che fornisce l'accesso da riga di comando alle risorse Google Cloud direttamente dal browser.
    2. Per abilitare le API richieste, utilizza il comando gcloud services enable: 
      gcloud services enable sqladmin.googleapis.com \
enable aiplatform.googleapis.com
      3. Questo comando abilita le seguenti API:
      • API Cloud SQL Admin
      • API Vertex AI

  7. Concedi all'account di servizio Cloud SQL le autorizzazioni IAM (Identity and Access Management) per accedere a Vertex AI.

    gcloud

    Per aggiungere le autorizzazioni Vertex AI all'account di servizio Cloud SQL per il progetto in cui si trova l'istanza Cloud SQL, utilizza il comando gcloud projects add-iam-policy-binding: 

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

    Apporta le seguenti sostituzioni:
    • PROJECT_ID: l'ID del progetto con l'endpoint Vertex AI. Cloud SQL utilizza questo endpoint per accedere al modello LLM ospitato in Vertex AI.

    • SERVICE_ACCOUNT_EMAIL: l'indirizzo email dell'account di servizio Cloud SQL.

      Per trovare questo indirizzo email, utilizza il comando gcloud sql instances describe INSTANCE_NAME e sostituisci INSTANCE_NAME con il nome dell'istanza Cloud SQL. Il valore visualizzato accanto al parametro serviceAccountEmailAddress è l'indirizzo email.

Attivare l'integrazione del database con Vertex AI

Per attivare l'integrazione del database con Vertex AI, completa i seguenti passaggi:

  1. Crea o aggiorna un'istanza Cloud SQL in modo che possa essere integrata con Vertex AI.

    gcloud

    Crea l'istanza

    Per creare l'istanza Cloud SQL, utilizza il 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

    Effettua le seguenti sostituzioni:

    • INSTANCE_NAME: il nome dell'istanza
    • DATABASE_VERSION: la versione del database per l'istanza (ad esempio POSTGRES_13)
    • MACHINE_TYPE: il tipo di macchina per l'istanza
    • REGION_NAME: il nome della regione per l'istanza

    Aggiorna l'istanza

    Per aggiornare l'istanza, utilizza il comando gcloud sql instances patch.

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

    Se questo aggiornamento modifica un valore che richiede un riavvio, viene visualizzato un messaggio che ti chiede di procedere con la modifica o di annullare.

    REST v1

    Crea l'istanza

    Utilizza questo esempio per creare l'istanza. Per un elenco completo dei parametri per questa chiamata, consulta la pagina instances:insert. Per informazioni sulle impostazioni delle istanze, inclusi i valori validi per una regione, consulta Impostazioni istanza.

    Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

    • PROJECT_ID: l'ID o il numero di progetto del progetto Google Cloud che contiene l'istanza
    • INSTANCE_NAME: il nome dell'istanza
    • REGION_NAME: il nome della regione per l'istanza
    • DATABASE_VERSION: stringa enum della versione del database (ad es. POSTGRES_13)
    • PASSWORD: la password per l'utente root
    • MACHINE_TYPE: stringa enum del tipo di macchina (livello), ad esempio: db-custom-[CPUS]-[MEMORY_MBS]
    • EDITION_TYPE: la tua versione Cloud SQL

    Nella richiesta devi includere anche l'oggetto enableGoogleMlIntegration. Imposta i seguenti parametri, come richiesto:

    • enableGoogleMlIntegration: quando questo parametro è impostato su true, le istanze Cloud SQL possono connettersi a Vertex AI per trasmettere all'AI richieste di previsioni in tempo reale e approfondimenti.
    • cloudsql.enable_google_ml_integration: quando questo parametro è impostato su on, Cloud SQL può essere integrato con Vertex AI

    Metodo HTTP e URL: 

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

    Corpo JSON della richiesta: 

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

    Per inviare la richiesta, espandi una di queste opzioni:

    Dovresti ricevere una risposta JSON simile alla seguente:

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

    Aggiorna l'istanza

    Utilizza questo esempio per aggiornare l'istanza. Per un elenco completo dei parametri per questa chiamata, consulta la pagina instances.patch.

    Se questo aggiornamento modifica un valore che richiede un riavvio, viene visualizzato un messaggio che ti chiede di procedere con la modifica o di annullare.

    Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

    • PROJECT_ID: l'ID o il numero di progetto del progetto Google Cloud che contiene l'istanza
    • INSTANCE_NAME: il nome dell'istanza

    Metodo HTTP e URL: 

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

    Corpo JSON della richiesta: 

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

    Per inviare la richiesta, espandi una di queste opzioni:

    Dovresti ricevere una risposta JSON simile alla seguente:

    {
  "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 l'istanza

    Utilizza questo esempio per creare l'istanza. Per un elenco completo dei parametri per questa chiamata, consulta la pagina instances:insert. Per informazioni sulle impostazioni delle istanze, inclusi i valori validi per una regione, consulta Impostazioni istanza.

    Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

    • PROJECT_ID: l'ID o il numero di progetto del progetto Google Cloud che contiene l'istanza
    • INSTANCE_NAME: il nome dell'istanza
    • REGION_NAME: il nome della regione per l'istanza
    • DATABASE_VERSION: stringa enum della versione del database (ad es. POSTGRES_13)
    • PASSWORD: la password per l'utente root
    • MACHINE_TYPE: stringa enum del tipo di macchina (livello), ad esempio: db-custom-[CPUS]-[MEMORY_MBS]
    • EDITION_TYPE: la tua versione Cloud SQL

    Nella richiesta devi includere anche l'oggetto enableGoogleMlIntegration. Imposta i seguenti parametri, come richiesto:

    • enableGoogleMlIntegration: quando questo parametro è impostato su true, le istanze Cloud SQL possono connettersi a Vertex AI per trasmettere all'AI richieste di previsioni in tempo reale e approfondimenti.
    • cloudsql.enable_google_ml_integration: quando questo parametro è impostato su on, Cloud SQL può essere integrato con Vertex AI

    Metodo HTTP e URL: 

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

    Corpo JSON della richiesta: 

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

    Per inviare la richiesta, espandi una di queste opzioni:

    Dovresti ricevere una risposta JSON simile alla seguente:

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

    Aggiorna l'istanza

    Utilizza questo esempio per aggiornare l'istanza. Per un elenco completo dei parametri per questa chiamata, consulta la pagina instances.patch.

    Se questo aggiornamento modifica un valore che richiede un riavvio, viene visualizzato un messaggio che ti chiede di procedere con la modifica o di annullare.

    Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

    • PROJECT_ID: l'ID o il numero di progetto del progetto Google Cloud che contiene l'istanza
    • INSTANCE_NAME: il nome dell'istanza

    Metodo HTTP e URL: 

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

    Corpo JSON della richiesta: 

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

    Per inviare la richiesta, espandi una di queste opzioni:

    Dovresti ricevere una risposta JSON simile alla seguente:

    {
  "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. Installa l'estensione google_ml_integration in un database dell'istanza Cloud SQL principale. Questo database contiene i dati su cui vuoi eseguire le previsioni.
    1. Connettiti a un client psql all'istanza principale, come descritto in Eseguire la connessione utilizzando un client psql.
    2. Al prompt dei comandi psql, connettiti al database: 
      \c DB_NAME

      Sostituisci DB_NAME con il nome del database su cui vuoi installare l'estensione.

    3. Installa l'estensione: 
      CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;

Risoluzione dei problemi

Questa sezione contiene informazioni sui problemi associati all'integrazione di Cloud SQL con Vertex AI, nonché i passaggi per la risoluzione dei problemi.

Problema Risoluzione dei problemi
Messaggio di errore: Google ML integration API is supported only on Postgres version 12 or above. Per attivare l'integrazione di Vertex AI in Cloud SQL, devi disporre di un database Cloud SQL per PostgreSQL, versione 12 o successiva. Per eseguire l'upgrade del database a questa versione, consulta Eseguire l'upgrade della versione principale del database sul posto.
Messaggio di errore: Google ML Integration API is not supported on shared core instance. Please upsize your machine type. Se hai selezionato un core condiviso per il tipo di macchina dell'istanza, non puoi attivare l'integrazione di Vertex AI in Cloud SQL. Esegui l'upgrade del tipo di macchina a un core dedicato. Per ulteriori informazioni, consulta Tipo di macchina.
Messaggio di errore: 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. Per attivare l'integrazione di Vertex AI in Cloud SQL, la versione di manutenzione dell'istanza deve essere R20240130 o successiva. Per eseguire l'upgrade dell'istanza a questa versione, consulta Manutenzione self-service.
Messaggio di errore: Cannot invoke ml_predict_row if 'cloudsql.enable_google_ml_integration' is off. Il flag di database cloudsql.enable_google_ml_integration è disattivato. Cloud SQL non può essere integrato con Vertex AI.

Per attivare questo flag, utilizza il comando gcloud sql instances patch:

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

Sostituisci INSTANCE_NAME con il nome dell'istanza Cloud SQL principale.
Messaggio di errore: Failed to connect to remote host: Connection refused. L'integrazione tra Cloud SQL e Vertex AI non è abilitata. Per attivare questa integrazione, utilizza il comando gcloud sql instances patch:

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

Sostituisci INSTANCE_NAME con il nome dell'istanza Cloud SQL principale.
Messaggio di errore: 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 non è abilitata. Per ulteriori informazioni sull'abilitazione di questa API, consulta Abilitare l'integrazione del database con Vertex AI.
Messaggio di errore: Permission 'aiplatform.endpoints.predict' denied on resource. Le autorizzazioni Vertex AI non vengono aggiunte all'account di servizio Cloud SQL per il progetto in cui si trova l'istanza Cloud SQL. Per ulteriori informazioni sull'aggiunta di queste autorizzazioni all'account di servizio, consulta Attivare l'integrazione del database con Vertex AI.
Messaggio di errore: Publisher Model `projects/PROJECT_ID/locations/REGION_NAME/publishers/google/models/MODEL_NAME` not found. Il modello di machine learning o l'LLM non esiste in Vertex AI.
Messaggio di errore: Resource exhausted: grpc: received message larger than max. Le dimensioni della richiesta che Cloud SQL passa a Vertex AI superano il limite di gRPC di 4 MB per richiesta.
Messaggio di errore: 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 tenta di inviare una richiesta a Vertex AI. Tuttavia, l'istanza si trova in una regione, ma l'endpoint Vertex AI si trova in un'altra regione. Per risolvere il problema, l'istanza e l'endpoint devono trovarsi nella stessa regione.
Messaggio di errore: The Vertex AI endpoint isn't formatted properly. L'endpoint Vertex AI non è formattato correttamente. Per ulteriori informazioni, consulta Utilizzare endpoint privati per la previsione online.
Messaggio di errore: Quota exceeded for aiplatform.googleapis.com/online_prediction_requests_per_base_model with base model: textembedding-gecko. Il numero di richieste che Cloud SQL passa a Vertex AI supera il limite di 1500 richieste al minuto per regione,per modello e per progetto.

Passaggi successivi