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

プレビュー版

このプロダクトは、サービス固有の規約の「一般サービス規約」セクションの「pre-GA サービス規約」の対象となります。 pre-GA のプロダクトは「現状のまま」利用できますが、サポートが制限されることがあります。 詳細については、リリース ステージの説明をご覧ください。

MySQL   |  PostgreSQL   |  SQL Server

このページでは、モデルを使用して予測を呼び出すか、エンベディングを生成し、モデル エンドポイント管理にモデル エンドポイントを登録する方法について説明します。

mysql.ml_create_model_registration() 関数の詳細については、モデル エンドポイント管理のリファレンスをご覧ください。

始める前に

• モデル プロバイダに基づいて認証を設定します。

• mysql クライアントまたは Cloud SQL Studio を使用してプライマリ インスタンスに接続します。

• 必要なデータベース ユーザー権限で説明されているデータベース権限を持つ MySQL データベース ユーザーとしてデータベースに接続していることを確認します。

認証を設定する

以降のセクションでは、Vertex AI モデル エンドポイントまたは Google Cloud内でホストされているモデル エンドポイントを追加する前に、認証を設定する方法について説明します。

Vertex AI の認証を設定する

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

カスタムホスト型モデルの認証を設定する

このセクションでは、Secret Manager を使用している場合に認証を設定する方法について説明します。Vertex AI モデル エンドポイントを除くすべてのモデルで、API キーまたは署名なしトークンを Secret Manager に保存できます。

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

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

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

   Secret 名と Secret パスは、mysql.ml_create_sm_secret_registration() SQL 関数で使用されます。

2. Cloud SQL インスタンスに Secret へのアクセス権を付与します。

     gcloud secrets add-iam-policy-binding SECRET_ID \
         --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
         --role="roles/secretmanager.secretAccessor"
   

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

   • SECRET_ID: Secret Manager のシークレット ID。
   • SERVICE_ACCOUNT_EMAIL: IAM ベースの Cloud SQL サービス アカウントのメールアドレス。このメールアドレスを確認するには、gcloud sql instances describe INSTANCE_NAME コマンドを使用し、INSTANCE_NAME をインスタンスの名前に置き換えます。serviceAccountEmailAddress パラメータの横に表示される値がメールアドレスです。

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

このセクションでは、モデル エンドポイント管理用にモデル エンドポイントを登録する方法について説明します。

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

モデル エンドポイント管理には、Vertex AI の text-embedding-gecko、text-embedding、gemini-embedding モデルのすべてのバージョンが組み込まれています。修飾名を使用して、モデル バージョンを textembedding-gecko@001 または textembedding-gecko@002 に設定します。

Vertex AI エンベディング モデル エンドポイント ID はモデル エンドポイント管理でデフォルトでサポートされているため、モデル ID として直接使用できます。これらのモデルの場合、エンベディング関数は入力と出力の変換を自動的に実行します。

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

gemini-embedding-001 モデル エンドポイントを登録するには、ml_create_model_registration 関数を呼び出します。

  CALL
    mysql.ml_create_model_registration(
      'gemini-embedding-001',
      'publishers/google/models/gemini-embedding-001',
      'google','text_embedding', 'gemini-embedding-001',
      'AUTH_TYPE_CLOUDSQL_SERVICE_AGENT_IAM',
       NULL,
      'mysql.cloudsql_ml_text_embedding_input_transform',
      'mysql.cloudsql_ml_text_embedding_output_transform', NULL);

カスタムホスト型テキスト エンベディング モデル

このセクションでは、 Google Cloud内のネットワークでホストされているカスタムモデル エンドポイントを登録する方法について説明します。

カスタムホスト型テキスト エンベディング モデルのエンドポイントを追加するには、変換関数を作成し、必要に応じてカスタム HTTP ヘッダーを作成します。一方、カスタムホスト型汎用モデル エンドポイントを追加する場合は、必要に応じてカスタム HTTP ヘッダーを生成し、モデル リクエスト URL を設定する必要があります。

次の例では、Cymbal によってホストされ、 Google Cloud内でホストされている custom-embedding-model テキスト エンベディング モデル エンドポイントを追加します。cymbal_text_input_transform 変換関数と cymbal_text_output_transform 変換関数は、モデルの入力形式と出力形式を予測関数の入力形式と出力形式に変換するために使用されます。

セルフホスト型テキスト エンベディング モデルのエンドポイントを登録するには、次の操作を行います。

1. Secret Manager に保存されている Secret を呼び出します。

   CALL
     mysql.ml_create_sm_secret_registration(
       'SECRET_ID',
       'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
   

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

   • SECRET_ID: 設定した Secret ID。モデル エンドポイントの登録時に使用されます（例: key1）。
   • SECRET_MANAGER_SECRET_ID: シークレットの作成時に Secret Manager で設定したシークレット ID。
   • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
   • VERSION_NUMBER: シークレット ID のバージョン番号。
   注: Secret Manager は、デフォルトで認証用の Authorization: Bearer SECRET_VALUE_FROM_SECRET_MANAGER ヘッダーを生成します。この形式がモデル エンドポイントの認可署名なしトークンの形式と一致する場合、ヘッダー生成関数を使用して認証ヘッダーを生成する必要はありません。

2. テキスト エンベディング モデルのエンドポイント用の予測関数の次の署名に基づいて、入力変換関数と出力変換関数を作成します。変換関数の作成方法については、変換関数の例をご覧ください。

   次の例は、custom-embedding-model テキスト エンベディング モデルのエンドポイントに固有の変換関数です。

   -- Input Transform Function corresponding to the custom model endpoint
   DELIMITER $$
   CREATE FUNCTION IF NOT EXISTS cymbal_text_input_transform(model_id VARCHAR(100), input_text TEXT)
   RETURNS JSON
   DETERMINISTIC
   
   BEGIN
     RETURN JSON_OBJECT('prompt', JSON_ARRAY(input_text));
   END $$
   
   -- Output Transform Function corresponding to the custom model endpoint
   CREATE FUNCTION IF NOT EXISTS cymbal_text_output_transform(model_id VARCHAR(100), response_json JSON)
   RETURNS BLOB
   DETERMINISTIC
   
   BEGIN
     RETURN STRING_TO_VECTOR(
            JSON_EXTRACT(
                 content,
                 '$.predictions[0].embeddings.values'
               )
        );
   
   END $$
   DELIMITER ;
   

3. モデル作成関数を呼び出して、カスタム エンベディング モデルのエンドポイントを登録します。

   CALL
      mysql.ml_create_model_registration(
        'MODEL_ID',
        'REQUEST_URL',
        'custom',
        'text_embedding',
        'MODEL_QUALIFIED_NAME',
        'auth_type_secret_manager',
        'SECRET_ID'
        'database_name.cymbal_text_input_transform',
        'database_name.cymbal_text_output_transform', NULL);

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

• MODEL_ID: 必須。定義するモデル エンドポイントの一意の ID（custom-embedding-model など）。このモデル ID は、モデル エンドポイントがエンベディングの生成や予測の呼び出しに必要なメタデータのために参照されます。
• REQUEST_URL: 必須。カスタム テキスト エンベディングと汎用モデル エンドポイントを追加する場合のモデル固有のエンドポイント（https://cymbal.com/models/text/embeddings/v1 など）。モデル エンドポイントに内部 IP アドレスからアクセスできることを確認します。モデル エンドポイント管理は外部 IP アドレスをサポートしていません。
• MODEL_QUALIFIED_NAME: モデル エンドポイントで修飾名を使用する場合に必須です。モデル エンドポイントに複数のバージョンがある場合の完全修飾名。
• SECRET_ID: mysql.ml_create_sm_secret_registration() プロシージャで以前に使用したシークレット ID。

汎用モデル

このセクションでは、Vertex AI Model Garden から汎用 gemini-flash モデル エンドポイントを登録する方法について説明します。このエンドポイントは、デフォルトでカタログに事前登録されています。 Google Cloud内でホストされている任意の汎用モデル エンドポイントを登録できます。

Cloud SQL は、Vertex AI Model Garden で利用可能なモデル エンドポイントと、 Google Cloud内のネットワークでホストされているモデル エンドポイントのみをサポートしています。

Gemini モデル

次の例では、Vertex AI Model Garden の gemini-2.5-flash モデル エンドポイントを使用しています。

gemini-2.5-flash モデル エンドポイントを登録するには、mysql.ml_create_model_registration 関数を呼び出します。

    CALL
      mysql.ml_create_model_registration(
        'MODEL_ID',
        'https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-2.5-flash:streamGenerateContent',
        'google',
        'auth_type_cloudsql_service_agent_iam',
        NULL, NULL, NULL, NULL);

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

• MODEL_ID: 定義するモデル エンドポイントの一意の ID（
  gemini-1 など）。このモデル ID は、モデル エンドポイントがエンベディングの生成や予測の呼び出しに必要なメタデータのために参照されます。
• PROJECT_ID: 実際の Google Cloud プロジェクト ID。

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

次のステップ

• モデルのエンドポイント管理のリファレンスをご覧ください。