Esta página foi traduzida pela API Cloud Translation.

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

MySQL | PostgreSQL | SQL Server

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. A página também apresenta os segredos que pode gerir através da gestão de endpoints de modelos. Para usar modelos de IA em ambientes de produção, consulte o artigo Crie aplicações de IA generativa com o Cloud SQL.

Modelos

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

`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 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. 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 através da Internet.
`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`. Para o Cloud SQL, defina o fornecedor como `google` para pontos finais de modelos da Vertex AI, `open_ai` para pontos finais de modelos da OpenAI, `anthropic` para pontos finais de modelos da Anthropic, `hugging_face` para pontos finais de modelos da Hugging Face ou `custom` para pontos finais de modelos alojados personalizados.
`MODEL_TYPE`	Opcional para endpoints de modelos genéricos	O tipo de modelo. Pode definir este valor como `text_embedding` para os pontos finais do modelo de incorporação de texto ou `generic` para todos os outros pontos finais do modelo.
`MODEL_QUALIFIED_NAME`	Obrigatório para pontos finais de modelos da OpenAI; opcional para outros pontos finais de modelos	O nome totalmente qualificado, caso o ponto final do modelo tenha várias versões ou se o ponto final do modelo o definir, por exemplo, `textembedding-gecko@001` ou `textembedding-gecko@002`. Uma vez que o modelo `textembedding-gecko@001` está pré-registado na gestão de pontos finais de modelos, pode gerar incorporações usando `textembedding-gecko@001` como ID do modelo.
`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 `cloudsql_service_agent_iam` para modelos do Vertex AI ou `secret_manager` para outros fornecedores.
`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 define para gerar cabeçalhos personalizados. A assinatura desta função depende da função `google_ml.predict_row()`. Consulte a função de geração de cabeçalhos HTTP.
`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');

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

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

`google_ml.model_info_view`

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.

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

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

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

`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 define e que é usado posteriormente quando regista 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.

`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 a secção Exemplos.

`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 a secção Exemplos.

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 seguinte exemplo de pedido curl 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": ["Cloud SQL 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, pode 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

A seguinte imagem mostra 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": ["Cloud SQL 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:

sql
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 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.

Referência de gestão de pontos finais de modelos Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Modelos

google_ml.create_model()

google_ml.alter_model()

google_ml.drop_model()

google_ml.list_model()

google_ml.model_info_view