Esta página mostra a documentação da versão 15.7.0 do AlloyDB Omni.
Acesse Versões da documentação do AlloyDB Omni para escolher uma versão diferente.

Esta página foi traduzida pela API Cloud Translation.

Referência de gerenciamento de endpoints de modelo

Esta página lista parâmetros para diferentes funções fornecidas pela extensão google_ml_integration para registrar e gerenciar endpoints de modelo e segredos com gerenciamento de endpoint de modelo.

É necessário definir a flag do banco de dados google_ml_integration.enable_model_support como on antes de começar a usar a extensão.

Para mais informações, consulte Usar o gerenciamento de endpoint de modelo com o AlloyDB Omni para modelos de IA.

Modelos

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

Função `google_ml.create_model()`

O exemplo a seguir mostra 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 modelos genéricos. Para o AlloyDB para PostgreSQL, forneça um URL `https`. O URL da 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 conferir uma lista de URLs de solicitação de endpoints de modelos da Vertex AI, consulte URL de solicitação de endpoints de modelos da Vertex AI. Para endpoints de modelo hospedados personalizados, verifique se o endpoint do modelo pode ser acessado pela rede em que o AlloyDB está localizado.
`PROVIDER_ID`	obrigatório para endpoints de modelos de embedding de texto com suporte integrado	O provedor do endpoint do modelo. O valor padrão é `custom`. Defina como uma das seguintes opções: `google` para endpoints de modelo da Vertex AI `open_ai` para endpoints de modelos da OpenAI `hugging_face` para endpoints de modelos do Hugging Face `anthropic` para endpoints de modelo da Anthropic `custom` para outros provedores
`MODEL_TYPE`	opcional para endpoints de modelo genéricos	O tipo de modelo. Defina como um dos seguintes: `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. Para nomes qualificados da Vertex AI que você precisa usar para modelos pré-registrados, consulte Modelos pré-registrados da Vertex AI. Para nomes qualificados que você precisa usar para modelos da OpenAI com suporte integrado, consulte Modelos 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. É possível definir como `alloydb_service_agent_iam` para modelos da Vertex AI ou `secret_manager` para outros provedores, se eles usam 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 são definidos para endpoints de modelo da Vertex AI; obrigatório para todos os outros endpoints de modelo que armazenam segredos no Secret Manager	O ID secreto que você define e é usado ao registrar um endpoint de modelo.
`GENERATE_HEADER_FUNCTION`	opcional	O nome da função que gera cabeçalhos personalizados. Para modelos da Anthropic, o gerenciamento de endpoint do modelo fornece uma função `google_ml.anthropic_claude_header_gen_fn` que pode ser usada para versões padrão. A assinatura dessa função depende da função de previsão usada. Consulte Função de geração de cabeçalho.
`INPUT_TRANSFORM_FUNCTION`	Opcional para endpoints de modelo de embedding de texto com suporte integrado. Não defina para endpoints de modelo genéricos.	A função para transformar a entrada da função de previsão correspondente na entrada específica do modelo. Consulte Funções de transformação.
`OUTPUT_TRANSFORM_FUNCTION`	Opcional para endpoints de modelo de embedding de texto com suporte integrado. Não defina para endpoints de modelo genéricos.	A função para transformar a saída específica do modelo na saída da função de previsão. Consulte Funções de transformação.

`google_ml.alter_model()`

O exemplo a seguir 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 saber quais valores você precisa definir para cada parâmetro, consulte Criar um modelo.

Função `google_ml.drop_model()`

O exemplo a seguir mostra 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()`

O exemplo a seguir mostra 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

Confira a seguir como chamar a visualização google_ml.model_info_view, que é usada para listar informações de endpoint 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 de funções que permitem gerenciar segredos.

Função `google_ml.create_sm_secret()`

Confira a seguir 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 é usado ao registrar um endpoint de modelo.
`PROJECT_ID`	O ID do projeto do Google Cloud que contém o segredo.
`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()`

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

  CALL google_ml.drop_sm_secret('SECRET_ID');

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

Funções de previsão

Use esta referência para entender os parâmetros de 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.

Para consultas SQL de exemplo para gerar embeddings de texto, consulte Exemplos de função de transformação para AlloyDB Omni.

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.

Para consultar exemplos de consultas SQL para invocar previsões, consulte Exemplos do AlloyDB Omni.

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 modelos 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 modelos 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 de forma personalizada que exija entrada e saída JSON.

O exemplo de solicitação cURL abaixo 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 resposta de exemplo a seguir é 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 nesta 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, uma para cada entrada de comando no modelo. Como a função google_ml.embedding() é uma função de linha, ela retorna uma única entrada por vez. Portanto, é necessário criar uma função de transformação de saída que possa ser usada para extrair a incorporação do array.

O exemplo a seguir mostra as funções de transformação de entrada e saída que são usadas para esse endpoint de modelo quando ele é registrado com o gerenciamento de endpoint 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

O exemplo a seguir mostra 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 é esta:

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 que são usados como cabeçalhos HTTP, considere um endpoint de modelo de incorporação de texto hospedado de forma personalizada.

O exemplo de solicitação cURL 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 a 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 este endpoint de modelo de embedding de texto quando ele é registrado com o gerenciamento de endpoint 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 a 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 de 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', 'anthropic-version', '2023-06-01')::JSON;
END;
$$;

Substitua API_KEY pela chave de API do provedor de modelo.

Geração de URL da 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 seguir a assinatura dessa 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 da 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 inserção de texto ou endpoint de modelo genérico. O gerenciamento de endpoints de modelos também inclui modelos pré-registrados da Vertex AI e modelos com suporte integrado. Para mais informações sobre os diferentes tipos de modelos, consulte Tipo de modelo.

Modelos pré-registrados do 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 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-005`	`text-embedding`
`text-embedding-preview-0815`	`text-embedding`
`text-multilingual-embedding-002`	`text-embedding`

OpenAI

Nome do modelo qualificado	Tipo de modelo
`text-embedding-ada-002`	`text-embedding`
`text-embedding-3-small`	`text-embedding`
`text-embedding-3-large`	`text-embedding`

Anthropic

Nome do modelo qualificado	Tipo de modelo
`claude-3-opus-20240229`	`generic`
`claude-3-sonnet-20240229`	`generic`
`claude-3-haiku-20240307`	`generic`