Esta página documenta a versão 16.3.0 do AlloyDB Omni usando a opção de implantação de contêineres. Escolha outra opção de implantação.

Esta página foi traduzida pela API Cloud Translation.

Referência de gestão de pontos finais de modelos

Selecione uma versão da documentação:

Esta página apresenta uma lista de parâmetros para 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.

Para mais informações, consulte o artigo Use a gestão de pontos finais de modelos com o AlloyDB Omni para modelos de IA.

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 ver uma lista de URLs de pedidos para pontos finais de modelos da Vertex AI, consulte o artigo URL de pedidos de pontos finais de modelos da Vertex AI. 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 AlloyDB 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 `open_ai` para pontos finais de modelos da OpenAI `hugging_face` para pontos finais do modelo Hugging Face `anthropic` para pontos finais do modelo da Anthropic `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. Para os nomes qualificados da Vertex AI que tem de usar para modelos pré-registados, consulte o artigo Modelos da Vertex AI pré-registados. Para os nomes qualificados que tem de usar para modelos da OpenAI com suporte integrado, consulte o artigo Modelos 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. Para os modelos da Anthropic, a gestão de pontos finais de modelos oferece uma função `google_ml.anthropic_claude_header_gen_fn` que pode usar para versões predefinidas. A assinatura desta função depende da função de previsão que usa. Consulte a função de geração de cabeçalhos.
`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. Consulte Funções de transformação.
`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. Consulte Funções de transformaçã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.
`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.

Para ver exemplos de consultas SQL para gerar incorporações de texto, consulte os exemplos de funções de transformação para o AlloyDB Omni.

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.

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

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', 'anthropic-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. Para mais informações sobre os diferentes tipos de modelos, consulte Tipo de modelo.

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-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`