モデル エンドポイント管理を使用してリモート AI モデルを登録して呼び出す

このページでは、モデル エンドポイント管理にモデル エンドポイントを登録し、モデルを使用して予測を呼び出す方法、またはエンベディングを生成する方法について説明します。

始める前に

拡張機能を設定する

  1. psql または AlloyDB for PostgreSQL Studio を使用して postgres ユーザーとしてデータベースに接続します。

  2. 省略可: マルチモーダル モデル、ランキング モデル、オペレーター関数のサポートなど、AlloyDB for PostgreSQL AI 関数（プレビュー）の機能を使用するアクセス権をリクエストします。

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

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

    次の変数を置き換えます。

    • NON_SUPER_USER: スーパーユーザー以外の PostgreSQL ユーザー名。

  4. サードパーティ モデルなど、VPC 外でホストされているモデルにアクセスできるように、アウトバウンド IP が有効になっていることを確認します。詳細については、インスタンスへのアウトバウンド接続を追加するをご覧ください。

認証を設定する

以降のセクションでは、モデル エンドポイントを登録する前に認証を設定する方法について説明します。

Vertex AI と統合して拡張機能をインストールする

Vertex AI モデル エンドポイントを使用するには、データベースへの接続に使用する IAM ベースの AlloyDB サービス アカウントに Vertex AI の権限を追加する必要があります。

  1. Vertex AI モデルへのユーザー アクセスを構成します。
  2. google_ml_integration の最新バージョンがインストールされていることを確認します。

    1. インストールされているバージョンを確認するには、次のコマンドを実行します。

              SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
        extversion 
        ------------
        1.5.2
        (1 row)

    2. 拡張機能がインストールされていない場合、またはインストールされているバージョンが 1.5.2 より前の場合は、拡張機能を更新します。

              CREATE EXTENSION IF NOT EXISTS google_ml_integration;
        ALTER EXTENSION google_ml_integration UPDATE;

      上記のコマンドを実行したときに問題が発生した場合、または上記のコマンドを実行しても拡張機能がバージョン 1.5.2 にアップデートされない場合は、Google Cloud サポートにお問い合わせください。

  3. AlloyDB AI クエリエンジンの機能を使用するには、google_ml_integration.enable_ai_query_engine フラグを true に設定します。

    SQL

    1. 現在のセッションで AI クエリエンジンを有効にします。
                    SET google_ml_integration.enable_ai_query_engine = true;
    2. セッション間で特定のデータベースの機能を有効にします。
                    ALTER DATABASE DATABASE_NAME SET google_ml_integration.enable_ai_query_engine = 'on';
    3. セッションとデータベース全体で特定のユーザーに対して AI クエリエンジンを有効にします。
                    ALTER ROLE postgres SET google_ml_integration.enable_ai_query_engine = 'on';

    コンソール

    google_ml_integration.enable_ai_query_engine フラグの値を変更するには、インスタンスのデータベース フラグを構成するの手順に沿って操作します。

    gcloud

    gcloud CLI を使用するには、Google Cloud CLI をインストールして初期化するか、Cloud Shell を使用します。

    google_ml_integration.enable_ai_query_engine フラグの値を変更できます。詳細については、インスタンスのデータベース フラグを構成するをご覧ください。 

                 gcloud alloydb instances update INSTANCE_ID \
               --database-flags google_ml_integration.enable_ai_query_engine=on \
               --region=REGION_ID \
               --cluster=CLUSTER_ID \
               --project=PROJECT_ID

Secret Manager を使用して認証を設定する

このセクションでは、サードパーティ プロバイダの認証情報を保存するために Secret Manager を使用する場合に、認証を設定する方法について説明します。

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

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

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

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

  2. AlloyDB クラスタに Secret へのアクセス権を付与します。

      gcloud secrets add-iam-policy-binding 'SECRET_NAME' \
      --member="serviceAccount:SERVICE_ACCOUNT_ID" \
      --role="roles/secretmanager.secretAccessor"

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

    • SECRET_NAME: Secret Manager 内のシークレット名。

    • SERVICE_ACCOUNT_ID: IAM ベースのサービス アカウントの ID（serviceAccount:service-PROJECT_ID@gcp-sa-alloydb.iam.gserviceaccount.com 形式、例: service-212340152456@gcp-sa-alloydb.iam.gserviceaccount.com）。

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

ヘッダーを使用して認証を設定する

次の例は、関数を使用して認証を設定する方法を示したものです。この関数は、エンベディング モデルへのリクエストに必要なヘッダーを含む JSON オブジェクトを返します。

  CREATE OR REPLACE FUNCTION HEADER_GEN_FUNCTION(
    model_id VARCHAR(100),
    input_text TEXT
  )
  RETURNS JSON
  LANGUAGE plpgsql
  AS $$
  #variable_conflict use_variable
  DECLARE
    api_key VARCHAR(255) := 'API_KEY';
    header_json JSON;
  BEGIN
    header_json := json_build_object(
      'Content-Type', 'application/json',
      'Authorization', 'Bearer ' || api_key
    );
    RETURN header_json;
  END;
  $$;

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

  • HEADER_GEN_FUNCTION: モデルの登録時に使用できるヘッダー生成関数の名前。
  • API_KEY: モデル プロバイダの API キー。

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

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

モデル エンドポイント管理では、事前登録済みのモデル エンドポイントとして、一部のテキスト エンベディング モデルと汎用 Vertex AI モデルがサポートされています。モデル ID を直接使用して、モデルタイプに基づくエンベディングの生成や予測の呼び出しを行えます。サポートされている事前登録済みモデルの詳細については、事前登録済みの Vertex AI モデルをご覧ください。

gemini-embedding-001 モデルは us-central1 リージョンでのみ使用できます。

たとえば、事前登録された gemini-embedding-001 モデルを呼び出すには、以下のとおりエンベディング関数を使用してモデルを直接呼び出します。

SELECT
      embedding(
        model_id => 'gemini-embedding-001',
        content => 'AlloyDB is a managed, cloud-hosted SQL database service');

AlloyDB クラスタと Vertex AI エンドポイントが異なるプロジェクトにある場合は、model_id をエンドポイントの完全修飾パス（projects/PROJECT_ID/locations/REGION_ID/publishers/google/models/gemini-embedding-001 など）に設定します。

同様に、事前登録された gemini-1.5-pro:generateContent モデルを呼び出すには、以下のとおり予測関数を使用してモデルを直接呼び出します。

 SELECT google_ml.predict_row(
            model_id => 'gemini-1.5-pro:generateContent',
            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. Only provide SQL query with no explanation."
                    }
                ]
            }
        ]
        }')-> 'candidates' -> 0 -> 'content' -> 'parts' -> 0 -> 'text';

エンベディングを生成するには、テキスト エンベディングを生成する方法をご覧ください。予測を呼び出すには、予測を呼び出す方法をご覧ください。

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

モデル エンドポイント管理には、Vertex AI と OpenAI の一部モデルのサポートが組み込まれています。サポートが組み込まれているモデルの一覧については、サポートが組み込まれているモデルをご覧ください。

サポートが組み込まれているモデルについては、修飾名をモデルの修飾名として設定し、リクエスト URL を指定できます。モデル エンドポイント管理は、モデルを自動的に識別し、デフォルトの変換関数を設定します。

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

次の手順では、組み込みサポートを使用して Vertex AI モデルを登録する方法を示します。例として、gemini-embedding-001 モデル エンドポイントと text-multilingual-embedding-002 モデル エンドポイントを使用します。

クエリを実行する AlloyDB クラスタと Vertex AI モデルの両方が同じリージョンに存在している必要があります。

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

  2. google_ml_integration 拡張機能を設定します。

  3. モデル作成関数を呼び出して、モデル エンドポイントを追加します。

    gemini-embedding-001

      CALL
    google_ml.create_model(
      model_id => 'gemini-embedding-001',
      model_request_url => 'publishers/google/models/gemini-embedding-001',
      model_provider => 'google',
      model_qualified_name => 'gemini-embedding-001',
      model_type => 'text_embedding',
      model_auth_type => 'alloydb_service_agent_iam');

    text-multilingual-embedding-002

      CALL
    google_ml.create_model(
      model_id => 'text-multilingual-embedding-002',
      model_request_url => 'publishers/google/models/text-multilingual-embedding-002',
      model_provider => 'google',
      model_qualified_name => 'text-multilingual-embedding-002',
      model_type => 'text_embedding',
      model_auth_type => 'alloydb_service_agent_iam'
      model_in_transform_fn => 'google_ml.vertexai_text_embedding_input_transform',
      model_out_transform_fn => 'google_ml.vertexai_text_embedding_output_transform');

モデルが AlloyDB クラスタとは別のプロジェクトとリージョンに保存されている場合は、リクエスト URL を projects/PROJECT_ID/locations/REGION_ID/publishers/google/models/MODEL_ID に設定します。ここで、REGION_ID はモデルがホストされているリージョン、MODEL_ID は修飾モデル名です。

また、AlloyDB インスタンスが存在するプロジェクトの AlloyDB サービス アカウントに Vertex AI ユーザー（roles/aiplatform.user）ロールを付与して、AlloyDB が他のプロジェクトでホストされているモデルにアクセスできるようにします。

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

google_ml_integration 拡張機能は、デフォルトの変換関数を自動的に設定し、遠隔の OpenAI モデルに対する呼び出しを行います。サポートが組み込まれている OpenAI モデルの一覧については、サポートが組み込まれているモデルをご覧ください。

次の例では、text-embedding-ada-002 OpenAI モデル エンドポイントを追加します。OpenAI の text-embedding-3-small モデル エンドポイントと text-embedding-3-large モデル エンドポイントは、同じ手順を使用し、モデルに固有のモデル修飾名を設定して登録できます。

  1. psql を使用してデータベースに接続します。
  2. google_ml_integration 拡張機能を設定します。
  3. 認証のため、OpenAI API キーを Secret Manager に Secret として追加します。

  4. Secret Manager に保存されている Secret を呼び出します。

    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 ヘッダーを作成する方法も説明します。セルフホスト型モデル エンドポイントは、ホストされている場所に関係なくすべてサポートされています。

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

セルフホスト型テキスト エンベディング モデルのエンドポイントを登録するには、次の操作を行います。

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

  2. google_ml_integration 拡張機能を設定します。

  3. 省略可: 認証のため、API キーを Secret Manager に Secret として追加します。

  4. Secret Manager に保存されている Secret を呼び出します。

    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 など）。モデル エンドポイントに内部 IP アドレスからアクセスできることを確認します。モデル エンドポイント管理はパブリック IP アドレスをサポートしていません。
    • MODEL_QUALIFIED_NAME: モデル エンドポイントで修飾名を使用する場合に必須です。モデル エンドポイントに複数のバージョンがある場合の完全修飾名。
    • SECRET_ID: google_ml.create_sm_secret() プロシージャで以前に使用したシークレット ID。

組み込みサポートのあるマルチモーダル モデル

Vertex AI と統合して拡張機能をインストールする

  1. Vertex AI モデルへのユーザー アクセスを構成します。
  2. google_ml_integration の最新バージョンがインストールされていることを確認します。

    1. インストールされているバージョンを確認するには、次のコマンドを実行します。

              SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
        extversion 
        ------------
        1.5.2
        (1 row)

    2. 拡張機能がインストールされていない場合、またはインストールされているバージョンが 1.5.2 より前の場合は、拡張機能を更新します。

              CREATE EXTENSION IF NOT EXISTS google_ml_integration;
        ALTER EXTENSION google_ml_integration UPDATE;

      上記のコマンドを実行したときに問題が発生した場合、または上記のコマンドを実行しても拡張機能がバージョン 1.5.2 にアップデートされない場合は、Google Cloud サポートにお問い合わせください。

  3. AlloyDB AI クエリエンジンの機能を使用するには、google_ml_integration.enable_ai_query_engine フラグを true に設定します。

    SQL

    1. 現在のセッションで AI クエリエンジンを有効にします。
                    SET google_ml_integration.enable_ai_query_engine = true;
    2. セッション間で特定のデータベースの機能を有効にします。
                    ALTER DATABASE DATABASE_NAME SET google_ml_integration.enable_ai_query_engine = 'on';
    3. セッションとデータベース全体で特定のユーザーに対して AI クエリエンジンを有効にします。
                    ALTER ROLE postgres SET google_ml_integration.enable_ai_query_engine = 'on';

    コンソール

    google_ml_integration.enable_ai_query_engine フラグの値を変更するには、インスタンスのデータベース フラグを構成するの手順に沿って操作します。

    gcloud

    gcloud CLI を使用するには、Google Cloud CLI をインストールして初期化するか、Cloud Shell を使用します。

    google_ml_integration.enable_ai_query_engine フラグの値を変更できます。詳細については、インスタンスのデータベース フラグを構成するをご覧ください。 

                 gcloud alloydb instances update INSTANCE_ID \
               --database-flags google_ml_integration.enable_ai_query_engine=on \
               --region=REGION_ID \
               --cluster=CLUSTER_ID \
               --project=PROJECT_ID

モデルを呼び出してマルチモーダル エンベディングを生成する

モデル エンドポイント管理には Vertex AI による multimodalembedding@001 モデルの組み込みサポートが用意されているため、モデルを直接呼び出してマルチモーダル エンベディングを生成できます。

次の例では、multimodalembedding@001 修飾モデル名をモデル ID として使用して、マルチモーダル画像エンベディングを生成します。

  1. psql を使用してデータベースに接続します。
  2. google_ml_integration 拡張機能を設定します。

  3. マルチモーダル画像エンベディングを生成します。

    SELECT
  ai.image_embedding(
    model_id => 'multimodalembedding@001',
    image => 'IMAGE_PATH_OR_TEXT',
    mimetype => 'MIMETYPE');

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

  • IMAGE_PATH_OR_TEXT は、画像の Cloud Storage パスに置き換えます。たとえば、gs://cymbal_user_data/image-85097193-cd9788aacebb.jpeg は、画像のベクトル エンベディングまたは Base64 の文字列に変換します。
  • MIMETYPE は、画像の MIME タイプに置き換えます。

ランキング モデル

Vertex AI ランキング モデル

サポートされているモデルで説明されている Vertex AI モデルは、登録なしで使用できます。

Vertex AI ランキング モデルを使用して検索結果をランク付けする方法については、検索結果をランク付けするをご覧ください。

サードパーティのランキング モデルを登録する

次の例は、Cohere から再ランキング モデルを登録する方法を示しています。

CREATE OR REPLACE FUNCTION cohere_rerank_input_transform(
    model_id VARCHAR(100),
    search_string TEXT,
    documents TEXT[],
    top_n INT DEFAULT NULL
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
DECLARE
  transformed_input JSONB;
BEGIN
  -- Basic Input Validation
  IF search_string IS NULL OR search_string = '' THEN
    RAISE EXCEPTION 'Invalid input: search_string cannot be NULL or empty.';
  END IF;

  IF documents IS NULL OR array_length(documents, 1) IS NULL OR array_length(documents, 1) = 0 THEN
    RAISE EXCEPTION 'Invalid input: documents array cannot be NULL or empty.';
  END IF;

  IF top_n IS NOT NULL AND top_n < 0 THEN
    RAISE EXCEPTION 'Invalid input: top_n must be greater than or equal to zero. Provided value: %', top_n;
  END IF;

  -- Construct the base JSON payload for Cohere Rerank API
  transformed_input := jsonb_build_object(
    'model', google_ml.model_qualified_name_of(model_id),
    'query', search_string,
    'documents', to_jsonb(documents), -- Convert TEXT[] directly to JSON array
    'return_documents', false -- Explicitly set to false (optional, as its default)
  );

  -- Add top_n to the payload only if it's provided and valid
  IF top_n IS NOT NULL THEN
     transformed_input := transformed_input || jsonb_build_object('top_n', top_n);
  END IF;

  -- Return the final JSON payload
  RETURN transformed_input::JSON;

END;
$$;

CREATE OR REPLACE FUNCTION cohere_rerank_output_transform(
    model_id VARCHAR(100),
    response_json JSON
)
RETURNS TABLE (index INT, score REAL)
LANGUAGE plpgsql
AS $$
DECLARE
  result_item JSONB;
  response_jsonb JSONB;
  cohere_index INT; -- 0-based index from Cohere response
BEGIN
  -- Validate response_json
  IF response_json IS NULL THEN
    RAISE EXCEPTION 'Invalid model response: response cannot be NULL.';
  END IF;

  -- Convert JSON to JSONB for easier processing
  response_jsonb := response_json::JSONB;

  -- Check top-level structure
  IF jsonb_typeof(response_jsonb) != 'object' THEN
    RAISE EXCEPTION 'Invalid model response: response must be a JSON object. Found: %', jsonb_typeof(response_jsonb);
  END IF;

  -- Check for the 'results' array
  IF response_jsonb->'results' IS NULL OR jsonb_typeof(response_jsonb->'results') != 'array' THEN
    -- Check for potential Cohere error structure
    IF response_jsonb->'message' IS NOT NULL THEN
       RAISE EXCEPTION 'Cohere API Error: %', response_jsonb->>'message';
    ELSE
       RAISE EXCEPTION 'Invalid model response: response does not contain a valid "results" array.';
    END IF;
  END IF;

  -- Loop through the 'results' array (JSONB array indices are 0-based)
  FOR i IN 0..jsonb_array_length(response_jsonb->'results') - 1 LOOP
    result_item := response_jsonb->'results'->i;

    -- Validate individual result item structure
    IF result_item IS NULL OR jsonb_typeof(result_item) != 'object' THEN
      RAISE WARNING 'Skipping invalid result item at array index %.', i;
      CONTINUE;
    END IF;

    IF result_item->'index' IS NULL OR jsonb_typeof(result_item->'index') != 'number' THEN
       RAISE WARNING 'Missing or invalid "index" field in result item at array index %.', i;
       CONTINUE;
    END IF;

    IF result_item->'relevance_score' IS NULL OR jsonb_typeof(result_item->'relevance_score') != 'number' THEN
       RAISE WARNING 'Missing or invalid "relevance_score" field in result item at array index %.', i;
       CONTINUE;
    END IF;

    -- Extract values
    BEGIN
      cohere_index := (result_item->>'index')::INT;
      -- Assign values to the output table columns
      -- Cohere returns 0-based index, map it to 1-based for consistency
      -- with input document array position
      index := cohere_index + 1;
      score := (result_item->>'relevance_score')::REAL;
      RETURN NEXT; -- Return the current row
    EXCEPTION WHEN others THEN
      RAISE WARNING 'Error processing result item at array index %: %', i, SQLERRM;
      CONTINUE; -- Skip this item and continue with the next
    END;
  END LOOP;

  RETURN; -- End of function
END;
$$;

CALL
  google_ml.create_sm_secret(
    '<SECRET_ID>',
    'projects/<PROJECT_NUMBER>/secrets/<SECRET_ID>/versions/latest');

CALL
  google_ml.create_model(
    model_id => 'cohere-reranker',
    model_type => 'reranking',
    model_provider => 'custom',
    model_request_url => 'https://api.cohere.com/v2/rerank',
    model_qualified_name => 'rerank-v3.5',
    model_auth_type => 'secret_manager',
    model_auth_id => '<SECRET_ID>',
    model_in_transform_fn => 'cohere_rerank_input_transform',
    model_out_transform_fn => 'cohere_rerank_output_transform'
  );

汎用モデル

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

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

事前登録済みの汎用モデルとサポートが組み込まれたモデルの詳細については、サポートされているモデルをご覧ください。

汎用 Gemini モデル

このセクションでは、汎用 Gemini モデルを登録する方法について説明します。

gemini-1.5-pro モデル

一部の gemini-pro モデルは事前登録されているため、モデル ID を直接呼び出して予測を呼び出すことができます。

次の例では、Vertex AI Model Garden の gemini-1.5-pro:generateContent モデル エンドポイントを使用しています。

  1. psql を使用してデータベースに接続します。
  2. google_ml_integration 拡張機能を設定します。

  3. 以下のとおり、事前登録済みのモデル ID を使用して予測を呼び出します。

    SELECT
    json_array_elements(
    google_ml.predict_row(
        model_id => 'gemini-1.5-pro:generateContent',
        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';

Hugging Face の汎用モデル

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

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

  4. Secret Manager に保存されている Secret を呼び出します。

    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。
    • 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 => 'hugging_face',
    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。

Anthropic 汎用モデル

次の例では、claude-3-opus-20240229 モデル エンドポイントを追加します。モデル エンドポイント管理は、Anthropic モデルの登録に必要なヘッダー関数を提供します。

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

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

    Secret Manager

    1. 認証のため、署名なしトークンを Secret として Secret Manager に追加します。

    2. Secret Manager に保存されている Secret を呼び出します。

      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。
      • SECRET_MANAGER_SECRET_ID: シークレットの作成時に Secret Manager で設定したシークレット ID。
      • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
      • VERSION_NUMBER: シークレット ID のバージョン番号。

    3. モデル作成関数を呼び出して、claude-3-opus-20240229 モデル エンドポイントを登録します。

      CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_provider => 'anthropic',
    model_request_url => 'REQUEST_URL',
    model_auth_type => 'secret_manager',
    model_auth_id => 'SECRET_ID',
    generate_headers_fn => 'google_ml.anthropic_claude_header_gen_fn');

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

      • MODEL_ID: 定義するモデル エンドポイントの一意の ID（anthropic-opus など）。このモデル ID は、モデル エンドポイントがエンベディングの生成や予測の呼び出しに必要なメタデータのために参照されます。
      • REQUEST_URL: カスタム テキスト エンベディングと汎用モデル エンドポイントを追加する場合のモデル固有のエンドポイント（https://api.anthropic.com/v1/messages など）。

    Auth ヘッダー

    1. google_ml.anthropic_claude_header_gen_fn のデフォルトのヘッダー生成関数を使用するか、ヘッダー生成関数を作成します。

        CREATE OR REPLACE FUNCTION anthropic_sample_header_gen_fn(model_id VARCHAR(100), request_body JSON)
  RETURNS JSON
  LANGUAGE plpgsql
  AS $$
  #variable_conflict use_variable
  BEGIN
        RETURN json_build_object('x-api-key', 'ANTHROPIC_API_KEY', 'anthropic-version', 'ANTHROPIC_VERSION')::JSON;
  END;
  $$;

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

      • ANTHROPIC_API_KEY: anthropic API キー。
      • ANTHROPIC_VERSION（省略可）: 使用する特定のモデル バージョン（例: 2023-06-01）。

    2. モデル作成関数を呼び出して、claude-3-opus-20240229 モデル エンドポイントを登録します。

      CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_provider => 'anthropic',
    model_request_url => 'REQUEST_URL',
    generate_headers_fn => 'google_ml.anthropic_claude_header_gen_fn');

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

      • MODEL_ID: 定義するモデル エンドポイントの一意の ID（anthropic-opus など）。このモデル ID は、モデル エンドポイントがエンベディングの生成や予測の呼び出しに必要なメタデータのために参照されます。
      • REQUEST_URL: カスタム テキスト エンベディングと汎用モデル エンドポイントを追加する場合のモデル固有のエンドポイント（https://api.anthropic.com/v1/messages など）。

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

Vertex AI Model Garden のモデル

汎用モデルに加えて、特定のタスク用に最適化された Vertex AI Model Garden のモデルを登録できます。一般的なプロセスは、まず Model Garden からパブリック Vertex AI エンドポイントにモデルをデプロイし、そのエンドポイントを AlloyDB for PostgreSQL に登録することです。こうしたタスクに固有のモデルは、専用の model_type に登録され、特殊な SQL 関数で使用されることがよくあります。

TimesFM モデルを使用した時系列予測

タスクに固有のモデルの一般的なユースケースは、TimesFM モデルを使用した時系列予測の実行です。

このモデルをデプロイして登録する手順は次のとおりです。

  1. Model Garden から Vertex AI エンドポイントに TimesFM モデルをデプロイして、次のようにモデル リクエスト URL を取得します。

    1. Google Cloud コンソールで、[Model Garden] ページに移動します。

      Model Garden に移動

    2. TimesFM モデルを見つけて、[デプロイ] を選択します。

    3. デプロイ設定の [エンドポイント アクセス] で [パブリック（共有エンドポイント）] を選択して、エンドポイントを一般公開し、AlloyDB for PostgreSQL からアクセスできるようにします。

    4. デプロイが完了したら、エンドポイントの詳細ページに移動し、[リクエストの例] ペインからモデル リクエスト URL をコピーします。

  2. デプロイされた TimesFM モデルを AlloyDB for PostgreSQL に登録するには、google_ml.create_model 関数を使用します。時系列予測の場合、model_type を ts_forecasting にする必要があります。

CALL
google_ml.create_model(
  model_id => 'vertex_timesfm',
  model_qualified_name => 'timesfm_v2',
  model_type => 'ts_forecasting',
  model_provider => 'google',
  model_request_url => 'https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/endpoints/ENDPOINT_ID:predict',
  model_auth_type => 'alloydb_service_agent_iam'
);

モデルを登録したら、ai.forecast() 関数または google_ml.forecast() 関数を使用して予測を生成できます。

次のステップ