Chame modelos através de pontos finais de modelos no AlloyDB

A pré-visualização da gestão de pontos finais de modelos permite-lhe registar um ponto final de modelo, gerir metadados de pontos finais de modelos no seu cluster de base de dados e, em seguida, interagir com os modelos através de consultas SQL. Fornece a extensão google_ml_integration que inclui funções para adicionar e registar os metadados do ponto final do modelo relacionados com os modelos e, em seguida, usar os modelos para gerar incorporações de vetores ou invocar previsões.

Seguem-se alguns exemplos de tipos de modelos que pode registar através da gestão de pontos finais de modelos:

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

Como funciona

Pode usar a gestão de pontos finais de modelos para registar um ponto final de modelo que esteja em conformidade com o seguinte:

  • A entrada e a saída do modelo suportam o formato JSON.
  • O modelo pode ser invocado através do protocolo REST.

Quando regista um ponto final do modelo com a gestão de pontos finais do modelo, regista cada ponto final com um ID do modelo exclusivo que forneceu como referência ao modelo. Pode usar este ID do modelo para consultar modelos:

  • Gerar incorporações para traduzir comandos de texto em vetores numéricos. Pode armazenar incorporações geradas como dados vetoriais quando a extensão pgvector está ativada na base de dados.

  • Invocar previsões para chamar um modelo através de SQL numa transação.

As suas aplicações podem aceder à gestão de pontos finais do modelo através da extensão google_ml_integration. Esta extensão oferece as seguintes funções:

  • A função SQL google_ml.create_model(), que é usada para registar o ponto final do modelo usado na função de previsão ou incorporação.
  • A função SQL google_ml.create_sm_secret(), que usa segredos no Google CloudSecret Manager, onde as chaves de API estão armazenadas.
  • A função SQL google_ml.embedding(), que é uma função de previsão que gera incorporações de texto.
  • A função SQL google_ml.predict_row() que gera previsões quando chama modelos genéricos que suportam o formato de entrada e saída JSON.
  • Outras funções auxiliares que processam a geração de URLs personalizados, a geração de cabeçalhos HTTP ou a transmissão de funções de transformação para os seus modelos genéricos.
  • Funções para gerir os segredos e os pontos finais do modelo registado.

Conceitos-chave

Antes de começar a usar a gestão de pontos finais de modelos, compreenda os conceitos necessários para estabelecer ligação aos modelos e usá-los.

Fornecedor do modelo

Fornecedor do modelo indica os fornecedores de alojamento de modelos suportados. A tabela seguinte mostra o valor do fornecedor do modelo que tem de definir com base no fornecedor do modelo que usa:

Fornecedor do modelo Definir na função como…
Vertex AI google
Outros modelos custom

O fornecedor de modelos predefinido é custom.

Com base no tipo de fornecedor, o método de autenticação suportado difere. Os modelos do Vertex AI usam a conta de serviço do Distributed Cloud para autenticação, enquanto outros fornecedores podem usar o Secret Manager para autenticação.

Tipo de modelo

O tipo de modelo indica o tipo de modelo de IA. A extensão suporta a incorporação de texto, bem como qualquer tipo de modelo genérico. Os tipos de modelos suportados que pode definir quando registar um ponto final do modelo são text-embedding e generic. A definição do tipo de modelo é opcional quando regista pontos finais de modelos genéricos, uma vez que generic é o tipo de modelo predefinido.

Modelos de incorporação de texto com suporte integrado
A gestão de pontos finais de modelos oferece suporte integrado para todas as versões do modelo textembedding-gecko através da Vertex AI. Para registar estes pontos finais do modelo, use a função google_ml.create_model(). A nuvem distribuída configura automaticamente funções de transformação predefinidas para estes modelos.
O tipo de modelo para estes modelos é text-embedding.
Outros modelos de incorporação de texto
Para outros modelos de incorporação de texto, tem de criar funções de transformação para processar os formatos de entrada e saída suportados pelo modelo. Opcionalmente, pode usar a função de geração de cabeçalhos HTTP que gera cabeçalhos personalizados exigidos pelo seu modelo.
O tipo de modelo para estes modelos é text-embedding.
Modelos genéricos
A gestão de pontos finais de modelos também suporta o registo de todos os outros tipos de modelos, exceto os modelos de incorporação de texto. Para invocar previsões para modelos genéricos, use a função google_ml.predict_row(). Pode definir metadados do ponto final do modelo, como um ponto final de pedido e cabeçalhos HTTP específicos do seu modelo.
Não pode transmitir funções de transformação quando regista um ponto final de modelo genérico. Certifique-se de que, quando invoca as previsões, a entrada da função está no formato JSON e de que analisa a saída JSON para obter a saída final.
O tipo de modelo para estes modelos é generic.

Autenticação

Os tipos de autenticação indicam o tipo de autenticação que pode usar para se ligar à gestão de pontos finais de modelos através da extensão google_ml_integration. A definição da autenticação é opcional e só é necessária se precisar de autenticação para aceder ao seu modelo.

Para os modelos da Vertex AI, a conta de serviço do Distributed Cloud é usada para autenticação. Para outros modelos, pode usar uma chave de API ou um token de portador armazenado como segredo no Secret Manager com a função google_ml.create_sm_secret() SQL.

A tabela seguinte mostra os tipos de autorização que pode definir:

Método de autenticação Definir na função como… Fornecedor do modelo
Agente de serviço do Distributed Cloud alloydb_service_agent_iam Fornecedor da Vertex AI
Secret Manager secret_manager fornecedores externos

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 ponto final do modelo de incorporação de texto registado para gerar incorporações. Inclui suporte integrado para o modelo textembedding-gecko do Vertex AI.
Para modelos de incorporação de texto sem suporte integrado, os parâmetros de entrada e saída são exclusivos de um modelo e têm de 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()
Usado para chamar um ponto final de modelo genérico registado, desde que 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 compreende e convertem a resposta do modelo no formato que a função de previsão espera. As funções de transformação são usadas quando regista o ponto final do modelo text-embedding sem suporte incorporado. A assinatura das funções de transformação depende da função de previsão para o tipo de modelo.

Não pode usar funções de transformação quando regista um ponto final do modelo generic.

Seguem-se 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çalhos HTTP gera o resultado em pares de valores-chave 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çalhos.

O exemplo seguinte 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;

Registe um modelo

Para invocar previsões ou gerar incorporações através de um modelo, registe o ponto final do modelo na gestão de pontos finais de modelos.

Para mais informações sobre a função google_ml.create_model(), consulte a referência de gestão de pontos finais de modelos.

Antes de registar um ponto final do modelo com a gestão de pontos finais do modelo, tem de ativar a extensão google_ml_integration e configurar a autenticação com base no fornecedor do modelo, se o ponto final do modelo exigir autenticação.

Certifique-se de que acede à base de dados com o postgres nome de utilizador predefinido.

Configure a autenticação

As secções seguintes mostram como configurar a autenticação antes de adicionar um ponto final do modelo do Vertex AI ou pontos finais do modelo de outros fornecedores.

Configure a autenticação para o Vertex AI

Para usar os pontos finais do modelo Google Vertex AI, tem de adicionar autorizações do Vertex AI à conta de serviço que usou durante a instalação do AlloyDB Omni.

Configure a autenticação para outros fornecedores de modelos

Para todos os modelos, exceto os modelos da Vertex AI, pode armazenar as suas chaves da API ou tokens de autorização no Secret Manager. Este passo é opcional se o seu ponto final do modelo não processar a autenticação através do Secret Manager. Por exemplo, se o seu ponto final do modelo usar cabeçalhos HTTP para transmitir informações de autenticação ou não usar autenticação.

Esta secção explica como configurar a autenticação se estiver a usar o Secret Manager.

Para criar e usar uma chave da API ou um token de autorização, conclua os seguintes passos:

  1. Crie o Secret no Secret Manager.

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

  2. Conceda autorizações ao cluster do Distributed Cloud para aceder ao segredo.

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

    Substitua o seguinte:

    • SECRET_ID: o ID do segredo no Secret Manager.

    • SERVICE_ACCOUNT_ID: o ID da conta de serviço que criou no passo anterior. Certifique-se de que esta é a mesma conta que usou durante a instalação do AlloyDB Omni. Isto inclui o sufixo completo PROJECT_ID.iam.gserviceaccount.com. Por exemplo: my-service@my-project.iam.gserviceaccount.com

      Também pode conceder esta função à conta de serviço ao nível do projeto.

Gere incorporações

Esta secção descreve uma pré-visualização que lhe permite fazer experiências com o registo de um ponto final de modelo de IA e invocar previsões com a gestão de pontos finais de modelos.

Depois de os pontos finais do modelo serem adicionados e registados na gestão de pontos finais do modelo, pode fazer referência aos mesmos através do ID do modelo para gerar incorporações.

Antes de começar

Certifique-se de que registou o ponto final do modelo na gestão de pontos finais do modelo.

Gere incorporações

Use a função SQL google_ml.embedding() para chamar o ponto final do modelo registado com o tipo de modelo de incorporação de texto para gerar incorporações.

Para chamar o modelo e gerar incorporações, use a seguinte consulta SQL:

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

Substitua o seguinte:

  • MODEL_ID: o ID do modelo que definiu quando registou o ponto final do modelo.
  • CONTENT: o texto a traduzir numa incorporação vetorial.

Exemplos

Alguns exemplos de geração de incorporações através do ponto final do modelo registado estão listados nesta secção.

Modelos de incorporação de texto com suporte integrado

Para gerar incorporações para um ponto final do modelo textembedding-gecko@002 registado, execute a seguinte declaração:

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

Invocar previsões

Esta secção descreve uma pré-visualização que lhe permite fazer experiências com o registo de um ponto final de modelo de IA e invocar previsões com a gestão de pontos finais de modelos.

Depois de adicionar e registar os pontos finais do modelo na gestão de pontos finais do modelo, pode fazer referência aos mesmos através do ID do modelo para invocar previsões.

Antes de começar

Certifique-se de que registou o ponto final do modelo na gestão de pontos finais do modelo.

Invocar previsões para modelos genéricos

Use a função SQL google_ml.predict_row() para chamar um ponto final de modelo genérico registado para invocar previsões. Pode 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 o seguinte:

  • MODEL_ID: o ID do modelo que definiu quando registou o ponto final do modelo.
  • REQUEST_BODY: os parâmetros da função de previsão, no formato JSON.

Exemplos

Alguns exemplos de invocar previsões através de pontos finais de modelos registados estão listados nesta secção.

Para gerar previsões para um ponto final do modelo gemini-pro registado, execute a seguinte declaraçã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 gestão de pontos finais de modelos

Esta secção apresenta os parâmetros de diferentes funções fornecidas pela extensão google_ml_integration para registar e gerir pontos finais de modelos e segredos com a gestão de pontos finais de modelos.

Tem de definir a flag da base de dados google_ml_integration.enable_model_support como on antes de poder começar a usar a extensão.

Modelos

Use esta referência para compreender os parâmetros das funções que lhe permitem gerir os pontos finais do modelo.

Função google_ml.create_model()

O exemplo seguinte mostra como chamar a função SQL google_ml.create_model() usada para registar metadados do endpoint do 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ória Descrição
MODEL_ID obrigatório para todos os pontos finais do modelo Um ID exclusivo para o ponto final do modelo que definir.
REQUEST_URL Opcional para outros pontos finais do modelo de incorporação de texto com suporte integrado O ponto final específico do modelo quando adiciona outros pontos finais de modelos genéricos e de incorporação de texto. Para o AlloyDB para PostgreSQL, indique um https URL.

O URL de pedido que a função gera para os pontos finais do modelo incorporado refere-se ao projeto e à região ou localização do seu cluster. Se quiser fazer referência a outro projeto, certifique-se de que especifica o model_request_url explicitamente.

Para pontos finais de modelos alojados personalizados, certifique-se de que o ponto final do modelo está acessível a partir da rede onde o Distributed Cloud está localizado.
PROVIDER_ID obrigatório para pontos finais do modelo de incorporação de texto com suporte integrado O fornecedor do ponto final do modelo. O valor predefinido é custom.

Defina um dos seguintes valores:
  • google para pontos finais de modelos do Vertex AI
  • custom para outros fornecedores
MODEL_TYPE Opcional para endpoints de modelos genéricos O tipo de modelo.

Definido para uma das seguintes opções:
  • text_embedding para pontos finais do modelo de incorporação de texto
  • generic para todos os outros pontos finais de modelos
MODEL_QUALIFIED_NAME obrigatório para modelos de incorporação de texto com suporte integrado; opcional para outros pontos finais de modelos O nome totalmente qualificado para modelos de incorporação de texto com suporte integrado.
AUTH_TYPE Opcional, a menos que o ponto final do modelo tenha um requisito de autenticação específico O tipo de autenticação usado pelo ponto final do modelo.

Pode defini-lo como alloydb_service_agent_iam para modelos da Vertex AI ou secret_manager para outros fornecedores, se usarem o Secret Manager para autenticação.

Não precisa de definir este valor se estiver a usar cabeçalhos de autenticação.
AUTH_ID Não é definido para os endpoints de modelos da Vertex AI; é obrigatório para todos os outros endpoints de modelos que armazenam segredos no Secret Manager O ID secreto que define e que é usado posteriormente quando regista um ponto final do modelo.
GENERATE_HEADER_FUNCTION opcional O nome da função que gera cabeçalhos personalizados.

A assinatura desta função depende da função de previsão que usa.
INPUT_TRANSFORM_FUNCTION Opcional para pontos finais do modelo de incorporação de texto com suporte integrado; não defina para pontos finais do 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 pontos finais do modelo de incorporação de texto com suporte integrado; não defina para pontos finais do 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()

O exemplo seguinte mostra 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 tem de definir para cada parâmetro, consulte o artigo Crie um modelo.

Função google_ml.drop_model()

O exemplo seguinte mostra como chamar a função SQL google_ml.drop_model() usada para eliminar um ponto final do modelo:

  CALL google_ml.drop_model('MODEL_ID');
Parâmetro Descrição
MODEL_ID Um ID exclusivo para o ponto final do modelo que definiu.

Função google_ml.list_model()

O exemplo seguinte mostra como chamar a função SQL google_ml.list_model() usada para listar informações do ponto final do modelo:

  SELECT google_ml.list_model('MODEL_ID');
Parâmetro Descrição
MODEL_ID Um ID exclusivo para o ponto final do modelo que definiu.

google_ml.model_info_view visualização

O exemplo seguinte mostra como chamar a vista google_ml.model_info_view que é usada para listar informações de pontos finais de modelos para todos os pontos finais de modelos:

  SELECT * FROM google_ml.model_info_view;

Secrets

Use esta referência para compreender os parâmetros das funções que lhe permitem gerir segredos.

Função google_ml.create_sm_secret()

O exemplo seguinte mostra como chamar a função SQL google_ml.create_sm_secret() usada para adicionar o segredo 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 define e que é usado posteriormente quando regista um ponto final do modelo.
PROJECT_ID O ID do seu Google Cloud projeto que contém o segredo. Este projeto pode ser diferente do projeto que contém o seu cluster do AlloyDB for PostgreSQL.

Para o AlloyDB Omni, o ID do seu Google Cloud projeto que contém o segredo.
SECRET_MANAGER_SECRET_ID O ID do Secret definido no Secret Manager quando criou o Secret.
VERSION_NUMBER O número da versão do ID do Secret.

Função google_ml.alter_sm_secret()

O exemplo seguinte mostra 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 obter informações sobre os valores que tem de definir para cada parâmetro, consulte o artigo Crie um segredo.

Função google_ml.drop_sm_secret()

O exemplo seguinte mostra como chamar a função SQL google_ml.drop_sm_secret()usada para eliminar um segredo:

  CALL google_ml.drop_sm_secret('SECRET_ID');
Parâmetro Descrição
SECRET_ID O ID secreto que definiu e que foi usado posteriormente quando registou um ponto final do modelo.

Funções de previsão

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

Função google_ml.embedding()

O exemplo seguinte mostra como gerar incorporações:

SELECT
  google_ml.embedding(
    model_id => 'MODEL_ID',
    contents => 'CONTENT');
Parâmetro Descrição
MODEL_ID Um ID exclusivo para o ponto final do modelo que definir.
CONTENT O texto a traduzir numa incorporação vetorial.

Função google_ml.predict_row()

O exemplo seguinte mostra 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 ponto final do modelo que definir.
REQUEST_BODY Os parâmetros da função de previsão, no formato JSON.

Funções de transformação

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

Função de transformação de entrada

Segue-se a assinatura da função de previsão para os pontos finais do 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 ponto final do modelo.

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

Segue-se a assinatura da função de previsão para os pontos finais do 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 ponto final do modelo na saída da função de previsão.

Exemplo de funções de transformação

Para compreender melhor como criar funções de transformação para o ponto final do seu modelo, considere um ponto final de modelo de incorporação de texto alojado de forma personalizada que requer entrada e saída JSON.

O exemplo de pedido cURL seguinte cria incorporações com base no comando e no ponto final do modelo:

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

É devolvida a seguinte resposta de exemplo:

[[ 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 nesta entrada e resposta, podemos inferir o seguinte:

  • O modelo espera uma entrada JSON através do campo prompt. Este campo aceita uma matriz de entradas. Como a função google_ml.embedding() é uma função ao nível da linha, espera uma entrada de texto de cada vez. Assim,tem de criar uma função de transformação de entrada que crie uma matriz com um único elemento.

  • A resposta do modelo é uma matriz de incorporações, uma para cada comando introduzido no modelo. Como a função google_ml.embedding() é uma função ao nível da linha, devolve uma única entrada de cada vez. Assim, tem de criar uma função de transformação de saída que possa ser usada para extrair a incorporação da matriz.

O exemplo seguinte mostra as funções de transformação de entrada e saída que são usadas para este ponto final do modelo quando é registado na gestão de pontos finais do 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

Segue-se a assinatura da função de geração de cabeçalhos que pode ser usada com a função de previsão google_ml.embedding() quando regista outros pontos finais do modelo de incorporação 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 pode transmitir o cabeçalho de autorização gerado pela função de geração de cabeçalhos ao registar o ponto final do modelo.

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

Para compreender melhor como criar uma função que gera resultados em pares de valores-chave JSON que são usados como cabeçalhos HTTP, considere um ponto final de modelo de incorporação de texto alojado personalizado.

O exemplo de pedido cURL seguinte transmite o cabeçalho HTTP version, que é usado pelo ponto final 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 uma entrada de texto através do campo version e devolve o valor da versão no formato JSON. O exemplo seguinte mostra a função de geração de cabeçalhos que é usada para este ponto final do modelo de incorporação de texto quando é registado na gestão de pontos finais do 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çalhos com a chave da API

Os exemplos seguintes mostram como configurar a autenticação através da chave da API.

modelo de incorporação

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 API do fornecedor 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 API do fornecedor do modelo.

Geração de URL de pedido

Use a função de geração de URLs de pedidos para inferir os URLs de pedidos para os pontos finais do modelo com suporte incorporado. A seguinte imagem mostra 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 pedido gerado pela extensão para pontos finais de modelos com suporte integrado.

Modelos suportados

Pode usar a gestão de pontos finais de modelos para registar qualquer incorporação de texto ou ponto final de modelo genérico. A gestão de pontos finais de modelos também inclui modelos do Vertex AI pré-registados e modelos com compatibilidade incorporada.

Modelos do Vertex AI pré-registados

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 posterior
text_embedding
  • textembedding-gecko
  • text-embedding-gecko@001
 versão 1.3 e posteriores

Modelos com suporte integrado

Vertex AI

Nome do modelo qualificado 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