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

プレビュー

このプロダクトには、サービス固有の利用規約の「一般的なサービス規約」の「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;

Secret

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

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 の作成時に Secret Manager で設定した Secret ID。
VERSION_NUMBER	Secret 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 の作成時に Secret Manager で設定した Secret ID。
VERSION_NUMBER	Secret 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 キー値ペアで出力を生成する関数を作成する方法を詳しく理解するには、カスタム ホストされたテキスト エンベディング モデル エンドポイントを検討してください。

次の 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 を生成する関数。