Registe e chame modelos de IA remotos na vista geral do Cloud SQL

Esta página descreve como registar um ponto final do modelo de IA e invocar previsões com a gestão de pontos finais do modelo no Cloud SQL. Para usar modelos de IA em ambientes de produção, consulte o artigo Gere e faça a gestão de incorporações vetoriais.

Vista geral

A gestão de pontos finais de modelos permite-lhe registar um ponto final de modelo, gerir metadados de pontos finais de modelos na sua instância do Cloud SQL e, em seguida, interagir com os modelos através de consultas SQL. Pode usar estes modelos para gerar incorporações vetoriais ou invocar previsões.

Pode registar os seguintes tipos de modelos através da gestão de pontos finais de modelos:

  • Modelos de incorporação de texto do Vertex AI.
  • Modelos de incorporação de texto alojados de forma personalizada em redes dentro do Google Cloud.

  • Modelos genéricos com uma API baseada em JSON. Seguem-se alguns exemplos destes modelos:

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

Como funciona

Pode usar a gestão de pontos finais de modelos para registar um ponto final de modelo que esteja em conformidade com o seguinte:

  • A entrada e a saída do modelo suportam o formato JSON.
  • Pode usar o protocolo REST para chamar o modelo.

Quando regista um ponto final do modelo com a gestão de pontos finais do modelo, a gestão de pontos finais do modelo regista cada ponto final com um ID do modelo exclusivo como referência ao modelo. Pode usar este ID do modelo para consultar modelos, da seguinte forma:

  • Gerar incorporações para traduzir comandos de texto em vetores numéricos. Pode armazenar incorporações geradas como dados vetoriais quando ativa o suporte de incorporação vetorial na sua instância. Para mais informações, consulte o artigo Ative e desative as incorporações vetoriais na sua instância.

  • Invocar previsões para chamar um modelo através de SQL numa transação.

Para registar e chamar modelos de IA remotos com a sua instância do Cloud SQL, esta tem de estar instalada com a versão de manutenção MYSQL_VERSION.R20250531.01_14 ou posterior. Se a sua instância estiver a executar uma versão de manutenção anterior a MYSQL_VERSION.R20250531.01_14, só pode usar as seguintes funções, conforme documentado com a integração do Cloud SQL e do Vertex AI.

Para atualizar a sua instância para a versão de manutenção MYSQL_VERSION.R20250531.01_14 ou posterior, consulte Manutenção self-service. Depois de atualizar a instância, pode usar as seguintes funções:

Além disso, pode usar as seguintes funções com o seu fornecedor de modelos registado:

Privilégios de utilizador da base de dados necessários

Para registar e chamar modelos de IA remotos, tem de ter sessão iniciada como utilizador da base de dados MySQL ao qual foram concedidos privilégios SELECT e EXECUTE em mysql.*.

Por predefinição, qualquer utilizador com a função cloudsqlsuperuser tem estes privilégios ou pode criar um utilizador e conceder os privilégios necessários.

Para mais informações sobre a função cloudsqlsuperuser no Cloud SQL, consulte os privilégios de utilizador do MySQL 8.0 e os privilégios de utilizador do MySQL 8.4.

Conceitos-chave

Antes de começar a usar a gestão de pontos finais de modelos, compreenda os conceitos necessários para se ligar aos modelos e usá-los.

Fornecedor do modelo

O fornecedor do modelo é o fornecedor de alojamento de modelos suportado. A tabela seguinte mostra o valor do fornecedor do modelo que tem de definir com base no fornecedor do modelo que usa:

Fornecedor do modelo Definir na função como…
Vertex AI (inclui o Gemini) google
Anthropic anthropic
Hugging Face hugging_face
OpenAI open_ai
Outros modelos alojados fora do Vertex AI,
Anthropic, Hugging Face e OpenAI		 custom

O fornecedor de modelos predefinido é custom.

Tipos de modelos

Os tipos de modelos são os tipos de modelo de IA. Quando regista um ponto final do modelo, pode definir os tipos de modelo text_embedding ou generic para o ponto final.

Se usar o Vertex AI como fornecedor de modelos, não precisa de registar um ponto final do modelo porque os pontos finais são suportados automaticamente. Por predefinição, com o Vertex AI, usa o modelo text-embedding-005.

Outros modelos de incorporação de texto
Para outros modelos de incorporação de texto, tem de criar funções de transformação para processar os formatos de entrada e saída suportados pelo modelo. Opcionalmente, pode usar a função de geração de cabeçalhos HTTP que gera cabeçalhos personalizados exigidos pelo seu modelo.

O tipo de modelo para estes modelos é text_embedding.

Modelos genéricos
A gestão de pontos finais de modelos também suporta o registo de todos os outros tipos de modelos, exceto os modelos de incorporação de texto. Para invocar previsões para modelos genéricos, use a função mysql.ml_predict_row(). Pode definir metadados do ponto final do modelo, como um ponto final de pedido e cabeçalhos HTTP específicos do seu modelo.
Não pode transmitir funções de transformação quando regista um ponto final de modelo genérico. Certifique-se de que, quando invoca as previsões, a entrada da função está no formato JSON e de que analisa a saída JSON para obter a saída final.
O tipo de modelo para estes modelos é generic. Uma vez que generic é o tipo de modelo predefinido, se registar pontos finais de modelos para este tipo, a definição do tipo de modelo é opcional.
Com a Vertex AI, a gestão de pontos finais de modelos inclui suporte pré-registado para o modelo gemini-2.5-flash.

Métodos de autenticação

Pode ativar o suporte para incorporações vetoriais na sua instância do Cloud SQL para MySQL e, em seguida, especificar diferentes métodos de autenticação para aceder ao seu modelo. A definição destes métodos é opcional e só é necessária se precisar de autenticar para aceder ao seu modelo.

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

A tabela seguinte mostra os métodos de autenticação que pode definir:

Método de autenticação Definir na função como… Fornecedor do modelo
Agente de serviço do Cloud SQL auth_type_cloudsql_service_agent_iam Fornecedor da Vertex AI
Secret Manager auth_type_secret_manager Modelos alojados fora do Vertex AI

Funções de previsão

mysql.ml_embedding()
Chama um ponto final do modelo de incorporação de texto registado para gerar incorporações. Inclui suporte integrado para todos os modelos de incorporação do Vertex AI.
Para modelos de incorporação de texto sem suporte integrado, os parâmetros de entrada e saída são exclusivos de um modelo e têm de 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 ponto final de modelo genérico registado, se o ponto final suportar 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 compreende e convertem a resposta do modelo no formato que a função de previsão espera. As funções de transformação são usadas quando regista o ponto final do modelo text-embedding sem suporte incorporado. A assinatura das funções de transformação depende da função de previsão para o tipo de modelo.

Não pode usar funções de transformação quando regista um ponto final do modelo generic.

Seguem-se 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 o exemplo de funções de transformação.

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

A função de geração de cabeçalhos HTTP gera o resultado em pares de valores-chave JSON que são usados como cabeçalhos HTTP. A assinatura da função de previsão define as assinaturas da função de geração de cabeçalhos.

O exemplo seguinte 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çalhos, consulte o exemplo de função de geração de cabeçalhos.

Limitações

  • Quando executa qualquer uma das funções de registo de modelos ou de gestão de segredos, confirma implicitamente todas as transações abertas na sessão. As funções de previsão não confirmam implicitamente as transações.

  • Se exportar ou importar a sua base de dados com mysqldump, o catálogo de pontos finais do modelo não é exportado.

  • Uma base de dados de utilizadores que contenha funções de transformação não pode ter um ponto final ('.') no nome. Por exemplo, uma base de dados denominada my.sql não é suportada.

  • A gestão de pontos finais de modelos só está disponível para o Cloud SQL para MySQL versão 8.0.36 e posteriores.

O que se segue?