Cloud SQL と Vertex AI を統合する

このページでは、Cloud SQL を Vertex AI と統合する方法について説明します。このインテグレーションにより、Vertex AI でホストされている大規模言語モデル（LLM）を Cloud SQL for PostgreSQL データベース（バージョン 12 以降）に適用できるようになります。

Cloud SQL を Vertex AI と統合することで、機械学習（ML）モデルのセマンティック機能と予測機能をデータに適用できます。このインテグレーションでは、モデルのクエリ用に次の 2 つの関数を使用して PostgreSQL 構文を拡張します。

  • 予測を呼び出し、トランザクション内で SQL を使用してモデルを呼び出します。
  • エンベディングを生成し、エンベディング モデルにテキスト プロンプトを数値ベクトルに変換させます。これらのベクトル エンベディングは pgvector 関数への入力として適用できます。これには、相対的なセマンティック距離に従ってテキストのサンプルを比較し、並べ替えるメソッドが含まれます。

その結果、リアルタイムの予測を行い、有益な分析情報をデータベース内で直接取得できるため、ワークフローを効率化し、意思決定能力を高めることができます。

Vertex AI の詳細については、Vertex AI の概要をご覧ください。

始める前に

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Make sure that billing is enabled for your Google Cloud project.

  6. 必要な Google Cloud APIs を有効にします。

    コンソール

    1. [API とサービス] ページに移動します。
    2. プロジェクト リストからプロジェクトを選択します。
    3. [API ライブラリ] が開いていない場合は、ナビゲーション メニューから [ライブラリ] を選択します。

    4. 有効にする API をクリックします。ここでは、Cloud SQL Admin API と Vertex AI API を有効にします。

    5. API を選択したら、[有効にする] をクリックします。

    gcloud

    1. Cloud Shell を開きます。これにより、ブラウザからコマンドラインで直接 Google Cloud リソースにアクセスできます。
    2. 必要な API を有効にするには、gcloud services enable コマンドを使用します。
      gcloud services enable sqladmin.googleapis.com \
enable aiplatform.googleapis.com
      3. このコマンドにより、次の API が有効になります。
      • Cloud SQL Admin API
      • Vertex AI API

  7. Cloud SQL サービス アカウントに、Vertex AI にアクセスするための Identity and Access Management（IAM）権限を付与します。

    gcloud

    Cloud SQL インスタンスが配置されているプロジェクトの Cloud SQL サービス アカウントに Vertex AI の権限を追加するには、gcloud projects add-iam-policy-binding コマンドを使用します。

    gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
  --role="roles/aiplatform.user"

    次のように置き換えます。
    • PROJECT_ID: Vertex AI エンドポイントを持つプロジェクトの ID。Cloud SQL は、このエンドポイントを使用して Vertex AI でホストされている LLM にアクセスします。

    • SERVICE_ACCOUNT_EMAIL: Cloud SQL サービス アカウントのメールアドレス。

      このメールアドレスを確認するには、gcloud sql instances describe INSTANCE_NAME コマンドを使用し、INSTANCE_NAME を Cloud SQL インスタンスの名前に置き換えます。serviceAccountEmailAddress パラメータの横に表示される値がメールアドレスです。

Vertex AI とデータベースのインテグレーションを有効にする

Vertex AI とデータベースのインテグレーションを有効にするには、次の操作を行います。

  1. インスタンスが Vertex AI と統合されるように Cloud SQL インスタンスを作成または更新します。

    gcloud

    インスタンスを作成する

    Cloud SQL インスタンスを作成するには、gcloud sql instances create コマンドを使用します。

    gcloud sql instances create INSTANCE_NAME \
--database-version=DATABASE_VERSION \
--tier=MACHINE_TYPE \
--region=REGION_NAME \
--enable-google-ml-integration \
--database-flags cloudsql.enable_google_ml_integration=on

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

    • INSTANCE_NAME: インスタンスの名前
    • DATABASE_VERSION: インスタンスのデータベース バージョン（例: POSTGRES_13）
    • MACHINE_TYPE: インスタンスのマシンタイプ
    • REGION_NAME: インスタンスのリージョン名。

    インスタンスを更新する

    インスタンスを更新するには、gcloud sql instances patch コマンドを使用します。

    gcloud sql instances patch INSTANCE_NAME \
--enable-google-ml-integration \
--database-flags cloudsql.enable_google_ml_integration=on

    再起動が必要な値を変更した場合、処理の続行またはキャンセルの選択を求められます。

    REST v1

    インスタンスを作成する

    この例ではインスタンスを作成します。呼び出しのパラメータの完全なリストについては、instances:insert ページをご覧ください。リージョンの有効な値など、インスタンスの設定の詳細については、インスタンスの設定をご覧ください。

    リクエストのデータを使用する前に、次のように置き換えます。

    • PROJECT_ID: インスタンスが含まれている Google Cloud プロジェクトの ID またはプロジェクト番号
    • INSTANCE_NAME: インスタンスの名前
    • REGION_NAME: インスタンスのリージョン名。
    • DATABASE_VERSION: データベース バージョンの列挙型文字列（例: POSTGRES_13）
    • PASSWORD: root ユーザーのパスワード
    • MACHINE_TYPE: マシン（階層）タイプの列挙型文字列（例: db-custom-[CPUS]-[MEMORY_MBS]）
    • EDITION_TYPE: Cloud SQL のエディション

    リクエストに enableGoogleMlIntegration オブジェクトも含める必要があります。必要に応じて、次のパラメータを設定します。

    • enableGoogleMlIntegration: このパラメータを true に設定すると、Cloud SQL インスタンスを Vertex AI に接続して、リアルタイム予測と分析情報のリクエストを AI に渡すことができます。
    • cloudsql.enable_google_ml_integration: このパラメータを on に設定すると、Cloud SQL を Vertex AI と統合できます。

    HTTP メソッドと URL:

    POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances

    リクエストの本文（JSON）: 

    {
  "name": "INSTANCE_NAME",
  "region": "REGION_NAME",
  "databaseVersion": "DATABASE_VERSION",
  "rootPassword": "PASSWORD",
  "settings": {
    "tier": "MACHINE_TYPE",
    "edition": "EDITION_TYPE",
    "enableGoogleMlIntegration": "true" | "false"
    "databaseFlags":
      {
        "name": "cloudsql.enable_google_ml_integration",
        "value": "on" | "off"
      }
  }
}

    リクエストを送信するには、次のいずれかのオプションを開きます。

    次のような JSON レスポンスが返されます。

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2019-09-25T22:19:33.735Z",
  "operationType": "CREATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

    インスタンスを更新する

    この例ではインスタンスを更新します。呼び出しのパラメータの完全なリストについては、Instances:patch ページをご覧ください。

    再起動が必要な値を変更した場合、処理の続行またはキャンセルの選択を求められます。

    リクエストのデータを使用する前に、次のように置き換えます。

    • PROJECT_ID: インスタンスが含まれている Google Cloud プロジェクトの ID またはプロジェクト番号
    • INSTANCE_NAME: インスタンスの名前

    HTTP メソッドと URL:

    PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

    リクエストの本文（JSON）: 

    {
  "settings": {
    "enableGoogleMlIntegration": true,
    "databaseFlags":
      {
        "name": "cloudsql.enable_google_ml_integration",
        "value": "on"
      }
   }
}

    リクエストを送信するには、次のいずれかのオプションを開きます。

    次のような JSON レスポンスが返されます。

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

    REST v1beta4

    インスタンスを作成する

    この例ではインスタンスを作成します。呼び出しのパラメータの完全なリストについては、instances:insert ページをご覧ください。リージョンの有効な値など、インスタンスの設定の詳細については、インスタンスの設定をご覧ください。

    リクエストのデータを使用する前に、次のように置き換えます。

    • PROJECT_ID: インスタンスが含まれている Google Cloud プロジェクトの ID またはプロジェクト番号
    • INSTANCE_NAME: インスタンスの名前
    • REGION_NAME: インスタンスのリージョン名。
    • DATABASE_VERSION: データベース バージョンの列挙型文字列（例: POSTGRES_13）
    • PASSWORD: root ユーザーのパスワード
    • MACHINE_TYPE: マシン（階層）タイプの列挙型文字列（例: db-custom-[CPUS]-[MEMORY_MBS]）
    • EDITION_TYPE: Cloud SQL のエディション

    リクエストに enableGoogleMlIntegration オブジェクトも含める必要があります。必要に応じて、次のパラメータを設定します。

    • enableGoogleMlIntegration: このパラメータを true に設定すると、Cloud SQL インスタンスを Vertex AI に接続して、リアルタイム予測と分析情報のリクエストを AI に渡すことができます。
    • cloudsql.enable_google_ml_integration: このパラメータを on に設定すると、Cloud SQL を Vertex AI と統合できます。

    HTTP メソッドと URL:

    POST https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances

    リクエストの本文（JSON）: 

    {
  "name": "INSTANCE_NAME",
  "region": "REGION_NAME",
  "databaseVersion": "DATABASE_VERSION",
  "rootPassword": "PASSWORD",
  "settings": {
    "tier": "MACHINE_TYPE",
    "edition": "EDITION_TYPE",
    "enableGoogleMlIntegration": "true" | "false"
    "databaseFlags":
      {
        "name": "cloudsql.enable_google_ml_integration",
        "value": "on" | "off"
      }
  }
}

    リクエストを送信するには、次のいずれかのオプションを開きます。

    次のような JSON レスポンスが返されます。

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2019-09-25T22:19:33.735Z",
  "operationType": "CREATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

    インスタンスを更新する

    この例ではインスタンスを更新します。呼び出しのパラメータの完全なリストについては、Instances:patch ページをご覧ください。

    再起動が必要な値を変更した場合、処理の続行またはキャンセルの選択を求められます。

    リクエストのデータを使用する前に、次のように置き換えます。

    • PROJECT_ID: インスタンスが含まれている Google Cloud プロジェクトの ID またはプロジェクト番号
    • INSTANCE_NAME: インスタンスの名前

    HTTP メソッドと URL:

    PATCH https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

    リクエストの本文（JSON）: 

    {
  "settings": {
    "enableGoogleMlIntegration": true,
    "databaseFlags":
      {
        "name": "cloudsql.enable_google_ml_integration",
        "value": "on"
      }
   }
}

    リクエストを送信するには、次のいずれかのオプションを開きます。

    次のような JSON レスポンスが返されます。

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}
  2. プライマリ Cloud SQL インスタンスのデータベースに google_ml_integration 拡張機能をインストールします。このデータベースには、予測を実行するデータが含まれています。
    1. psql クライアントを使用して接続するの説明に従って、psql クライアントをプライマリ インスタンスに接続します。
    2. psql コマンド プロンプトで、データベースに接続します。
      \c DB_NAME

      DB_NAME は、拡張機能をインストールするデータベースの名前に置き換えます。

    3. 拡張機能をインストールします。
      CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;

トラブルシューティング

このセクションでは、Cloud SQL と Vertex AI の統合に関連する問題と、その問題のトラブルシューティング手順について説明します。

問題 トラブルシューティング
エラー メッセージ: Google ML integration API is supported only on Postgres version 12 or above. Cloud SQL で Vertex AI のインテグレーションを有効にするには、バージョン 12 以降の Cloud SQL for PostgreSQL データベースが必要です。データベースをこのバージョンにアップグレードするには、データベースのメジャー バージョンをインプレースでアップグレードするをご覧ください。
エラー メッセージ: Google ML Integration API is not supported on shared core instance. Please upsize your machine type. インスタンスのマシンタイプに共有コアを選択した場合、Cloud SQL で Vertex AI とのインテグレーションを有効にすることはできません。マシンタイプを専用コアにアップグレードします。詳細については、マシンタイプをご覧ください。
エラー メッセージ: Google ML Integration is unsupported for this maintenance version. Please follow https://cloud.google.com/sql/docs/postgres/self-service-maintenance to update the maintenance version of the instance. Cloud SQL で Vertex AI とのインテグレーションを有効にするには、インスタンスのメンテナンス バージョンが R20240130 以降である必要があります。インスタンスをこのバージョンにアップグレードするには、セルフサービス メンテナンスをご覧ください。
エラー メッセージ: Cannot invoke ml_predict_row if 'cloudsql.enable_google_ml_integration' is off. cloudsql.enable_google_ml_integration データベース フラグがオフになっていて、Cloud SQL を Vertex AI と統合できません。

このフラグをオンにするには、gcloud sql instances patch コマンドを使用します。

gcloud sql instances patch INSTANCE_NAME --database-flags cloudsql.enable_google_ml_integration=on

INSTANCE_NAME は、プライマリ Cloud SQL インスタンスの名前に置き換えます。
エラー メッセージ: Failed to connect to remote host: Connection refused. Cloud SQL と Vertex AI のインテグレーションが有効になっていません。このインテグレーションを有効にするには、gcloud sql instances patch コマンドを使用します。

gcloud sql instances patch INSTANCE_NAME
--enable-google-ml-integration

INSTANCE_NAME は、プライマリ Cloud SQL インスタンスの名前に置き換えます。
エラー メッセージ: Vertex AI API has not been used in project PROJECT_ID before or it is disabled. Enable it by visiting /apis/api/aiplatform.googleapis.com/overview?project=PROJECT_ID then retry. Vertex AI API が有効になっていません。この API を有効にする方法については、Vertex AI とデータベースのインテグレーションを有効にするをご覧ください。
エラー メッセージ: Permission 'aiplatform.endpoints.predict' denied on resource. Vertex AI の権限が、Cloud SQL インスタンスが配置されているプロジェクトの Cloud SQL サービス アカウントに追加されていません。これらの権限をサービス アカウントに追加する方法については、Vertex AI とデータベースのインテグレーションを有効にするをご覧ください。
エラー メッセージ: Publisher Model `projects/PROJECT_ID/locations/REGION_NAME/publishers/google/models/MODEL_NAME` not found. ML モデルまたは LLM が Vertex AI に存在しません。
エラー メッセージ: Resource exhausted: grpc: received message larger than max. Cloud SQL が Vertex AI に渡すリクエストのサイズが、gRPC の上限（リクエストあたり 4 MB）を超えています。
エラー メッセージ: Cloud SQL attempts to send a request to Vertex AI. However, the instance is in the %s region, but the Vertex AI endpoint is in the %s region. Make sure the instance and endpoint are in the same region. Cloud SQL が Vertex AI にリクエストを送信しようとしていますが、インスタンスのリージョンと Vertex AI エンドポイントのリージョンが異なります。この問題を解決するには、インスタンスとエンドポイントの両方を同じリージョンに配置する必要があります。
エラー メッセージ: The Vertex AI endpoint isn't formatted properly. Vertex AI エンドポイントの形式が正しくありません。詳細については、オンライン予測にプライベート エンドポイントを使用するをご覧ください。
エラー メッセージ: Quota exceeded for aiplatform.googleapis.com/online_prediction_requests_per_base_model with base model: textembedding-gecko. Cloud SQL が Vertex AI に渡すリクエストの数が上限（1 リージョン、1 プロジェクト、1 分あたり 1,500 件）を超えています。

次のステップ