Visão geral do gerenciamento de endpoints de modelos

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. É possível usar esses modelos para gerar embeddings de vetor ou invocar previsões.

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

  • Modelos de embedding de texto daVertex 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. Confira alguns 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 dentro de 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 de modelo para consultar modelos, da seguinte maneira:

  • 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 instância. Para mais informações, consulte Ativar e desativar embeddings de vetor na instância.

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

Para registrar e chamar modelos de IA remotos com a instância do Cloud SQL, a instância precisa ser 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, então 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, é possível usar as seguintes funções:

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

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

Para registrar e chamar modelos de IA remotos, é necessário fazer 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 o papel cloudsqlsuperuser tem esses privilégios ou pode criar um usuário e conceder os privilégios necessários.

Para mais informações sobre o papel 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

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

Tipos de modelos 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ê usar a Vertex AI como provedor de modelos, não será 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. Opcionalmente, é possível usar a função de geração de cabeçalho HTTP que gera cabeçalhos personalizados exigidos pelo 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 mysql.ml_predict_row() função. É 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, 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 instância do Cloud SQL para MySQL e, em seguida, 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 mysql.ml_create_sm_secret_registration() função SQL.

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 da Vertex AI
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 Prediction

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 embedding 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 oferecer suporte a 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 do 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 de 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 o banco de dados com mysqldump, o catálogo de endpoints de modelo não será exportado.

  • Um banco de dados do usuário que contém funções de transformação não pode ter um caractere de ponto ('.') 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