Integra Cloud SQL con Vertex AI

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

Integrando 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 PostgreSQL con due funzioni per l'esecuzione di query sui modelli:

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

Di conseguenza, è possibile fare previsioni in tempo reale e ottenere informazioni preziose direttamente all'interno del database, ottimizzando i flussi di lavoro e migliorando le capacità decisionali.

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

Prima di iniziare

  1. Accedi al tuo account Google Cloud. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.

  2. Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

    Vai al selettore progetti

  3. Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

  4. Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

    Vai al selettore progetti

  5. Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

Abilita l'integrazione del database con Vertex AI

Per abilitare l'integrazione del database con Vertex AI, completa questi passaggi:

  1. 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 abilitare. Per questa procedura, abilita l'API Cloud SQL Admin e l'API Vertex AI.

    5. Dopo aver selezionato ciascuna API, fai clic su Abilita.

    gcloud

    1. Apri Cloud Shell, che fornisce l'accesso tramite 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

  2. Crea o aggiorna un'istanza Cloud SQL in modo che possa integrarsi 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: tipo di macchina per l'istanza
    • REGION_NAME: 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, ti verrà chiesto di procedere con la modifica o di annullare l'operazione.

    REST v1

    Crea l'istanza

    Utilizza questo esempio per creare l'istanza. Per un elenco completo dei parametri di 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, effettua 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: nome della regione per l'istanza
    • DATABASE_VERSION: stringa enum della versione del database (ad esempio: 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 di Cloud SQL

    Devi includere nella richiesta 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 passare all'IA richieste di previsioni in tempo reale e insight
    • cloudsql.enable_google_ml_integration: se questo parametro è impostato su on, Cloud SQL può integrarsi 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 di questa chiamata, vedi la pagina instances.patch.

    Se questo aggiornamento modifica un valore che richiede un riavvio, ti verrà chiesto di procedere con la modifica o di annullare l'operazione.

    Prima di utilizzare i dati della richiesta, effettua 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 di 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, effettua 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: nome della regione per l'istanza
    • DATABASE_VERSION: stringa enum della versione del database (ad esempio: 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 di Cloud SQL

    Devi includere nella richiesta 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 passare all'IA richieste di previsioni in tempo reale e insight
    • cloudsql.enable_google_ml_integration: se questo parametro è impostato su on, Cloud SQL può integrarsi 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 di questa chiamata, vedi la pagina instances.patch.

    Se questo aggiornamento modifica un valore che richiede un riavvio, ti verrà chiesto di procedere con la modifica o di annullare l'operazione.

    Prima di utilizzare i dati della richiesta, effettua 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"
}

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

    Effettua le seguenti sostituzioni:
    • PROJECT_ID: l'ID del progetto che ha l'endpoint Vertex AI. Cloud SQL utilizza questo endpoint per accedere all'LLM ospitato in Vertex AI.

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

      Per trovare questo indirizzo email, usa 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.

  4. 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. Connetti un client psql all'istanza principale, come descritto in Connessione tramite un client psql.
    2. Nel prompt dei comandi di psql, connettiti al database: 
      \c DB_NAME

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

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

Risolvere i problemi

Questa sezione contiene informazioni sui problemi associati all'integrazione di Cloud SQL con Vertex AI, oltre ai 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 abilitare 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, vedi Eseguire l'upgrade della versione principale del database in uso.
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 abilitare l'integrazione di Vertex AI in Cloud SQL. Esegui l'upgrade del tipo di macchina a core dedicato. Per ulteriori informazioni, vedi 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 abilitare 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 del database cloudsql.enable_google_ml_integration è disattivato. Cloud SQL non può integrarsi 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 abilitare 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 maggiori 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 di Vertex AI non vengono aggiunte all'account di servizio Cloud SQL per il progetto in cui si trova l'istanza Cloud SQL. Per saperne di più su come aggiungere queste autorizzazioni all'account di servizio, consulta Abilitare 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 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. Per risolvere questo problema, sia l'istanza che 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 gli endpoint privati per le previsioni 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 per progetto.

Passaggi successivi