Integre o Cloud SQL com o Vertex AI

Esta página descreve como integrar o Cloud SQL com a Vertex AI. Esta integração permite-lhe aplicar modelos de linguagem de grande dimensão (LLMs), alojados no Vertex AI, a uma base de dados do Cloud SQL para MySQL, versão 8.0.36 e posteriores.

Ao integrar o Cloud SQL com a Vertex AI, pode aplicar o poder semântico e preditivo dos modelos de aprendizagem automática (AA) aos seus dados. Esta integração expande a sintaxe SQL com duas funções para consultar modelos:

  • Invocar previsões para chamar um modelo através de SQL numa transação.
  • Gere incorporações para que um modelo de incorporação traduza comandos de texto em vetores numéricos. Em seguida, pode aplicar estas incorporações vetoriais como entradas para as funções vector. Isto inclui métodos para comparar e ordenar amostras de texto de acordo com a respetiva distância semântica relativa.

Como resultado, pode fazer previsões em tempo real e obter estatísticas valiosas diretamente na base de dados, simplificando os seus fluxos de trabalho e melhorando as suas capacidades de tomada de decisões.

Para mais informações sobre o Vertex AI, consulte o artigo Introdução ao Vertex AI.

Antes de começar

  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.

    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 (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 (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. Ative as Google Cloud APIs necessárias.

    Consola

    1. Aceda à página APIs e serviços.
    2. Na lista de projetos, selecione o seu projeto.
    3. Se a biblioteca de APIs não estiver aberta, no menu de navegação, selecione Biblioteca.
    4. Clique nas APIs que quer ativar. Para este procedimento, ative a API Admin do Cloud SQL e a API Vertex AI.

    5. Depois de selecionar cada API, clique em Ativar.

    gcloud

    1. Abra a Cloud Shell, que dá acesso à linha de comandos aos seus Google Cloud recursos diretamente a partir do navegador.
    2. Para ativar as APIs necessárias, use o comando gcloud services enable:
      gcloud services enable sqladmin.googleapis.com \
      enable aiplatform.googleapis.com
    3. Este comando ativa as seguintes APIs:
      • API Cloud SQL Admin
      • API Vertex AI

  7. Conceda à conta de serviço do Cloud SQL autorizações da gestão de identidade e de acesso (IAM) para aceder ao Vertex AI.

    gcloud

    Para adicionar as autorizações do Vertex AI à conta de serviço do Cloud SQL para o projeto onde a instância do Cloud SQL está localizada, use o comando gcloud projects add-iam-policy-binding:

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

    Faça as seguintes substituições:
    • PROJECT_ID: o ID do projeto que tem o ponto final do Vertex AI. O Cloud SQL usa este ponto final para aceder ao MDG alojado no Vertex AI.
    • SERVICE_ACCOUNT_EMAIL: o endereço de email da conta de serviço do Cloud SQL.

      Para encontrar este endereço de email, use o comando gcloud sql instances describe INSTANCE_NAME e substitua INSTANCE_NAME pelo nome da instância do Cloud SQL. O valor apresentado junto ao parâmetro serviceAccountEmailAddress é o endereço de email.

  8. Ative a integração da base de dados com o Vertex AI

    Para ativar a integração da base de dados com o Vertex AI, conclua os seguintes passos:

    1. Crie ou atualize uma instância do Cloud SQL para que a instância possa ser integrada com o Vertex AI.

      gcloud

      Crie a instância

      Para criar a instância do Cloud SQL, use o 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

      Faça as seguintes substituições:

      • INSTANCE_NAME: o nome da instância
      • DATABASE_VERSION: a versão da base de dados para a instância
      • MACHINE_TYPE: o tipo de máquina da instância
      • REGION_NAME: o nome da região da instância
      • EDITION_NAME: a edição do Cloud SQL para a instância

      Atualize a instância

      Para atualizar a instância, use o comando gcloud sql instances patch.

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

      Se esta atualização modificar um valor que requer um reinício, é apresentada uma mensagem para continuar com a alteração ou cancelar.

      REST v1

      Crie a instância

      Use este exemplo para criar a instância. Para ver uma lista completa dos parâmetros desta chamada, consulte a página instances:insert. Para informações sobre as definições de instâncias, incluindo valores válidos para uma região, consulte o artigo Definições de instâncias.

      Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

      • PROJECT_ID: o ID ou o número do projeto do Google Cloud projeto que contém a instância
      • INSTANCE_NAME: o nome da instância
      • REGION_NAME: o nome da região da instância
      • DATABASE_VERSION: string enum da versão da base de dados (por exemplo: POSTGRES_13)
      • PASSWORD: a palavra-passe do utilizador root
      • MACHINE_TYPE: string enum do tipo de máquina (nível), como: db-custom-[CPUS]-[MEMORY_MBS]
      • EDITION_TYPE: a sua edição do Cloud SQL

      Também tem de incluir o objeto enableGoogleMlIntegration no pedido. Defina os seguintes parâmetros, conforme necessário:

      • enableGoogleMlIntegration: quando este parâmetro está definido como true, as instâncias do Cloud SQL podem ligar-se à Vertex AI para transmitir pedidos de previsões em tempo real e estatísticas à IA
      • cloudsql.enable_google_ml_integration: quando este parâmetro está definido como on, o Cloud SQL pode integrar-se com a Vertex AI

      Método HTTP e URL:

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

      Corpo JSON do pedido:

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

      Para enviar o seu pedido, expanda uma destas opções:

      Deve receber uma resposta JSON semelhante à seguinte:

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

      Atualize a instância

      Use este exemplo para atualizar a instância. Para ver uma lista completa de parâmetros para esta chamada, consulte a página instances.patch.

      Se esta atualização modificar um valor que requer um reinício, é apresentada uma mensagem para continuar com a alteração ou cancelar.

      Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

      • PROJECT_ID: o ID ou o número do projeto do Google Cloud projeto que contém a instância
      • INSTANCE_NAME: o nome da instância

      Método HTTP e URL:

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

      Corpo JSON do pedido:

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

      Para enviar o seu pedido, expanda uma destas opções:

      Deve receber uma resposta JSON semelhante à seguinte:

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

      Crie a instância

      Use este exemplo para criar a instância. Para ver uma lista completa dos parâmetros desta chamada, consulte a página instances:insert. Para informações sobre as definições de instâncias, incluindo valores válidos para uma região, consulte o artigo Definições de instâncias.

      Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

      • PROJECT_ID: o ID ou o número do projeto do Google Cloud projeto que contém a instância
      • INSTANCE_NAME: o nome da instância
      • REGION_NAME: o nome da região da instância
      • DATABASE_VERSION: string enum da versão da base de dados (por exemplo: POSTGRES_13)
      • PASSWORD: a palavra-passe do utilizador root
      • MACHINE_TYPE: string enum do tipo de máquina (nível), como: db-custom-[CPUS]-[MEMORY_MBS]
      • EDITION_TYPE: a sua edição do Cloud SQL

      Também tem de incluir o objeto enableGoogleMlIntegration no pedido. Defina os seguintes parâmetros, conforme necessário:

      • enableGoogleMlIntegration: quando este parâmetro está definido como true, as instâncias do Cloud SQL podem ligar-se à Vertex AI para transmitir pedidos de previsões em tempo real e estatísticas à IA
      • cloudsql.enable_google_ml_integration: quando este parâmetro está definido como on, o Cloud SQL pode integrar-se com a Vertex AI

      Método HTTP e URL:

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

      Corpo JSON do pedido:

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

      Para enviar o seu pedido, expanda uma destas opções:

      Deve receber uma resposta JSON semelhante à seguinte:

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

      Atualize a instância

      Use este exemplo para atualizar a instância. Para ver uma lista completa de parâmetros para esta chamada, consulte a página instances.patch.

      Se esta atualização modificar um valor que requer um reinício, é apresentada uma mensagem para continuar com a alteração ou cancelar.

      Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

      • PROJECT_ID: o ID ou o número do projeto do Google Cloud projeto que contém a instância
      • INSTANCE_NAME: o nome da instância

      Método HTTP e URL:

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

      Corpo JSON do pedido:

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

      Para enviar o seu pedido, expanda uma destas opções:

      Deve receber uma resposta JSON semelhante à seguinte:

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

    Resolver problemas

    Esta secção contém informações sobre problemas associados à integração do Cloud SQL com a Vertex AI, juntamente com passos para resolver os problemas.

    Problema Resolução de problemas
    Mensagem de erro: Google ML integration API is supported only on MySQL version 8.0.36 or above. Para ativar a integração do Vertex AI no Cloud SQL, tem de ter uma base de dados do Cloud SQL para MySQL, versão 8.0.36 ou posterior. Para atualizar a base de dados para esta versão, consulte o artigo Atualize a versão secundária da base de dados.
    Mensagem de erro: Google ML Integration API is not supported on shared core instance. Please upsize your machine type. Se selecionou um núcleo partilhado para o tipo de máquina da sua instância, não pode ativar a integração do Vertex AI no Cloud SQL. Atualize o tipo de máquina para núcleo dedicado. Para mais informações, consulte o artigo Tipo de máquina.
    Mensagem de erro: 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. Para ativar a integração do Vertex AI no Cloud SQL, a versão de manutenção da sua instância tem de ser R20240130 ou posterior. Para atualizar a sua instância para esta versão, consulte o artigo Manutenção self-service.
    Mensagem de erro: Cannot invoke ml_predict_row if 'cloudsql.enable_google_ml_integration' is off. O cloudsql.enable_google_ml_integration indicador da base de dados está desativado. O Cloud SQL não pode ser integrado com o Vertex AI.

    Para ativar esta flag, use o comando gcloud sql instances patch:

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

    Substitua INSTANCE_NAME pelo nome da instância principal do Cloud SQL.
    Mensagem de erro: Failed to connect to remote host: Connection refused. A integração entre o Cloud SQL e o Vertex AI não está ativada. Para ativar esta integração, use o comando gcloud sql instances patch:

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


    Substitua INSTANCE_NAME pelo nome da instância principal do Cloud SQL.
    Mensagem de erro: 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. A API Vertex AI não está ativada. Para mais informações sobre como ativar esta API, consulte o artigo Ative a integração da base de dados com o Vertex AI.
    Mensagem de erro: Permission 'aiplatform.endpoints.predict' denied on resource. As autorizações da Vertex AI não são adicionadas à conta de serviço do Cloud SQL para o projeto onde a instância do Cloud SQL está localizada. Para mais informações sobre como adicionar estas autorizações à conta de serviço, consulte o artigo Ative a integração da base de dados com o Vertex AI.
    Mensagem de erro: Publisher Model `projects/PROJECT_ID/locations/REGION_NAME/publishers/google/models/MODEL_NAME` not found. O modelo de aprendizagem automática ou o GML não existe no Vertex AI.
    Mensagem de erro: Resource exhausted: grpc: received message larger than max. O tamanho do pedido que o Cloud SQL transmite à Vertex AI excede o limite de gRPC de 4 MB por pedido.
    Mensagem de erro: 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. O Cloud SQL tenta enviar um pedido para o Vertex AI. No entanto, a instância está numa região, mas o ponto final da Vertex AI está numa região diferente. Para resolver este problema, a instância e o ponto final têm de estar na mesma região.
    Mensagem de erro: The Vertex AI endpoint isn't formatted properly. O ponto final da Vertex AI não está formatado corretamente. Para mais informações, consulte o artigo Use pontos finais privados para a previsão online.
    Mensagem de erro: Quota exceeded for aiplatform.googleapis.com/online_prediction_requests_per_base_model with base model: textembedding-gecko. O número de pedidos que o Cloud SQL transmite ao Vertex AI excede o limite de 1500 pedidos por minuto por região por modelo por projeto.

    O que se segue?