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 endpoints de modelo na instância do Cloud SQL e interagir com os modelos usando consultas SQL. Você pode usar esses modelos para gerar embeddings de vetores 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 maneira 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.
  • É possível usar o protocolo REST para chamar o modelo.

Ao registrar um endpoint de modelo com o gerenciamento de endpoints de modelo, cada endpoint é registrado com um ID de modelo exclusivo como referência ao modelo. É possível usar esse ID para consultar modelos da seguinte forma:

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

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

Para registrar e chamar modelos remotos de IA 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 com a 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 de IA remotos, 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 modelo compatível. A tabela a seguir mostra o valor do provedor de modelo que você precisa definir com base no provedor usado:

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, você precisa 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 modelo também permite registrar todos os outros tipos de modelo, exceto os de embeddings de texto. Para invocar previsões para modelos genéricos, use a função mysql.ml_predict_row(). É possível definir metadados do endpoint de 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 analise 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, definir o tipo de modelo é opcional ao registrar endpoints de modelo para esse tipo.
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 configuraçã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 do portador armazenado como um secret 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 entrada de transformação para transformar a entrada da função de previsão na entrada específica do modelo e uma função de saída de transformação 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 de 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.

Confira as assinaturas da função de previsão para modelos de embedding 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 do 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