ML.PREDICT 関数

`ML.PREDICT` 関数

ML.PREDICT 関数は、モデルを使用した結果を予測する場合に使用できます。予測は、モデルの作成中や作成後に実行できます。また、少なくとも 1 回の繰り返しが終了していれば、失敗後に行うこともできます。ML.PREDICT は常に、最後に成功した繰り返しからモデルの重み付けを取得します。

ML.PREDICT 関数の出力には入力テーブルと同数の行があり、入力テーブルのすべての列とモデルのすべての出力列が含まれます。モデルの出力列名は predicted_<label_column_name> と predicted_<label_column_name>_probs（ロジスティック回帰モデルの場合）です。両方の列で、label_column_name はトレーニング中に使用された入力ラベル列の名前です。

ロジスティック回帰モデルの場合:
- 出力列 predicted_<label_column_name>_probs は、各ラベルの予測確率が含まれる [<label, prob>] 型の STRUCT の配列です。
- 出力列 predicted_<label_column_name> は、予測確率が高いラベルに応じて、2 つの入力ラベルのいずれかになります。
多項ロジスティック回帰モデルの場合:
- 出力列 predicted_<label_column_name>_probs は、softmax 関数を使用して計算したクラスラベルごとの確率です。
- 出力列 predicted_<label_column_name> は、予測確率スコアが最も高いラベルです。
線形回帰モデルの場合:
- 出力列 predicted_<label_column_name> は、ラベルの予測値です。
K 平均法モデルの場合:
- centroid_id と nearest_centroids_distance というラベルの付いた列を返します。nearest_centroids_distance には、nearest_centroids_distance という STRUCT の ARRAY が含まれています。これには、最も近い k 個のクラスタまでの距離が含まれます。ここで k は num_clusters または 5 の小さい方の値になります。standardize_features を TRUE に設定してこのモデルを作成した場合、モデルは標準化された特徴を使用して距離を計算します。それ以外の場合は、標準化されていない特徴で距離を計算します。
TensorFlow モデルの場合:
- 入力は、モデルが想定する型に変換可能である必要があります。
- 出力は、TensorFlow モデルの predict メソッドの出力です。

`ML.PREDICT` の権限

ML.PREDICT を実行するには、bigquery.models.create と bigquery.models.getData の両方が必要です。

`ML.PREDICT` の構文

ML.PREDICT(MODEL model_name,
          {TABLE table_name | (query_statement)}
          [, STRUCT<threshold FLOAT64> settings)])

`model_name`

model_name は、評価するモデルの名前です。デフォルトプロジェクトを構成していない場合は、`[PROJECT_ID].[DATASET].[MODEL]`（バッククォートを含む）の形式でプロジェクト ID をモデル名の前に追加します（例: `myproject.mydataset.mymodel`）。

`table_name`

table_name は、評価データを含む入力テーブルの名前です。デフォルトプロジェクトを構成していない場合は、`[PROJECT_ID].[DATASET].[TABLE]`（バッククォートを含む）の形式でプロジェクト ID をテーブル名の前に追加します（例: `myproject.mydataset.mytable`）。

テーブルの入力列名には、モデルの列名が含まれている必要があります。また、型は BigQuery の暗黙の強制変換ルールに従って互換性がある必要があります。

テーブルに未使用の列がある場合、出力列に渡されます。

`query_statement`

query_statement 句は、評価データの生成に使用する標準 SQL クエリを指定します。query_statement 句でサポートされる SQL 構文については、標準 SQL クエリ構文ページをご覧ください。

クエリの入力列名には、モデルの列名が含まれている必要があります。また、型は BigQuery の暗黙の強制変換ルールに従って互換性がある必要があります。

クエリに未使用の列がある場合、出力列に渡されます。

model_name を作成した CREATE MODEL ステートメントに TRANSFORM 句が含まれている場合、TRANSFORM 句に含まれている入力列のみが query_statement に表示される必要があります。

`threshold`

（省略可）しきい値は、2 項ロジスティック回帰モデルのカスタムしきい値です。2 つのラベル間のカットオフとして使用されます。しきい値を超える予測は陽性の予測として処理されます。しきい値以下の予測は陰性の予測です。しきい値の型は FLOAT64 で、STRUCT 設定の一部です。デフォルト値は 0.5 です。

補完

統計学では、欠損データを代替値で置き換えるために補完を使用します。BigQuery ML でモデルをトレーニングする場合、NULL 値は欠損データとして処理されます。BigQuery ML で結果を予測する場合、BigQuery ML が NULL 値や未知の値に遭遇すると、欠損値が発生する可能性があります。BigQuery ML は、列が数値、ワンホットエンコード、またはタイムスタンプのいずれであるかに基づいて、欠損データを処理します。

数値列

トレーニングと予測の両方で、数値列の NULL 値は、元の入力データの特徴列によって計算された平均値に置き換えられます。

ワンホット / マルチホットエンコード列

トレーニングと予測の両方で、エンコード列の NULL 値は、データに追加される追加カテゴリにマッピングされます。未知のデータには、予測時に重み 0 が割り当てられます。

タイムスタンプ列

TIMESTAMP 列では、標準化列とワンホットエンコード列の両補完方法が組み合わせて使用されます。生成された Unix 時間列の場合、BigQuery ML は値を元の列全体の平均 Unix 時間で置き換えます。その他の生成された値の場合、BigQuery ML は抽出された各特徴のそれぞれの NULL カテゴリに値を割り当てます。

STRUCT 列

トレーニングと予測の両方で、STRUCT の各フィールドはタイプに応じて補完されます。

`ML.PREDICT` の例

次の例では、デフォルトプロジェクトにモデルと入力テーブルがあることを前提にしています。

結果を予測する

次のクエリは、ML.PREDICT 関数を使用して結果を予測します。クエリは次の列を返します。

predicted_label
label
column1
column2

SELECT
  *
FROM
  ML.PREDICT(MODEL `mydataset.mymodel`,
    (
    SELECT
      label,
      column1,
      column2
    FROM
      `mydataset.mytable`))

2 つの異なるモデルの予測を比較する

この例では、次のクエリを使用して最初のモデルを作成します。

CREATE MODEL
  `mydataset.mymodel1`
OPTIONS
  (model_type='linear_reg',
    input_label_cols=['label'],
  ) AS
SELECT
  label,
  input_column1
FROM
  `mydataset.mytable`

次のクエリで 2 番目のモデルを作成します。

CREATE MODEL
  `mydataset.mymodel2`
OPTIONS
  (model_type='linear_reg',
    input_label_cols=['label'],
  ) AS
SELECT
  label,
  input_column2
FROM
  `mydataset.mytable`

次のクエリは、ML.PREDICT 関数を使用して 2 つのモデルの出力を比較します。

SELECT
  label,
  predicted_label1,
  predicted_label AS predicted_label2
FROM
  ML.PREDICT(MODEL `mydataset.mymodel2`,
    (
    SELECT
      * EXCEPT (predicted_label),
          predicted_label AS predicted_label1
    FROM
      ML.PREDICT(MODEL `mydataset.mymodel1`,
        TABLE `mydataset.mytable`)))

カスタムしきい値を指定する

次のクエリは、入力データとカスタムしきい値 0.55 を指定して ML.PREDICT 関数を使用します。

SELECT
  *
FROM
  ML.PREDICT(MODEL `mydataset.mymodel`,
    (
    SELECT
      custom_label,
      column1,
      column2
    FROM
      `mydataset.mytable`),
    STRUCT(0.55 AS threshold))

インポートした TensorFlow モデルで結果を予測する

次のクエリは、ML.PREDICT 関数とインポートした TensorFlow モデルを使用して結果を予測します。input_data テーブルには、my_model で想定されるスキーマ内の入力が含まれています。詳細については、TensorFlow モデルの CREATE MODEL ステートメントをご覧ください。

SELECT *
FROM ML.PREDICT(MODEL `my_project`.my_dataset.my_model,
               (SELECT * FROM input_data))

TRANSFORM 句を使用してトレーニングされたモデルで結果を予測する

次のクエリは、TRANSFORM 句を使用してモデルをトレーニングします。

CREATE MODEL m
  TRANSFORM(f1 + f2 as c, label)
  OPTIONS(...)
AS SELECT f1, f2, f3, label FROM t;

f3 列は TRANSFORM 句に表示されないため、次の予測クエリでは query_statement でその列は省略されます。

SELECT * FROM ML.PREDICT(
  MODEL m, (SELECT f1, f2 FROM t1));

f3 が SELECT ステートメントでに含まれている場合、予測の計算には使用されず、残りの SQL ステートメントで使用されるために渡されます。

ML.PREDICT 関数