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

プレビュー版

このプロダクトは、サービス固有の規約の「一般サービス規約」セクションの「pre-GA サービス規約」の対象となります。 pre-GA のプロダクトは「現状のまま」利用できますが、サポートが制限されることがあります。 詳細については、リリース ステージの説明をご覧ください。

MySQL   |  PostgreSQL   |  SQL Server

このページでは、モデル エンドポイントを登録して管理するために google_ml_integration 拡張機能によって提供されるさまざまな関数のパラメータについて説明します。このページには、モデル エンドポイント管理を使用して管理できるシークレットも示します。本番環境で AI モデルを使用するには、Cloud SQL を使用して生成 AI アプリケーションを作成するをご覧ください。

注: モデル エンドポイント管理で拡張機能を使用するには、google_ml_integration.enable_model_support データベース フラグを on に設定する必要があります。また、モデル エンドポイント管理の詳細については、Cloud SQL でリモート AI モデルを登録して呼び出すをご覧ください。

モデル

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

google_ml.create_model()

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

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

パラメータ	必須	説明
MODEL_ID	すべてのモデル エンドポイントで必須	定義するモデル エンドポイントの一意の ID。
REQUEST_URL	組み込みサポートのあるテキスト エンベディング モデル エンドポイントの場合は省略可	他のテキスト エンベディング エンドポイントと汎用モデル エンドポイントを追加する場合のモデル固有のエンドポイント。 関数が組み込みモデル エンドポイント用に生成するリクエスト URL は、クラスタのプロジェクトとリージョンまたはロケーションを参照します。別のプロジェクトを参照する場合は、model_request_url を明示的に指定してください。 カスタムホスト型のモデル エンドポイントの場合は、モデル エンドポイントにインターネット経由でアクセスできることを確認します。
PROVIDER_ID	組み込みサポートのあるテキスト エンベディング モデル エンドポイントの場合は必須	モデル エンドポイントのプロバイダ。デフォルト値は custom です。Cloud SQL で、Vertex AI モデル エンドポイントの場合はプロバイダを google に設定します。OpenAI モデル エンドポイントの場合は open_ai、Anthropic モデル エンドポイントの場合は anthropic、Hugging Face モデル エンドポイントの場合は hugging_face、カスタム ホストモデル エンドポイントの場合は custom に設定します。
MODEL_TYPE	汎用モデル エンドポイントの場合は省略可	モデルタイプ。この値は、テキスト エンベディング モデル エンドポイントの場合は text_embedding、他のすべてのモデル エンドポイントの場合は generic に設定できます。
MODEL_QUALIFIED_NAME	OpenAI モデル エンドポイントの場合は必須、他のモデル エンドポイントでは省略可	モデル エンドポイントに複数のバージョンがある場合や、モデル エンドポイントが定義している場合は完全修飾名（例: textembedding-gecko@001、textembedding-gecko@002）。textembedding-gecko@001 モデルはモデル エンドポイント管理で事前登録されているため、モデル ID として textembedding-gecko@001 を使用してエンベディングを生成できます。
AUTH_TYPE	モデル エンドポイントに特定の認証要件がない限り省略可	モデル エンドポイントで使用される認証タイプ。Vertex AI モデルの場合は cloudsql_service_agent_iam、他のプロバイダの場合は secret_manager に設定できます。
AUTH_ID	Vertex AI モデル エンドポイントの場合は設定しない。Secret Manager にシークレットを保存する他のモデル エンドポイントの場合は必須	ユーザーが設定し、モデル エンドポイントの登録時に使用したシークレット ID。
GENERATE_HEADER_FUNCTION	オプション	カスタム ヘッダーの生成に設定した関数名。この関数の署名は google_ml.predict_row() 関数によって異なります。HTTP ヘッダー生成関数をご覧ください。
INPUT_TRANSFORM_FUNCTION	組み込みサポートのあるテキスト エンベディング モデル エンドポイントの場合は省略可。汎用モデル エンドポイントの場合は設定しない	対応する予測関数の入力をモデル固有の入力に変換する関数。変換関数をご覧ください。
OUTPUT_TRANSFORM_FUNCTION	組み込みサポートのあるテキスト エンベディング モデル エンドポイントの場合は省略可。汎用モデル エンドポイントの場合は設定しない	モデル固有の出力を予測関数出力に変換する関数。変換関数をご覧ください。

google_ml.alter_model()

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

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

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

  CALL google_ml.drop_model('MODEL_ID');

パラメータ	説明
MODEL_ID	定義するモデル エンドポイントの一意の ID。

google_ml.list_model()

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

  SELECT google_ml.list_model('MODEL_ID');

パラメータ	説明
MODEL_ID	定義するモデル エンドポイントの一意の ID。

google_ml.model_info_view

次の例は、すべてのモデル エンドポイントのモデル エンドポイント情報を一覧取得するための google_ml.model_info_view ビューを呼び出す方法を示しています。

  SELECT * FROM google_ml.model_info_view;

シークレット

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

google_ml.create_sm_secret()

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

    CALL
    google_ml.create_sm_secret(
      secret_id => 'SECRET_ID',
      secret_path => 'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

パラメータ	説明
SECRET_ID	ユーザーが設定し、モデル エンドポイントの登録時に使用したシークレット ID。
PROJECT_ID	シークレットを含む Google Cloud プロジェクトの ID。このプロジェクトは、Cloud SQL インスタンスを含むプロジェクトとは異なる場合があります。
SECRET_MANAGER_SECRET_ID	シークレットの作成時に Secret Manager で設定したシークレット ID。
VERSION_NUMBER	シークレット ID のバージョン番号。

google_ml.alter_sm_secret()

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

  CALL
    google_ml.alter_sm_secret(
      secret_id => 'SECRET_ID',
      secret_path => 'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

パラメータ	説明
SECRET_ID	ユーザーが設定し、モデル エンドポイントの登録時に使用したシークレット ID。
PROJECT_ID	シークレットを含む Google Cloud プロジェクトの ID。このプロジェクトは、Cloud SQL インスタンスを含むプロジェクトとは異なる場合があります。
SECRET_MANAGER_SECRET_ID	シークレットの作成時に Secret Manager で設定したシークレット ID。
VERSION_NUMBER	シークレット ID のバージョン番号。

google_ml.drop_sm_secret()

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

  CALL google_ml.drop_sm_secret('SECRET_ID');

パラメータ	説明
SECRET_ID	ユーザーが設定し、モデル エンドポイントの登録時に使用したシークレット ID。

予測関数

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

google_ml.embedding()

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

SELECT
  google_ml.embedding(
    model_id => 'MODEL_ID',
    contents => 'CONTENT');

パラメータ	説明
MODEL_ID	定義するモデル エンドポイントの一意の ID。
CONTENT	ベクトル エンベディングに変換するテキスト。

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

google_ml.predict_row()

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

SELECT
  google_ml.predict_row(
    model_id => 'MODEL_ID',
    request_body => 'REQUEST_BODY');

パラメータ	説明
MODEL_ID	定義するモデル エンドポイントの一意の ID。
REQUEST_BODY	JSON 形式の予測関数のパラメータ

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

変換関数

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

入力変換関数

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

  CREATE OR REPLACE FUNCTION INPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;

パラメータ	説明
INPUT_TRANSFORM_FUNCTION	対応する予測関数の入力をモデル エンドポイント固有の入力に変換する関数。

出力変換関数

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

  CREATE OR REPLACE FUNCTION OUTPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), response_json JSON) RETURNS real[];

パラメータ	説明
OUTPUT_TRANSFORM_FUNCTION	モデルのエンドポイント固有の出力を予測関数出力に変換する関数。

変換関数の例

モデル エンドポイントの変換関数の作成方法について理解を深めるため、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 入力を受け取ることを想定しています。このフィールドには入力の配列を指定できます。google_ml.embedding() 関数は行レベルの関数であるため、一度に 1 つのテキスト入力を想定しています。そのため、単一要素の配列を作成する入力変換関数を作成する必要があります。

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

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

入力変換関数

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

出力変換関数

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

HTTP ヘッダー生成関数

以下に、他のテキスト エンベディング モデル エンドポイントを登録するときに google_ml.embedding() 予測関数で使用できるヘッダー生成関数の署名を示します。

  CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;

google_ml.predict_row() 予測関数の署名は次のとおりです。

CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id TEXT, input JSON) RETURNS JSON;

パラメータ	説明
GENERATE_HEADERS	カスタム ヘッダーを生成する関数。モデル エンドポイントを登録するときに、ヘッダー生成関数によって生成された認可ヘッダーを渡すこともできます。

ヘッダー生成関数の例

HTTP ヘッダーとして使用される JSON Key-Value ペアで出力を生成する関数を作成する方法について理解を深めるため、カスタムホスト型のテキスト エンベディング モデル エンドポイントについて考えてみましょう。

次の cURL リクエストの例では、モデル エンドポイントで使用される version HTTP ヘッダーを渡します。

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

このモデルは、version フィールドを介してテキスト入力を受け取ることを想定しており、バージョンの値を JSON 形式で返します。次の例は、モデル エンドポイント管理に登録するときに、このテキスト エンベディング モデル エンドポイントで使用されるヘッダー生成関数を示しています。

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

リクエスト URL の生成

リクエスト URL 生成関数を使用して、組み込みサポートのあるモデル エンドポイントのリクエスト URL を推測します。この関数の署名は次のとおりです。

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)

パラメータ	説明
GENERATE_REQUEST_URL	組み込みサポートのあるモデル エンドポイント用に拡張機能が生成するリクエスト URL を生成する関数。