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

AlloyDB でモデルエンドポイントを使用してモデルを呼び出す

モデルエンドポイント管理のプレビュー版を使用すると、モデルエンドポイントを登録して、データベースクラスタでモデルエンドポイントのメタデータを管理し、SQL クエリでモデルを操作できます。これには google_ml_integration 拡張機能が用意されています。この機能により、モデルに関連するモデルエンドポイントメタデータを追加して登録する関数を実行できます。また、モデルを使用してベクトルエンベディングを生成したり、予測を呼び出すこともできます。

モデルエンドポイント管理を使用して登録できるモデルタイプの例を次に示します。

Vertex AI テキストエンベディングモデル
サードパーティプロバイダが提供するエンベディングモデル。
カスタムホスト型テキストエンベディングモデル
JSON ベースの API を使用した汎用モデル（Vertex AI Model Garden の gemini-pro モデルなど）

仕組み

モデルエンドポイント管理を使用すると、次の要件を満たすモデルエンドポイントを登録できます。

モデルの入力と出力は JSON 形式をサポートしています。
モデルは REST プロトコルを使用して呼び出すことができます。

モデルエンドポイントをモデルエンドポイント管理に登録すると、モデルへの参照として指定した一意のモデル ID を使用して各エンドポイントが登録されます。このモデル ID を使用してモデルをクエリできます。

エンベディングを生成して、テキストプロンプトを数値ベクトルに変換します。データベースで pgvector 拡張機能が有効になっている場合、生成されたエンベディングをベクトルデータとして保存できます。
予測を呼び出し、トランザクション内で SQL を使用してモデルを呼び出します。

アプリケーションは、google_ml_integration 拡張機能を使用してモデルエンドポイント管理にアクセスできます。この拡張機能では、次の関数を使用できます。

google_ml.create_model() SQL 関数。予測関数またはエンベディング関数で使用されるモデルエンドポイントを登録するために使用されます。
google_ml.create_sm_secret() SQL 関数。API キーが保存されている Google CloudSecret Manager のシークレットを使用します。
google_ml.embedding() SQL 関数。テキストエンベディングを生成する予測関数です。
JSON の入力形式と出力形式をサポートする汎用モデルを呼び出すときに予測を生成する google_ml.predict_row() SQL 関数。
汎用モデルでカスタム URL の生成、HTTP ヘッダーの生成、変換関数の渡しを処理するその他のヘルパー関数。
登録されたモデルエンドポイントとシークレットを管理する関数。

主なコンセプト

モデルエンドポイント管理を使い始める前に、モデルに接続して使用するために必要なコンセプトを理解しておく必要があります。

モデルプロバイダ

モデルプロバイダは、サポートされているモデルのホスティングプロバイダです。次の表に、使用するモデルプロバイダごとに設定が必要なモデルプロバイダの値を示します。

モデルプロバイダ	関数での設定…
Vertex AI	`google`
その他のモデル	`custom`

デフォルトのモデルプロバイダは custom です。

サポートされている認証方法は、プロバイダのタイプによって異なります。Vertex AI モデルは Distributed Cloud サービスアカウントを使用して認証を行いますが、他のプロバイダは Secret Manager を使用して認証できます。

モデルタイプ

モデルタイプは、AI モデルのタイプを示します。この拡張機能は、テキストエンベディングと任意の汎用モデルタイプをサポートしています。モデルエンドポイントの登録時に設定できるサポート対象のモデルタイプは、text-embedding と generic です。generic がデフォルトのモデルタイプであるため、汎用モデルエンドポイントを登録する場合、モデルタイプの設定は省略可能です。

サポートが組み込まれたテキストエンベディングモデル: モデルエンドポイント管理では、Vertex AI の textembedding-gecko モデルのすべてのバージョンに対して組み込みサポートが提供されます。これらのモデルエンドポイントを登録するには、google_ml.create_model() 関数を使用します。Distributed Cloud は、これらのモデルのデフォルトの変換関数を自動的に設定します。; これらのモデルのモデルタイプは text-embedding です。
その他のテキストエンベディングモデル: 他のテキストエンベディングモデルの場合は、モデルがサポートする入力形式と出力形式を処理する変換関数を作成する必要があります。必要に応じて、HTTP ヘッダー生成関数を使用して、モデルに必要なカスタムヘッダーを生成できます。; これらのモデルのモデルタイプは text-embedding です。
汎用モデル: モデルエンドポイント管理では、テキストエンベディングモデルを除くすべてのモデルタイプを登録できます。汎用モデルの予測を呼び出すには、google_ml.predict_row() 関数を使用します。モデル固有のリクエストエンドポイントや HTTP ヘッダーなど、モデルエンドポイントのメタデータを設定できます。; 汎用モデルエンドポイントを登録するときに変換関数を渡すことはできません。予測を呼び出す前に、関数への入力が JSON 形式であることと、JSON 出力を解析して最終出力を導出していることを確認します。; これらのモデルのモデルタイプは generic です。

認証

認証タイプは、google_ml_integration 拡張機能を使用してモデルエンドポイント管理に接続するために使用できる認証タイプを示します。認証の設定は省略可能です。モデルにアクセスするために認証が必要な場合にのみ必要です。

Vertex AI モデルの場合、認証には Distributed Cloud サービスアカウントが使用されます。他のモデルでは、Secret Manager にシークレットとして保存されている API キーまたは署名なしトークンを google_ml.create_sm_secret() SQL 関数で使用できます。

次の表に、設定可能な認証タイプを示します。

認証方法	関数での設定…	モデルプロバイダ
Distributed Cloud サービスエージェント	`alloydb_service_agent_iam`	Vertex AI プロバイダ
Secret Manager	`secret_manager`	サードパーティプロバイダ

予測関数

google_ml_integration 拡張機能には、次の予測関数が含まれています。

google_ml.embedding(): 登録されたテキストエンベディングモデルエンドポイントを呼び出してエンベディングを生成するために使用されます。Vertex AI の textembedding-gecko モデルに対する組み込みサポートも含まれます。; 組み込みサポートのないテキストエンベディングモデルの場合、入力パラメータと出力パラメータはモデルに固有であり、関数でモデルを呼び出すには変換する必要があります。予測関数の入力をモデル固有の入力に変換する入力変換関数と、モデル固有の出力を予測関数出力に変換する出力変換関数を作成します。
google_ml.predict_row(): モデルが JSON ベースの API をサポートしている限り、登録済みの汎用モデルエンドポイントを呼び出して予測を呼び出すために使用されます。

変換関数

変換関数は、入力をモデルが理解できる形式に変更し、モデルのレスポンスを予測関数が想定する形式に変換します。変換関数は、組み込みサポートなしで text-embedding モデルエンドポイントを登録する場合に使用されます。変換関数の署名は、モデルタイプの予測関数によりも異なります。

generic モデルエンドポイントを登録するときに変換関数を使用できません。

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

// define custom model specific input/output transform functions.
CREATE OR REPLACE FUNCTION input_transform_function(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;

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

HTTP ヘッダー生成関数

HTTP ヘッダー生成関数は、HTTP ヘッダーとして使用される JSON Key-Value ペアで出力を生成します。予測関数の署名は、ヘッダー生成関数の署名を定義します。

次の例は、google_ml.embedding() 予測関数の署名を示しています。

CREATE OR REPLACE FUNCTION generate_headers(model_id VARCHAR(100), input TEXT) RETURNS JSON;

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

CREATE OR REPLACE FUNCTION generate_headers(model_id VARCHAR(100), input JSON) RETURNS JSON;

モデルを登録する

モデルを使用して予測を呼び出すか、エンベディングを生成するには、モデルエンドポイント管理にモデルエンドポイントを登録します。

google_ml.create_model() 関数の詳細については、モデルのエンドポイント管理のリファレンスをご覧ください。

モデルエンドポイント管理にモデルエンドポイントを登録する前に、google_ml_integration 拡張機能を有効にし、モデルエンドポイントで認証が必要な場合はモデルプロバイダに基づいて認証を設定する必要があります。

postgres のデフォルトユーザー名でデータベースにアクセスしていることを確認します。

認証を設定する

以降のセクションでは、Vertex AI モデルエンドポイントまたは他のプロバイダのモデルエンドポイントを追加する前に、認証を設定する方法について説明します。

Vertex AI の認証を設定する

Google Vertex AI モデルエンドポイントを使用するには、AlloyDB Omni のインストール時に使用したサービスアカウントに Vertex AI の権限を追加する必要があります。

他のモデルプロバイダの認証を設定する

Vertex AI モデルを除くすべてのモデルで、API キーまたは署名なしトークンを Secret Manager に保存できます。モデルエンドポイントが Secret Manager を介した認証を処理しない場合（たとえば、モデルエンドポイントが HTTP ヘッダーを使用して認証情報を渡す場合や、認証をまったく使用しない場合）は、この手順は省略可能です。

このセクションでは、Secret Manager を使用している場合に認証を設定する方法について説明します。

API キーまたは署名なしトークンを作成して使用する手順は次のとおりです。

Secret Manager でシークレットを作成します。

シークレットの名前とパスは、google_ml.create_sm_secret() SQL 関数で使用されます。
Distributed Cloud クラスタに Secret へのアクセス権を付与します。
```
  gcloud secrets add-iam-policy-binding 'SECRET_ID' \
      --member="serviceAccount:SERVICE_ACCOUNT_ID" \
      --role="roles/secretmanager.secretAccessor"
```
次のように置き換えます。
- SECRET_ID: Secret Manager のシークレット ID。
- SERVICE_ACCOUNT_ID: 前の手順で作成したサービスアカウントの ID。これが、AlloyDB Omni のインストール時に使用したものと同じアカウントであることを確認してください。これには、PROJECT_ID.iam.gserviceaccount.com 接尾辞全体が含まれます（例: my-service@my-project.iam.gserviceaccount.com）。
  
  このロールは、プロジェクトレベルでサービスアカウントに付与することもできます。

エンベディングを生成する

このセクションでは、モデルエンドポイント管理を使用して AI モデルエンドポイントの登録と予測の呼び出しをテストできるプレビューについて説明します。

モデルエンドポイントがモデルエンドポイント管理に追加されて登録されると、モデル ID を使用してエンドポイントを参照し、エンベディングを生成できます。

始める前に

モデルエンドポイントがモデルエンドポイント管理に登録されていることを確認します。

エンベディングを生成する

google_ml.embedding() SQL 関数を使用して、テキストエンベディングモデルタイプで登録済みモデルエンドポイントを呼び出し、エンベディングを生成します。

モデルを呼び出してエンベディングを生成するには、次の SQL クエリを使用します。

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

次のように置き換えます。

MODEL_ID: モデルエンドポイントの登録時に定義したモデル ID
CONTENT: ベクトルエンベディングに変換するテキスト。

例

このセクションでは、登録済みモデルエンドポイントを使用してエンベディングを生成する例を示します。

組み込みサポートのあるテキストエンベディングモデル

登録済みの textembedding-gecko@002 モデルエンドポイントのエンベディングを生成するには、次のステートメントを実行します。

    SELECT
      google_ml.embedding(
        model_id => 'textembedding-gecko@002',
        content => 'AlloyDB is a managed, cloud-hosted SQL database service');

予測を呼び出す

モデルエンドポイントをモデルエンドポイント管理に追加して登録すると、モデル ID を使用してモデルエンドポイントを参照し、予測を呼び出すことができます。

始める前に

モデルエンドポイントがモデルエンドポイント管理に登録されていることを確認します。

汎用モデルの予測を呼び出す

google_ml.predict_row() SQL 関数を使用して、登録済みの汎用モデルエンドポイントを呼び出し、予測を呼び出します。google_ml.predict_row() 関数は、任意のモデルタイプで使用できます。

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

次のように置き換えます。

MODEL_ID: モデルエンドポイントの登録時に定義したモデル ID
REQUEST_BODY: JSON 形式の予測関数のパラメータ

例

このセクションには、登録済みのモデルエンドポイントを使って予測を呼び出す方法の例がいくつか挙げられています。

登録済みの gemini-pro モデルエンドポイントの予測を生成するには、次のステートメントを実行します。

    SELECT
        json_array_elements(
        google_ml.predict_row(
            model_id => 'gemini-pro',
            request_body => '{
        "contents": [
            {
                "role": "user",
                "parts": [
                    {
                        "text": "For TPCH database schema as mentioned here https://www.tpc.org/TPC_Documents_Current_Versions/pdf/TPC-H_v3.0.1.pdf , generate a SQL query to find all supplier names which are located in the India nation."
                    }
                ]
            }
        ]
        }'))-> 'candidates' -> 0 -> 'content' -> 'parts' -> 0 -> 'text';

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

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

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

モデル

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

`google_ml.create_model()` 関数

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

  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` を明示的に指定してください。カスタムホスト型のモデルエンドポイントの場合は、Distributed Cloud が配置されているネットワークからそのモデルエンドポイントにアクセスできることを確認してください。
`PROVIDER_ID`	組み込みサポートのあるテキストエンベディングモデルエンドポイントの場合は必須	モデルエンドポイントのプロバイダ。デフォルト値は `custom` です。次のいずれかに設定します。 `google`（Vertex AI モデルエンドポイントの場合） `custom`（他のプロバイダの場合）
`MODEL_TYPE`	汎用モデルエンドポイントの場合は省略可	モデルタイプ。次のいずれかに設定します。 `text_embedding`（テキストエンベディングモデルエンドポイントの場合） `generic`（他のすべてのモデルエンドポイントの場合）
`MODEL_QUALIFIED_NAME`	組み込みサポートのあるテキストエンベディングモデルの場合は必須、他のモデルエンドポイントの場合は省略可	組み込みサポートのあるテキストエンベディングモデルの完全修飾名。
`AUTH_TYPE`	モデルエンドポイントに特定の認証要件がない限り省略可	モデルエンドポイントで使用される認証タイプ。 Vertex AI モデルの場合は `alloydb_service_agent_iam`、他のプロバイダの場合は `secret_manager` に設定できます（認証に Secret Manager を使用している場合）。認証ヘッダーを使用している場合、この値を設定する必要はありません。
`AUTH_ID`	Vertex AI モデルエンドポイントの場合は設定しない。Secret Manager にシークレットを保存する他のモデルエンドポイントの場合は必須	ユーザーが設定し、モデルエンドポイントの登録時に使用したシークレット ID。
`GENERATE_HEADER_FUNCTION`	オプション	カスタムヘッダーを生成する関数の名前。この関数の署名は、使用する予測関数によって異なります。
`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。このプロジェクトは、AlloyDB for PostgreSQL クラスタを含むプロジェクトとは異なる場合があります。 AlloyDB Omni の場合、シークレットを含む 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`	ベクトルエンベディングに変換するテキスト。

`google_ml.predict_row()` 関数

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

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

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

変換関数

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

入力変換関数

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

  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', 'model-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-preview-0815`	`text-embedding`
`text-multilingual-embedding-002`	`text-embedding`

AlloyDB でモデル エンドポイントを使用してモデルを呼び出す コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

仕組み

主なコンセプト

モデル プロバイダ

モデルタイプ

認証

予測関数

変換関数

HTTP ヘッダー生成関数

モデルを登録する

認証を設定する

Vertex AI の認証を設定する

他のモデル プロバイダの認証を設定する

エンベディングを生成する

始める前に

エンベディングを生成する

例

組み込みサポートのあるテキスト エンベディング モデル

予測を呼び出す

始める前に

汎用モデルの予測を呼び出す

例

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

モデル

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

AlloyDB でモデルエンドポイントを使用してモデルを呼び出す

モデルプロバイダ

他のモデルプロバイダの認証を設定する

組み込みサポートのあるテキストエンベディングモデル

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

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

エンベディングモデル