モデルのエンドポイント管理のリファレンス

このページでは、モデル エンドポイントを登録して管理するために Cloud SQL によって提供されるさまざまな関数のパラメータについて説明します。このページには、モデル エンドポイント管理を使用して管理できるシークレットも示します。

モデル

このリファレンスでは、モデル エンドポイントを管理できる関数のパラメータについて説明します。

mysql.ml_create_model_registration()

次の例は、mysql.ml_create_model_registration() 関数を使用してモデル エンドポイント メタデータを登録する方法を示しています。

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

mysql.ml_alter_model_registration()

次の例は、モデル エンドポイント メタデータの更新に使用される mysql.ml_alter_model_registration() SQL 関数を呼び出す方法を示しています。

    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()

次のコードは、モデル エンドポイントの削除に使用される mysql.ml_drop_model_registration() SQL 関数を呼び出す方法を示しています。

  CALL mysql.ml_drop_model_registration('MODEL_ID');

mysql.ml_list_registered_model()

次の例は、モデル エンドポイント情報の一覧取得に使用される mysql.ml_list_registered_model() SQL 関数を呼び出す方法を示しています。

  SELECT mysql.ml_list_registered_model('MODEL_ID');

mysql.cloudsql_ml_models

次の例は、すべてのモデル エンドポイントのモデル エンドポイント情報を一覧取得するための mysql.cloudsql_ml_models テーブルをクエリする方法を示しています。

  SELECT * FROM mysql.cloudsql_ml_models;

Secret

このリファレンスでは、シークレットを管理できる関数のパラメータについて説明します。

mysql.ml_create_sm_secret_registration()

次の例は、Secret Manager で作成されたシークレットを追加するための mysql.ml_create_sm_secret_registration() SQL 関数を呼び出す方法を示しています。

    CALL
    mysql.ml_create_sm_secret_registration(
      'SECRET_ID',
      'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

mysql.ml_alter_sm_secret_registration()

次の例は、シークレット情報の更新に使用される mysql.ml_alter_sm_secret_registration() SQL 関数を呼び出す方法を示しています。

  CALL
    mysql.ml_alter_sm_secret_registration(
      'SECRET_ID',
      'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

mysql.ml_drop_sm_secret_registration()

次の例は、シークレットの削除に使用される mysql.ml_drop_sm_secret_registration() SQL 関数を呼び出す方法を示しています。

  CALL mysql.ml_drop_sm_secret_registration('SECRET_ID');

予測関数

このリファレンスでは、エンベディングの生成や予測の呼び出しを行う関数のパラメータについて説明します。

mysql.ml_embedding()

エンベディングの生成方法は次のとおりです。

SELECT
  mysql.ml_embedding(
    'MODEL_ID',
    'CONTENT');

テキスト エンベディングを生成する SQL クエリの例については、例をご覧ください。

mysql.ml_predict_row()

予測を呼び出す方法は次のとおりです。

SELECT
  mysql.ml_predict_row(
    'MODEL_ID',
    'REQUEST_BODY');

予測を呼び出す SQL クエリの例については、例をご覧ください。

変換関数

このリファレンスでは、入力変換関数と出力変換関数のパラメータについて説明します。

入力変換関数

次のコードは、テキスト エンベディング モデル エンドポイントの予測関数の署名を示しています。

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

出力変換関数

次のコードは、テキスト エンベディング モデル エンドポイントの予測関数の署名を示しています。

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

変換関数の例

モデル エンドポイントの変換関数の作成方法について理解を深めるため、JSON の入力と出力を必要とするカスタムホスト型のテキスト エンベディング モデル エンドポイントについて考えてみましょう。

次の curl リクエストの例では、プロンプトとモデル エンドポイントに基づいてエンベディングを作成します。

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
    -H "Content-Type: application/json"
    -d '{"prompt": ["Cloud SQL Embeddings"]}'

次のようなレスポンスが返されます。

[[ 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]]

この入力とレスポンスから、次のことがわかります。

• このモデルは、prompt フィールドを介して JSON 入力を受け取ることを想定しています。このフィールドには入力の配列を指定できます。mysql.ml_embedding() 関数は行レベルの関数であるため、一度に 1 つのテキスト入力を想定しています。そのため、単一要素の配列を作成する入力変換関数を作成する必要があります。

• モデルからのレスポンスはエンベディングの配列で、モデルに入力されたプロンプトごとに 1 つずつ返されます。mysql.ml_embedding() 関数は行レベルの関数であるため、一度に 1 つの入力を返します。そのため、配列からエンベディングを抽出するための出力変換関数を作成する必要があります。

次の例は、モデル エンドポイント管理に登録するときに、このモデル エンドポイントに使用される入力変換関数と出力変換関数を示しています。

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

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;

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 ;