このページでは、AlloyDB Omni バージョン 15.7.0 について説明します。別のバージョンのドキュメントを選択する。

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

このページでは、モデルエンドポイントを登録および管理するために google_ml_integration 拡張機能によって提供されるさまざまな関数のパラメータと、シークレットおよびモデルエンドポイントの管理について説明します。

この拡張機能の使用を開始する前に、データベースフラグ google_ml_integration.enable_model_support を on に設定する必要があります。

詳細については、AlloyDB Omni で 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`	組み込みサポートのある他のテキストエンベディングモデルエンドポイントの場合は省略可	他のテキストエンベディングエンドポイントと汎用モデルエンドポイントを追加する場合のモデル固有のエンドポイント。AlloyDB for PostgreSQL の場合は、`https` の URL を指定します。関数が組み込みモデルエンドポイント用に生成するリクエスト URL は、クラスタのプロジェクトとリージョン、またはロケーションを参照します。別のプロジェクトを参照する場合は、`model_request_url` を明示的に指定してください。 Vertex AI モデルエンドポイントのリクエスト URL の一覧については、Vertex AI モデルエンドポイントのリクエスト URL をご覧ください。セルフホスト型のモデルエンドポイントの場合は、AlloyDB が配置されているネットワークからそのモデルエンドポイントにアクセスできることを確認してください。
`PROVIDER_ID`	組み込みサポートのあるテキストエンベディングモデルエンドポイントの場合は必須	モデルエンドポイントのプロバイダ。デフォルト値は `custom` です。次のいずれかに設定します。 `google`（Vertex AI モデルエンドポイントの場合） `open_ai`（OpenAI モデルエンドポイントの場合） `hugging_face`（Hugging Face モデルエンドポイントの場合） `anthropic`（Anthropic モデルエンドポイントの場合） `custom`（他のプロバイダの場合）
`MODEL_TYPE`	汎用モデルエンドポイントの場合は省略可	モデルタイプ。次のいずれかに設定します。 `text_embedding`（テキストエンベディングモデルエンドポイントの場合） `generic`（他のすべてのモデルエンドポイントの場合）
`MODEL_QUALIFIED_NAME`	組み込みサポートのあるテキストエンベディングモデルの場合は必須、他のモデルエンドポイントの場合は省略可	組み込みサポートのあるテキストエンベディングモデルの完全修飾名。事前登録済みモデルに使用する必要がある Vertex AI 修飾名については、事前登録済みの Vertex AI モデルをご覧ください。組み込みサポートのある OpenAI モデルに使用する必要がある修飾名については、組み込みサポートのあるモデルをご覧ください。
`AUTH_TYPE`	モデルエンドポイントに特定の認証要件がない限り省略可	モデルエンドポイントで使用される認証タイプ。 Vertex AI モデルの場合は `alloydb_service_agent_iam`、他のプロバイダの場合は `secret_manager` に設定できます（認証に Secret Manager を使用している場合）。認証ヘッダーを使用している場合、この値を設定する必要はありません。
`AUTH_ID`	Vertex AI モデルエンドポイントの場合は設定しない。Secret Manager にシークレットを保存する他のモデルエンドポイントの場合は必須	ユーザーが設定し、モデルエンドポイントの登録時に使用したシークレット ID。
`GENERATE_HEADER_FUNCTION`	オプション	カスタムヘッダーを生成する関数の名前。 Anthropic モデルの場合、デフォルトバージョンに使用できる `google_ml.anthropic_claude_header_gen_fn` 関数がモデルエンドポイント管理に用意されています。この関数の署名は、使用する予測関数によって異なります。ヘッダー生成関数をご覧ください。
`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。
`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');

各パラメータに設定する必要がある値については、シークレットを作成するをご覧ください。

`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 クエリの例については、AlloyDB Omni 用の変換関数の例をご覧ください。

`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": ["AlloyDB 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 リクエストの例では、モデルエンドポイントで使用される HTTP ヘッダー version を渡します。

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
      -H "Content-Type: application/json" \
      -H "version: 2024-01-01" \
      -d '{"prompt": ["AlloyDB 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;
$$;

API キーを使用するヘッダー生成関数

次の例は、API キーを使用する認証の設定方法を示しています。

エンベディングモデル

CREATE OR REPLACE FUNCTION header_gen_func(
  model_id VARCHAR(100),
  input_text TEXT
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
BEGIN
  RETURN json_build_object('Authorization', 'API_KEY')::JSON;
END;
$$;

API_KEY は、モデルプロバイダの API キーに置き換えます。

汎用モデル

CREATE OR REPLACE FUNCTION header_gen_func(
  model_id VARCHAR(100),
  response_json JSON
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
DECLARE
transformed_output REAL[];
BEGIN
  -- code to add Auth token to API request
RETURN json_build_object('x-api-key', 'API_KEY', 'anthropic-version', '2023-06-01')::JSON;
END;
$$;

API_KEY は、モデルプロバイダの API キーに置き換えます。

リクエスト 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 を生成する関数。

サポートされているモデル

モデルエンドポイント管理には任意のテキストエンベディングモデルエンドポイントと汎用モデルエンドポイントを登録でき、事前登録済みの Vertex AI モデルと組み込みサポートのあるモデルも含まれています。さまざまなモデルタイプの詳細については、モデルタイプをご覧ください。

事前登録済みの Vertex AI モデル

モデルタイプ	モデル ID	拡張機能のバージョン
`generic`	`gemini-1.5-pro:streamGenerateContent` `gemini-1.5-pro:generateContent` `gemini-1.0-pro:generateContent`	バージョン 1.4.2 以降
`text_embedding`	`textembedding-gecko` `text-embedding-gecko@001`	バージョン 1.3 以降

サポートが組み込まれたモデル

Vertex AI

修飾モデル名	モデルタイプ
`text-embedding-gecko@001`	`text-embedding`
`text-embedding-gecko@003`	`text-embedding`
`text-embedding-004`	`text-embedding`
`text-embedding-005`	`text-embedding`
`text-embedding-preview-0815`	`text-embedding`
`text-multilingual-embedding-002`	`text-embedding`

OpenAI

修飾モデル名	モデルタイプ
`text-embedding-ada-002`	`text-embedding`
`text-embedding-3-small`	`text-embedding`
`text-embedding-3-large`	`text-embedding`

Anthropic

修飾モデル名	モデルタイプ
`claude-3-opus-20240229`	`generic`
`claude-3-sonnet-20240229`	`generic`
`claude-3-haiku-20240307`	`generic`

モデルのエンドポイント管理のリファレンス コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

モデル

google_ml.create_model() 関数

google_ml.alter_model()

google_ml.drop_model() 関数

google_ml.list_model() 関数

google_ml.model_info_view 個のビュー

シークレット

google_ml.create_sm_secret() 関数

google_ml.alter_sm_secret() 関数

google_ml.drop_sm_secret() 関数

予測関数

google_ml.embedding() 関数

google_ml.predict_row() 関数

変換関数

入力変換関数

出力変換関数

変換関数の例

入力変換関数

出力変換関数

HTTP ヘッダー生成関数

ヘッダー生成関数の例

API キーを使用するヘッダー生成関数

エンベディング モデル

汎用モデル

リクエスト URL の生成

サポートされているモデル

事前登録済みの Vertex AI モデル

サポートが組み込まれたモデル

Vertex AI

OpenAI

Anthropic

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

`google_ml.create_model()` 関数

`google_ml.alter_model()`

`google_ml.drop_model()` 関数

`google_ml.list_model()` 関数

`google_ml.model_info_view` 個のビュー

`google_ml.create_sm_secret()` 関数

`google_ml.alter_sm_secret()` 関数

`google_ml.drop_sm_secret()` 関数

`google_ml.embedding()` 関数

`google_ml.predict_row()` 関数

エンベディングモデル