このページでは、AI モデル エンドポイントを登録し、Cloud SQL でモデル エンドポイント管理を使用して予測を呼び出す方法について説明します。本番環境で AI モデルを使用するには、Cloud SQL を使用して生成 AI アプリケーションを作成するとベクトル エンベディングを操作するをご覧ください。
概要
モデル エンドポイント管理を使用すると、モデル エンドポイントを登録し、Cloud SQL インスタンスでモデル エンドポイントのメタデータを管理し、SQL クエリを使用してモデルを操作できます。Cloud SQL には、モデルに関連するモデル エンドポイント メタデータを追加して登録する関数を含む google_ml_integration 拡張機能が用意されています。これらのモデルを使用して、ベクトル エンベディングを生成したり、予測を呼び出したりできます。
モデル エンドポイント管理を使用して、次のモデルタイプを登録できます。
- Vertex AI テキスト エンベディング モデル。
- Google Cloud 内のネットワークでホストされるカスタム ホストテキスト エンベディング モデル。
- JSON ベースの API を使用した汎用モデル。これらのモデルの例を以下に示します。
- Vertex AI Model Garden の
gemini-proモデル - OpenAI モデルの
open_aiモデル - Google Cloud 内のネットワークでホストされているモデル
- Vertex AI Model Garden の
仕組み
モデル エンドポイント管理を使用すると、次の要件を満たすモデル エンドポイントを登録できます。
- モデルの入力と出力は JSON 形式をサポートしています。
- REST プロトコルを使用してモデルを呼び出すことができます。
モデルエンドポイント管理にモデルエンドポイントを登録すると、モデルエンドポイント管理は、モデルへの参照として一意のモデル ID を持つ各エンドポイントを登録します。このモデル ID を使用して、次のようにモデルをクエリできます。
エンベディングを生成して、テキスト プロンプトを数値ベクトルに変換します。データベースで
pgvector拡張機能が有効になっている場合、生成されたエンベディングをベクトルデータとして保存できます。詳細については、pgvector を使用したエンベディングのクエリとインデックス登録をご覧ください。予測を呼び出し、トランザクション内で SQL を使用してモデルを呼び出します。
アプリケーションは、google_ml_integration 拡張機能を使用してモデル エンドポイントを管理できます。この拡張機能は、次の SQL 関数を提供します。
google_ml.create_model(): 予測関数またはエンベディング関数で使用されるモデル エンドポイントを登録します。google_ml.create_sm_secret(): Google Cloud Secret Manager のシークレットを使用します。ここに API キーが保存されます。google_ml.embedding(): テキスト エンベディングを生成します。google_ml.predict_row(): JSON の入力形式と出力形式をサポートする汎用モデルを呼び出すときに予測を生成します。
主なコンセプト
モデル エンドポイント管理の使用を開始する前に、モデルに接続して使用するのに必要なコンセプトを理解してください。
モデル プロバイダ
モデル プロバイダは、サポートされているモデル ホスティング プロバイダです。次の表に、使用するモデル プロバイダに基づいて設定する必要があるモデル プロバイダの値を示します。
| モデル プロバイダ | 関数で次のように設定します。 |
|---|---|
| Vertex AI（Gemini を含む） | google |
| OpenAI | open_ai |
| Vertex AI の外部でホストされているその他のモデル | custom |
デフォルトのモデル プロバイダは custom です。
モデルタイプ
モデルタイプは、AI モデルのタイプです。モデル エンドポイントを登録するときに、エンドポイントのモデルタイプとして text-embedding または generic を設定できます。
- サポートが組み込まれたテキスト エンベディング モデル
- モデル エンドポイント管理には、
textembedding-geckoモデルのすべてのバージョンが組み込まれています。これらのモデル エンドポイントを登録するには、google_ml.create_model()関数を使用します。Cloud SQL は、これらのモデルのデフォルトの変換関数を自動的に設定します。 - これらのモデルのモデルタイプは
text-embeddingです。 - その他のテキスト エンベディング モデル
- 他のテキスト エンベディング モデルの場合は、モデルがサポートする入力形式と出力形式を処理する変換関数を作成する必要があります。必要に応じて、モデルに必要なカスタム ヘッダーを生成する HTTP ヘッダー生成関数を使用できます。
- これらのモデルのモデルタイプは
text-embeddingです。 - 汎用モデル
- モデル エンドポイント管理では、テキスト エンベディング モデルを除く他のすべてのモデルタイプの登録もサポートされています。汎用モデルの予測を呼び出すには、
google_ml.predict_row()関数を使用します。モデル固有のリクエスト エンドポイントや HTTP ヘッダーなど、モデル エンドポイントのメタデータを設定できます。 - 汎用モデル エンドポイントを登録するときに変換関数を渡すことはできません。予測を呼び出すときに、関数への入力が JSON 形式であること、および JSON 出力を解析して最終出力を導出していることを確認します。
- これらのモデルのモデルタイプは
genericです。genericはデフォルトのモデルタイプであるため、このタイプのモデル エンドポイントを登録する場合、モデルタイプの設定は省略可能です。
認証方法
google_ml_integration 拡張機能を使用すると、モデルにアクセスするためのさまざまな認証方法を指定できます。これらの方法の設定は省略可能です。モデルにアクセスするために認証が必要な場合にのみ必要です。
Vertex AI モデルの場合、認証には Cloud SQL サービス アカウントが使用されます。他のモデルでは、Secret Manager にシークレットとして保存されている API キーまたはベアラートークンを google_ml.create_sm_secret() SQL 関数で使用できます。
次の表に、設定できる認証方法を示します。
| 認証方法 | 関数で次のように設定します。 | モデル プロバイダ |
|---|---|---|
| Cloud SQL サービス エージェント | cloudsql_service_agent_iam |
Vertex AI プロバイダ |
| Secret Manager | secret_manager |
Vertex AI の外部でホストされているモデル |
予測関数
google_ml_integration 拡張機能には、次の予測関数が含まれています。
google_ml.embedding()- 登録されたテキスト エンベディング モデル エンドポイントを呼び出してエンベディングを生成します。Vertex AI の
textembedding-geckoモデルのサポートが組み込まれています。 - 組み込みサポートのないテキスト エンベディング モデルの場合、入力パラメータと出力パラメータはモデルに固有であり、関数でモデルを呼び出すには変換する必要があります。予測関数の入力をモデル固有の入力に変換する変換入力関数と、モデル固有の出力を予測関数出力に変換する変換出力関数を作成します。
google_ml.predict_row()- 登録済みの汎用モデル エンドポイントを呼び出します（エンドポイントが予測を呼び出す JSON ベースの API をサポートしている場合）。
変換関数
変換関数は、入力をモデルが理解できる形式に変更し、モデルのレスポンスを予測関数が想定する形式に変換します。変換関数は、組み込みサポートなしで text-embedding モデル エンドポイントを登録する場合に使用されます。変換関数の署名は、モデルタイプの予測関数によって異なります。
generic モデル エンドポイントを登録するときに変換関数を使用できません。
次のコードは、テキスト エンベディング モデルの予測関数のシグネチャを示しています。
// define custom model specific input/output transform functions.
CREATE OR REPLACE FUNCTION input_transform_function(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;
CREATE OR REPLACE FUNCTION output_transform_function(model_id VARCHAR(100), response_json JSON) RETURNS real[];
変換関数の作成方法については、変換関数の例をご覧ください。
HTTP ヘッダー生成関数
HTTP ヘッダー生成関数は、HTTP ヘッダーとして使用される JSON の Key-Value ペアで出力を生成します。予測関数のシグネチャは、ヘッダー生成関数のシグネチャを定義します。
次の例は、google_ml.embedding() 予測関数のシグネチャを示しています。
CREATE OR REPLACE FUNCTION generate_headers(model_id VARCHAR(100), input TEXT) RETURNS JSON;
google_ml.predict_row() 予測関数のシグネチャは次のとおりです。
CREATE OR REPLACE FUNCTION generate_headers(model_id VARCHAR(100), input JSON) RETURNS JSON;
ヘッダー生成関数の作成方法については、ヘッダー生成関数の例をご覧ください。
制限事項
- Cloud SQL インスタンスで AI モデルを使用するには、インスタンスのメンテナンス バージョンが
R20240910.01_02以降である必要があります。インスタンスをこのバージョンにアップグレードするには、セルフサービス メンテナンスをご覧ください。
次のステップ
- モデル プロバイダの認証を設定します。
- モデル エンドポイント管理でモデル エンドポイントを登録する。
- モデル エンドポイント管理リファレンスをご覧ください。