Integrar o Cloud SQL à Vertex AI

Nesta página, descrevemos como integrar o Cloud SQL à Vertex AI. Essa integração permite aplicar modelos de linguagem grandes (LLMs), hospedados na Vertex AI, a um banco de dados do Cloud SQL para PostgreSQL, versão 12 em diante.

Ao integrar o Cloud SQL com a Vertex AI, é possível aplicar o poder semântico e preditivo dos modelos de machine learning (ML) aos seus dados. Essa integração estende a sintaxe do PostgreSQL com duas funções para consultar modelos:

  • Invoque previsões para chamar um modelo usando SQL em uma transação.
  • Gerar embeddings para que um modelo de embedding traduza comandos de texto em vetores numéricos. Em seguida, é possível aplicar esses embeddings de vetores como entradas para funções pgvector. Isso inclui métodos para comparar e classificar amostras de texto de acordo com a distância semântica relativa.

Como resultado, é possível fazer previsões em tempo real e obter insights valiosos diretamente no banco de dados, simplificando seus fluxos de trabalho e aprimorando sua capacidade de tomada de decisão.

Para mais informações sobre a Vertex AI, consulte Introdução à 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.

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

    Console

    1. Ir para a página APIs e serviços.
    2. Selecione um projeto na lista.
    3. Se a Biblioteca de APIs não estiver aberta, selecione Biblioteca no menu de navegação.

    4. Clique nas APIs que você quer ativar. Para este procedimento, ative a API Cloud SQL Admin e a API Vertex AI.

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

    gcloud

    1. Abra o Cloud Shell, que fornece acesso de linha de comando aos seus recursos do Google Cloud diretamente no 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. Esse comando ativa as seguintes APIs:
      • API Cloud SQL Admin
      • API Vertex AI

  7. Conceder à conta de serviço do Cloud SQL permissões de Identity and Access Management (IAM) para acessar a Vertex AI.

    gcloud

    Para adicionar permissões da Vertex AI à conta de serviço do Cloud SQL do projeto em que 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 endpoint da Vertex AI. O Cloud SQL usa esse endpoint para acessar o LLM hospedado na Vertex AI.

    • SERVICE_ACCOUNT_EMAIL: o endereço de e-mail da conta de serviço do Cloud SQL.

      Para encontrar esse endereço de e-mail, use o comando gcloud sql instances describe INSTANCE_NAME e substitua INSTANCE_NAME pelo nome da instância do Cloud SQL. O valor que aparece ao lado do parâmetro serviceAccountEmailAddress é o endereço de e-mail.

Ativar a integração de bancos de dados com a Vertex AI

Para ativar a integração do banco de dados com a Vertex AI, siga estas etapas:

  1. Criar ou atualizar uma instância do Cloud SQL para que ela possa se integrar à Vertex AI.

    gcloud

    Criar 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 \
--enable-google-ml-integration \
--database-flags cloudsql.enable_google_ml_integration=on

    Faça as seguintes substituições:

    • INSTANCE_NAME: o nome da instância
    • DATABASE_VERSION: a versão do banco de dados para a instância (por exemplo, POSTGRES_13)
    • MACHINE_TYPE: o tipo de máquina da instância
    • REGION_NAME: o nome da região da instância

    Atualizar 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 \
--database-flags cloudsql.enable_google_ml_integration=on

    Se essa atualização modificar um valor que requer reinicialização, você verá uma solicitação para prosseguir com a mudança ou cancelar.

    REST v1

    Criar instância

    Use este exemplo para criar a instância. Para uma lista completa de parâmetros dessa chamada, consulte a página instances:insert. Para informações sobre configurações da instância, incluindo valores válidos para região, consulte Configurações da instância.

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID ou número do projeto do Google Cloud 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 de enumeração da versão do banco de dados (por exemplo: POSTGRES_13)
    • PASSWORD: a senha do usuário root
    • MACHINE_TYPE: string de tipo enumerado do tipo de máquina (camada), como: db-custom-[CPUS]-[MEMORY_MBS]
    • EDITION_TYPE: sua edição do Cloud SQL

    Você também precisa incluir o objeto enableGoogleMlIntegration na solicitação. Defina os seguintes parâmetros, conforme necessário:

    • enableGoogleMlIntegration: quando o parâmetro é definido como true, as instâncias do Cloud SQL podem se conectar à Vertex AI para transmitir solicitações de previsões em tempo real e insights para a IA.
    • cloudsql.enable_google_ml_integration: quando esse parâmetro é definido como on, o Cloud SQL pode se integrar à Vertex AI

    Método HTTP e URL: 

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

    Corpo JSON da solicitação:

    {
  "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 a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

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

    Atualizar a instância

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

    Se essa atualização modificar um valor que requer reinicialização, você verá uma solicitação para prosseguir com a mudança ou cancelar.

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID ou número do projeto do Google Cloud 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 da solicitação:

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

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

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

    Criar instância

    Use este exemplo para criar a instância. Para uma lista completa de parâmetros dessa chamada, consulte a página instances:insert. Para informações sobre configurações da instância, incluindo valores válidos para região, consulte Configurações da instância.

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID ou número do projeto do Google Cloud 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 de enumeração da versão do banco de dados (por exemplo: POSTGRES_13)
    • PASSWORD: a senha do usuário root
    • MACHINE_TYPE: string de tipo enumerado do tipo de máquina (camada), como: db-custom-[CPUS]-[MEMORY_MBS]
    • EDITION_TYPE: sua edição do Cloud SQL

    Você também precisa incluir o objeto enableGoogleMlIntegration na solicitação. Defina os seguintes parâmetros, conforme necessário:

    • enableGoogleMlIntegration: quando o parâmetro é definido como true, as instâncias do Cloud SQL podem se conectar à Vertex AI para transmitir solicitações de previsões em tempo real e insights para a IA.
    • cloudsql.enable_google_ml_integration: quando esse parâmetro é definido como on, o Cloud SQL pode se integrar à Vertex AI

    Método HTTP e URL: 

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

    Corpo JSON da solicitação:

    {
  "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 a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

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

    Atualizar a instância

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

    Se essa atualização modificar um valor que requer reinicialização, você verá uma solicitação para prosseguir com a mudança ou cancelar.

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • PROJECT_ID: o ID ou número do projeto do Google Cloud 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 da solicitação:

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

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

    {
  "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. Instale a extensão google_ml_integration em um banco de dados da instância principal do Cloud SQL. Esse banco de dados contém dados sobre os quais você quer executar previsões.
    1. Conecte um cliente psql à instância principal, conforme descrito em Conectar usando um cliente psql.
    2. No prompt de comando psql, conecte-se ao banco de dados: 
      \c DB_NAME

      Substitua DB_NAME pelo nome do banco de dados em que você quer instalar a extensão.

    3. Instalar a extensão: 
      CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;

Resolver problemas

Esta seção contém informações sobre problemas associados à integração do Cloud SQL com a Vertex AI, além de etapas para solucionar os problemas.

Problema Solução de problemas
Mensagem de erro: Google ML integration API is supported only on Postgres version 12 or above. Para ativar a integração da Vertex AI no Cloud SQL, você precisa ter um banco de dados do Cloud SQL para PostgreSQL versão 12 ou mais recente. Para fazer upgrade do banco de dados para esta versão, consulte Fazer upgrade da versão principal do banco de dados no local.
Mensagem de erro: Google ML Integration API is not supported on shared core instance. Please upsize your machine type. Se você selecionou um núcleo compartilhado para o tipo de máquina da sua instância, não vai ser possível ativar a integração da Vertex AI no Cloud SQL. Faça upgrade do seu tipo de máquina para o núcleo dedicado. Para mais informações, consulte Tipo de máquina.
Mensagem de erro: 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. Para ativar a integração da Vertex AI no Cloud SQL, a versão de manutenção da instância precisa ser R20240130 ou posterior. Se quiser fazer upgrade da instância para esta versão, consulte Manutenção de autoatendimento.
Mensagem de erro: Cannot invoke ml_predict_row if 'cloudsql.enable_google_ml_integration' is off. A flag do banco de dados cloudsql.enable_google_ml_integration está desativada. Não é possível integrar o Cloud SQL à Vertex AI.

Para ativar essa sinalização, 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 a Vertex AI não está ativada. Para ativar essa integração, use ogcloud sql instances patch comando:

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

Substituir 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 essa API, consulte Ativar a integração do banco de dados com a Vertex AI.
Mensagem de erro: Permission 'aiplatform.endpoints.predict' denied on resource. As permissões da Vertex AI não são adicionadas à conta de serviço do Cloud SQL para o projeto em que a instância do Cloud SQL está localizada. Para mais informações sobre como adicionar essas permissões à conta de serviço, consulte Ativar a integração do banco de dados com a Vertex AI.
Mensagem de erro: Publisher Model `projects/PROJECT_ID/locations/REGION_NAME/publishers/google/models/MODEL_NAME` not found. O modelo de machine learning ou o LLM não existe na Vertex AI.
Mensagem de erro: Resource exhausted: grpc: received message larger than max. O tamanho da solicitação que o Cloud SQL transmite para a Vertex AI excede o limite gRPC de 4 MB por solicitação.
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 uma solicitação para a Vertex AI. No entanto, a instância está em uma região, mas o endpoint da Vertex AI está em outra região. Para resolver esse problema, a instância e o endpoint precisam estar na mesma região.
Mensagem de erro: The Vertex AI endpoint isn't formatted properly. O endpoint da Vertex AI não está formatado corretamente. Para mais informações, consulte Usar endpoints particulares para previsão on-line.
Mensagem de erro: Quota exceeded for aiplatform.googleapis.com/online_prediction_requests_per_base_model with base model: textembedding-gecko. O número de solicitações que o Cloud SQL transmite para a Vertex AI excede o limite de 1.500 solicitações por minuto, região, modelo e projeto.

A seguir