このページは Cloud Translation API によって翻訳されました。

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

MySQL | PostgreSQL | SQL Server

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

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

始める前に

モデルエンドポイントで認証が必要な場合は、google_ml_integration 拡張機能を有効にする。
モデルプロバイダに基づいて認証を設定します。
データベースにアクセスする際に、postgres のデフォルトユーザー名を使用していることを確認してください。

拡張機能を有効にする

インスタンスの google_ml_integration.enable_model_support データベースフラグを on に設定します。データベースフラグの設定の詳細については、データベースフラグを構成するをご覧ください。
psql クライアントまたは Cloud SQL Studio を使用してプライマリインスタンスに接続します。
次のコマンドを実行して、google_ml_integration 拡張機能がバージョン 1.4.2 に更新されていることを確認します。
```
    ALTER EXTENSION google_ml_integration UPDATE TO '1.4.2'
```
psql を使用して google_ml_integration バージョン 1.4.2 拡張機能を追加します。
```
  CREATE EXTENSION google_ml_integration VERSION '1.4.2';
```
省略可: モデルのメタデータを管理する権限を PostgreSQL の非スーパーユーザーに付与します。
```
  GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA google_ml TO NON_SUPER_USER;
```
NON_SUPER_USER は、スーパー以外の PostgreSQL ユーザー名に置き換えます。

認証の設定

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

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 キーまたはベアラートークンを作成して使用する手順は次のとおりです。

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

シークレット名とシークレットパスは、google_ml.create_sm_secret() SQL 関数で使用されます。
Cloud SQL インスタンスにシークレットへのアクセス権を付与します。
```
  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 モデルのすべてのバージョンが組み込みでサポートされています。修飾名を使用して、モデルバージョンを textembedding-gecko@001 または textembedding-gecko@002 に設定します。

textembedding-gecko モデルエンドポイント ID と textembedding-gecko@001 モデルエンドポイント ID はどちらもモデルエンドポイント管理で事前登録されているため、どちらか一方をモデル ID として直接使用できます。これらのモデルの場合、拡張機能はデフォルトの変換関数を自動的に設定します。

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

textembedding-gecko@002 モデルエンドポイントを登録するには、create_model 関数を呼び出します。

  CALL
    google_ml.create_model(
      model_id => 'textembedding-gecko@002',
      model_provider => 'google',
      model_qualified_name => 'textembedding-gecko@002',
      model_type => 'text_embedding',
      model_auth_type => 'cloudsql_service_agent_iam');

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

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

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

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

カスタムホストされたテキストエンベディングモデルのエンドポイントを登録するには、次の操作を行います。

Secret Manager に保存されているシークレットを呼び出します。
```
CALL
  google_ml.create_sm_secret(
    secret_id => 'SECRET_ID',
    secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
```
次のように置き換えます。
- SECRET_ID: 設定したシークレット ID。モデルエンドポイントの登録時に使用されます（例: key1）。
- SECRET_MANAGER_SECRET_ID: Secret の作成時に Secret Manager で設定したシークレット ID。
- PROJECT_ID: Google Cloud プロジェクトの ID。
- VERSION_NUMBER: シークレット ID のバージョン番号。
注: Secret Manager は、デフォルトで認証用の Authorization: Bearer SECRET_VALUE_FROM_SECRET_MANAGER ヘッダーを生成します。この形式がモデルエンドポイントの認可ベアラトークンの形式と一致する場合、ヘッダー生成関数を使用して認証ヘッダーを生成する必要はありません。

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

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

-- Input Transform Function corresponding to the custom model endpoint
CREATE OR REPLACE FUNCTION cymbal_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
DECLARE
  transformed_input JSON;
  model_qualified_name TEXT;
BEGIN
  SELECT json_build_object('prompt', json_build_array(input_text))::JSON INTO transformed_input;
  RETURN transformed_input;
END;
$$;
-- Output Transform Function corresponding to the custom model endpoint
CREATE OR REPLACE FUNCTION cymbal_text_output_transform(model_id VARCHAR(100), response_json JSON)
RETURNS REAL[]
LANGUAGE plpgsql
AS $$
DECLARE
  transformed_output REAL[];
BEGIN
  SELECT ARRAY(SELECT json_array_elements_text(response_json->0)) INTO transformed_output;
  RETURN transformed_output;
END;
$$;

モデル作成関数を呼び出して、カスタムエンベディングモデルエンドポイントを登録します。
```
CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_request_url => 'REQUEST_URL',
    model_provider => 'custom',
    model_type => 'text_embedding',
    model_auth_type => 'secret_manager',
    model_auth_id => 'SECRET_ID',
    model_qualified_name => 'MODEL_QUALIFIED_NAME',
    model_in_transform_fn => 'cymbal_text_input_transform',
    model_out_transform_fn => 'cymbal_text_output_transform');
```
次のように置き換えます。
- MODEL_ID: 必須。定義したモデルエンドポイントの一意の ID（custom-embedding-model など）。このモデル ID は、モデルエンドポイントがエンベディングの生成や予測の呼び出しに必要なメタデータに参照されます。
- REQUEST_URL: 必須。カスタムテキストエンベディングと汎用モデルエンドポイントを追加する場合のモデル固有のエンドポイント（https://cymbal.com/models/text/embeddings/v1 など）。モデルエンドポイントに内部 IP アドレスからアクセスできることを確認します。モデルエンドポイント管理は外部 IP アドレスをサポートしていません。
- MODEL_QUALIFIED_NAME: モデルエンドポイントで修飾名を使用する場合に必要です。モデルエンドポイントに複数のバージョンがある場合の完全修飾名。
- SECRET_ID: 前の google_ml.create_sm_secret() 手順で使用したシークレット ID。

汎用モデル

このセクションでは、Vertex AI Model Garden から汎用の gemini-pro モデルエンドポイントを登録する方法について説明します。このエンドポイントは組み込みでサポートされていません。Google Cloud 内でホストされている汎用モデルエンドポイントを登録できます。

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

Gemini モデル

次の例では、Vertex AI Model Garden から gemini-1.0-pro モデルエンドポイントを追加します。

gemini-1.0-pro モデルエンドポイントを登録するには、create model 関数を呼び出します。

```sql
CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_request_url => 'https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-1.0-pro:streamGenerateContent',
    model_provider => 'google',
    model_auth_type => 'cloudsql_service_agent_iam');
```

Replace the following:
* <code><var>MODEL_ID</var></code>: a unique ID for the model endpoint that you define (for example,<br> `gemini-1`). This model ID is referenced for metadata that the model endpoint needs to generate embeddings or invoke predictions.
* <code><var>PROJECT_ID</var></code>: the ID of your Google Cloud project.

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

次のステップ

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