このページでは、Cloud SQL を Vertex AI と統合する方法について説明します。
このインテグレーションにより、Vertex AI でホストされている大規模言語モデル(LLM)を Cloud SQL for SQL Server 2025 データベースに適用できるようになります。
Cloud SQL を Vertex AI と統合することで、機械学習(ML)モデルのセマンティック機能と予測機能をデータに適用できます。このインテグレーションでは、モデルのクエリ用にエンベディングを生成する関数を使用して SQL 構文を拡張します。
エンベディング モデルがテキスト プロンプトを数値ベクトルに変換できるように、エンベディング生成関数を使用します。これらのベクトル エンベディングは、ベクトル データ型への入力として適用できます。詳細については、Microsoft のドキュメントの SQL Database Engine のベクトル検索とベクトル インデックスをご覧ください。
Vertex AI の詳細については、Vertex AI の概要をご覧ください。
サポートされているエディションとデータベース バージョン
Vertex AI の統合は、Cloud SQL Enterprise Plus エディションと Cloud SQL Enterprise エディションの両方と、SQL Server 2025 のすべてのデータベース バージョンでサポートされています。
サポートされているモデルタイプ
Cloud SQL との Vertex AI の統合は、次のソースのモデル エンドポイントをサポートしています。
- Vertex AI
- Hugging Face
- OpenAI
始める前に
- Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、 アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
- 必要な Google Cloud API を有効にします。
コンソール
- [API とサービス] ページに移動します。
- プロジェクト リストからプロジェクトを選択します。
- [API ライブラリ] が開いていない場合は、ナビゲーション メニューから [ライブラリ] を選択します。
有効にする API をクリックします。この手順では、次のものを有効にします。
- Cloud SQL Admin API
- Vertex AI API
- Compute Engine API
- 省略可: サードパーティ モデルを使用する場合は、Secret Manager API が必要です。
- API を選択したら、[有効にする] をクリックします。
gcloud
- Cloud Shell を開きます。これにより、ブラウザから Google Cloud リソースにコマンドラインで直接アクセスできます
- 必要な API を有効にするには、
gcloud services enableコマンドを使用します。gcloud services enable sqladmin.googleapis.com \ aiplatform.googleapis.com \ compute.googleapis.com \ secretmanager.googleapis.com
このコマンドにより、次の API が有効になります。
- Cloud SQL Admin API
- Vertex AI API
- Compute Engine API
- 省略可: サードパーティ モデルを使用する場合は、Secret Manager API が必要です。
- Cloud SQL サービス アカウントに、Vertex AI にアクセスするための Identity and Access Management(IAM)権限を付与します。
- PROJECT_ID: Vertex AI エンドポイントを持つプロジェクトの ID。Cloud SQL は、このエンドポイントを使用して Vertex AI でホストされている LLM にアクセスします。
SERVICE_ACCOUNT_EMAIL: Cloud SQL サービス アカウントのメールアドレス。
このメールアドレスを確認するには、
gcloud sql instances describeコマンドを使用します。gcloud sql instances describe INSTANCE_NAME | grep EmailAddress
INSTANCE_NAME は、Cloud SQL インスタンスの名前に置き換えます。
- エンベディング モデルを操作する Cloud SQL ユーザーに次のデータベース権限が付与されていることを確認します。
- データベース ユーザーがモデルを作成または変更できるようにするには、次のストアド プロシージャに対する
EXECUTE権限を Cloud SQL ユーザーに付与する必要があります。[msdb].gcloudsql_ml_create_external_model: AI モデルの推論エンドポイントのロケーション、認証方法、目的を含む外部モデル オブジェクトを作成します。[msdb].gcloudsql_ml_alter_external_model: 外部モデル オブジェクトを変更できます。[msdb].gcloudsql_ml_drop_external_model: 外部モデル オブジェクトをデータベースから削除します。
- 前に記載したストアド プロシージャを呼び出すには、ターゲット データベースに次の権限が必要です。
CREATE EXTERNAL MODELALTER EXTERNAL MODEL
これらの権限を付与する方法については、Microsoft のドキュメントで Create external model コマンドと命名規則をご覧ください。
Cloud SQL スーパーユーザーの権限については、SQL Server ユーザーとストアド プロシージャについてをご覧ください。
- データベース ユーザーがモデルを作成または変更できるようにするには、次のストアド プロシージャに対する
- サードパーティの外部モデルを使用する場合は、Cloud SQL インスタンスからアクセス可能な Secret Manager のロケーションに、モデルの有効な API キーが保存されている必要があります。
- サードパーティの外部モデルを使用している場合、Cloud SQL インスタンスはパブリック IP アドレスを使用する必要があります。プライベート IP インスタンスは、サードパーティの外部モデルにアクセスできません。プライベート サービス アクセスと Private Service Connect は、Vertex AI 統合でのみサポートされています。
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"
Vertex AI とデータベースのインテグレーションを有効にする
Vertex AI とデータベースのインテグレーションを有効にするには、次の操作を行います。
- インスタンスが 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
次のように置き換えます。
- INSTANCE_NAME: インスタンスの名前。
- DATABASE_VERSION: インスタンスのデータベース バージョン(
SQLSERVER_2025_ENTERPRISEなど)。 - MACHINE_TYPE: インスタンスのマシンタイプ(例:
db-perf-optimized-N-8.)。 - REGION_NAME: インスタンスのリージョン(
us-central1など)。
インスタンスを更新する
インスタンスを更新するには、
gcloud sql instances patchコマンドを使用します。gcloud sql instances patch INSTANCE_NAME \ --enable-google-ml-integration
REST v1
インスタンスを作成する
この例ではインスタンスを作成します。呼び出しのパラメータの完全なリストについては、instances:insert ページをご覧ください。リージョンの有効な値など、インスタンスの設定の詳細については、インスタンスの設定をご覧ください。
リクエストのデータを使用する前に、次のように置き換えます。
- PROJECT_ID: インスタンスが含まれている Google Cloud プロジェクトの ID またはプロジェクト番号。
- INSTANCE_NAME: インスタンスの名前。
- REGION_NAME: インスタンスのリージョン名。
- DATABASE_VERSION: データベース バージョンの列挙型文字列(例:
SQLSERVER_2025_ENTERPRISE)。 - PASSWORD: データベース
rootユーザーのパスワード。 - MACHINE_TYPE: マシン(階層)タイプの列挙型文字列(
db-custom-[CPUS]-[MEMORY_MBS]など)。詳細については、マシンティアをご覧ください。 - EDITION_TYPE: Cloud SQL のエディション(
ENTERPRISEなど)。
リクエストに enableGoogleMlIntegration オブジェクトも含める必要があります。必要に応じて、次のパラメータを設定します。
enableGoogleMlIntegration: このパラメータをtrueに設定すると、Cloud SQL インスタンスを Vertex AI に接続して、リアルタイム予測と分析情報のリクエストを 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" } }リクエストを送信するには、次のいずれかのオプションを展開します。
次のような 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, } }リクエストを送信するには、次のいずれかのオプションを展開します。
次のような 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: データベース バージョンの列挙型文字列(例:
SQLSERVER_2025_ENTERPRISE)。 - PASSWORD: データベース
rootユーザーのパスワード。 - MACHINE_TYPE: マシン(階層)タイプの列挙型文字列(
db-custom-[CPUS]-[MEMORY_MBS]など)。詳細については、マシンティアをご覧ください。 - EDITION_TYPE: Cloud SQL のエディション(
ENTERPRISEなど)。
リクエストに enableGoogleMlIntegration オブジェクトも含める必要があります。必要に応じて、次のパラメータを設定します。
enableGoogleMlIntegration: このパラメータをtrueに設定すると、Cloud SQL インスタンスを Vertex AI に接続して、リアルタイム予測と分析情報のリクエストを 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" } }リクエストを送信するには、次のいずれかのオプションを展開します。
次のような 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, } }リクエストを送信するには、次のいずれかのオプションを展開します。
次のような 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" }
Secret Manager の権限を追加する
OpenAI や Hugging Face などの外部ソースのモデルを使用する場合は、モデルソースの API キーを Secret Manager に保存する必要があります。
次に、Cloud SQL インスタンスに Secret Manager のモデルソースの API キーへのアクセス権を付与する必要があります。アクセス権を取得するには、次のコマンドを実行します。
SA_NAME=$(gcloud sql instances describe INSTANCE_NAME --format="value(serviceAccountEmailAddress)");
gcloud secrets add-iam-policy-binding SECRET_NAME \
--member="serviceAccount:${SA_NAME}" \
--role="roles/secretmanager.secretAccessor"
次のように置き換えます。
- INSTANCE_NAME: Cloud SQL インスタンスの名前。
- SECRET_NAME: Secret Manager で使用されるシークレットの名前。
外部モデル オブジェクト
外部ソースからモデルにアクセスするには、SQL Server が使用するモデル オブジェクトを作成する必要があります。Cloud SQL には、外部モデル オブジェクトの作成、変更、削除を行うための 3 つのストアド プロシージャが用意されています。
gcloudsql_ml_create_external_modelgcloudsql_ml_alter_external_modelgcloudsql_ml_drop_external_model
外部モデルを作成する
モデルを作成するには、msdb データベースにある gcloudsql_ml_create_external_model ストアド プロシージャを実行します。
EXECUTE [msdb].[dbo].[gcloudsql_ml_create_external_model] @db = [DB_NAME], @model_name = MODEL_NAME, @model_provider = 'MODEL_PROVIDER', @model = 'MODEL', @model_url = MODEL_URL, @secret_url = SECRET_URL
次のように置き換えます。
- DB_NAME: 外部モデルを作成するターゲット データベース。
- MODEL_NAME: 新しい外部モデルの名前。
- MODEL_PROVIDER: モデル プロバイダの名前(次のいずれかなど)。
- Vertex AI
- OpenAI
- Hugging Face
- MODEL_URL: モデル エンドポイントの URL。
- MODEL: 呼び出される AI モデル。例:
gemini-embedding-002。 - SECRET_URL: Vertex AI がモデル プロバイダの場合、このパラメータは空にする必要があります。外部モデルを使用している場合、この値は API キーの Secret Manager のロケーションを参照する必要があります。URL の例の形式は次のとおりです。
https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_NAME/versions/VERSION次のように置き換えます。
- PROJECT_ID: シークレットが配置されているプロジェクト ID。
- SECRET_NAME: Secret Manager で使用されるシークレットの名前。
- VERSION: シークレットのバージョン番号。
外部モデルを変更する
外部モデル オブジェクトを変更するには、msdb データベースにある gcloudsql_ml_alter_external_model ストアド プロシージャを実行します。
EXECUTE [msdb].[dbo].[gcloudsql_ml_alter_external_model] @db = [DB_NAME], @model_name = MODEL_NAME, @model_provider = 'MODEL_PROVIDER', @model = 'MODEL', @model_url = MODEL_URL, @secret_url = SECRET_URL
次のように置き換えます。
- DB_NAME: 変更するモデルが存在するターゲット データベース。
- MODEL_NAME: 既存のモデルの名前。
- MODEL_PROVIDER: モデル プロバイダの名前(次のいずれかなど)。
- Vertex AI
- OpenAI
- Hugging Face
- MODEL_URL: モデル エンドポイントの URL。
- MODEL: 呼び出される AI モデル。例:
gemini-embedding-001 - SECRET_URL: Vertex AI がモデル プロバイダの場合、このパラメータは空にする必要があります。外部モデルを使用している場合、この値は API キーの Secret Manager のロケーションを参照する必要があります。URL の例は次の形式を使用します。
https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_NAME/versions/VERSION次のように置き換えます。
- PROJECT_ID: シークレットが配置されているプロジェクト ID。
- SECRET_NAME: Secret Manager で使用されるシークレットの名前。
- VERSION: シークレットのバージョン番号。
Vertex AI のインテグレーションを無効にする
Cloud SQL インスタンスで Vertex AI の統合を無効にするには、次のコマンドを実行します。
gcloud sql instances patch [instance-name] --no-enable-google-ml-integration
INSTANCE_NAME は、Cloud SQL インスタンスの名前に置き換えます。
SQL Server で外部モデルを削除する
SQL Server から外部モデルを削除するには、msdb データベースにある gcloudsql_ml_drop_external_model ストアド プロシージャを実行します。
EXECUTE [msdb].[dbo].[gcloudsql_ml_drop_external_model] @db = [DB_NAME], @model_name = MODEL_NAME
次のように置き換えます。
- DB_NAME: 削除する外部モデルが存在するターゲット データベース。
- MODEL_NAME: 削除する外部モデルの名前。
外部モデルを呼び出す
Cloud SQL インスタンスで Vertex AI 統合が有効になり、SQL Server で使用するモデル オブジェクトが作成されたら、SQL Server の AI_GENERATE_EMBEDDINGS 関数を呼び出して、データのベクトル エンベディングを作成できます。
外部モデルを使用してベクトル エンベディングを作成するには、次のコマンドを実行します。
SELECT AI_GENERATE_EMBEDDINGS(N'Test Text' USE MODEL MODEL_NAME)
MODEL_NAME は、使用するモデルの名前に置き換えます。
実行するプリンシパル ユーザーには、適切なロールまたは権限付与を使用して EXECUTE ON EXTERNAL MODEL 権限が付与されている必要があります。
詳細については、Microsoft の 外部モデルの権限付与に関するドキュメントをご覧ください。
モデルサイズの制限
gemini-embedding-01 などの一部のモデルでは、SQL Server が float32 ベクトルでサポートできる最大次元数(1,998)よりも高いデフォルトの出力次元数が設定されています。必要に応じて、ベクトル ベースタイプに float16(Microsoft のプレビュー機能)を使用するか、AI_GENERATE_EMBEDDINGS リクエストでディメンション パラメータを指定して次元を削減する必要があります。float16 では、最大 3,996 個のベクトル ディメンションを使用できます。
詳細については、ベクトル データ型の半精度浮動小数点数のサポートをご覧ください。
例については、以下をご覧ください。
DECLARE @params JSON = N'{"dimensions": "DIMENSIONS"}';
SELECT AI_GENERATE_EMBEDDINGS('This article introduces AI concepts.' USE MODEL MODEL_NAME PARAMETERS @params)
次のように置き換えます。
- DIMENSIONS: モデルに使用するディメンション(
1536など)。この値は文字列として受け入れられます。 - MODEL_NAME: 使用するモデルの名前。
トラブルシューティング
表示される可能性のあるエラー メッセージは次のとおりです。
| コンテキスト | 表示されたエラーまたはメッセージ | 考えられる原因 |
|---|---|---|
CREATE/ALTER 手順 |
「指定されたモデル プロバイダは無効です。」 | サポートされていないモデル プロバイダが指定されました。 |
CREATE/ALTER 手順 |
「指定されたシークレット URL は、このモデル プロバイダに対して有効ではありません。」 | Vertex AI の場合、シークレット URL は空にする必要があります。他のモデル プロバイダの場合、シークレット URL を空にすることはできません。 |
CREATE/ALTER/DROP 手順 |
「指定されたモデル名は無効です。」 | モデル名は必須項目です。 |
CREATE/ALTER 手順 |
「指定されたモデル URL は無効です。」 | モデル URL は必須項目です。 |
CREATE/ALTER/DROP 手順 |
「指定された DB 名が無効です。」 | 有効な DB 名は必須項目です。 |
AI_GENERATE_EMBEDDINGS 件 |
400、403、404、405、500 などのさまざまなエラーコード。 |
AI_GENERATE_EMBEDDINGS 関数を実行しようとしたときに問題が発生した場合は、エラーコードのみが返されます。これは Microsoft の既知の制限事項です。 |
AI_GENERATE_EMBEDDINGS 件 |
HTTP レスポンスに有効な JSON が含まれていません。 | 429 や 500 などの再試行を求めるエラーコードが、ML エージェントから返されました。ただし、クライアントには代わりにこのテキスト メッセージが届きます。これは Microsoft の既知の制限事項です。 |
エラーコード
AI_GENERATE_EMBEDDINGS 関数はエラーコードのみを提供し、メッセージは提供しません。次の表に、一部のエラーコードで考えられる原因を示します。
| エラーコード | 考えられる原因 |
|---|---|
400 Bad Request |
|
401 Unauthorized |
サードパーティ モデルに有効な API キーがない。 |
403 Forbidden |
|
404 Not Found |
|
405 Method Not Allowed |
POST 以外のメソッドが指定されました。 |
413 Request Body Too Large |
リクエスト サイズが 1 MB の上限を超えています。 |
429 Too Many Requests |
モデル プロバイダからの Exhausted エラー。 |
500 Internal Server Error |
|