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 でシークレットを作成します。詳細については、シークレットを作成してシークレット バージョンにアクセスするをご覧ください。

   シークレットの名前とパスは、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 の場合は、AlloyDB Omni がクラウドベースの Vertex AI モデルをクエリするように設定してください。

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: 設定した Secret ID。モデル エンドポイントの登録時に使用されます（例: key1）。
   • SECRET_MANAGER_SECRET_ID: シークレットの作成時に Secret Manager で設定したシークレット 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: 設定した Secret ID。モデル エンドポイントの登録時に使用されます（例: key1）。
   • SECRET_MANAGER_SECRET_ID: シークレットの作成時に Secret Manager で設定したシークレット 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 テキスト エンベディングの 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 Manager で設定したシークレット 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 Manager で設定したシークレット 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。

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

次のステップ

• モデルのエンドポイント管理のリファレンスをご覧ください。