Referência de gerenciamento de endpoints de modelo

Prévia

Este produto está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os produtos pré-GA estão disponíveis no estado em que se encontram e podem ter suporte limitado. Você encontra mais detalhes nas descrições das fases de lançamento.

MySQL   |  PostgreSQL   |  SQL Server

Esta página lista parâmetros para diferentes funções fornecidas pela extensão google_ml_integration para registrar e gerenciar endpoints de modelo. A página também lista os secrets que podem ser gerenciados usando o gerenciamento de endpoints de modelo. Para usar modelos de IA em ambientes de produção, consulte Criar aplicativos de IA generativa usando o Cloud SQL.

Observação: antes de começar a usar a extensão para gerenciamento de endpoints de modelo, defina a flag de banco de dados google_ml_integration.enable_model_support como on. Para mais informações sobre o gerenciamento de endpoints de modelos, consulte Registrar e chamar modelos remotos de IA no Cloud SQL.

Modelos

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

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 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. 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 modelos personalizados hospedados, verifique se o endpoint do modelo está acessível pela Internet.
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. Para o Cloud SQL, defina o provedor como google para endpoints de modelo da Vertex AI, open_ai para endpoints de modelo da OpenAI, anthropic para endpoints de modelo da Anthropic, hugging_face para endpoints de modelo da Hugging Face ou custom para endpoints de modelo hospedados personalizados.
MODEL_TYPE	opcional para endpoints de modelos genéricos	O tipo de modelo. Defina esse valor como text_embedding para endpoints de modelo de embedding de texto ou generic para todos os outros endpoints de modelo.
MODEL_QUALIFIED_NAME	obrigatório para endpoints de modelos da OpenAI e opcional para outros endpoints de modelos	O nome totalmente qualificado caso o endpoint do modelo tenha várias versões ou se o endpoint do modelo o definir. Por exemplo, textembedding-gecko@001 ou textembedding-gecko@002. Como o modelo textembedding-gecko@001 está pré-registrado com o gerenciamento de endpoints de modelo, é possível gerar incorporações usando textembedding-gecko@001 como o ID do modelo.
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 cloudsql_service_agent_iam para modelos da Vertex AI ou secret_manager para outros provedores.
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 você definiu para gerar cabeçalhos personalizados. A assinatura dessa função depende da função google_ml.predict_row(). Consulte Função de geração de cabeçalho HTTP.
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 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');

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ê define.

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ê define.

google_ml.model_info_view

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.

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 a instância do Cloud SQL.
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.

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');

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 a instância do Cloud SQL.
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.

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ê define e que é 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.

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.

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 exemplos de consultas SQL que invocam previsões, consulte Exemplos.

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": ["Cloud SQL 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, é possível 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.

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": ["Cloud SQL 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;
$$;

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.