BigQuery DataFrames で ML と AI を使用する

BigQuery DataFrames は、bigframes.ml ライブラリを使用して BigQuery DataFrames に ML と AI の機能を提供します。

BigQuery DataFrames でデータを前処理したり、モデルをトレーニングする推定ツールを作成したり、ML パイプラインを作成したり、トレーニング データセットとテスト データセットを分割したりできます。

必要なロール

このドキュメントのタスクを実行するために必要な権限を取得するには、プロジェクトに対して次の IAM ロールを付与するように管理者へ依頼してください。

ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

ML のロケーション

bigframes.ml ライブラリは、BigQuery ML と同じロケーションをサポートしています。BigQuery ML モデル予測および他の ML 関数は、すべての BigQuery リージョンでサポートされています。モデル トレーニングのサポートはリージョンによって異なります。詳細については、BigQuery ML のロケーションをご覧ください。

データを前処理する

bigframes.ml.preprocessing モジュールと bigframes.ml.compose モジュールを使用して、推定ツール（モデル）で使用するデータを準備するために変換ツールを作成します。BigQuery DataFrames では、次の変換が用意されています。

  • 連続データを区間データにビン化するには、bigframes.ml.preprocessing モジュールの KBinsDiscretizer クラスを使用します。

  • ターゲット ラベルを整数値として正規化するには、bigframes.ml.preprocessing モジュールの LabelEncoder クラスを使用します。

  • 各特徴量を最大絶対値で [-1, 1] の範囲にスケーリングするには、bigframes.ml.preprocessing モジュールの MaxAbsScaler クラスを使用します。

  • 各特徴量を範囲 [0, 1] にスケーリングして特徴量を標準化するには、bigframes.ml.preprocessing モジュールの MinMaxScaler クラスを使用します。

  • 平均値を削除して単位分散にスケーリングすることで特徴を標準化するには、bigframes.ml.preprocessing モジュールの StandardScaler クラスを使用します。

  • カテゴリ値を数値形式に変換するには、bigframes.ml.preprocessing モジュールの OneHotEncoder クラスを使用します。

  • DataFrame 列にトランスフォーマーを適用するには、bigframes.ml.compose モジュールの ColumnTransformer クラスを使用します。

モデルのトレーニング

BigQuery DataFrames でモデルをトレーニングする推定ツールを作成できます。

クラスタリング モデル

bigframes.ml.cluster モジュールを使用して、クラスタリング モデルの推定ツールを作成できます。K 平均法クラスタリング モデルを作成するには、KMeans クラスを使用します。これらのモデルはデータのセグメンテーションに使用します。たとえば、お客様のセグメントを特定します。K 平均法は教師なし学習にあたるため、モデルのトレーニングを行う際にラベルは必要なく、トレーニングや評価用にデータの分割を行う必要もありません。

bigframes.ml.cluster モジュールを使用して、クラスタリング モデル用の推定ツールを作成できます。

次のコードサンプルでは、データ セグメンテーション用の K 平均法クラスタリング モデルを作成するために bigframes.ml.cluster KMeans クラスを使用する場合を示します。

from bigframes.ml.cluster import KMeans
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Create the KMeans model
cluster_model = KMeans(n_clusters=10)
cluster_model.fit(bq_df["culmen_length_mm"], bq_df["sex"])

# Predict using the model
result = cluster_model.predict(bq_df)
# Score the model
score = cluster_model.score(bq_df)

分解モデル

bigframes.ml.decomposition モジュールを使用して、分解モデルの推定ツールを作成できます。主成分分析（PCA）モデルを作成するには、PCA クラスを使用します。このモデルは、主成分を計算し、その結果を使用してデータに基底変換を行うために使用します。PCA クラスを使用すると、データのバリエーションをできるだけ多く保持しながら、各データポイントを最初のいくつかの主成分にのみ射影して低次元のデータを取得することで、次元数を削減できます。

モデルのアンサンブル

bigframes.ml.ensemble モジュールを使用して、アンサンブル モデルの推定ツールを作成できます。

  • ランダム フォレスト分類モデルを作成するには、RandomForestClassifier クラスを使用します。このモデルは、分類を目的とする複数の学習方法のディシジョン ツリーを構築するために使用します。

  • ランダム フォレスト回帰モデルを作成するには、RandomForestRegressor クラスを使用します。このモデルは、回帰を目的とする複数の学習方法のディシジョン ツリーを構築するために使用します。

  • 勾配ブーストツリー分類モデルを作成するには、XGBClassifier クラスを使用します。このモデルは、分類を目的とする複数の学習方法のディシジョン ツリーを追加的に構築するために使用します。

  • 勾配ブーストツリー回帰モデルを作成するには、XGBRegressor クラスを使用します。このモデルは、回帰を目的とする複数の学習方法のディシジョン ツリーを追加的に構築するために使用します。

予測のモデル

bigframes.ml.forecasting モジュールを使用して、予測モデルの推定ツールを作成できます。時系列予測モデルを作成するには、ARIMAPlus クラスを使用します。

インポートされたモデル

bigframes.ml.imported モジュールを使用して、インポートしたモデルの推定ツールを作成できます。

線形モデル

bigframes.ml.linear_model モジュールを使用して、線形モデルの推定ツールを作成します。

  • 線形回帰モデルを作成するには、LinearRegression クラスを使用します。このモデルは、特定の日の商品の売上を予測するなど、予測に使用します。

  • ロジスティック回帰モデルを作成するには、LogisticRegression クラスを使用します。このモデルは、入力が low-value、medium-value、high-value のいずれであるかなど、2 つ以上の有効な値を分類するために使用します。

以下のコードサンプルでは、bigframes.ml を使用して次のことを行います。

  • BigQuery からデータを読み込みます。
  • トレーニング データをクリーニングして準備する。
  • bigframes.ml.LinearRegression 回帰モデルを作成して適用する。
from bigframes.ml.linear_model import LinearRegression
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Filter down to the data to the Adelie Penguin species
adelie_data = bq_df[bq_df.species == "Adelie Penguin (Pygoscelis adeliae)"]

# Drop the species column
adelie_data = adelie_data.drop(columns=["species"])

# Drop rows with nulls to get training data
training_data = adelie_data.dropna()

# Specify your feature (or input) columns and the label (or output) column:
feature_columns = training_data[
    ["island", "culmen_length_mm", "culmen_depth_mm", "flipper_length_mm", "sex"]
]
label_columns = training_data[["body_mass_g"]]

test_data = adelie_data[adelie_data.body_mass_g.isnull()]

# Create the linear model
model = LinearRegression()
model.fit(feature_columns, label_columns)

# Score the model
score = model.score(feature_columns, label_columns)

# Predict using the model
result = model.predict(test_data)

大規模言語モデル

bigframes.ml.llm モジュールを使用して、LLM の推定ツールを作成できます。

  • Gemini テキスト生成モデルを作成するには、GeminiTextGenerator クラスを使用します。このモデルは、テキスト生成タスクに使用します。

  • リモート大規模言語モデル（LLM）の推定ツールを作成するには、bigframes.ml.llm モジュールを使用します。

次のコードサンプルは、コード生成用の Gemini モデルを作成するために bigframes.ml.llm GeminiTextGenerator クラスを使用する場合を示しています。

from bigframes.ml.llm import GeminiTextGenerator
import bigframes.pandas as bpd

# Create the Gemini LLM model
session = bpd.get_global_session()
connection = f"{PROJECT_ID}.{REGION}.{CONN_NAME}"
model = GeminiTextGenerator(
    session=session, connection_name=connection, model_name="gemini-2.0-flash-001"
)

df_api = bpd.read_csv("gs://cloud-samples-data/vertex-ai/bigframe/df.csv")

# Prepare the prompts and send them to the LLM model for prediction
df_prompt_prefix = "Generate Pandas sample code for DataFrame."
df_prompt = df_prompt_prefix + df_api["API"]

# Predict using the model
df_pred = model.predict(df_prompt.to_frame(), max_output_tokens=1024)

リモートモデル

BigQuery DataFrames ML リモートモデル（bigframes.ml.remote または bigframes.ml.llm）を使用するには、次の API を有効にする必要があります。

BigQuery DataFrames ML リモートモデルを使用する場合は、デフォルトの BigQuery 接続を使用している場合はプロジェクト IAM 管理者ロール（roles/resourcemanager.projectIamAdmin）、事前構成済みの接続を使用している場合は参照者ロール（roles/browser）が必要です。この要件は、bigframes.pandas.options.bigquery.skip_bq_connection_check オプションを True に設定することで回避できます。この場合、接続（デフォルトまたは事前構成済み）は存在チェックや権限チェックなしでそのまま使用されます。事前構成済みの接続を使用して接続チェックを省略する場合は、次のことを確認します。

  • 接続が適切な場所に作成されている。
  • BigQuery DataFrames ML リモートモデルを使用している場合、サービス アカウントにプロジェクトに対する Vertex AI ユーザー ロール（roles/aiplatform.user）が付与されている。

BigQuery DataFrames でリモートモデルを作成すると、BigQuery 接続が作成されます。デフォルトでは、bigframes-default-connection という名前の接続が使用されます。必要に応じて、事前構成済みの BigQuery 接続も使用できます。この場合、接続の作成はスキップされます。デフォルト接続のサービス アカウントには、プロジェクトに対する Vertex AI ユーザー ロール（roles/aiplatform.user）が付与されます。

パイプラインを作成する

bigframes.ml.pipeline モジュールを使用して、ML パイプラインを作成できます。パイプラインを使用すると、さまざまなパラメータを設定しながら、複数の ML ステップを組み合わせてクロス検証できます。これにより、コードが簡素化され、データの前処理ステップと推定ツールを一緒にデプロイできます。

最終的な推定ツールを含む変換のパイプラインを作成するには、Pipeline クラスを使用します。

モデルを選択する

トレーニング データセットとテスト データセットを分割して最適なモデルを選択するには、bigframes.ml.model_selection モジュールを使用します。

  • 次のコードサンプルに示すように、データをトレーニング セットとテスト（評価）セットに分割するには、train_test_split 関数を使用します。

    X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)

  • 次のコードサンプルに示すように、モデルをトレーニングして評価するための多重交差検定のトレーニング セットとテストセットを作成するには、KFold クラスと KFold.split メソッドを使用します。この機能は、小規模なデータセットに役立ちます。

    kf = KFold(n_splits=5)
for i, (X_train, X_test, y_train, y_test) in enumerate(kf.split(X, y)):
# Train and evaluate models with training and testing sets

  • 次のコードサンプルに示すように、多重交差検定のトレーニング セットとテストセットを自動的に作成し、モデルをトレーニングして評価して、各フォールドの結果を取得するには、cross_validate 関数を使用します。

    scores = cross_validate(model, X, y, cv=5)

次のステップ