Registrar e chamar modelos de IA remotos na visão geral do AlloyDB

Nesta página, você vai entender os principais conceitos que precisa conhecer antes de registrar um endpoint de modelo de IA e invocar previsões com o gerenciamento de endpoint de modelo.

Para registrar endpoints de modelos remotos com o AlloyDB Omni, consulte Registrar e chamar modelos de IA remotos no AlloyDB Omni.

Visão geral

O gerenciamento de endpoint de modelo permite registrar um endpoint de modelo, gerenciar metadados de endpoint de modelo no cluster de banco de dados e fazer chamadas para os endpoints de modelo remotos usando consultas SQL. Ele fornece a extensão google_ml_integration, que inclui funções que permitem registrar os metadados relacionados a modelos de IA com o AlloyDB. Esses metadados registrados são usados para gerar embeddings de vetor ou invocar previsões.

Confira alguns exemplos de tipos de modelos que podem ser registrados usando o gerenciamento de endpoint de modelo:

  • Incorporação de texto e modelos genéricos da Vertex AI
  • Modelos de embedding fornecidos por provedores de terceiros, como o Hugging Face ou o OpenAI
  • Modelos de embedding de texto hospedados de forma personalizada, incluindo modelos auto-hospedados ou disponíveis em endpoints particulares
  • Modelos genéricos com uma API baseada em JSON, por exemplo, modelo facebook/bart-large-mnli hospedado no Hugging Face, modelo gemini-pro do Model Garden da Vertex AI ou modelos claude da Anthropic

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.
  • O modelo pode ser chamado usando o protocolo REST.

Quando você registra um endpoint de modelo com o gerenciamento de endpoint de modelo, cada endpoint é registrado com um ID de modelo exclusivo que você forneceu como referência.

É possível usar o ID do endpoint do modelo para consultar modelos e:

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

  • Invocar previsões usando SQL.

Seus apps podem acessar o gerenciamento de endpoints de modelo usando a extensão google_ml_integration. Essa extensão oferece as seguintes funções:

  • A função SQL google_ml.create_model(), que é usada para registrar o endpoint do modelo usado na função de previsão ou embedding.
  • A função SQL google_ml.create_sm_secret(), que usa segredos no Google Cloud Secret Manager, em que as chaves da API são armazenadas.
  • A função SQL google_ml.embedding(), que é uma função de previsão que gera embeddings de texto. O tipo de retorno da função de incorporação é REAL[].
  • A função SQL google_ml.predict_row() gera previsões quando você chama modelos genéricos que oferecem suporte ao formato de entrada e saída JSON.
  • Outras funções auxiliares que processam a geração de URL personalizado, geram cabeçalhos HTTP ou transmitem funções de transformação.
  • Funções para gerenciar os endpoints e secrets registrados do modelo.

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 indica os provedores de hospedagem de modelos compatíveis. A configuração do provedor de modelo é opcional, mas ajuda o gerenciamento de endpoint do modelo a identificar o provedor e formatar automaticamente os cabeçalhos para modelos compatíveis. A tabela a seguir mostra o valor do provedor de modelo que pode ser definido com base no provedor de modelo usado:

Provedor de modelo Definir na função como…
Vertex AI google
Modelos do Hugging Face hugging_face
Modelos Anthropic anthropic
OpenAI open_ai
Outros modelos custom

O provedor de modelo padrão é custom.

O método de autenticação varia de acordo com o tipo de provedor. Os modelos do Vertex AI usam a conta de serviço do AlloyDB para fazer a autenticação, enquanto outros provedores podem usar o Secret Manager ou transmitir detalhes de autenticação por cabeçalhos. Para mais informações, consulte Configurar a autenticação.

Tipo de modelo

Tipo de modelo indica o tipo do modelo de IA. A extensão oferece suporte a embedding de texto, bem como a qualquer tipo de modelo genérico. O tipo de modelo compatível que você pode definir ao registrar um endpoint de modelo é text-embedding e generic.

A definição do tipo de modelo é opcional ao registrar endpoints de modelo genéricos, porque generic é o tipo de modelo padrão.

Modelos pré-registrados do Vertex AI
O gerenciamento de endpoint de modelo oferece suporte a alguns modelos genéricos e de incorporação de texto da Vertex AI como IDs de modelos pré-registrados. É possível usar o ID do modelo diretamente para gerar embeddings ou invocar previsões com base no tipo de modelo.
Para mais informações sobre os modelos pré-registrados compatíveis, consulte Modelos pré-registrados da Vertex AI.

Por exemplo, para chamar o modelo textembedding-gecko pré-registrado, chame-o diretamente usando a função de embedding:

SELECT
      google_ml.embedding(
        model_id => 'textembedding-gecko',
        content => 'AlloyDB is a managed, cloud-hosted SQL database service');
Modelos com suporte integrado
O gerenciamento de endpoint de modelo oferece suporte integrado a alguns modelos da Vertex AI, Anthropic e OpenAI. Para modelos de embedding de texto com suporte integrado, o AlloyDB configura automaticamente as funções de transformação padrão.
Ao registrar esses endpoints de modelo, defina o nome qualificado explicitamente. Para mais informações sobre uma lista de modelos com suporte integrado, consulte Modelos com suporte integrado.
O tipo de modelo pode ser text-embedding ou generic.
Outros modelos de embedding de texto
Para registrar um endpoint de modelo de embedding de texto sem suporte integrado, recomendamos que você crie funções de transformação para processar os formatos de entrada e saída compatíveis com o modelo. Opcionalmente, dependendo dos requisitos do modelo, talvez seja necessário criar uma função de cabeçalho personalizada para especificar o cabeçalho.
O tipo de modelo desses modelos é text-embedding.
Modelos genéricos
O gerenciamento de endpoint de modelo 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.

Autenticação

Tipos de autenticação indicam o tipo de autenticação que pode ser usado para se conectar ao gerenciamento de endpoint do modelo usando a extensão google_ml_integration. A configuração de autenticação é 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 AlloyDB é 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(). Se você estiver transmitindo a autenticação por cabeçalhos, pule a configuração do método de autenticação.

A tabela a seguir mostra os tipos 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 AlloyDB alloydb_service_agent_iam Provedor da Vertex AI
Secret Manager secret_manager provedores terceirizados, como Anthropic, Hugging Face ou OpenAI;

Funções de previsão

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

google_ml.embedding()
É usado para chamar um endpoint de modelo de embedding de texto registrado para gerar embeddings.
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. Você precisa criar 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()
É usado para chamar um endpoint de modelo genérico registrado, desde que o modelo ofereça suporte a uma API baseada 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 entrada esperada pelo 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.

A seguir