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 SQL Server 2025.

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 SQL com a função gerar embeddings para consultar seus modelos.

Você usa a função de geração de embeddings para que o modelo de embedding possa traduzir comandos de texto em vetores numéricos. Em seguida, é possível aplicar esses embeddings de vetores como entradas para tipos de dados vetoriais. Para mais informações, consulte a documentação da Microsoft sobre Pesquisa de vetores e índices de vetores no mecanismo de banco de dados SQL.

Para mais informações sobre a Vertex AI, consulte Introdução à Vertex AI.

Edições e versões de banco de dados compatíveis

A integração da Vertex AI é compatível com as edições do Cloud SQL Enterprise Plus e do Cloud SQL Enterprise e com todas as versões de banco de dados do SQL Server 2025.

Tipos de modelo compatíveis

A integração da Vertex AI com o Cloud SQL é compatível com endpoints de modelo das seguintes fontes:

  • Vertex AI
  • Hugging face
  • OpenAI

Antes de começar

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

  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. Ative as APIs 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 o seguinte:

      • API Cloud SQL Admin
      • API Vertex AI
      • API Compute Engine
      • Opcional: se você estiver usando um modelo de terceiros, a API Secret Manager será necessária.
    5. Depois de selecionar cada API, clique em Ativar.

    gcloud

    1. Abra o Cloud Shell, que oferece 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 \
  aiplatform.googleapis.com \
  compute.googleapis.com \
  secretmanager.googleapis.com
      3. Esse comando ativa as seguintes APIs:
      • API Cloud SQL Admin
      • API Vertex AI
      • API Compute Engine
      • Opcional: se você estiver usando um modelo de terceiros, a API Secret Manager será necessária.

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

    8. gcloud

    Para adicionar as 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: 

      gcloud sql instances describe INSTANCE_NAME | grep EmailAddress

      Substitua INSTANCE_NAME pelo nome da instância do Cloud SQL.

  8. Verifique se o usuário do Cloud SQL que está trabalhando com os modelos de incorporação tem as seguintes permissões de banco de dados:
    • Para permitir que um usuário do banco de dados crie ou modifique modelos, conceda ao usuário do Cloud SQL a permissão EXECUTE nos seguintes procedimentos armazenados:
      • [msdb].gcloudsql_ml_create_external_model: cria um objeto de modelo externo que contém o local, o método de autenticação e a finalidade de um endpoint de inferência de modelo de IA.
      • [msdb].gcloudsql_ml_alter_external_model: permite modificar o objeto do modelo externo.
      • [msdb].gcloudsql_ml_drop_external_model: remove o objeto do modelo externo do banco de dados.
    • Para chamar os procedimentos armazenados listados anteriormente, você precisa das seguintes permissões no banco de dados de destino:
      • CREATE EXTERNAL MODEL
      • ALTER EXTERNAL MODEL

      • Para saber como conceder essas permissões, consulte a documentação da Microsoft sobre o comando e a nomenclatura Criar modelo externo.

      Para informações sobre as permissões de superusuário do Cloud SQL, consulte Sobre usuários e procedimentos armazenados do SQL Server.

  9. Se você quiser usar um modelo externo de terceiros, precisará ter uma chave de API válida para o modelo armazenada em um local do Secret Manager acessível à instância do Cloud SQL.
  10. Se você estiver usando um modelo externo de terceiros, a instância do Cloud SQL precisará usar um endereço IP público. As instâncias de IP particular não podem acessar modelos externos de terceiros. O acesso a serviços particulares e o Private Service Connect só são compatíveis com a integração da Vertex AI.

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

    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, como SQLSERVER_2025_ENTERPRISE.
    • MACHINE_TYPE: o tipo de máquina da instância, como db-perf-optimized-N-8..
    • REGION_NAME: a região da instância, como us-central1.

    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

    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 projeto 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 tipo enumerado da versão do banco de dados, como SQLSERVER_2025_ENTERPRISE.
    • PASSWORD: a senha do usuário root do banco de dados.
    • MACHINE_TYPE: string de tipo enumerado do tipo de máquina (camada), como db-custom-[CPUS]-[MEMORY_MBS]. Para mais informações, consulte Níveis de máquina.
    • EDITION_TYPE: sua edição do Cloud SQL, como ENTERPRISE.

    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.

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

    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 projeto Google Cloud que contém a instância
    • INSTANCE_NAME: 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,
    
   }
}

    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 projeto 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 tipo enumerado da versão do banco de dados, como SQLSERVER_2025_ENTERPRISE.
    • PASSWORD: a senha do usuário root do banco de dados.
    • MACHINE_TYPE: string de tipo enumerado do tipo de máquina (camada), como db-custom-[CPUS]-[MEMORY_MBS]. Para mais informações, consulte Níveis de máquina.
    • EDITION_TYPE: sua edição do Cloud SQL, como ENTERPRISE.

    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.

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

    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 projeto Google Cloud que contém a instância
    • INSTANCE_NAME: 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,
    
   }
}

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

Adicionar permissões do Secret Manager

Se você quiser usar um modelo de uma fonte externa, como OpenAI ou Hugging Face, armazene a chave de API da fonte do modelo no Secret Manager.

Em seguida, você precisa dar à instância do Cloud SQL acesso à chave de API da fonte do modelo no Secret Manager. Para ter acesso, execute o seguinte comando:


SA_NAME=$(gcloud sql instances describe INSTANCE_NAME --format="value(serviceAccountEmailAddress)");

gcloud secrets add-iam-policy-binding SECRET_NAME \
    --member="serviceAccount:${SA_NAME}" \
    --role="roles/secretmanager.secretAccessor"

Substitua:

  • INSTANCE_NAME: o nome da instância do Cloud SQL.
  • SECRET_NAME: o nome do secret usado no Secret Manager.

Objetos de modelo externo

Para acessar um modelo de uma fonte externa, crie um objeto de modelo para o SQL Server usar. O Cloud SQL oferece três procedimentos armazenados que permitem criar, alterar e excluir um objeto de modelo externo:

  • gcloudsql_ml_create_external_model
  • gcloudsql_ml_alter_external_model
  • gcloudsql_ml_drop_external_model

Criar um modelo externo

Para criar um modelo, execute o procedimento armazenado gcloudsql_ml_create_external_model encontrado no banco de dados msdb:

EXECUTE [msdb].[dbo].[gcloudsql_ml_create_external_model]
@db = [DB_NAME],
@model_name = MODEL_NAME,
@model_provider = 'MODEL_PROVIDER',
@model = 'MODEL',
@model_url = MODEL_URL,
@secret_url = SECRET_URL

Substitua:

  • DB_NAME: o banco de dados de destino em que você quer criar o modelo externo.
  • MODEL_NAME: o nome do novo modelo externo.
  • MODEL_PROVIDER: o nome do provedor do modelo, como um dos seguintes:
    • Vertex AI
    • OpenAI
    • Hugging face
  • MODEL_URL: o URL do endpoint do modelo.
  • MODEL: o modelo de IA que está sendo invocado. Por exemplo, gemini-embedding-002.
  • SECRET_URL: se a Vertex AI for o provedor do modelo, esse parâmetro precisará estar vazio. Se você estiver usando um modelo externo, esse valor precisará fazer referência ao local da chave de API no Secret Manager. Um exemplo de URL usa o seguinte formato: 
        https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_NAME/versions/VERSION

    Substitua:

    • PROJECT_ID: o ID do projeto em que o secret está localizado.
    • SECRET_NAME: o nome do secret usado no Secret Manager.
    • VERSION: o número da versão do secret.

Alterar um modelo externo

Para alterar um objeto de modelo externo, execute o procedimento armazenado gcloudsql_ml_alter_external_model encontrado no banco de dados msdb:

EXECUTE [msdb].[dbo].[gcloudsql_ml_alter_external_model]
@db = [DB_NAME],
@model_name = MODEL_NAME,
@model_provider = 'MODEL_PROVIDER',
@model = 'MODEL',
@model_url = MODEL_URL,
@secret_url = SECRET_URL

Substitua:

  • DB_NAME: o banco de dados de destino em que o modelo que você quer modificar está.
  • MODEL_NAME: o nome do modelo atual.
  • MODEL_PROVIDER: o nome do provedor do modelo, como um dos seguintes:
    • Vertex AI
    • OpenAI
    • Hugging face
  • MODEL_URL: o URL do endpoint do modelo.
  • MODEL: o modelo de IA que está sendo invocado. Por exemplo, gemini-embedding-001.
  • SECRET_URL: se a Vertex AI for o provedor do modelo, esse parâmetro precisa estar vazio. Se você estiver usando um modelo externo, esse valor precisará fazer referência ao local da chave de API no Secret Manager. Um exemplo de URL usa o seguinte formato: 
        https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_NAME/versions/VERSION

    Substitua:

    • PROJECT_ID: o ID do projeto em que o secret está localizado.
    • SECRET_NAME: o nome do secret usado no Secret Manager.
    • VERSION: o número da versão do secret.

Desativar a integração com a Vertex AI

Para desativar a integração da Vertex AI em uma instância do Cloud SQL, execute o seguinte:

gcloud sql instances patch [instance-name] --no-enable-google-ml-integration

Substitua INSTANCE_NAME pelo nome da instância do Cloud SQL.

Remover um modelo externo no SQL Server

Para excluir um modelo externo do SQL Server, execute o procedimento armazenado gcloudsql_ml_drop_external_model encontrado no banco de dados msdb:

EXECUTE [msdb].[dbo].[gcloudsql_ml_drop_external_model]
@db = [DB_NAME],
@model_name = MODEL_NAME

Substitua:

  • DB_NAME: o banco de dados de destino em que o modelo externo que você quer remover existe.
  • MODEL_NAME: o nome do modelo externo a ser descartado.

Invocar um modelo externo

Depois que a integração da Vertex AI for ativada na instância do Cloud SQL e um objeto de modelo for criado para uso do SQL Server, será possível invocar a função AI_GENERATE_EMBEDDINGS do SQL Server para criar embeddings de vetor para seus dados.

Para criar embeddings de vetores usando o modelo externo, execute o seguinte comando:

SELECT AI_GENERATE_EMBEDDINGS(N'Test Text' USE MODEL MODEL_NAME)

Substitua MODEL_NAME pelo nome do modelo que você quer usar.

O usuário principal de execução precisa ter recebido permissões EXECUTE ON EXTERNAL MODEL usando uma função ou concessão adequada.

Para mais informações, consulte a documentação da Microsoft sobre Concessões de modelo externo.

Restrições de tamanho do modelo

Alguns modelos, como o gemini-embedding-01, têm dimensões de saída padrão maiores do que o SQL Server pode oferecer para vetores float32, que têm um máximo de 1.998 dimensões. Quando necessário, use float16 (um recurso de prévia da Microsoft) para o tipo de base vetorial, que oferece um máximo de 3.996 dimensões vetoriais, ou forneça o parâmetro "dimensions" na solicitação AI_GENERATE_EMBEDDINGS para reduzir a dimensionalidade.

Para mais informações, consulte Suporte a ponto flutuante de meia precisão no tipo de dados de vetor.

Por exemplo, consulte:

DECLARE @params JSON = N'{"dimensions": "DIMENSIONS"}';
SELECT AI_GENERATE_EMBEDDINGS('This article introduces AI concepts.' USE MODEL MODEL_NAME PARAMETERS @params)

Substitua:

  • DIMENSIONS: as dimensões que você quer usar no modelo, como 1536. Esse valor é aceito como uma string.
  • MODEL_NAME: o nome do modelo que você quer usar.

Resolver problemas

Confira abaixo algumas mensagens de erro que você pode receber:

Contexto Erro ou mensagem recebida Possível causa
Procedimento CREATE/ALTER "O provedor de modelo especificado não é válido." Um provedor de modelo incompatível foi informado.
Procedimento CREATE/ALTER "O URL secreto especificado não é válido para este provedor de modelo." Para a Vertex AI, o URL secreto precisa estar vazio. Para outros provedores de modelos, o URL secreto não pode ficar vazio.
Procedimento CREATE/ALTER/DROP "O nome do modelo especificado não é válido." O nome do modelo é um campo obrigatório.
Procedimento CREATE/ALTER "O URL do modelo especificado não é válido." O URL do modelo é um campo obrigatório.
Procedimento CREATE/ALTER/DROP "O nome do banco de dados especificado não é válido." Um nome de banco de dados válido é um campo obrigatório.
AI_GENERATE_EMBEDDINGS chamada Vários códigos de erro, incluindo 400, 403, 404, 405 e 500. Se você tiver problemas ao tentar executar a função AI_GENERATE_EMBEDDINGS, somente códigos de erro serão retornados. Essa é uma limitação conhecida da Microsoft.
AI_GENERATE_EMBEDDINGS chamada "A resposta HTTP não contém um JSON válido." Um código de erro que pede para você tentar de novo, como 429 ou 500, foi retornado pelo agente de aprendizado de máquina. No entanto, o cliente recebe esta mensagem de texto. Essa é uma limitação conhecida da Microsoft.

Códigos de erro

A função AI_GENERATE_EMBEDDINGS fornece apenas códigos de erro, não mensagens. A tabela a seguir lista possíveis causas para alguns códigos de erro:

Código do erro Possível causa
400 Bad Request
  • Tipo de modelo incompatível.
  • Payload JSON malformado.
  • URL inválido para o tipo de modelo.
401 Unauthorized O modelo de terceiros não tem uma chave de API válida.
403 Forbidden
  • A instância do Cloud SQL não tem as permissões adequadas para acessar a Vertex AI.
  • A instância do Cloud SQL não tem as permissões adequadas para acessar o Secret Manager.
  • A chave de API não concede permissão ao modelo de terceiros especificado.
  • A Vertex AI não está ativada no projeto.
404 Not Found
  • O secret_url especificado não existe.
  • O model_url especificado não existe.
405 Method Not Allowed Um método diferente de POST foi fornecido.
413 Request Body Too Large O tamanho da solicitação é maior do que o limite de 1 MB.
429 Too Many Requests Erro de esgotamento do provedor de modelo.
500 Internal Server Error
  • Erros não especificados do provedor de modelos.
  • Resposta inesperada do provedor do modelo.

A seguir