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

Pré-visualização

Este produto está sujeito aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. Os produtos pré-GA estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

MySQL   |  PostgreSQL   |  SQL Server

Esta página apresenta os parâmetros de diferentes funções fornecidas pelo Cloud SQL 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.

Nota: para mais informações sobre a gestão de pontos finais de modelos, consulte o artigo Registe e chame modelos de IA remotos no Cloud SQL.

Modelos

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

mysql.ml_create_model_registration()

O exemplo seguinte mostra como usar a função mysql.ml_create_model_registration() para registar metadados de pontos finais de modelos:

  CALL
    mysql.ml_create_model_registration(
      'MODEL_ID',
      'REQUEST_URL',
      'PROVIDER_ID',
      'MODEL_TYPE',
      'MODEL_QUALIFIED_NAME',
      'AUTH_TYPE',
      'AUTH_ID',
      'GENERATE_HEADER_FUNCTION',
      'INPUT_TRANSFORM_FUNCTION',
      'OUTPUT_TRANSFORM_FUNCTION');

Parâmetro	Obrigatória	Descrição
MODEL_ID	Obrigatório para todos os pontos finais de modelos	Um ID exclusivo para o ponto final do modelo que definir.
REQUEST_URL	Pode ser NULL para modelos do Vertex AI	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	Pode ser NULL para pontos finais 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 do modelo OpenAI; pode ser NULL para outros pontos finais do modelo	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	Pode ser NULL, 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 auth_type_cloudsql_service_agent_iam para modelos do Vertex AI ou auth_type_secret_manager para outros fornecedores.
AUTH_ID	Transmita como NULL para pontos finais da Vertex AI; obrigatório para todos os outros pontos finais 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	Pode ser NULL	O nome da função que define para gerar cabeçalhos personalizados. A assinatura desta função depende da função mysql.ml_predict_row(). Consulte a função de geração de cabeçalhos HTTP.
INPUT_TRANSFORM_FUNCTION	Opcional para pontos finais de modelos de incorporação de texto com suporte integrado; não defina para pontos finais de modelos 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 pontos finais de modelos de incorporação de texto com suporte integrado; não defina para pontos finais de modelos 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.

mysql.ml_alter_model_registration()

O exemplo seguinte mostra como chamar a função SQL mysql.ml_alter_model_registration() usada para atualizar os metadados do endpoint do modelo:

    CALL
    mysql.ml_alter_model_registration(
      'MODEL_ID',
      'REQUEST_URL',
      'PROVIDER_ID',
      'MODEL_TYPE',
      'MODEL_QUALIFIED_NAME',
      'AUTH_TYPE',
      'AUTH_ID',
      'GENERATE_HEADER_FUNCTION',
      'INPUT_TRANSFORM_FUNCTION',
      'OUTPUT_TRANSFORM_FUNCTION');

mysql.ml_drop_model_registration()

O exemplo seguinte mostra como chamar a função SQL mysql.ml_drop_model_registration() usada para eliminar um ponto final do modelo:

  CALL mysql.ml_drop_model_registration('MODEL_ID');

Parâmetro	Descrição
MODEL_ID	Um ID exclusivo para o ponto final do modelo que definir.

mysql.ml_list_registered_model()

O exemplo seguinte mostra como chamar a função SQL mysql.ml_list_registered_model() usada para listar informações do ponto final do modelo:

  SELECT mysql.ml_list_registered_model('MODEL_ID');

Parâmetro	Descrição
MODEL_ID	Um ID exclusivo para o ponto final do modelo que definir.

mysql.cloudsql_ml_models

O exemplo seguinte mostra como consultar a tabela mysql.cloudsql_ml_models que é usada para listar informações de pontos finais de modelos para todos os pontos finais de modelos:

  SELECT * FROM mysql.cloudsql_ml_models;

Secrets

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

mysql.ml_create_sm_secret_registration()

O exemplo seguinte mostra como chamar a função SQL mysql.ml_create_sm_secret_registration() usada para adicionar o segredo criado no Secret Manager:

    CALL
    mysql.ml_create_sm_secret_registration(
      'SECRET_ID',
      '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.

mysql.ml_alter_sm_secret_registration()

O exemplo seguinte mostra como chamar a função SQL mysql.ml_alter_sm_secret_registration() usada para atualizar informações secretas:

  CALL
    mysql.ml_alter_sm_secret_registration(
      'SECRET_ID',
      '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.

mysql.ml_drop_sm_secret_registration()

O exemplo seguinte mostra como chamar a função SQL mysql.ml_drop_sm_secret_registration()usada para eliminar um segredo:

  CALL mysql.ml_drop_sm_secret_registration('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.

mysql.ml_embedding()

O exemplo seguinte mostra como gerar incorporações:

SELECT
  mysql.ml_embedding(
    'MODEL_ID',
    '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.

mysql.ml_predict_row()

O exemplo seguinte mostra como invocar previsões:

SELECT
  mysql.ml_predict_row(
    'MODEL_ID',
    '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 FUNCTION IF NOT EXISTS
  INPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), input_text TEXT) RETURNS JSON DETERMINISTIC;

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 FUNCTION IF NOT EXISTS
  OUTPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), response_json JSON) RETURNS BLOB DETERMINISTIC;

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

DELIMITER $$
CREATE FUNCTION IF NOT EXISTS cymbal_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
DETERMINISTIC

BEGIN
  RETURN JSON_OBJECT('prompt', JSON_ARRAY(input_text));
END $$

função de transformação de saída

CREATE FUNCTION IF NOT EXISTS cymbal_text_output_transform(model_id VARCHAR(100), response_json JSON)
RETURNS BLOB
DETERMINISTIC

BEGIN
  RETURN STRING_TO_VECTOR(
         JSON_EXTRACT(
              content,
              '$.predictions[0].embeddings.values'
            )
    );

END $$
DELIMITER ;

HTTP header generation function

The following shows signature for the header generation function that can be used with the `mysql.ml_embedding()` prediction function when registering other text embedding model endpoints.

  CREATE FUNCTION IF NOT EXISTS GENERATE_HEADERS(model_id VARCHAR(100), input_text TEXT) RETURNS JSON DETERMINISTIC;

For the mysql.ml_predict_row() prediction function, the signature is as follows:

CREATE FUNCTION IF NOT EXISTS GENERATE_HEADERS(model_id TEXT, input JSON) RETURNS JSON DETERMINISTIC;

Parameter	Description
GENERATE_HEADERS	The function to generate custom headers. You can also pass the authorization header generated by the header generation function while registering the model endpoint.

Header generation function example

To better understand how to create a function that generates output in JSON key value pairs that are used as HTTP headers, consider a custom-hosted text embedding model endpoint.

The following example curl request passes the version HTTP header, which is used by the model endpoint:

  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"]}'

The model expects text input through the version field and returns the version value in JSON format. The following example shows the header generation function that is used for this text embedding model endpoint when it is registered with model endpoint management:

DELIMITER $$
CREATE FUNCTION IF NOT EXISTS header_gen_fn(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
DETERMINISTIC
BEGIN
  RETURN JSON_OBJECT('version', '2024-01-01');
END;
$$
DELIMITER ;