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 Criar aplicativos de IA generativa usando o Cloud SQL e Trabalhar com 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. 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 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. Confira alguns exemplos desses modelos:
    • O modelo gemini-pro 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 embeddings gerados como dados vetoriais quando a extensão pgvector está 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 de modelo usando a extensão google_ml_integration. Essa 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 incorporação.
  • google_ml.create_sm_secret(): usa secrets no Google Cloud Secret Manager, 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 aceitam os formatos de entrada e saída JSON.

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 modelo é 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 de modelo que você usa:

Provedor de modelos Definido na função como…
Vertex AI (inclui 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 endpoints 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 funções de transformação padrão para esses modelos automaticamente.
O tipo de modelo para esses 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 quiser, use a função de geração de cabeçalho HTTP que gera 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 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 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.

Métodos de autenticação

Você pode usar a extensão google_ml_integration para especificar diferentes métodos de autenticação e acessar seu 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 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 Definido na função como… Provedor de modelos
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 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.
google_ml.predict_row()
Chama um endpoint de modelo genérico registrado, se o endpoint aceitar 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 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 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çalho, consulte Exemplo de função de geração de cabeçalho.

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. Para fazer upgrade da instância para essa versão, consulte Realizar manutenção de autoatendimento.

A seguir