Chamar modelos usando endpoints de modelo no AlloyDB

Pré-lançamento — Gerenciamento de endpoints de modelo
Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos gerais de serviço" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado.

Com a prévia do gerenciamento de endpoints de modelo, é possível registrar um endpoint de modelo, gerenciar metadados de endpoint de modelo no cluster de banco de dados e interagir com os modelos usando consultas SQL. Ele fornece a extensão google_ml_integration, que inclui funções para adicionar e registrar os metadados do endpoint do modelo relacionados aos modelos e, em seguida, usar os modelos para gerar embeddings de vetor ou invocar previsões.

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

• Modelos de embedding de texto da Vertex AI
• Modelos de embedding fornecidos por terceiros.
• Modelos de incorporação de texto hospedados de forma personalizada
• Modelos genéricos com uma API baseada em JSON, por exemplo, o modelo gemini-pro do Model Garden da Vertex AI

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. Você pode usar esse ID para consultar modelos:

• 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.

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

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 Secret Manager Google Cloud, onde 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.
• A função SQL google_ml.predict_row() que gera previsões quando você chama modelos genéricos que aceitam 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 para seus modelos genéricos.
• 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 modelo indica os provedores de hospedagem de modelo compatíveis. 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	google
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 do Distributed Cloud para autenticar, enquanto outros provedores podem usar o Secret Manager para autenticar.

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 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 da Vertex AI. Para registrar esses endpoints de modelo, use a função google_ml.create_model(). A Distributed Cloud configura automaticamente as funções de transformação padrão para esses modelos.

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 registrar 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.

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 Distributed Cloud é usada para autenticação. Para outros modelos, a chave de API ou o token de autenticação armazenado como um secret no Secret Manager pode ser usado com a função SQL google_ml.create_sm_secret().

A tabela a seguir 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 Distributed Cloud	alloydb_service_agent_iam	Provedor da Vertex AI
Secret Manager	secret_manager	provedores terceirizados

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. 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()

Usado para chamar um endpoint de modelo genérico registrado, desde que ele suporte a 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 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[];

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;

Registrar um modelo

Para invocar previsões ou gerar embeddings usando um modelo, registre o endpoint do modelo com o gerenciamento de endpoints de modelo.

Para mais informações sobre a função google_ml.create_model(), consulte Referência do gerenciamento de endpoints de modelo.

Antes de registrar um endpoint de modelo com o gerenciamento de endpoints de modelo, ative a extensão google_ml_integration e configure a autenticação com base no provedor do modelo, se o endpoint exigir autenticação.

Acesse o banco de dados com o nome de usuário padrão postgres.

Configurar a autenticação

As seções a seguir mostram como configurar a autenticação antes de adicionar um endpoint de modelo da Vertex AI ou endpoints de modelo de outros provedores.

Configurar a autenticação para a Vertex AI

Para usar os endpoints de modelo da Vertex AI do Google, adicione permissões da Vertex AI à conta de serviço usada durante a instalação do AlloyDB Omni.

Configurar a autenticação para outros provedores de modelos

Para todos os modelos, exceto os da Vertex AI, é possível armazenar suas chaves de API ou tokens de acesso no Secret Manager. Esta etapa é opcional se o endpoint do modelo não processar a autenticação pelo Secret Manager. Por exemplo, se o endpoint do modelo usar cabeçalhos HTTP para transmitir informações de autenticação ou não usar autenticação.

Esta seção explica como configurar a autenticação se você estiver usando o Secret Manager.

Para criar e usar uma chave de API ou um token de autenticação, siga estas etapas:

1. Crie o secret no Secret Manager.

   O nome e o caminho do secret são usados na função SQL google_ml.create_sm_secret().

2. Conceda permissões ao cluster do Distributed Cloud para acessar o secret.

     gcloud secrets add-iam-policy-binding 'SECRET_ID' \
         --member="serviceAccount:SERVICE_ACCOUNT_ID" \
         --role="roles/secretmanager.secretAccessor"
   

   Substitua:

   • SECRET_ID: o ID do secret no Secret Manager.

   • SERVICE_ACCOUNT_ID: o ID da conta de serviço que você criou na etapa anterior. Confira se é a mesma conta usada durante a instalação do AlloyDB Omni. Isso inclui o sufixo PROJECT_ID.iam.gserviceaccount.com completo. Por exemplo: [e-mail]

     Também é possível conceder esse papel à conta de serviço no nível do projeto.

gerar embeddings

Esta seção descreve uma prévia que permite testar o registro de um endpoint de modelo de IA e invocar previsões com o gerenciamento de endpoints de modelo.

Depois que os endpoints de modelo são adicionados e registrados no gerenciamento de endpoints de modelo, é possível referenciá-los usando o ID do modelo para gerar incorporações.

Antes de começar

Verifique se você registrou o endpoint do modelo com o gerenciamento de endpoints de modelo.

gerar embeddings

Use a função SQL google_ml.embedding() para chamar o endpoint do modelo registrado com o tipo de modelo de embedding de texto e gerar embeddings.

Para chamar o modelo e gerar embeddings, use a seguinte consulta SQL:

SELECT
  google_ml.embedding(
    model_id => 'MODEL_ID',
    content => 'CONTENT');

Substitua:

• MODEL_ID: o ID do modelo definido ao registrar o endpoint do modelo.
• CONTENT: o texto a ser traduzido em um embedding vetorial.

Exemplos

Confira alguns exemplos de como gerar embeddings usando o endpoint do modelo registrado nesta seção.

Modelos de embeddings de texto com suporte integrado

Para gerar embeddings para um endpoint de modelo textembedding-gecko@002 registrado, execute a seguinte instrução:

    SELECT
      google_ml.embedding(
        model_id => 'textembedding-gecko@002',
        content => 'AlloyDB is a managed, cloud-hosted SQL database service');

Invocar previsões

Esta seção descreve uma prévia que permite testar o registro de um endpoint de modelo de IA e invocar previsões com o gerenciamento de endpoints de modelo.

Depois que os endpoints de modelo são adicionados e registrados no gerenciamento de endpoints de modelo, é possível referenciá-los usando o ID do modelo para invocar previsões.

Antes de começar

Verifique se você registrou o endpoint do modelo com o gerenciamento de endpoints de modelo.

Invocar previsões para modelos genéricos

Use a função SQL google_ml.predict_row() para chamar um endpoint de modelo genérico registrado e invocar previsões. É possível usar a função google_ml.predict_row() com qualquer tipo de modelo.

SELECT
  google_ml.predict_row(
    model_id => 'MODEL_ID',
    request_body => 'REQUEST_BODY');

Substitua:

• MODEL_ID: o ID do modelo definido ao registrar o endpoint do modelo.
• REQUEST_BODY: os parâmetros para a função de previsão, no formato JSON.

Exemplos

Confira alguns exemplos de como invocar previsões usando endpoints de modelos registrados nesta seção.

Para gerar previsões para um endpoint de modelo gemini-pro registrado, execute a seguinte instrução:

    SELECT
        json_array_elements(
        google_ml.predict_row(
            model_id => 'gemini-pro',
            request_body => '{
        "contents": [
            {
                "role": "user",
                "parts": [
                    {
                        "text": "For TPCH database schema as mentioned here https://www.tpc.org/TPC_Documents_Current_Versions/pdf/TPC-H_v3.0.1.pdf , generate a SQL query to find all supplier names which are located in the India nation."
                    }
                ]
            }
        ]
        }'))-> 'candidates' -> 0 -> 'content' -> 'parts' -> 0 -> 'text';

Referência da API de gerenciamento de endpoints de modelo

Esta seção lista parâmetros para diferentes funções fornecidas pela extensão google_ml_integration para registrar e gerenciar endpoints de modelo e secrets com gerenciamento de endpoints de modelo.

Defina a flag de banco de dados google_ml_integration.enable_model_support como on antes de começar a usar a extensão.

Modelos

Use esta referência para entender os parâmetros das funções que permitem gerenciar endpoints de modelo.

Função google_ml.create_model()

Confira a seguir como chamar a função SQL google_ml.create_model() usada para registrar metadados de endpoint de modelo:

  CALL
    google_ml.create_model(
      model_id => 'MODEL_ID',
      model_request_url => 'REQUEST_URL',
      model_provider => 'PROVIDER_ID',
      model_type => 'MODEL_TYPE',
      model_qualified_name => 'MODEL_QUALIFIED_NAME',
      model_auth_type => 'AUTH_TYPE',
      model_auth_id => 'AUTH_ID',
      generate_headers_fn => 'GENERATE_HEADER_FUNCTION',
      model_in_transform_fn => 'INPUT_TRANSFORM_FUNCTION',
      model_out_transform_fn => 'OUTPUT_TRANSFORM_FUNCTION');

Parâmetro	Obrigatório	Descrição
MODEL_ID	obrigatório para todos os endpoints de modelo	Um ID exclusivo para o endpoint do modelo que você define.
REQUEST_URL	opcional para outros endpoints de modelo de embedding de texto com suporte integrado	O endpoint específico do modelo ao adicionar outros endpoints de incorporação de texto e de modelo genérico. Para o AlloyDB para PostgreSQL, forneça um URL https. O URL de solicitação que a função gera para endpoints de modelo integrados se refere ao projeto e à região ou local do cluster. Se você quiser se referir a outro projeto, especifique o model_request_url explicitamente. Para endpoints de modelo hospedados personalizados, verifique se o endpoint do modelo está acessível na rede em que o Distributed Cloud está localizado.
PROVIDER_ID	obrigatório para endpoints de modelo de embedding de texto com suporte integrado	O provedor do endpoint do modelo. O valor padrão é custom. Defina um dos seguintes valores: google para endpoints de modelo da Vertex AI custom para outros provedores
MODEL_TYPE	opcional para endpoints de modelos genéricos	O tipo de modelo. Defina como uma das seguintes opções: text_embedding para endpoints de modelos de embedding de texto generic para todos os outros endpoints de modelo
MODEL_QUALIFIED_NAME	obrigatório para modelos de embedding de texto com suporte integrado; opcional para outros endpoints de modelo	O nome totalmente qualificado para modelos de embedding de texto com suporte integrado.
AUTH_TYPE	opcional, a menos que o endpoint do modelo tenha um requisito de autenticação específico	O tipo de autenticação usado pelo endpoint do modelo. Você pode definir como alloydb_service_agent_iam para modelos da Vertex AI ou secret_manager para outros provedores, se eles usarem o Secret Manager para autenticação. Não é necessário definir esse valor se você estiver usando cabeçalhos de autenticação.
AUTH_ID	não defina para endpoints de modelo da Vertex AI. É obrigatório para todos os outros endpoints de modelo que armazenam secrets no Secret Manager.	O ID secreto que você define e que é usado posteriormente ao registrar um endpoint de modelo.
GENERATE_HEADER_FUNCTION	opcional	O nome da função que gera cabeçalhos personalizados. A assinatura dessa função depende da função de previsão que você usa.
INPUT_TRANSFORM_FUNCTION	opcional para endpoints de modelo de embedding de texto com suporte integrado. Não defina para endpoints de modelo genérico.	A função para transformar a entrada da função de previsão correspondente na entrada específica do modelo.
OUTPUT_TRANSFORM_FUNCTION	opcional para endpoints de modelo de embedding de texto com suporte integrado. Não defina para endpoints de modelo genérico.	A função para transformar a saída específica do modelo na saída da função de previsão.

google_ml.alter_model()

Confira a seguir como chamar a função SQL google_ml.alter_model() usada para atualizar os metadados do endpoint do modelo:

    CALL
    google_ml.alter_model(
      model_id => 'MODEL_ID',
      model_request_url => 'REQUEST_URL',
      model_provider => 'PROVIDER_ID',
      model_type => 'MODEL_TYPE',
      model_qualified_name => 'MODEL_QUALIFIED_NAME',
      model_auth_type => 'AUTH_TYPE',
      model_auth_id => 'AUTH_ID',
      generate_headers_fn => 'GENERATE_HEADER_FUNCTION',
      model_in_transform_fn => 'INPUT_TRANSFORM_FUNCTION',
      model_out_transform_fn => 'OUTPUT_TRANSFORM_FUNCTION');

Para informações sobre os valores que você precisa definir para cada parâmetro, consulte Criar um modelo.

Função google_ml.drop_model()

Confira a seguir como chamar a função SQL google_ml.drop_model() usada para excluir um endpoint de modelo:

  CALL google_ml.drop_model('MODEL_ID');

Parâmetro	Descrição
MODEL_ID	Um ID exclusivo para o endpoint do modelo que você definiu.

Função google_ml.list_model()

A seguir, mostramos como chamar a função SQL google_ml.list_model() usada para listar informações do endpoint do modelo:

  SELECT google_ml.list_model('MODEL_ID');

Parâmetro	Descrição
MODEL_ID	Um ID exclusivo para o endpoint do modelo que você definiu.

google_ml.model_info_view visualização

A seguir, mostramos como chamar a visualização google_ml.model_info_view usada para listar informações de endpoints de modelo para todos os endpoints de modelo:

  SELECT * FROM google_ml.model_info_view;

Secrets

Use esta referência para entender os parâmetros das funções que permitem gerenciar secrets.

Função google_ml.create_sm_secret()

A seguir, mostramos como chamar a função SQL google_ml.create_sm_secret() usada para adicionar o secret criado no Secret Manager:

    CALL
    google_ml.create_sm_secret(
      secret_id => 'SECRET_ID',
      secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

Parâmetro	Descrição
SECRET_ID	O ID secreto que você define e que é usado posteriormente ao registrar um endpoint de modelo.
PROJECT_ID	O ID do seu projeto Google Cloud que contém o secret. Esse projeto pode ser diferente daquele que contém seu cluster do AlloyDB para PostgreSQL. Para o AlloyDB Omni, o ID do seu projeto Google Cloud que contém o secret.
SECRET_MANAGER_SECRET_ID	O ID do secret definido no Secret Manager quando você criou o secret.
VERSION_NUMBER	O número da versão do ID do secret.

Função google_ml.alter_sm_secret()

Confira a seguir como chamar a função SQL google_ml.alter_sm_secret() usada para atualizar informações secretas:

  CALL
    google_ml.alter_sm_secret(
      secret_id => 'SECRET_ID',
      secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

Para informações sobre os valores que você precisa definir para cada parâmetro, consulte Criar um secret.

Função google_ml.drop_sm_secret()

Veja a seguir como chamar a função SQL google_ml.drop_sm_secret() usada para excluir um secret:

  CALL google_ml.drop_sm_secret('SECRET_ID');

Parâmetro	Descrição
SECRET_ID	O ID secreto que você definiu e que foi usado posteriormente ao registrar um endpoint de modelo.

Funções de previsão

Use esta referência para entender os parâmetros das funções que permitem gerar embeddings ou invocar previsões.

Função google_ml.embedding()

Confira a seguir como gerar embeddings:

SELECT
  google_ml.embedding(
    model_id => 'MODEL_ID',
    contents => 'CONTENT');

Parâmetro	Descrição
MODEL_ID	Um ID exclusivo para o endpoint do modelo que você define.
CONTENT	O texto a ser traduzido em um embedding vetorial.

Função google_ml.predict_row()

Confira abaixo como invocar previsões:

SELECT
  google_ml.predict_row(
    model_id => 'MODEL_ID',
    request_body => 'REQUEST_BODY');

Parâmetro	Descrição
MODEL_ID	Um ID exclusivo para o endpoint do modelo que você define.
REQUEST_BODY	Os parâmetros da função de previsão, no formato JSON.

Funções de transformação

Use esta referência para entender os parâmetros das funções de transformação de entrada e saída.

Função de transformação de entrada

A seguir, mostramos a assinatura da função de previsão para endpoints de modelo de incorporação de texto:

  CREATE OR REPLACE FUNCTION INPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;

Parâmetro	Descrição
INPUT_TRANSFORM_FUNCTION	A função para transformar a entrada da função de previsão correspondente na entrada específica do endpoint do modelo.

Função de transformação de saída

A seguir, mostramos a assinatura da função de previsão para endpoints de modelo de incorporação de texto:

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

Parâmetro	Descrição
OUTPUT_TRANSFORM_FUNCTION	A função para transformar a saída específica do endpoint do modelo na saída da função de previsão.

Exemplo de funções de transformação

Para entender melhor como criar funções de transformação para o endpoint do modelo, considere um endpoint de modelo de embedding de texto hospedado personalizado que exige entrada e saída JSON.

O exemplo de solicitação cURL a seguir cria embeddings com base no comando e no endpoint do modelo:

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
    -H "Content-Type: application/json"
    -d '{"prompt": ["AlloyDB Embeddings"]}'

A seguinte resposta de exemplo é retornada:

[[ 0.3522231  -0.35932037  0.10156056  0.17734447 -0.11606089 -0.17266059
   0.02509351  0.20305622 -0.09787305 -0.12154685 -0.17313677 -0.08075467
   0.06821183 -0.06896557  0.1171584  -0.00931572  0.11875633 -0.00077482
   0.25604948  0.0519384   0.2034983  -0.09952664  0.10347155 -0.11935943
  -0.17872004 -0.08706985 -0.07056875 -0.05929353  0.4177883  -0.14381726
   0.07934926  0.31368294  0.12543282  0.10758053 -0.30210832 -0.02951015
   0.3908268  -0.03091059  0.05302926 -0.00114946 -0.16233777  0.1117468
  -0.1315904   0.13947351 -0.29569918 -0.12330773 -0.04354299 -0.18068913
   0.14445548  0.19481727]]

Com base nessa entrada e resposta, podemos inferir o seguinte:

• O modelo espera entrada JSON pelo campo prompt. Esse campo aceita uma matriz de entradas. Como a função google_ml.embedding() é uma função de nível de linha, ela espera uma entrada de texto por vez. Portanto,é necessário criar uma função de transformação de entrada que crie uma matriz com um único elemento.

• A resposta do modelo é uma matriz de embeddings, um para cada entrada de comando para o modelo. Como a função google_ml.embedding() é uma função de nível de linha, ela retorna uma entrada por vez. Portanto, é necessário criar uma função de transformação de saída que possa ser usada para extrair o encadeamento do array.

O exemplo a seguir mostra as funções de transformação de entrada e saída usadas para esse endpoint de modelo quando ele é registrado no gerenciamento de endpoints de modelo:

função de transformação de entrada

CREATE OR REPLACE FUNCTION cymbal_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
DECLARE
  transformed_input JSON;
  model_qualified_name TEXT;
BEGIN
  SELECT json_build_object('prompt', json_build_array(input_text))::JSON INTO transformed_input;
  RETURN transformed_input;
END;
$$;

função de transformação de saída

CREATE OR REPLACE FUNCTION cymbal_text_output_transform(model_id VARCHAR(100), response_json JSON)
RETURNS REAL[]
LANGUAGE plpgsql
AS $$
DECLARE
  transformed_output REAL[];
BEGIN
SELECT ARRAY(SELECT json_array_elements_text(response_json->0)) INTO transformed_output;
RETURN transformed_output;
END;
$$;

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

A seguir, mostramos a assinatura da função de geração de cabeçalho que pode ser usada com a função de previsão google_ml.embedding() ao registrar outros endpoints de modelo de embedding de texto.

  CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id VARCHAR(100), input_text 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 TEXT, input JSON) RETURNS JSON;

Parâmetro	Descrição
GENERATE_HEADERS	A função para gerar cabeçalhos personalizados. Também é possível transmitir o cabeçalho de autorização gerado pela função de geração de cabeçalho ao registrar o endpoint do modelo.

Exemplo de função de geração de cabeçalho

Para entender melhor como criar uma função que gera saída em pares de chave-valor JSON usados como cabeçalhos HTTP, considere um endpoint de modelo de incorporação de texto hospedado de forma personalizada.

A solicitação cURL de exemplo a seguir transmite o cabeçalho HTTP version, que é usado pelo endpoint do modelo:

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
      -H "Content-Type: application/json" \
      -H "version: 2024-01-01" \
      -d '{"prompt": ["AlloyDB Embeddings"]}'

O modelo espera entrada de texto pelo campo version e retorna o valor da versão no formato JSON. O exemplo a seguir mostra a função de geração de cabeçalho usada para esse endpoint do modelo de embedding de texto quando ele é registrado no gerenciamento de endpoints de modelo:

CREATE OR REPLACE FUNCTION header_gen_fn(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
BEGIN
  RETURN json_build_object('version', '2024-01-01')::JSON;
END;
$$;

Função de geração de cabeçalho usando chave de API

Os exemplos a seguir mostram como configurar a autenticação usando a chave de API.

modelo de embedding

CREATE OR REPLACE FUNCTION header_gen_func(
  model_id VARCHAR(100),
  input_text TEXT
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
BEGIN
  RETURN json_build_object('Authorization', 'API_KEY')::JSON;
END;
$$;

Substitua API_KEY pela chave de API do provedor do modelo.

modelo genérico

CREATE OR REPLACE FUNCTION header_gen_func(
  model_id VARCHAR(100),
  response_json JSON
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
DECLARE
transformed_output REAL[];
BEGIN
  -- code to add Auth token to API request
RETURN json_build_object('x-api-key', 'API_KEY', 'model-version', '2023-06-01')::JSON;
END;
$$;

Substitua API_KEY pela chave de API do provedor do modelo.

Geração de URL de solicitação

Use a função de geração de URL de solicitação para inferir os URLs de solicitação dos endpoints do modelo com suporte integrado. Confira a assinatura desta função:

CREATE OR REPLACE FUNCTION GENERATE_REQUEST_URL(provider google_ml.model_provider, model_type google_ml.MODEL_TYPE, model_qualified_name VARCHAR(100), model_region VARCHAR(100) DEFAULT NULL)

Parâmetro	Descrição
GENERATE_REQUEST_URL	A função para gerar o URL de solicitação gerado pela extensão para endpoints de modelo com suporte integrado.

Modelos compatíveis

É possível usar o gerenciamento de endpoints de modelo para registrar qualquer endpoint de modelo genérico ou de incorporação de texto. O gerenciamento de endpoints de modelos também inclui modelos pré-registrados da Vertex AI e modelos com suporte integrado.

Modelos pré-registrados da Vertex AI

Observação: o suporte a modelos da Vertex AI é regido pelas diretrizes de controle de versão e ciclo de vida de modelos da Vertex AI.

Tipo de modelo	ID do modelo	Versão da extensão
generic	gemini-1.5-pro:streamGenerateContent gemini-1.5-pro:generateContent gemini-1.0-pro:generateContent	versão 1.4.2 e mais recentes
text_embedding	textembedding-gecko text-embedding-gecko@001	versão 1.3 e mais recentes

Modelos com suporte integrado

Vertex AI

Nome qualificado do modelo	Tipo de modelo
text-embedding-gecko@001	text-embedding
text-embedding-gecko@003	text-embedding
text-embedding-004	text-embedding
text-embedding-preview-0815	text-embedding
text-multilingual-embedding-002	text-embedding