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

Esta página descreve como registrar um endpoint de modelo de IA e invocar previsões com o gerenciamento de endpoint de modelo no Cloud SQL. Para usar modelos de IA em ambientes de produção, consulte Criar aplicativos de IA generativa usando o Cloud SQL e Trabalhar com embeddings de vetor.

Visão geral

O gerenciamento de endpoint de modelo permite registrar um endpoint de modelo, gerenciar metadados de endpoint de modelo na sua instância do Cloud SQL e interagir com os modelos usando consultas SQL. O Cloud SQL fornece a extensão google_ml_integration, que inclui funções para adicionar e registrar os metadados do endpoint do modelo relacionados aos modelos. É 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 endpoint de modelo:

  • Modelos de embedding de texto da Vertex AI.
  • Modelos de incorporação de texto hospedados de forma personalizada em redes no Google Cloud.
  • Modelos genéricos com uma API baseada em JSON. Confira alguns exemplos desses modelos:
    • O modelo gemini-pro do Model Garden da Vertex AI
    • Modelo open_ai para modelos da OpenAI
    • Modelos hospedados em redes no Google Cloud

Como funciona

É possível usar o gerenciamento de endpoint de modelo para registrar um endpoint de modelo que obedece aos seguintes requisitos:

  • 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, o gerenciamento de endpoints de modelo registra cada endpoint com um ID de modelo exclusivo como referência ao modelo. É possível usar esse ID para consultar modelos da seguinte maneira:

  • Gerar embeddings para traduzir comandos de texto em vetores numéricos. É possível armazenar embeddings gerados como dados vetoriais quando a extensão pgvector estiver ativada no banco de dados. Para mais informações, consulte Consultar e indexar embeddings com pgvector.

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

Seus aplicativos podem gerenciar os endpoints do modelo usando a extensão google_ml_integration. Esta extensão oferece as seguintes funções SQL:

  • google_ml.create_model(): registra o endpoint do modelo usado na função de previsão ou de incorporação.
  • google_ml.create_sm_secret(): usa segredos no Secret Manager do Google Cloud, onde as chaves de API são armazenadas.
  • google_ml.embedding(): gera embeddings de texto
  • google_ml.predict_row(): gera previsões quando você chama modelos genéricos que oferecem suporte aos formatos de entrada e saída JSON.

Principais conceitos

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

Provedor de modelo

Provedor de modelo é 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 usa:

Provedor de modelo Definir na função como…
Vertex AI (incluindo o Gemini) google
OpenAI open_ai
Outros modelos hospedados fora da Vertex AI 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.

Modelos de embedding de texto com suporte integrado
O gerenciamento de endpoint de modelo
oferece suporte integrado a todas as versões do modelo textembedding-gecko. Para registrar esses endpoints de modelo, use a função google_ml.create_model(). O Cloud SQL configura automaticamente as funções de transformação padrão para esses modelos.
O tipo de modelo desses modelos é text-embedding.
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 preferir, use a função de geração de cabeçalho HTTP, que gera cabeçalhos personalizados exigidos pelo modelo.
O tipo de modelo desses modelos é text-embedding.
Modelos genéricos
O gerenciamento de endpoints de modelos também oferece suporte ao registro de todos os outros tipos de modelos, exceto modelos de embeddings de texto. Para invocar previsões para modelos genéricos, use a função google_ml.predict_row(). É possível definir metadados de endpoint do modelo, como um endpoint de solicitação e cabeçalhos HTTP específicos do modelo.
Não é possível transmitir funções de transformação ao registrar um endpoint de modelo genérico. Confira se, ao invocar previsões, a entrada para a função está no formato JSON e se você analisa a saída JSON para derivar a saída final.
O tipo de modelo desses modelos é generic. Como generic é o tipo de modelo padrão, se você registrar endpoints de modelo para esse tipo, a configuração do tipo de modelo será opcional.

Métodos de autenticação

É possível usar a extensão google_ml_integration para 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 de portador armazenado como um segredo no Secret Manager pode ser usado com a função SQL google_ml.create_sm_secret().

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

Método de autenticação Definir na função como… Provedor de modelo
Agente de serviço do Cloud SQL cloudsql_service_agent_iam Provedor da Vertex AI
Secret Manager secret_manager Modelos hospedados fora da Vertex AI

Funções de previsão

A extensão google_ml_integration inclui as seguintes funções de previsão:

google_ml.embedding()
Chama um endpoint de modelo de embedding de texto registrado para gerar embeddings. Ele inclui suporte integrado para o modelo textembedding-gecko 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.
google_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 do 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 a seguir as assinaturas da função de previsão para modelos de incorporação de texto:

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

CREATE OR REPLACE FUNCTION output_transform_function(model_id VARCHAR(100), response_json JSON) RETURNS real[];

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 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çalho.

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

CREATE OR REPLACE FUNCTION generate_headers(model_id VARCHAR(100), input TEXT) RETURNS JSON;

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

CREATE OR REPLACE FUNCTION generate_headers(model_id VARCHAR(100), input JSON) RETURNS JSON;

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

Limitações

  • Para usar modelos de IA com sua instância do Cloud SQL, a versão de manutenção dela precisa ser R20240910.01_02 ou mais recente. Se quiser fazer upgrade da instância para esta versão, consulte Manutenção de autoatendimento.

A seguir