AlloyDB Omni でリモート AI モデルを登録して呼び出す

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

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

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

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

拡張機能を有効にする

関連する関数を使用するには、google_ml_integration 拡張機能を追加して有効にする必要があります。モデルのエンドポイント管理では、google_ml_integration 拡張機能がインストールされている必要があります。

  1. psql を使用してデータベースに接続します。

  2. 省略可: google_ml_integration 拡張機能がすでにインストールされている場合は、最新バージョンに更新するように変更します。

        ALTER EXTENSION google_ml_integration UPDATE;

  3. psql を使用して google_ml_integration 拡張機能を追加します。

      CREATE EXTENSION google_ml_integration;

  4. 省略可: モデルのメタデータを管理する権限を PostgreSQL の非スーパーユーザーに付与します。

      GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA google_ml TO NON_SUPER_USER;

    NON_SUPER_USER は、スーパー以外の PostgreSQL ユーザー名に置き換えます。

  5. データベースでモデル エンドポイント管理を有効にします。

      ALTER SYSTEM SET google_ml_integration.enable_model_support=on;
  SELECT pg_reload_conf();

認証の設定

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

Vertex AI の認証を設定する

Google Vertex AI モデル エンドポイントを使用するには、AlloyDB Omni のインストール時に使用したサービス アカウントに Vertex AI の権限を追加する必要があります。詳細については、クラウドベースのモデルをクエリするように AlloyDB Omni インストールを構成するをご覧ください。

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

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

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

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

  1. Secret Manager で Secret を作成します。詳細については、シークレットを作成してシークレット バージョンにアクセスするをご覧ください。

    シークレット名とシークレット パスは、google_ml.create_sm_secret() SQL 関数で使用されます。

  2. AlloyDB クラスタにシークレットへのアクセス権を付与します。

      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）。

      このロールは、プロジェクト レベルでサービス アカウントに付与することもできます。詳細については、Identity and Access Management ポリシー バインディングを追加するをご覧ください。

サポートが組み込まれたテキスト エンベディング モデル

このセクションでは、モデル エンドポイント管理で組み込みサポートされているモデル エンドポイントを登録する方法について説明します。

Vertex AI エンベディング モデル

モデル エンドポイント管理には、Vertex AI の text-embedding-gecko モデルのすべてのバージョンが組み込まれています。修飾名を使用して、モデル バージョンを textembedding-gecko@001 または textembedding-gecko@002 に設定します。

textembedding-gecko モデル エンドポイント ID と textembedding-gecko@001 モデル エンドポイント ID はモデル エンドポイント管理で事前登録されているため、モデル ID として直接使用できます。これらのモデルの場合、拡張機能はデフォルトの変換関数を自動的に設定します。

textembedding-gecko@002 モデル エンドポイント バージョンを登録する手順は次のとおりです。

AlloyDB Omni の場合は、クラウドベースの Vertex AI モデルをクエリするように AlloyDB Omni を設定してください。

  1. google_ml_integration 拡張機能を作成して有効にする。

  2. psql を使用してデータベースに接続します。

  3. google_ml_integration 拡張機能を作成して有効にする。

  4. モデル作成関数を呼び出して、textembedding-gecko@002 モデル エンドポイントを追加します。

    CALL
  google_ml.create_model(
    model_id => 'textembedding-gecko@002',
    model_provider => 'google',
    model_qualified_name => 'textembedding-gecko@002',
    model_type => 'text_embedding',
    model_auth_type => 'alloydb_service_agent_iam');

  The request URL that the function generates refers to the project associated with the AlloyDB Omni service account. If you want to refer to another project, then ensure that you specify the `model_request_url` explicitly.

Open AI テキスト エンベディング モデル

モデル エンドポイント管理には、OpenAI の text-embedding-ada-002 モデルの組み込みサポートが用意されています。google_ml_integration 拡張機能は、デフォルトの変換関数を自動的に設定し、リモートモデルへの呼び出しを呼び出します。

次の例では、text-embedding-ada-002 OpenAI モデル エンドポイントを追加します。

  1. psql を使用してデータベースに接続します。
  2. google_ml_integration 拡張機能を作成して有効にする。
  3. 認証用に OpenAI API キーを Secret Manager にシークレットとして追加します。

  4. Secret Manager に保存されているシークレットを呼び出します。

    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。モデル エンドポイントの登録時に使用されます（例: key1）。
    • SECRET_MANAGER_SECRET_ID: Secret の作成時に Secret Manager で設定した Secret ID。
    • PROJECT_ID: Google Cloud プロジェクトの ID。
    • VERSION_NUMBER: シークレット ID のバージョン番号。

  5. モデル作成関数を呼び出して、text-embedding-ada-002 モデル エンドポイントを登録します。

    CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_provider => 'open_ai',
    model_type => 'text_embedding',
    model_qualified_name => 'text-embedding-ada-002',
    model_auth_type => 'secret_manager',
    model_auth_id => 'SECRET_ID');

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

    • MODEL_ID: 定義するモデル エンドポイントの一意の ID。このモデル ID は、モデル エンドポイントがエンベディングの生成や予測の呼び出しに必要なメタデータで参照されます。
    • SECRET_ID: 前の google_ml.create_sm_secret() 手順で使用したシークレット ID。

エンベディングを生成するには、組み込みサポートを使用してモデル エンドポイントのエンベディングを生成する方法をご覧ください。

その他のテキスト エンベディング モデル

このセクションでは、カスタム ホストされているテキスト エンベディング モデル エンドポイントまたはモデル ホスティング プロバイダが提供するテキスト エンベディング モデル エンドポイントを登録する方法について説明します。モデルのエンドポイント メタデータに基づいて、変換関数の追加、HTTP ヘッダーの生成、エンドポイントの定義が必要になる場合があります。

カスタム ホスト テキスト エンベディング モデル

このセクションでは、カスタム ホスト型モデル エンドポイントを登録する方法と、変換関数を作成する方法について説明します。必要に応じて、カスタム HTTP ヘッダーも作成します。AlloyDB Omni は、ホストされている場所に関係なく、すべてのカスタム ホストモデル エンドポイントをサポートしています。

次の例では、Cymbal でホストされている custom-embedding-model カスタムモデル エンドポイントを追加します。cymbal_text_input_transform 変換関数と cymbal_text_output_transform 変換関数は、モデルの入力形式と出力形式を予測関数の入力形式と出力形式に変換するために使用されます。

カスタム ホストされているテキスト エンベディング モデルのエンドポイントを登録するには、次の操作を行います。

  1. psql を使用してデータベースに接続します。

  2. google_ml_integration 拡張機能を作成して有効にする。

  3. 省略可: 認証用に API キーをシークレットとして Secret Manager に追加する。

  4. Secret Manager に保存されているシークレットを呼び出します。

    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。モデル エンドポイントの登録時に使用されます（例: key1）。
    • SECRET_MANAGER_SECRET_ID: Secret の作成時に Secret Manager で設定した Secret ID。
    • PROJECT_ID: Google Cloud プロジェクトの ID。
    • VERSION_NUMBER: シークレット ID のバージョン番号。

  5. テキスト エンベディング モデル エンドポイントの予測関数の次のシグネチャに基づいて、入力変換関数と出力変換関数を作成します。変換関数の作成方法の詳細については、変換関数の例をご覧ください。

    次の例は、custom-embedding-model テキスト エンベディング モデル エンドポイントに固有の変換関数です。

    -- Input Transform Function corresponding to the custom model endpoint
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;
$$;
-- Output Transform Function corresponding to the custom model endpoint
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;
$$;

  6. モデル作成関数を呼び出して、カスタム エンベディング モデル エンドポイントを登録します。

    CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_request_url => 'REQUEST_URL',
    model_provider => 'custom',
    model_type => 'text_embedding',
    model_auth_type => 'secret_manager',
    model_auth_id => 'SECRET_ID',
    model_qualified_name => 'MODEL_QUALIFIED_NAME',
    model_in_transform_fn => 'cymbal_text_input_transform',
    model_out_transform_fn => 'cymbal_text_output_transform');

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

    • MODEL_ID: 必須。定義するモデル エンドポイントの一意の ID（custom-embedding-model など）。このモデル ID は、モデル エンドポイントがエンベディングの生成や予測の呼び出しに必要なメタデータで参照されます。
    • REQUEST_URL: 必須。カスタム テキスト エンベディングと汎用モデル エンドポイントを追加する場合のモデル固有のエンドポイント（https://cymbal.com/models/text/embeddings/v1 など）。
    • MODEL_QUALIFIED_NAME: モデル エンドポイントで修飾名を使用する場合に必須です。モデル エンドポイントに複数のバージョンがある場合の完全修飾名。
    • SECRET_ID: 前の google_ml.create_sm_secret() 手順で使用したシークレット ID。

OpenAI Text Embedding 3 の小規模モデルと大規模モデル

OpenAI text-embedding-3-small モデル エンドポイントと text-embedding-3-large モデル エンドポイントは、エンベディング予測関数とモデル エンドポイントに固有の変換関数を使用して登録できます。次の例は、OpenAI text-embedding-3-small モデル エンドポイントを登録する方法を示しています。

text-embedding-3-small エンベディング モデル エンドポイントを登録する手順は次のとおりです。

  1. psql を使用してデータベースに接続します。
  2. google_ml_integration 拡張機能を作成して有効にする。
  3. 認証用に OpenAI API キーを Secret Manager にシークレットとして追加します。他の OpenAI モデルのシークレットをすでに作成している場合は、同じシークレットを再利用できます。

  4. Secret Manager に保存されているシークレットを呼び出します。

    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。モデル エンドポイントの登録時に使用されます。
    • SECRET_MANAGER_SECRET_ID: Secret の作成時に Secret Manager で設定した Secret ID。
    • PROJECT_ID: Google Cloud プロジェクトの ID。
    • VERSION_NUMBER: シークレット ID のバージョン番号。

  5. テキスト エンベディング モデルの予測関数の次のシグネチャに基づいて、入力変換関数と出力変換関数を作成します。変換関数の作成方法については、変換関数の例をご覧ください。OpenAI モデル エンドポイントが想定する入力形式と出力形式については、エンベディングをご覧ください。

    以下は、text-embedding-ada-002、text-embedding-3-small、text-embedding-3-large OpenAI テキスト エンベディング モデル エンドポイントの変換関数の例です。

    -- Input Transform Function corresponding to openai_text_embedding model endpoint family
CREATE OR REPLACE FUNCTION openai_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
DECLARE
  transformed_input JSON;
  model_qualified_name TEXT;
BEGIN
  SELECT google_ml.model_qualified_name_of(model_id) INTO model_qualified_name;
  SELECT json_build_object('input', input_text, 'model', model_qualified_name)::JSON INTO transformed_input;
  RETURN transformed_input;
END;
$$;

-- Output Transform Function corresponding to openai_text_embedding model endpoint family
CREATE OR REPLACE FUNCTION openai_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->'data'->0->'embedding')) INTO transformed_output;
  RETURN transformed_output;
END;
$$;

  6. モデル作成関数を呼び出して、text-embedding-3-small エンベディング モデル エンドポイントを登録します。

    CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_provider => 'open_ai',
    model_type => 'text_embedding',
    model_auth_type => 'secret_manager',
    model_auth_id => 'SECRET_ID',
    model_qualified_name => 'text-embedding-3-small',
    model_in_transform_fn => 'openai_text_input_transform',
    model_out_transform_fn => 'openai_text_output_transform');

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

    • MODEL_ID: 定義するモデル エンドポイントの一意の ID（例: openai-te-3-small）。このモデル ID は、モデル エンドポイントがエンベディングの生成や予測の呼び出しに必要なメタデータで参照されます。
    • SECRET_ID: 前の google_ml.create_sm_secret() 手順で使用したシークレット ID。

詳細については、他のテキスト エンベディング モデル エンドポイントのエンベディングを生成する方法をご覧ください。

汎用モデル

このセクションでは、Hugging Face、OpenAI、Vertex AI などのホスト型モデル プロバイダで使用可能な汎用モデル エンドポイントを登録する方法について説明します。このセクションでは、Hugging Face でホストされている汎用モデル エンドポイントと、Vertex AI Model Garden の汎用 gemini-pro モデル（組み込みサポートなし）を登録する例を示します。

入力と出力が JSON 形式であれば、任意の汎用モデル エンドポイントを登録できます。モデルのエンドポイント メタデータに基づいて、HTTP ヘッダーの生成やエンドポイントの定義が必要になる場合があります。

Hugging Face の汎用モデル

次の例では、Hugging Face でホストされている facebook/bart-large-mnli カスタム分類モデル エンドポイントを追加します。

  1. psql を使用してデータベースに接続します。
  2. google_ml_integration 拡張機能を作成して有効にする。
  3. 認証用にベアラートークンをシークレットとして Secret Manager に追加します。

  4. Secret Manager に保存されているシークレットを呼び出します。

    CALL
  google_ml.create_sm_secret(
    secret_id => 'SECRET_ID',
    secret_path => 'projects/project-id/secrets/SECRE_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

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

    • SECRET_ID: 設定したシークレット ID。モデル エンドポイントの登録時に使用されます。
    • SECRET_MANAGER_SECRET_ID: Secret の作成時に Secret Manager で設定した Secret ID。
    • PROJECT_ID: Google Cloud プロジェクトの ID。
    • VERSION_NUMBER: シークレット ID のバージョン番号。

  5. モデル作成関数を呼び出して、facebook/bart-large-mnli モデル エンドポイントを登録します。

    CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_provider => 'custom',
    model_request_url => 'REQUEST_URL',
    model_qualified_name => 'MODEL_QUALIFIED_NAME',
    model_auth_type => 'secret_manager',
    model_auth_id => 'SECRET_ID');

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

    • MODEL_ID: 定義するモデル エンドポイントの一意の ID（例: custom-classification-model）。このモデル ID は、モデル エンドポイントがエンベディングの生成や予測の呼び出しに必要なメタデータで参照されます。
    • REQUEST_URL: カスタムテキスト エンベディングと汎用モデル エンドポイントを追加する場合のモデル固有のエンドポイント（例: https://api-inference.huggingface.co/models/facebook/bart-large-mnli）。
    • MODEL_QUALIFIED_NAME: モデル エンドポイント バージョンの完全修飾名（例: facebook/bart-large-mnli）。
    • SECRET_ID: 前の google_ml.create_sm_secret() 手順で使用したシークレット ID。

Gemini モデル

クラウドベースの Vertex AI モデルをクエリするように AlloyDB Omni を設定していることを確認します。

次の例では、Vertex AI Model Garden から gemini-1.0-pro モデル エンドポイントを追加します。

  1. psql を使用してデータベースに接続します。
  2. google_ml_integration 拡張機能を作成して有効にする。

  3. モデル作成関数を呼び出して、gemini-1.0-pro モデルを登録します。

    CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_request_url => 'https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-1.0-pro:streamGenerateContent',
    model_provider => 'google',
    model_auth_type => 'alloydb_service_agent_iam');

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

    • MODEL_ID: 定義するモデル エンドポイントの一意の ID（例: gemini-1）。このモデル ID は、モデル エンドポイントがエンベディングの生成または予測の呼び出しに必要なメタデータで参照されます。
    • PROJECT_ID: Google Cloud プロジェクトの ID。

詳細については、汎用モデル エンドポイントの予測を呼び出す方法をご覧ください。

次のステップ