Visão geral sobre como registrar e chamar modelos de IA remotos no Cloud SQL

Nesta página, descrevemos como registrar um endpoint de modelo de IA e invocar previsões com o gerenciamento de endpoints de modelo no Cloud SQL. Para usar modelos de IA em ambientes de produção, consulte Gerar e gerenciar embeddings de vetor.

Visão geral

Com o gerenciamento de endpoints de modelo, é possível registrar um endpoint de modelo, gerenciar metadados de endpoint de modelo na instância do Cloud SQL e interagir com os modelos usando consultas SQL. É possível usar esses modelos para gerar embeddings de vetor ou invocar previsões.

É possível registrar os seguintes tipos de modelos usando o gerenciamento de endpoints de modelo:

  • Modelos de embedding de texto da Vertex AI.
  • Modelos de embedding de texto hospedados de forma personalizada em redes dentro de Google Cloud.

  • Modelos genéricos com uma API baseada em JSON. Exemplos desses modelos:

    • O modelo gemini-flash do Model Garden da Vertex AI
    • O modelo open_ai para modelos da OpenAI
    • Modelos hospedados em redes no Google Cloud

Como funciona

É possível usar o gerenciamento de endpoints de modelo para registrar um endpoint que esteja em conformidade com o seguinte:

  • A entrada e a saída do modelo são compatíveis com o formato JSON.
  • Você pode usar o protocolo REST para chamar o modelo.

Quando você registra um endpoint de modelo com o gerenciamento de endpoints de modelo, ele registra cada endpoint com um ID de modelo exclusivo como referência ao modelo. Use esse ID para consultar modelos da seguinte forma:

  • Gere embeddings para traduzir comandos de texto em vetores numéricos. É possível armazenar os embeddings gerados como dados de vetor ao ativar o suporte a embeddings de vetor na sua instância. Para mais informações, consulte Ativar e desativar incorporações de vetores na sua instância.

  • Invoque previsões para chamar um modelo usando SQL em uma transação.

Para registrar e chamar modelos de IA remotos com sua instância do Cloud SQL, ela precisa estar instalada com a versão de manutenção MYSQL_VERSION.R20250531.01_14 ou mais recente. Se a instância estiver executando uma versão de manutenção anterior a MYSQL_VERSION.R20250531.01_14, só será possível usar as seguintes funções, conforme documentado na integração do Cloud SQL e da Vertex AI.

Para fazer upgrade da instância para a versão de manutenção MYSQL_VERSION.R20250531.01_14 ou mais recente, consulte Manutenção de autoatendimento. Depois de fazer upgrade da instância, você poderá usar as seguintes funções:

Além disso, é possível usar as seguintes funções com seu provedor de modelo registrado:

Privilégios de usuário do banco de dados necessários

Para registrar e chamar modelos remotos de IA, faça login como um usuário do banco de dados MySQL que recebeu os privilégios SELECT e EXECUTE em mysql.*.

Por padrão, qualquer usuário com a função cloudsqlsuperuser tem esses privilégios ou pode criar um usuário e conceder os privilégios necessários.

Para mais informações sobre a função cloudsqlsuperuser no Cloud SQL, consulte Privilégios de usuário do MySQL 8.0 e Privilégios de usuário do MySQL 8.4.

Principais conceitos

Antes de começar a usar o gerenciamento de endpoints de modelo, entenda os conceitos necessários para se conectar e usar os modelos.

Provedor de modelos

O provedor de modelos é o provedor de hospedagem de modelos aceito. A tabela a seguir mostra o valor do provedor de modelo que você precisa definir com base no provedor de modelo que você usa:

Provedor de modelos Definido na função como…
Vertex AI (inclui o Gemini) google
Anthropic anthropic
Hugging face hugging_face
OpenAI open_ai
Outros modelos hospedados fora da Vertex AI,
Anthropic, Hugging Face e OpenAI		 custom

O provedor de modelo padrão é custom.

Tipos de modelos

Os tipos de modelo são os tipos de modelo de IA. Ao registrar um endpoint de modelo, é possível definir os tipos de modelo text_embedding ou generic para o endpoint.

Se você usa a Vertex AI como provedor de modelos, não é necessário registrar um endpoint de modelo porque os endpoints são compatíveis automaticamente. Por padrão, com a Vertex AI, você usa o modelo text-embedding-005.

Outros modelos de embedding de texto
Para outros modelos de embedding de texto, é necessário criar funções de transformação para processar os formatos de entrada e saída compatíveis com o modelo. Se quiser, use a função de geração de cabeçalho HTTP que cria cabeçalhos personalizados exigidos pelo seu modelo.

O tipo de modelo para esses modelos é text_embedding.

Modelos genéricos
O gerenciamento de endpoints de modelos também permite o registro de todos os outros tipos de modelos, exceto os de embeddings de texto. Para invocar previsões de modelos genéricos, use a função mysql.ml_predict_row(). É possível definir metadados de endpoint do modelo, como um endpoint de solicitação e cabeçalhos HTTP específicos do seu modelo.
Não é possível transmitir funções de transformação ao registrar um endpoint de modelo genérico. Verifique se, ao invocar previsões, a entrada da função está no formato JSON e se você analisa a saída JSON para derivar a saída final.
O tipo de modelo para esses modelos é generic. Como generic é o tipo de modelo padrão, se você registrar endpoints de modelo para esse tipo, a definição do tipo de modelo será opcional.
Com a Vertex AI, o gerenciamento de endpoints de modelo inclui suporte pré-registrado para o modelo gemini-2.5-flash.

Métodos de autenticação

É possível ativar o suporte a embeddings de vetor na sua instância do Cloud SQL para MySQL e especificar diferentes métodos de autenticação para acessar o modelo. A definição desses métodos é opcional e só é necessária se você precisar se autenticar para acessar o modelo.

Para modelos da Vertex AI, a conta de serviço do Cloud SQL é usada para autenticação. Para outros modelos, a chave de API ou o token de acesso armazenado como um secreto no Secret Manager pode ser usado com a função SQL mysql.ml_create_sm_secret_registration().

A tabela a seguir mostra os métodos de autenticação que podem ser definidos:

Método de autenticação Definido na função como… Provedor de modelos
Agente de serviço do Cloud SQL auth_type_cloudsql_service_agent_iam Provedor da Vertex AI
Secret Manager auth_type_secret_manager Modelos hospedados fora da Vertex AI

Funções de previsão

mysql.ml_embedding()
Chama um endpoint de modelo de embedding de texto registrado para gerar embeddings. Ele inclui suporte integrado para todos os modelos de incorporação da Vertex AI.
Para modelos de embedding de texto sem suporte integrado, os parâmetros de entrada e saída são exclusivos de um modelo e precisam ser transformados para que a função chame o modelo. Crie uma função de transformação de entrada para transformar a entrada da função de previsão na entrada específica do modelo e uma função de transformação de saída para transformar a saída específica do modelo na saída da função de previsão.
mysql.ml_predict_row()
Chama um endpoint de modelo genérico registrado, se o endpoint for compatível com APIs baseadas em JSON para invocar previsões.

Funções de transformação

As funções de transformação modificam a entrada para um formato que o modelo entende e convertem a resposta do modelo para o formato esperado pela função de previsão. As funções de transformação são usadas ao registrar o endpoint do modelo text-embedding sem suporte integrado. A assinatura das funções de transformação depende da função de previsão para o tipo de modelo.

Não é possível usar funções de transformação ao registrar um endpoint de modelo generic.

A seguir, mostramos as assinaturas da função de previsão para modelos de incorporação de texto:

// define custom model specific input/output transform functions.
CREATE FUNCTION IF NOT EXISTS input_transform_function(model_id VARCHAR(100), input_text TEXT) RETURNS JSON DETERMINISTIC;

// the returned BLOB should be of type VECTOR
CREATE FUNCTION IF NOT EXISTS output_transform_function(model_id VARCHAR(100), response_json JSON) RETURNS BLOB DETERMINISTIC;

Para mais informações sobre como criar funções de transformação, consulte Exemplo de funções de transformação.

Função de geração de cabeçalho HTTP

A função de geração de cabeçalho HTTP gera a saída em pares de chave-valor JSON usados como cabeçalhos HTTP. A assinatura da função de previsão define as assinaturas da função de geração de cabeçalho.

O exemplo a seguir mostra a assinatura da função de previsão mysql.ml_embedding():

CREATE FUNCTION IF NOT EXISTS generate_headers(model_id VARCHAR(100), input TEXT) RETURNS JSON DETERMINISTIC;

Para a função de previsão mysql.ml_predict_row(), a assinatura é a seguinte:

CREATE FUNCTION IF NOT EXISTS generate_headers(model_id VARCHAR(100), input JSON) RETURNS JSON DETERMINISTIC;

Para mais informações sobre como criar uma função de geração de cabeçalho, consulte Exemplo de função de geração de cabeçalho.

Limitações

  • Ao executar qualquer uma das funções de registro de modelo ou gerenciamento de secrets, você confirma implicitamente todas as transações abertas na sessão. As funções de previsão não confirmam transações implicitamente.

  • Se você exportar ou importar seu banco de dados com mysqldump, o catálogo de endpoints de modelo não será exportado.

  • Um banco de dados de usuário que contém funções de transformação não pode ter um ponto final ('.') no nome. Por exemplo, um banco de dados chamado my.sql não é compatível.

  • O gerenciamento de endpoints de modelo está disponível apenas para o Cloud SQL para MySQL versão 8.0.36 e mais recentes.

A seguir