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

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

始める前に

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

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

拡張機能を有効にする

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

  1. インスタンスの google_ml_integration.enable_model_support データベース フラグが on に設定されていることを確認します。データベース フラグの設定の詳細については、インスタンスのデータベース フラグを構成するをご覧ください。

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

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

        ALTER EXTENSION google_ml_integration UPDATE;
    
  4. psql を使用して google_ml_integration 拡張機能を追加します。

      CREATE EXTENSION IF NOT EXISTS google_ml_integration;
    
  5. 省略可: モデルのメタデータを管理する権限を PostgreSQL の非スーパーユーザーに付与します。

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

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

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

認証の設定

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

Vertex AI の認証を設定する

Google Vertex AI モデル エンドポイントを使用するには、データベースへの接続に使用する IAM ベースの AlloyDB サービス アカウントに Vertex AI 権限を追加する必要があります。Vertex AI との統合の詳細については、Vertex AI と統合するをご覧ください。

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

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

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

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

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

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

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

      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 モデルをご覧ください。

たとえば、事前登録された textembedding-gecko モデルを呼び出すには、エンベディング関数

を使用してモデルを直接呼び出します。

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

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

 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'; 

エンベディングを生成するには、事前登録済みモデル エンドポイントのエンベディングを生成する方法をご覧ください。予測を呼び出すには、事前登録済みのモデル エンドポイントの予測を呼び出す方法をご覧ください。

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

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

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

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

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

クエリを実行する AlloyDB クラスタと Vertex AI モデルの両方が同じリージョンにあることを確認します。

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

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

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

    text-embedding-005

      CALL
        google_ml.create_model(
          model_id => 'text-embedding-005',
          model_request_url => 'publishers/google/models/text-embedding-005',
          model_provider => 'google',
          model_qualified_name => 'text-embedding-005',
          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 にシークレットとして追加します
  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 ヘッダーを作成する方法について説明します。カスタム ホスト型モデル エンドポイントは、ホストされている場所に関係なくすべてサポートされています。

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

汎用モデル

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

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

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

Gemini モデル

一部の 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 にシークレットとして追加します。他の 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. モデル作成関数を呼び出して、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 Manager に追加します
    2. 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 のバージョン番号。
    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)。

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

次のステップ