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

このページは Cloud Translation API によって翻訳されました。

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

このページでは、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` です。次のいずれかに設定します。 Vertex AI モデルエンドポイントの場合は `google` `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;

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

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

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

次の 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": ["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 個のビュー

Secret

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()` 関数

エンベディングモデル