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 in 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 incorporamenti vettoriali 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 insight preziosi direttamente nel database, semplificando i flussi di lavoro e migliorando le capacità decisionali.

Per saperne di più 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. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

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

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

    Go to project selector

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

  6. Abilita le API Google Cloud necessarie.

    Console

    1. Vai alla pagina API e servizi.
    2. Seleziona il tuo progetto dall'elenco di progetti.
    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

  7. Concedi all'account di servizio Cloud SQL le autorizzazioni Identity and Access Management (IAM) 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 che include 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, 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.

Abilita l'integrazione dei database con Vertex AI

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

  1. 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 dell'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, ti verrà chiesto se vuoi procedere con la modifica o 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 dell'istanza, 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: il nome della regione per l'istanza
    • DATABASE_VERSION: stringa enum della versione del database (ad esempio: POSTGRES_13)
    • PASSWORD: la password dell'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

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

    • enableGoogleMlIntegration: se questo parametro è impostato su true, le istanze Cloud SQL possono connettersi a Vertex AI per passare all'IA richieste per 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 delle seguenti 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, ti verrà chiesto se vuoi procedere con la modifica o annullare.

    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 delle seguenti 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 dell'istanza, 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: il nome della regione per l'istanza
    • DATABASE_VERSION: stringa enum della versione del database (ad esempio: POSTGRES_13)
    • PASSWORD: la password dell'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

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

    • enableGoogleMlIntegration: se questo parametro è impostato su true, le istanze Cloud SQL possono connettersi a Vertex AI per passare all'IA richieste per 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 delle seguenti 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, ti verrà chiesto se vuoi procedere con la modifica o annullare.

    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 delle seguenti 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 dati su cui vuoi eseguire previsioni.
    1. Connetti un client psql all'istanza principale, come descritto in Connettiti utilizzando un client psql.
    2. Al prompt dei comandi 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 Esegui l'upgrade della versione principale del database in loco.
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 dedicati. 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 di 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 saperne di più 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, vedi 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 il problema, l'istanza e l'endpoint devono trovarsi entrambi nella stessa regione.
Messaggio di errore: The Vertex AI endpoint isn't formatted properly. Il formato dell'endpoint Vertex AI non è corretto. Per maggiori informazioni, vedi 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 progetto.

Passaggi successivi