Visão geral do registro e da chamada de modelos de IA remotos no AlloyDB Omni

Selecione uma versão da documentação:

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 endpoints de modelo.

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

Visão geral

Com o gerenciamento de endpoints de modelo, é possível registrar um endpoint de modelo, gerenciar metadados de endpoints de modelo no cluster de banco de dados e fazer chamadas para os endpoints de modelo remoto usando consultas SQL. Ele fornece a extensão google_ml_integration, que inclui funções para registrar os metadados relacionados a modelos de IA no AlloyDB. Esses metadados registrados são usados para gerar embeddings de vetores ou invocar previsões.

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

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

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

Ao registrar um endpoint de modelo com o gerenciamento de endpoints de modelo, cada endpoint é registrado com um ID de modelo exclusivo que você forneceu como referência ao modelo.

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

  • Gere embeddings para traduzir comandos de texto em vetores numéricos. É possível armazenar embeddings gerados como dados vetoriais quando a extensão vector está ativada no banco de dados. Para mais informações, consulte Armazenar embeddings de vetores.

  • Invocar previsões usando o SQL.

Seus aplicativos 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(), 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 secrets no Google Cloud Secret Manager, no qual as chaves de 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() que gera previsões quando você chama modelos genéricos que são compatíveis com o formato de entrada e saída JSON.
  • Outras funções auxiliares que processam a geração de URLs personalizados, cabeçalhos HTTP ou a transmissão de funções de transformação.
  • Funções para gerenciar os endpoints e segredos do modelo registrado.

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

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

O provedor de modelo padrão é custom.

O método de autenticação compatível varia de acordo com o tipo de provedor. Os modelos da Vertex AI usam a conta de serviço usada para instalar o AlloyDB Omni para 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

O tipo de modelo indica o tipo de modelo de IA. A extensão é compatível com embeddings de texto e qualquer tipo de modelo genérico. Os tipos de modelo compatíveis que podem ser definidos ao registrar um endpoint de modelo são text-embedding e generic.

Definir o tipo de modelo é opcional ao registrar endpoints de modelo genéricos, já que generic é o tipo de modelo padrão.

Modelos pré-registrados da Vertex AI
O gerenciamento de endpoints de modelo é compatível com alguns modelos de embedding de texto e genéricos da Vertex AI como IDs de modelo pré-registrados. Você pode usar diretamente o ID do modelo 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, você pode chamar diretamente o modelo 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 endpoints de modelo oferece suporte integrado a alguns modelos da Vertex AI, da Anthropic e da OpenAI. Para modelos de embedding de texto com suporte integrado, o AlloyDB configura automaticamente 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 para esses modelos 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. Dependendo dos requisitos do modelo, talvez seja necessário também criar uma função de cabeçalho personalizada para especificar o cabeçalho.
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 função google_ml.predict_row(). É 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.

Autenticação

Os tipos de autenticação indicam o tipo de autenticação que você pode usar para se conectar ao gerenciamento de endpoints de modelo usando a extensão google_ml_integration. A configuração da 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 do portador armazenado como um secret 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 seguinte tabela mostra os tipos 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 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 e 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 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()
Usado para chamar um endpoint de modelo genérico registrado, desde que o modelo seja compatível com 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 de 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 as assinaturas da função de previsão para modelos de embedding 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.

A seguir