SQL を使用して ML 予測を生成する

このページでは、Spanner データベースから機械学習（ML）予測を生成する方法について説明します。ML 予測は、Google SQL データベースと PostgreSQL データベースの両方で機能します。

Spanner Vertex AI インテグレーションにより、GoogleSQL 用の ML.PREDICT 関数または PostgreSQL 用の spanner.ML_PREDICT_ROW 関数を呼び出して、SQL コードを使用して予想を生成できます。Spanner Vertex AI インテグレーションの詳細については、Spanner Vertex AI インテグレーションの概要をご覧ください。

始める前に

Spanner インスタンスから予測を生成する前に、データベースを準備してモデルを選択する必要があります。

Spanner Vertex AI の統合の Vertex AI エンドポイントへのアクセスを構成する

Spanner は、サービスエージェントを作成し、Cloud Spanner が最初の MODEL DDL ステートメントを実行したときに、必要な権限を自動的に付与します。Spanner データベースと Vertex AI エンドポイントの両方が同じプロジェクトにある場合、追加の設定は必要ありません。

プロジェクトに Spanner サービスエージェントアカウントが存在しない場合は、次のコマンドを実行して作成します。

gcloud beta services identity create --service=spanner.googleapis.com --project={PROJECT}`

単一ロールの付与に記載の手順に沿って、Vertex AI プロジェクトの Spanner サービスエージェントアカウント service-PROJECT_ID@gcp-sa-spanner.iam.gserviceaccount.com に Spanner API Service Agent ロールを付与します。

モデルの選択

ML.PREDICT（GoogleSQL の場合）または spanner.ML_PREDICT_ROW（PostgreSQL の場合）関数を使用する場合は、ML モデルのロケーションを指定する必要があります。選択するモデルは次のいずれかになります。

Vertex AI Model Garden で実行されているモデル。
Spanner サービスエージェントにアクセスの IAM 権限があるアクティブなエンドポイントを持つ Vertex AI モデル。

Spanner Vertex AI インテグレーションの詳細については、Spanner Vertex AI インテグレーションの仕組みをご覧ください。

予測を生成する

選択したモデルのタイプによって、予測を生成する手順は異なります。

Vertex AI Model Garden でモデルを使用する

Vertex AI Model Garden のモデルを使用して予測を生成するには、Model Garden からモデルを選択します。

GoogleSQL

ML.PREDICT() でモデルを使用する前に、CREATE MODEL ステートメントを使用してモデルを登録する必要があります。

CREATE MODEL 'MODEL_NAME'
INPUT (INPUT_COLUMN_NAME INPUT_COLUMN_TYPE)
OUTPUT (OUTPUT_COLUMN_NAME OUTPUT_COLUMN_TYPE)
REMOTE
OPTIONS (
  endpoint = '//aiplatform.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/publishers/google/models/model_id'
);

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

MODEL_NAME: モデルに付ける名前
INPUT_COLUMN_NAME: 入力列の名前。たとえば、gemini-pro モデルを使用している場合、入力列名は prompt です。
INPUT_COLUMN_TYPE: INPUT_COLUMN_NAME のデータ型
OUTPUT_COLUMN_NAME: 出力列の名前。たとえば、gemini-pro モデルを使用している場合、出力列名は content になります。
OUTPUT_COLUMN_TYPE: OUTPUT_COLUMN_NAME のデータ型
PROJECT_ID: Google Cloud プロジェクトの ID
REGION_ID: モデルが配置されている Google Cloud リージョンの ID（例: us-central1）
MODEL_ID: 使用する ML モデルの ID（例: gemini-pro）

モデルの詳細については、生成 AI の Model API リファレンスをご覧ください。

Model Garden で選択したモデルで ML.PREDICT GoogleSQL 関数を使用して、予測を生成します。

SELECT * FROM ML.PREDICT(
  MODEL `MODEL_NAME`,
  `INPUT_RELATION`[, `PARAMETERS`])

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

MODEL_NAME: モデルに付ける名前

モデルの詳細については、生成 AI の Model API リファレンスをご覧ください。
INPUT_RELATION: TABLE table_name または ML 予測を実行するデータを提供するサブクエリのテーブルまたはサブクエリ。
PARAMETERS: model_id でサポートされているパラメータを含む STRUCT 値。

SAFE.ML.PREDICT を使用して、予測でエラーの代わりに null を返すこともできます。これは、一部の失敗した予測が許容できる大規模なクエリを実行する場合に役立ちます。

PostgreSQL

Model Garden から選択したモデルで ML_PREDICT_ROW PostgreSQL 関数を使用して、予測を生成します。

SELECT spanner.ml_predict_row(
  'projects/PROJECT_ID/locations/REGION_ID/publishers/google/models/MODEL_ID'::text,
  '{
    "instances": [ INSTANCES ],
    "parameters": { PARAMETERS }
   }'::jsonb);

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

PROJECT_ID: Google Cloud プロジェクトの ID
REGION_ID: モデルが配置されている Google Cloud リージョンの ID（例: us-central1）
MODEL_ID: 使用する ML モデルの ID（例: gemini-pro）

モデルの詳細については、生成 AI の Model API リファレンスをご覧ください。
INSTANCES: JSON 形式の予測呼び出しの入力
PARAMETERS: JSON 形式の予測呼び出しのオプションパラメータ

このクエリは JSON レスポンスを生成します。モデルの JSON レスポンスメッセージについては、PredictResponse をご覧ください。

Vertex AI モデルエンドポイントを使用する

Spanner Vertex AI インテグレーションでトレーニング済みまたはダウンロードしたモデルを使用するには、モデルを Vertex AI にデプロイする必要があります。Vertex AI のエンドポイントにモデルをデプロイする方法については、エンドポイントにモデルをデプロイするをご覧ください。

GoogleSQL

Vertex AI エンドポイントのモデルで ML.PREDICT GoogleSQL 関数を使用して、予測を生成します。ML.PREDICT() でモデルを使用する前に、CREATE MODEL ステートメントを使用してモデルを登録する必要があります。デプロイされた各モデルには、独自のスキーマがあります。次に、分類と回帰の概要のスキーマの例を示します。

CREATE MODEL MyClassificationModel
INPUT (
  length FLOAT64,
  material STRING(MAX),
  tag_array ARRAY<STRING(MAX)>
)
OUTPUT (
  scores ARRAY<FLOAT64>,
  classes ARRAY<STRING(MAX)>
)
REMOTE
OPTIONS (
  endpoint = '//aiplatform.googleapis.com/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID'
)

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

PROJECT_ID: Google Cloud プロジェクトの ID
LOCATION: モデルが配置されている Google Cloud リージョンの ID（例: us-central1）
ENDPOINT_ID: 使用する ML モデルの ID（例: gemini-pro）

モデルの詳細については、生成 AI の Model API リファレンスをご覧ください。

Model Garden で選択したモデルで ML.PREDICT GoogleSQL 関数を使用して、予測を生成します。

SELECT * FROM ML.PREDICT(
  `MODEL_ID`,
  `INPUT_RELATION`[, `PARAMETERS`])

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

MODEL_ID: 使用する ML モデルの ID。
INPUT_RELATION: ML 予測を実行するテーブルまたはサブクエリ。
PARAMETERS: model_name でサポートされているパラメータを含む STRUCT 値。

このクエリは、モデルのすべての出力列と入力リレーションのすべての列を含むリレーションを生成します。

PostgreSQL

Vertex AI エンドポイントのモデルで ML.PREDICT PostgreSQL 関数を使用して、予測を生成します。

  SELECT spanner.ml_predict_row(
    'projects/PROJECT_ID/locations/REGION_ID/endpoints/ENDPOINT_ID'::text,
    '{
      "instances": [ INSTANCES ],
      "parameters": { PARAMETERS }
      }'::jsonb);
  ```

Replace the following:

PROJECT_ID: モデルが配置されている Google Cloud プロジェクトの ID
REGION_ID: モデルが配置されている Google Cloud リージョンの ID（例: us-central1）
ENDPOINT_ID: モデルエンドポイントの ID
INSTANCES: JSON 形式の予測呼び出しの入力
PARAMETERS: JSON 形式の予測呼び出しのオプションパラメータ

このクエリは JSON レスポンスを生成します。モデルの JSON レスポンスメッセージについては、PredictResponse をご覧ください。

ML 関数を使用して予測を生成する例

次の例では、Model Garden の gemini-pro モデルを使用して、引数として指定された短いプロンプトに基づいてテキストを生成します。このモデルは、Spanner の Gemini の一部として利用できます。

GoogleSQL

gemini-pro モデルを登録する

CREATE MODEL GeminiPro
INPUT (prompt STRING(MAX))
OUTPUT (content STRING(MAX))
REMOTE
OPTIONS (
  endpoint = '//aiplatform.googleapis.com/projects/PROJECT/locations/LOCATION/publishers/google/models/gemini-pro',
  default_batch_size = 1
);

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

PROJECT: プロジェクト ID
LOCATION: Vertex AI を使用するリージョン

モデルを実行する

SELECT content
FROM ML.PREDICT(
  MODEL GeminiPro,
  (SELECT "Is 7 a prime number?" AS prompt),
  STRUCT(256 AS maxOutputTokens, 0.2 AS temperature, 40 as topK, 0.95 AS topP)
);

予想される出力

想定される出力は次のとおりです。

+--------------------+
| content            |
+--------------------+
| "Yes"              |
+--------------------+

PostgreSQL

モデルを実行する

select spanner.ml_predict_row(
  '{
    "endpoint": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-pro",
    "default_batch_size": 1
   }'::jsonb,
  '{
    "instances":[{"prompt": "Is 7 a prime number?"}],
    "parameters":{"maxOutputTokens":256, "topK": 40, "topP":0.96, "temperature":0.2}
    }'
);

予想される出力

想定される出力は次のとおりです。

+--------------------+
| content            |
+--------------------+
| "Yes"              |
+--------------------+

SQL を使用して ML 予測を生成する

始める前に

Spanner Vertex AI の統合の Vertex AI エンドポイントへのアクセスを構成する

モデルの選択

予測を生成する

Vertex AI Model Garden でモデルを使用する

GoogleSQL

PostgreSQL

Vertex AI モデル エンドポイントを使用する

GoogleSQL

PostgreSQL

ML 関数を使用して予測を生成する例

GoogleSQL

PostgreSQL

Vertex AI モデルエンドポイントを使用する