google_ml_integration
para registrar e gerenciar endpoints de modelo e segredos com o 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.
Para mais informações, consulte Usar o gerenciamento de endpoints de modelo com o AlloyDB Omni para modelos de IA.
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 endpoints 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 embeddings de texto e endpoints de modelo genéricos. 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 conferir uma lista de URLs de solicitação para endpoints de modelo da Vertex AI, consulte URL de solicitação de endpoints de modelo da Vertex AI. Para endpoints de modelos hospedados de maneira personalizada, verifique se o endpoint do modelo está acessível na rede em que o AlloyDB 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 como um dos seguintes:
|
MODEL_TYPE |
opcional para endpoints de modelo genéricos | O tipo de modelo. Defina como uma das seguintes opções:
|
MODEL_QUALIFIED_NAME |
obrigatório para modelos de embedding de texto com suporte integrado; opcional para outros endpoints de modelo | O nome totalmente qualificado dos modelos de embedding de texto com suporte integrado. Para nomes qualificados da Vertex AI que precisam ser usados em modelos pré-registrados, consulte Modelos pré-registrados da Vertex AI. Para nomes qualificados que precisam ser usados em 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. 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ê definiu e que é usado posteriormente 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 endpoints de modelo oferece 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 que você usa. 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é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 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. Consulte Funções de transformação. |
google_ml.alter_model()
Confira a seguir como chamar a função SQL google_ml.alter_model()
usada
para atualizar metadados de endpoint de 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()
A seguir, mostramos 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
, que é
usada para listar informações de endpoints de modelo para todos os endpoints:
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 Gerenciador de secrets:
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ê definiu e que é usado posteriormente ao registrar um endpoint de modelo. |
PROJECT_ID |
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. |
Para exemplos de consultas SQL que geram embeddings de texto, consulte Exemplos de funções de transformação para o 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 para a função de previsão, no formato JSON. |
Para exemplos de consultas SQL que invocam previsões, consulte Exemplos para o 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
Confira a assinatura da função de previsão para endpoints de modelo de embedding 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
Confira a assinatura da função de previsão para endpoints de modelo de embedding 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 maneira personalizada que exija 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çãogoogle_ml.embedding()
é uma função de nível de linha, ela espera uma entrada de texto por vez. Portanto,você precisa 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 com o 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
Confira 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 de modelo de embedding de texto quando ele é registrado com o 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', 'anthropic-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 de modelo com suporte integrado. Confira 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 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 embedding de texto. O gerenciamento de endpoints de modelo também inclui modelos pré-registrados da Vertex AI e modelos com suporte integrado. Para mais informações sobre diferentes tipos de modelos, consulte Tipo de modelo.
Modelos pré-registrados da Vertex AI
Tipo de modelo | ID do modelo | Versão da extensão |
---|---|---|
generic |
|
versão 1.4.2 e mais recentes |
text_embedding |
|
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-005 |
text-embedding |
text-embedding-preview-0815 |
text-embedding |
text-multilingual-embedding-002 |
text-embedding |
OpenAI
Nome qualificado do modelo | Tipo de modelo |
---|---|
text-embedding-ada-002 |
text-embedding |
text-embedding-3-small |
text-embedding |
text-embedding-3-large |
text-embedding |
Anthropic
Nome qualificado do modelo | Tipo de modelo |
---|---|
claude-3-opus-20240229 |
generic |
claude-3-sonnet-20240229 |
generic |
claude-3-haiku-20240307 |
generic |