Cloud SQL でのリモート AI モデルの登録と呼び出しの概要

MySQL | PostgreSQL | SQL Server

このページでは、Cloud SQL でモデルエンドポイント管理を使用して AI モデルエンドポイントを登録し、予測を呼び出す方法について説明します。本番環境で AI モデルを使用するには、ベクトルエンベディングを生成して管理するをご覧ください。

概要

モデルエンドポイント管理を使用すると、モデルエンドポイントの登録、Cloud SQL インスタンスでのモデルエンドポイントのメタデータの管理、SQL クエリでのモデルの操作ができます。このようなモデルを使用することで、ベクトルエンベディングの生成と予測の呼び出しが可能になります。

モデルエンドポイント管理では、次のモデルタイプを登録できます。

Vertex AI テキストエンベディングモデル。
Google Cloud内のネットワークにホストされているカスタムホストテキストエンベディングモデル。
JSON ベースの API を使用した汎用モデル。このようなモデルの例としては以下のものがあります。
- Vertex AI Model Garden の gemini-flash モデル
- OpenAI モデルの open_ai モデル
- Google Cloud内のネットワークにホストされているモデル

仕組み

モデルエンドポイント管理を使用すると、次の要件を満たすモデルエンドポイントを登録できます。

モデルの入力と出力は JSON 形式をサポートしています。
モデルを呼び出すのに REST プロトコルを使用できます。

モデルエンドポイント管理にモデルエンドポイントを登録すると、モデルエンドポイント管理は、モデルへの参照として一意のモデル ID を使用して各エンドポイントを登録します。このモデル ID を使用すると、次のようにモデルをクエリできます。

エンベディングを生成して、テキストプロンプトを数値ベクトルに変換します。インスタンスでベクトルエンベディングのサポートを有効にすると、生成されたエンベディングをベクトルデータとして保存できます。詳細については、インスタンスでベクトルエンベディングを有効または無効にするをご覧ください。
予測を呼び出し、トランザクション内で SQL を使用してモデルを呼び出します。

Cloud SQL インスタンスでリモート AI モデルを登録し呼び出すには、インスタンスのメンテナンスバージョン MYSQL_VERSION.R20250531.01_14 以降をインストールする必要があります。インスタンスで MYSQL_VERSION.R20250531.01_14 より前のメンテナンスバージョンが実行されている場合は、Cloud SQL と Vertex AI のインテグレーションに記載されている次の関数のみを使用できます。

インスタンスをメンテナンスバージョン MYSQL_VERSION.R20250531.01_14 以降にアップグレードするには、セルフサービスメンテナンスをご覧ください。インスタンスをアップグレードすると、次の関数を使用できるようになります。

mysql.ml_create_model_registration(): 予測関数またはエンベディング関数で使用されるモデルエンドポイントを登録します。
mysql.ml_create_sm_secret_registration(): API キーが保存されている Google Cloud Secret Manager のシークレットを使用します。

また、登録したモデルプロバイダで次の関数を使用することもできます。

mysql.ml_embedding(): テキストエンベディングを生成します。
mysql.ml_predict_row(): JSON の入力形式と出力形式をサポートする汎用モデルを呼び出すときに予測を生成します。

必要なデータベースユーザー権限

リモート AI モデルを登録して呼び出すには、mysql.* 権限で SELECT と EXECUTE が付与されている MySQL データベースユーザーとしてログインする必要があります。

デフォルトでは、cloudsqlsuperuser ロールを持っているユーザーにはこれらの権限が付与されています。またはユーザーを作成して必要な権限を付与することもできます。

Cloud SQL の cloudsqlsuperuser ロールの詳細については、MySQL 8.0 のユーザー権限と MySQL 8.4 のユーザー権限をご覧ください。

主なコンセプト

モデルエンドポイント管理を使い始める前に、モデルに接続して使用するために必要なコンセプトを理解しておく必要があります。

モデルプロバイダ

モデルプロバイダは、サポートされているモデルのホスティングプロバイダです。次のテーブルでは、使用するモデルプロバイダに基づいて設定が必要なモデルプロバイダの値をまとめています。

モデルプロバイダ	関数での設定…
Vertex AI（Gemini を含む）	`google`
Anthropic	`anthropic`
Hugging Face	`hugging_face`
OpenAI	`open_ai`
Vertex AI、Anthropic、Hugging Face、OpenAI の外部でホストされているその他のモデル	`custom`

デフォルトのモデルプロバイダは custom です。

モデルタイプ

モデルタイプは、AI モデルのタイプです。モデルエンドポイントを登録するときに、エンドポイントのモデルタイプとして text_embedding または generic を設定できます。

Vertex AI をモデルプロバイダとして使用する場合は、エンドポイントが自動的にサポートされるため、モデルエンドポイントを登録する必要はありません。デフォルトでは、Vertex AI の場合 text-embedding-005 モデルを使用します。

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

他のテキストエンベディングモデルの場合は、モデルがサポートする入力形式と出力形式を処理する変換関数を作成する必要があります。必要に応じて、HTTP ヘッダー生成関数を使用して、モデルに必要なカスタムヘッダーを生成できます。

これらのモデルのモデルタイプは text_embedding です。

汎用モデル

モデルエンドポイント管理では、テキストエンベディングモデルを除くすべてのモデルタイプを登録できます。汎用モデルの予測を呼び出すには、mysql.ml_predict_row() 関数を使用します。モデル固有のリクエストエンドポイントや HTTP ヘッダーなど、モデルエンドポイントのメタデータを設定できます。

汎用モデルエンドポイントを登録するときに変換関数を渡すことはできません。予測を呼び出すときに、関数への入力が JSON 形式になっていることと、JSON 出力を解析して最終出力を取得していることを確認します。

これらのモデルのモデルタイプは generic です。generic はデフォルトのモデルタイプであるため、このタイプのモデルエンドポイントを登録する場合、モデルタイプの設定は省略可能です。

Vertex AI の場合、モデルエンドポイント管理に gemini-2.5-flash モデルの事前登録済みサポートが含まれています。

認証方法

Cloud SQL for MySQL インスタンスでベクトルエンベディングのサポートを有効にしたうえで、モデルにアクセスするためのさまざまな認証方法を指定できます。これらのメソッドの設定は省略可能です。モデルにアクセスするために認証が必要な場合にのみ必須となります。

Vertex AI モデルの場合、認証には Cloud SQL サービスアカウントが使用されます。他のモデルの場合、Secret Manager にシークレットとして保存されている API キーまたは署名なしトークンを mysql.ml_create_sm_secret_registration() SQL 関数で使用できます。

次の表では、設定可能な認証方法をまとめています。

認証方法	関数での設定…	モデルプロバイダ
Cloud SQL サービスエージェント	`auth_type_cloudsql_service_agent_iam`	Vertex AI プロバイダ
Secret Manager	`auth_type_secret_manager`	Vertex AI の外部でホストされているモデル

予測関数

mysql.ml_embedding(): 登録されたテキストエンベディングモデルエンドポイントを呼び出してエンベディングを生成します。Vertex AI のエンベディングモデルすべてに対する組み込みサポートも含まれます。; 組み込みサポートのないテキストエンベディングモデルの場合、入力パラメータと出力パラメータはモデルに固有であり、関数でモデルを呼び出すには変換が必要となります。予測関数の入力をモデル固有の入力に変換する入力変換関数と、モデル固有の出力を予測関数出力に変換する出力変換関数を作成します。
mysql.ml_predict_row(): 登録された汎用モデルエンドポイントを呼び出します（エンドポイントが予測を呼び出す JSON ベースの API をサポートしている場合）。

変換関数

変換関数は、入力をモデルが理解できる形式に変更し、モデルのレスポンスを予測関数が想定する形式に変換します。変換関数は、組み込みサポートなしで text-embedding モデルエンドポイントを登録する場合に使用されます。変換関数の署名は、モデルタイプの予測関数によって異なります。

generic モデルエンドポイントを登録するときには変換関数を使用できません。

次のコードはテキストエンベディングモデルの予測関数の署名を示しています。

// define custom model specific input/output transform functions.
CREATE FUNCTION IF NOT EXISTS input_transform_function(model_id VARCHAR(100), input_text TEXT) RETURNS JSON DETERMINISTIC;

// the returned BLOB should be of type VECTOR
CREATE FUNCTION IF NOT EXISTS output_transform_function(model_id VARCHAR(100), response_json JSON) RETURNS BLOB DETERMINISTIC;

変換関数の作成方法については、変換関数の例をご覧ください。

HTTP ヘッダー生成関数

HTTP ヘッダー生成関数は、HTTP ヘッダーとして使用される JSON Key-Value ペアで出力を生成します。予測関数の署名は、ヘッダー生成関数の署名を定義します。

次の例は、mysql.ml_embedding() 予測関数の署名を示しています。

CREATE FUNCTION IF NOT EXISTS generate_headers(model_id VARCHAR(100), input TEXT) RETURNS JSON DETERMINISTIC;

mysql.ml_predict_row() 予測関数の署名は次のとおりです。

CREATE FUNCTION IF NOT EXISTS generate_headers(model_id VARCHAR(100), input JSON) RETURNS JSON DETERMINISTIC;

ヘッダー生成関数の作成方法については、ヘッダー生成関数の例をご覧ください。

制限事項

モデル登録関数またはシークレット管理関数を実行すると、セッション内のオープントランザクションが暗黙的に commit されます。予測関数の場合、トランザクションは暗黙的に commit されません。
mysqldump を使用してデータベースをエクスポートまたはインポートすると、モデルエンドポイントカタログはエクスポートされません。
変換関数を含むユーザーデータベースの名前には、ピリオド文字（'.'）を使用できません。たとえば、my.sql という名前のデータベースはサポートされません。
モデルエンドポイント管理は、Cloud SQL for MySQL バージョン 8.0.36 以降でのみ使用できます。