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 ステートメントで使用されるために渡されます。