Integra Cloud SQL con Agent Platform

Questa pagina descrive come integrare Cloud SQL con Agent Platform.

Questa integrazione ti consente di applicare modelli linguistici di grandi dimensioni (LLM), ospitati in Agent Platform, a un database Cloud SQL per MySQL, versione 8.0.36 e successive.

Integrando Cloud SQL con Agent Platform, puoi applicare la potenza semantica e predittiva dei modelli di machine learning (ML) ai tuoi dati. Questa integrazione estende la sintassi SQL 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 embedding per consentire a un modello di embedding di tradurre i prompt di testo in vettori numerici. Puoi quindi applicare questi vector embedding come input alle funzioni vector. Sono inclusi metodi per confrontare e ordinare campioni di testo in base alla loro distanza semantica relativa.

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

Per ulteriori informazioni su Agent Platform, consulta la pagina Introduzione ad Agent Platform.

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 senza costi per l'esecuzione, il test e il deployment dei workload.

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify 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. Dall'elenco dei progetti, seleziona il tuo progetto.
    3. Se la libreria API non è aperta, seleziona Libreria dal menu di navigazione.

    4. Fai clic sulle API che vuoi abilitare. Per questa procedura, attiva quanto segue:

      • API Cloud SQL Admin
      • API Agent Platform
      • API Compute Engine
    5. Dopo aver selezionato ogni API, fai clic su Attiva.

    gcloud

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

  7. Concedi all'account di servizio Cloud SQL le autorizzazioni Identity and Access Management (IAM) per accedere ad Agent Platform.

    8. gcloud

    Per aggiungere le autorizzazioni della piattaforma agent alaccount di serviziot 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"

    Esegui le seguenti sostituzioni:
    • PROJECT_ID: l'ID del progetto che ha l'endpoint della piattaforma agent. Cloud SQL utilizza questo endpoint per accedere al modello LLM ospitato in Agent Platform.

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

      Per trovare questo indirizzo email, utilizza il comando gcloud sql instances describe: 

      gcloud sql instances describe INSTANCE_NAME | grep EmailAddress

      Sostituisci INSTANCE_NAME con il nome dell'istanza Cloud SQL.

  8. Concedi i seguenti privilegi a qualsiasi utente del database MySQL che deve effettuare richieste alla piattaforma dell'agente:

    • SELECT ON mysql.*
    • EXECUTE ON mysql.*

    Per impostazione predefinita, qualsiasi utente con il ruolo cloudsqlsuperuser dispone di questi privilegi o può creare un utente e concedere i privilegi richiesti. Per ulteriori informazioni sul ruolo cloudsqlsuperuser in Cloud SQL, consulta Privilegi utente MySQL 8.0 e Privilegi utente MySQL 8.4.

Abilitare l'integrazione del database con Agent Platform

Per attivare l'integrazione del database con Agent Platform, completa i seguenti passaggi:

  1. Crea o aggiorna un'istanza Cloud SQL in modo che possa integrarsi con Agent Platform.

    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 \
--edition=EDITION_NAME \
--enable-google-ml-integration

    Effettua le seguenti sostituzioni:

    • INSTANCE_NAME: il nome dell'istanza
    • DATABASE_VERSION: la versione del database per l'istanza
    • MACHINE_TYPE: il tipo di macchina per l'istanza
    • REGION_NAME: il nome della regione dell'istanza
    • EDITION_NAME: la versione Cloud SQL 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 \

    Se questo aggiornamento modifica un valore che richiede un riavvio, viene visualizzato un prompt per procedere con la modifica o annullarla.

    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, vedi Impostazioni delle istanze.

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

    • 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.
    • PASSWORD: la password per l'utente root.
    • MACHINE_TYPE: stringa enum del tipo di macchina (livello), ad esempio db-custom-[CPUS]-[MEMORY_MBS]. Per ulteriori informazioni, vedi Livelli di macchine.
    • EDITION_TYPE: la tua versione di Cloud SQL, ad esempio ENTERPRISE.

    Devi includere anche l'oggetto enableGoogleMlIntegration nella richiesta. Imposta i seguenti parametri, se necessario:

    • enableGoogleMlIntegration: quando questo parametro è impostato su true, le istanze Cloud SQL possono connettersi ad Agent Platform per inoltrare richieste di previsioni in tempo reale e insight all'AI.
    • cloudsql.enable_google_ml_integration: quando questo parametro è impostato su on, Cloud SQL può integrarsi con Agent Platform.

    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 prompt per procedere con la modifica o annullarla.

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

    • 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, vedi Impostazioni delle istanze.

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

    • 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.
    • PASSWORD: la password per l'utente root.
    • MACHINE_TYPE: stringa enum del tipo di macchina (livello), ad esempio db-custom-[CPUS]-[MEMORY_MBS]. Per ulteriori informazioni, vedi Livelli di macchine.
    • EDITION_TYPE: la tua versione di Cloud SQL, ad esempio ENTERPRISE.

    Devi includere anche l'oggetto enableGoogleMlIntegration nella richiesta. Imposta i seguenti parametri, se necessario:

    • enableGoogleMlIntegration: quando questo parametro è impostato su true, le istanze Cloud SQL possono connettersi ad Agent Platform per inoltrare richieste di previsioni in tempo reale e insight all'AI.
    • cloudsql.enable_google_ml_integration: quando questo parametro è impostato su on, Cloud SQL può integrarsi con Agent Platform.

    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 prompt per procedere con la modifica o annullarla.

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

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

Risoluzione dei problemi

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

Problema Risoluzione dei problemi
Messaggio di errore: Google ML integration API is supported only on MySQL version 8.0.36 or above. Per abilitare l'integrazione della piattaforma di agenti in Cloud SQL, devi disporre di un database Cloud SQL per MySQL, versione 8.0.36 o successive. Per eseguire l'upgrade del database a questa versione, vedi Esegui l'upgrade della versione secondaria del database.
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 della tua istanza, non puoi attivare l'integrazione della piattaforma dell'agente in Cloud SQL. Esegui l'upgrade del tipo di macchina a core dedicato. Per saperne di più, consulta Tipo di macchina.
Messaggio di errore: Google ML Integration is unsupported for this maintenance version. Please follow https://cloud.google.com/sql/docs/mysql/self-service-maintenance to update the maintenance version of the instance. Per attivare l'integrazione della piattaforma dell'agente 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 Agent Platform.

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 Agent Platform 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: Agent Platform 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 Agent Platform non è abilitata. Per saperne di più su come abilitare questa API, vedi Abilitare l'integrazione del database con Agent Platform.
Messaggio di errore: Permission 'aiplatform.endpoints.predict' denied on resource. Le autorizzazioni della piattaforma dell'agente non vengono aggiunte al account di servizio Cloud SQL per il progetto in cui si trova l'istanza Cloud SQL. Per ulteriori informazioni sull'aggiunta di queste autorizzazioni al account di servizio, consulta Concedere al account di servizio Cloud SQL le autorizzazioni Identity and Access Management (IAM) per accedere alla piattaforma Agent.
Messaggio di errore: Publisher Model `projects/PROJECT_ID/locations/REGION_NAME/publishers/google/models/MODEL_NAME` not found. Il modello di machine learning o il LLM non esiste in Agent Platform.
Messaggio di errore: Resource exhausted: grpc: received message larger than max. Le dimensioni della richiesta che Cloud SQL trasmette ad Agent Platform superano il limite gRPC di 4 MB per richiesta.
Messaggio di errore: Cloud SQL attempts to send a request to Agent Platform. However, the instance is in the %s region, but the Agent Platform endpoint is in the %s region. Make sure the instance and endpoint are in the same region. Cloud SQL tenta di inviare una richiesta alla piattaforma dell'agente. Tuttavia, l'istanza si trova in una regione, mentre l'endpoint Agent Platform si trova in un'altra regione. Per risolvere il problema, sia l'istanza che l'endpoint devono trovarsi nella stessa regione.
Messaggio di errore: The Agent Platform endpoint isn't formatted properly. L'endpoint di Agent Platform non è formattato correttamente. Per saperne di più, consulta Utilizzo di 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 trasmette ad Agent Platform supera il limite di 1500 richieste al minuto per regione per modello per progetto.
Messaggio di errore: execute command denied to user DB_USER for routine 'mysql.ml_embedding'. L'utente del database MySQL non dispone dei privilegi necessari per chiamare la funzione mysql.ml_embedding. Consulta le sovvenzioni richieste.

Passaggi successivi