使用 BigQuery DataFrames

BigQuery DataFrames 提供由 BigQuery 引擎驅動的 Pythonic DataFrame 和機器學習 (ML) API。BigQuery DataFrames 是開放原始碼套件，你可以執行 pip install --upgrade bigframes 安裝最新版本。

BigQuery DataFrames 提供三種程式庫：

  • bigframes.pandas 提供 pandas API，可用於分析及操控 BigQuery 中的資料。只要變更幾個匯入項目，即可將許多工作負載從 pandas 遷移至 bigframes。bigframes.pandas API 可擴充，支援處理 TB 級的 BigQuery 資料，且 API 會使用 BigQuery 查詢引擎執行計算。
  • bigframes.bigquery 提供許多 BigQuery SQL 函式，可能沒有對應的 pandas 函式。
  • bigframes.ml 提供類似於 scikit-learn API 的 ML API。BigQuery DataFrames 的機器學習功能可讓您預先處理資料，然後根據該資料訓練模型。您也可以將這些動作鏈結在一起，建立資料管道。

必要的角色

如要取得完成本文工作所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

此外，使用 BigQuery DataFrames 遠端函式或 BigQuery DataFrames ML 遠端模型時，如果您使用預設的 BigQuery 連線，則需要專案 IAM 管理員角色 (roles/resourcemanager.projectIamAdmin)；如果您使用預先設定的連線，則需要瀏覽器角色 (roles/browser)。如要避免這項規定，請將 bigframes.pandas.options.bigquery.skip_bq_connection_check 選項設為 True，這樣系統就會直接使用連線 (預設或預先設定)，不會檢查連線是否存在或權限是否正確。如果您使用預先設定的連線，並略過連線檢查，請確認下列事項：

  • 連線是在正確位置建立。
  • 如果您使用 BigQuery DataFrames 遠端函式，服務帳戶在專案中必須具備 Cloud Run Invoker 角色 (roles/run.invoker)。
  • 如果您使用 BigQuery DataFrames ML 遠端模型，服務帳戶在專案中必須具備 Vertex AI 使用者角色 (roles/aiplatform.user)。

在筆記本、Python REPL 或指令列等互動式環境中執行使用者驗證時，BigQuery DataFrames 會視需要提示驗證。否則，請參閱如何為各種環境設定應用程式預設憑證。

設定安裝選項

安裝 BigQuery DataFrames 後，您可以指定下列選項。

位置和專案

您需要指定要使用 BigQuery DataFrames 的位置和專案。

您可以在筆記本中定義位置和專案，方法如下：

import bigframes.pandas as bpd

PROJECT_ID = "bigframes-dev"  # @param {type:"string"}
REGION = "US"  # @param {type:"string"}

# Set BigQuery DataFrames options
# Note: The project option is not required in all environments.
# On BigQuery Studio, the project ID is automatically detected.
bpd.options.bigquery.project = PROJECT_ID

# Note: The location option is not required.
# It defaults to the location of the first table or query
# passed to read_gbq(). For APIs where a location can't be
# auto-detected, the location defaults to the "US" location.
bpd.options.bigquery.location = REGION

資料處理位置

BigQuery DataFrames 的設計宗旨是擴充性，因此會將資料和處理作業保留在 BigQuery 服務中。不過，您可以在 DataFrame 或 Series 物件上呼叫 .to_pandas()，將資料帶入用戶端機器的記憶體。如果選擇這麼做，用戶端機器的記憶體限制就會適用。

講座舉行地點

BigQuery DataFrames 會在內部使用本機工作階段物件管理中繼資料。這場講座與地點相關。BigQuery DataFrames 會使用 US 多區域做為預設位置，但您可以使用 session_options.location 設定其他位置。工作階段中的每個查詢都會在建立工作階段的位置執行。如果使用者以 read_gbq/read_gbq_table/read_gbq_query() 開頭並指定資料表 (直接指定或在 SQL 陳述式中指定)，BigQuery DataFrames 會自動填入 bf.options.bigquery.location 的資料表位置。

如要重設所建立 DataFrame 或 Series 物件的位置，可以執行 bigframes.pandas.close_session() 關閉工作階段。之後，您可以使用 bigframes.pandas.options.bigquery.location 指定其他位置。

如果查詢的資料集不在 US 多區域中，則 read_gbq() 會要求您指定位置。如果您嘗試從其他位置讀取資料表，系統會擲回 NotFound 例外狀況。

遷移至 BigQuery DataFrames 2.0 版

BigQuery DataFrames 2.0 版改善了 BigQuery DataFrames API 的安全性和效能，並新增功能，同時也導入重大變更。本文說明這些變更，並提供遷移指南。您可以使用最新版 1.x 的 BigQuery DataFrames，在安裝 2.0 版前套用這些建議。

BigQuery DataFrames 2.0 版具有下列優點：

  • 執行查詢時，如果查詢會將結果傳回給用戶端，由於 allow_large_results 預設為 False，因此查詢速度會更快，建立的資料表也會較少。這有助於降低儲存空間費用，特別是您採用實際位元組計費時。
  • BigQuery DataFrame 部署的遠端函式預設會提高安全性。

安裝 BigQuery DataFrames 2.0 版

如要避免重大變更，請在 requirements.txt 檔案 (例如 bigframes==1.42.0) 或 pyproject.toml 檔案 (例如 dependencies = ["bigframes = 1.42.0"]) 中，釘選特定版本的 BigQuery DataFrames。準備好試用最新版本時，可以執行 pip install --upgrade bigframes 安裝最新版本的 BigQuery DataFrames。

使用「allow_large_results」選項

BigQuery 對查詢工作設有回應大小上限。從 BigQuery DataFrames 2.0 版開始，BigQuery DataFrames 會在將結果傳回用戶端的函式 (例如 peek()、to_pandas() 和 to_pandas_batches()) 中，預設強制執行這項限制。如果工作傳回的結果很大，您可以在 BigQueryOptions 物件中將 allow_large_results 設為 True，避免發生重大變更。在 BigQuery DataFrames 2.0 版中，這個選項預設為 False。

import bigframes.pandas as bpd

bpd.options.bigquery.allow_large_results = True

您可以在 to_pandas() 和其他方法中使用 allow_large_results 參數，覆寫 allow_large_results 選項。例如：

bf_df = bpd.read_gbq(query)
# ... other operations on bf_df ...
pandas_df = bf_df.to_pandas(allow_large_results=True)

使用 @remote_function 裝飾器

BigQuery DataFrames 2.0 版對 @remote_function 裝飾項的預設行為進行了部分變更。

針對不明確的參數強制執行關鍵字引數

為避免將值傳遞至非預期的參數，BigQuery DataFrames 2.0 以上版本會強制對下列參數使用關鍵字引數：

  • bigquery_connection
  • reuse
  • name
  • packages
  • cloud_function_service_account
  • cloud_function_kms_key_name
  • cloud_function_docker_repository
  • max_batching_rows
  • cloud_function_timeout
  • cloud_function_max_instances
  • cloud_function_vpc_connector
  • cloud_function_memory_mib
  • cloud_function_ingress_settings

使用這些參數時，請提供參數名稱。例如：

@remote_function(
  name="my_remote_function",
  ...
)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

設定服務帳戶

從 2.0 版開始，BigQuery DataFrames 預設不再使用 Compute Engine 服務帳戶，部署 Cloud Run 函式。如要限制部署函式的權限，請按照下列步驟操作：

  1. 建立服務帳戶，並僅授予所需權限。
  2. 將服務帳戶電子郵件提供給 @remote_function 裝飾器的 cloud_function_service_account 參數。

例如：

@remote_function(
  cloud_function_service_account="my-service-account@my-project.iam.gserviceaccount.com",
  ...
)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

如要使用 Compute Engine 服務帳戶，請將 @remote_function 裝飾項的 cloud_function_service_account 參數設為 "default"。例如：

# This usage is discouraged. Use only if you have a specific reason to use the
# default Compute Engine service account.
@remote_function(cloud_function_service_account="default", ...)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

設定輸入設定

從 2.0 版開始，BigQuery DataFrames 會為部署至 "internal-only" 的 Cloud Run 函式設定 Ingress 設定。先前，預設的連入設定為 "all"。如要變更進入設定，請設定 @remote_function 裝飾項的 cloud_function_ingress_settings 參數。例如：

@remote_function(cloud_function_ingress_settings="internal-and-gclb", ...)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

使用自訂端點

在 2.0 之前的 BigQuery DataFrames 版本中，如果區域不支援區域服務端點和 bigframes.pandas.options.bigquery.use_regional_endpoints = True，BigQuery DataFrames 就會改用位置端點。BigQuery DataFrames 2.0 版已移除這項備援行為。如要連線至 2.0 版中的位置端點，請設定 bigframes.pandas.options.bigquery.client_endpoints_override 選項。例如：

import bigframes.pandas as bpd

bpd.options.bigquery.client_endpoints_override = {
  "bqclient": "https://LOCATION-bigquery.googleapis.com",
  "bqconnectionclient": "LOCATION-bigqueryconnection.googleapis.com",
  "bqstoragereadclient": "LOCATION-bigquerystorage.googleapis.com",
}

將 LOCATION 替換為要連線的 BigQuery 位置名稱。

使用 bigframes.ml.llm 模組

在 BigQuery DataFrames 2.0 版中，預設的 model_name for GeminiTextGenerator 已更新為 "gemini-2.0-flash-001"。建議您直接提供 model_name，以免日後預設模型變更時發生中斷。

import bigframes.ml.llm

model = bigframes.ml.llm.GeminiTextGenerator(model_name="gemini-2.0-flash-001")

輸入和輸出

使用 bigframes.pandas 程式庫，即可存取各種來源的資料，包括本機 CSV 檔案、Cloud Storage 檔案、pandas DataFrame、BigQuery 模型和 BigQuery 函式。然後將該資料載入 BigQuery DataFrames DataFrame。您也可以從 BigQuery DataFrame 建立 BigQuery 資料表。

從 BigQuery 資料表或查詢載入資料

您可以透過下列方式，從 BigQuery 資料表或查詢建立 DataFrame：

# Create a DataFrame from a BigQuery table:
import bigframes.pandas as bpd

query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

從 CSV 檔案載入資料

您可以透過下列方式，從本機或 Cloud Storage CSV 檔案建立 DataFrame：

import bigframes.pandas as bpd

filepath_or_buffer = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
df_from_gcs = bpd.read_csv(filepath_or_buffer)
# Display the first few rows of the DataFrame:
df_from_gcs.head()

資料操縱

以下各節說明 BigQuery DataFrame 的資料操作功能。您可以在 bigframes.bigquery 程式庫中找到所述函式。

pandas API

BigQuery DataFrames 的顯著特色是，bigframes.pandas API 的設計與 pandas 程式庫中的 API 相似。這個設計可讓您使用熟悉的語法模式執行資料操縱工作。透過 BigQuery DataFrames API 定義的作業會在伺服器端執行，直接對 BigQuery 中儲存的資料進行操作，因此不需要將資料集移出 BigQuery。

如要查看 BigQuery DataFrames 支援哪些 pandas API，請參閱「支援的 pandas API」。

檢查及操控資料

您可以使用 bigframes.pandas API 執行資料檢查和計算作業。以下程式碼範例使用 bigframes.pandas 程式庫檢查 body_mass_g 欄、計算平均值 body_mass，以及依 species 計算平均值 body_mass：

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)

# Inspect one of the columns (or series) of the DataFrame:
bq_df["body_mass_g"]

# Compute the mean of this series:
average_body_mass = bq_df["body_mass_g"].mean()
print(f"average_body_mass: {average_body_mass}")

# Find the heaviest species using the groupby operation to calculate the
# mean body_mass_g:
(
    bq_df["body_mass_g"]
    .groupby(by=bq_df["species"])
    .mean()
    .sort_values(ascending=False)
    .head(10)
)

BigQuery 程式庫

BigQuery 程式庫提供 BigQuery SQL 函式，這些函式可能沒有對應的 pandas 函式。以下各節將舉例說明。

處理陣列值

您可以在 bigframes.bigquery 程式庫中使用 bigframes.bigquery.array_agg() 函式，在 groupby 作業後匯總值：

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

s = bpd.Series([0, 1, 2, 3, 4, 5])

# Group values by whether they are divisble by 2 and aggregate them into arrays
bbq.array_agg(s.groupby(s % 2 == 0))
# False    [1 3 5]
# True     [0 2 4]
# dtype: list<item: int64>[pyarrow]

您也可以使用 array_length() 和 array_to_string() 陣列函式。

建立結構體 Series 物件

您可以在 bigframes.bigquery 程式庫中使用 bigframes.bigquery.struct() 函式，為 DataFrame 中的每個資料欄建立具有子欄位的新 struct Series 物件：

import bigframes.bigquery as bbq
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 a new STRUCT Series with subfields for each column in a DataFrames.
lengths = bbq.struct(
    bq_df[["culmen_length_mm", "culmen_depth_mm", "flipper_length_mm"]]
)

lengths.peek()
# 146	{'culmen_length_mm': 51.1, 'culmen_depth_mm': ...
# 278	{'culmen_length_mm': 48.2, 'culmen_depth_mm': ...
# 337	{'culmen_length_mm': 36.4, 'culmen_depth_mm': ...
# 154	{'culmen_length_mm': 46.5, 'culmen_depth_mm': ...
# 185	{'culmen_length_mm': 50.1, 'culmen_depth_mm': ...
# dtype: struct[pyarrow]

將時間戳記轉換為 Unix Epoch

您可以使用 bigframes.bigquery 程式庫中的 bigframes.bigquery.unix_micros() 函式，將時間戳記轉換為 Unix 毫秒：

import pandas as pd

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Create a series that consists of three timestamps: [1970-01-01, 1970-01-02, 1970-01-03]
s = bpd.Series(pd.date_range("1970-01-01", periods=3, freq="d", tz="UTC"))

bbq.unix_micros(s)
# 0               0
# 1     86400000000
# 2    172800000000
# dtype: Int64

您也可以使用 unix_seconds() 和 unix_millis() 時間函式。

使用 SQL 純量函式

您可以在 bigframes.bigquery 程式庫中使用 bigframes.bigquery.sql_scalar() 函式，存取代表單一資料欄運算式的任意 SQL 語法：

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"

# The sql_scalar function can be used to inject SQL syntax that is not supported
# or difficult to express with the bigframes.pandas APIs.
bq_df = bpd.read_gbq(query_or_table)
shortest = bbq.sql_scalar(
    "LEAST({0}, {1}, {2})",
    columns=[
        bq_df["culmen_depth_mm"],
        bq_df["culmen_length_mm"],
        bq_df["flipper_length_mm"],
    ],
)

shortest.peek()
#         0
# 149	18.9
# 33	16.3
# 296	17.2
# 287	17.0
# 307	15.0
# dtype: Float64

自訂 Python 函式

透過 BigQuery DataFrames，您可以將自訂 Python 函式轉換為 BigQuery 物件，並大規模在 BigQuery DataFrames 物件上執行。這項擴充性支援功能可讓您執行 BigQuery DataFrames 和 SQL API 無法執行的作業，因此您可能會想善用開放原始碼程式庫。以下各節將說明這兩種擴充性機制。

使用者定義的函式 (UDF)

透過 UDF (預先發布版)，您可以將自訂 Python 函式轉換為 Python UDF。如需使用範例，請參閱「建立永久性 Python UDF」。

在 BigQuery DataFrames 中建立 UDF 時，系統會在指定資料集中建立 BigQuery 常式，做為 Python UDF。如需查看支援的完整參數集，請參閱 udf。

清除所用資源

除了直接在 Google Cloud 控制台 或使用其他工具清除雲端構件，您也可以使用 bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id) 指令，清除以明確名稱引數建立的 BigQuery DataFrames UDF。

需求條件

如要使用 BigQuery DataFrames UDF，請在專案中啟用 BigQuery API。如果您在專案中提供 bigquery_connection 參數，也必須啟用 BigQuery Connection API。

限制

  • UDF 中的程式碼必須為獨立性質，也就是不得包含對函式主體外部定義的匯入或變數的參照。
  • UDF 中的程式碼必須與 Python 3.11 相容，因為程式碼會在雲端環境中執行。
  • 在函式程式碼中進行微小變更 (例如重新命名變數或插入新行) 後，重新執行 UDF 定義程式碼會導致 UDF 重新建立，即使這些變更對函式的行為無關緊要。
  • 使用者程式碼會向具有 BigQuery 常式讀取權的使用者顯示，因此請謹慎加入私密內容。
  • 在 BigQuery 位置中，一個專案一次最多可有 1,000 個 Cloud Run 函式。

BigQuery DataFrames UDF 會部署使用者定義的 BigQuery Python 函式，並套用相關限制。

遠端函式

您可以使用 BigQuery DataFrames，將自訂純量函式轉換為 BigQuery 遠端函式。如需使用範例，請參閱「建立遠端函式」。如需完整的支援參數集，請參閱 remote_function。

在 BigQuery DataFrames 中建立遠端函式時，會建立下列項目：

  • Cloud Run 函式。
  • BigQuery 連線。 根據預設，系統會使用名為 bigframes-default-connection 的連線。您也可以使用預先設定的 BigQuery 連線，這樣系統就會略過連線建立程序。預設連線的服務帳戶會取得 Cloud Run 角色 (roles/run.invoker)。
  • 使用透過 BigQuery 連線建立的 Cloud Run 函式的 BigQuery 遠端函式。

BigQuery 連線會在與 BigQuery DataFrame 工作階段相同的位置建立，並使用您在自訂函式定義中提供的名稱。如要查看及管理連結，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往 BigQuery

  2. 選取您建立遠端函式的專案。

  3. 在「Explorer」窗格中展開專案，然後展開「外部連線」。

BigQuery 遠端函式會在您指定的資料集中建立，或是在匿名資料集中建立，這是一種隱藏資料集。如果在建立遠端函式時未設定名稱，BigQuery DataFrames 會套用以 bigframes 前置字元開頭的預設名稱。如要查看及管理在使用者指定資料集中建立的遠端函式，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往 BigQuery

  2. 選取您建立遠端函式的專案。

  3. 在「Explorer」窗格中，依序展開專案、建立遠端函式的資料集，然後展開「Routines」。

如要查看及管理 Cloud Run 函式，請按照下列步驟操作：

  1. 前往「Cloud Run」頁面。

    前往 Cloud Run

  2. 選取您建立函式的專案。

  3. 在可用服務清單中，依「函式部署類型」篩選。

  4. 如要找出 BigQuery DataFrames 建立的函式，請尋找具有 bigframes 前置字串的函式名稱。

清除所用資源

除了直接在 Google Cloud 控制台或使用其他工具清除雲端構件，您也可以透過下列方式，清除未提供明確名稱引數而建立的 BigQuery 遠端函式，以及相關聯的 Cloud Run 函式：

  • 如要啟動 BigQuery DataFrames 工作階段，請使用 session.close() 指令。
  • 如要使用預設的 BigQuery DataFrames 工作階段，請使用 bigframes.pandas.close_session() 指令。
  • 如要查看使用 session_id 的過往工作階段，請使用 bigframes.pandas.clean_up_by_session_id(session_id) 指令。

您也可以使用 bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id) 指令，清除以明確名稱引數建立的 BigQuery 遠端函式，以及相關聯的 Cloud Run 函式。

需求條件

如要使用 BigQuery DataFrames 遠端函式，必須啟用下列 API：

限制

  • 首次建立遠端函式時，大約需要 90 秒才能使用。額外的套件依附元件可能會增加延遲時間。
  • 在函式程式碼中或附近進行微小變更後，重新執行遠端函式定義程式碼 (例如重新命名變數、插入新行或在筆記本中插入新儲存格)，可能會導致系統重新建立遠端函式，即使這些變更對函式的行為沒有影響也一樣。
  • 使用者程式碼會向具有 Cloud Run 函式讀取權限的使用者顯示，因此請務必謹慎處理敏感內容。
  • 每個專案在一個區域中，最多可同時有 1,000 個 Cloud Run 函式。詳情請參閱「配額」。

機器學習與 AI

以下各節說明 BigQuery DataFrame 的 ML 和 AI 功能。這些功能會使用 bigframes.ml 程式庫。

機器學習位置

bigframes.ml 程式庫支援的區域與 BigQuery ML 相同。所有 BigQuery 區域都支援 BigQuery ML 模型預測和其他 ML 函式。模型訓練支援情況因地區而異。詳情請參閱 BigQuery ML 位置。

預先處理資料

使用 bigframes.ml.preprocessing 模組和 bigframes.ml.compose 模組建立轉換器，準備資料以供估算器 (模型) 使用。BigQuery DataFrames 提供下列轉換：

  • 在 bigframes.ml.preprocessing 模組中使用 KBinsDiscretizer 類別，將連續資料分組到間隔中。

  • 請使用 bigframes.ml.preprocessing 模組中的 LabelEncoder 類別，將目標標籤正規化為整數值。

  • 使用 bigframes.ml.preprocessing 模組中的 MaxAbsScaler 類別，將每個特徵縮放至 [-1, 1] 範圍，方法是使用特徵的最大絕對值。

  • 在 bigframes.ml.preprocessing 模組中使用 MinMaxScaler 類別，將每個特徵縮放至 [0, 1] 範圍，藉此標準化特徵。

  • 在 bigframes.ml.preprocessing 模組中使用 StandardScaler 類別，移除平均值並縮放至單位變異數，藉此標準化特徵。

  • 請使用 bigframes.ml.preprocessing 模組中的 OneHotEncoder 類別，將類別值轉換為數字格式。

  • 在 bigframes.ml.compose 模組中使用 ColumnTransformer 類別，將轉換器套用至 DataFrame 資料欄。

訓練模型

您可以建立估算器，在 BigQuery DataFrames 中訓練模型。

分群模型

您可以使用 bigframes.ml.cluster 模組，為叢集模型建立估算器。

  • 使用 KMeans 類別建立 k-means 分群模型。使用這些模型進行資料區隔。例如識別顧客區隔。K-means 是一種非監督式學習技術，因此模型訓練無須藉助標籤或拆分資料即可執行訓練或評估。

您可以使用 bigframes.ml.cluster 模組，為叢集模型建立估算器。

下列程式碼範例說明如何使用 bigframes.ml.cluster KMeans 類別，為資料區隔建立 k-means 叢集模型：

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) 模型。您可以使用這些模型計算主成分，並利用這些主成分對資料執行基底變更。這項技術會將每個資料點投影到前幾個主成分上，以取得低維度資料，同時盡可能保留資料的變異，藉此縮減維度。

Ensemble 模型

您可以使用 bigframes.ml.ensemble 模組，為集合模型建立估算器。

  • 使用 RandomForestClassifier 類別建立隨機樹系分類器模型。您可以使用這些模型，為分類建構多個學習方法決策樹。

  • 使用 RandomForestRegressor 類別建立隨機樹系迴歸模型。使用這些模型建構多個迴歸學習方法決策樹。

  • 使用 XGBClassifier 類別建立梯度提升樹狀分類器模型。使用這些模型，以加法方式建構多個分類學習方法決策樹。

  • 使用 XGBRegressor 類別建立梯度提升樹狀迴歸模型。使用這些模型，以累加方式建構多個迴歸學習方法決策樹。

預測模型

您可以使用 bigframes.ml.forecasting 模組，為預測模型建立估算器。

匯入的模型

您可以使用 bigframes.ml.imported 模組，為匯入的模型建立估算器。

線性模型

使用 bigframes.ml.linear_model 模組建立線性模型估算器。

  • 使用 LinearRegression 類別建立線性迴歸模型。使用這些模型進行預測。例如預測指定日子的項目銷售額。

  • 使用 LogisticRegression 類別建立邏輯迴歸模型。使用這些模型分類兩個以上可能的值，例如輸入是 low-value、medium-value 還是 high-value。

下列程式碼範例說明如何使用 bigframes.ml 執行下列操作：

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 建立估算器。

使用 GeminiTextGenerator 類別建立 Gemini 文字生成器模型。使用這些模型執行文字生成工作。

使用 bigframes.ml.llm 模組，為遠端大型語言模型 (LLM) 建立估算器。
下列程式碼範例說明如何使用 bigframes.ml.llm GeminiTextGenerator 類別建立 Gemini 模型，用於生成程式碼：

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 中建立遠端模型時，會建立 BigQuery 連線。根據預設，系統會使用名稱為 bigframes-default-connection 的連線。您也可以使用預先設定的 BigQuery 連線，這樣系統就會略過連線建立程序。預設連線的服務帳戶已取得專案的 Vertex AI 使用者角色 (roles/aiplatform.user)。

建立管道

您可以使用 bigframes.ml.pipeline 模組建立機器學習管道。您可以透過管線組裝多個機器學習步驟，同時設定不同參數，一起進行交叉驗證。這樣一來，程式碼就會簡化，您也能一併部署資料預先處理步驟和估算器。

使用 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)

效能最佳化

本節說明如何提升 BigQuery DataFrames 的效能。

部分排序模式

BigQuery DataFrames 提供排序模式功能。將 ordering_mode 屬性設為 partial，即可產生更有效率的查詢。

partial排序模式與預設的 strict 模式不同，後者會針對所有資料列建立總排序。總排序可透過 DataFrame.iloc 屬性提供以順序為基礎的資料列存取權，讓 BigQuery DataFrame 更能與 pandas 相容。不過，總排序和該排序的預設循序索引表示，除非將資料欄篩選器和資料列篩選器套用為 read_gbq 和 read_gbq_table 函式的參數，否則這些篩選器不會減少掃描的位元組數。為提供 DataFrame 中所有資料列的總排序，BigQuery DataFrame 會建立所有資料列的雜湊。這可能會導致系統忽略資料列和資料欄篩選器，掃描所有資料。

將 ordering_mode 屬性設為 partial，可防止 BigQuery DataFrames 對所有資料列產生總排序。部分排序模式也會關閉需要對所有資料列進行總排序的功能，例如 DataFrame.iloc 屬性。部分排序模式會將 DefaultIndexKind 類別設為空值索引，而不是排序的連續索引。

將 ordering_mode 屬性設為 partial 來篩選 DataFrame 時，BigQuery DataFrames 不再需要計算連續索引中缺少的資料列，因此能更快產生查詢，效率也更高。BigQuery DataFrames API 仍是您熟悉的 pandas API，就像嚴格排序模式的預設體驗一樣。不過，部分排序模式與常見的 pandas 行為不同，舉例來說，部分排序模式不會依索引執行隱含聯結。

無論是部分排序模式或嚴格排序模式，您都必須支付所用 BigQuery 資源的費用。不過，使用部分排序模式處理大型叢集資料表和分區資料表時，由於叢集和分區資料欄的資料列篩選器會減少處理的位元組數，因此可降低費用。

用量

如要使用部分排序，請在對 BigQuery DataFrames 執行任何其他作業前，將 ordering_mode 屬性設為 partial，如下列程式碼範例所示：

import bigframes.pandas as bpd

bpd.options.bigquery.ordering_mode = "partial"

由於部分排序模式沒有連續索引，因此不相關的 BigQuery DataFrame 不會隱含聯結。您必須明確呼叫 DataFrame.merge 方法，才能聯結衍生自不同資料表運算式的兩個 BigQuery DataFrame。

Series.unique() 和 Series.drop_duplicates() 功能與部分排序模式不相容。請改用 groupby 方法，以這種方式找出不重複的值：

# Avoid order dependency by using groupby instead of drop_duplicates.
unique_col = df.groupby(["column"], as_index=False).size().drop(columns="size")

在部分排序模式下，DataFrame.head(n) 和 Series.head(n) 函式的輸出內容在所有呼叫中並非等冪。如要下載任意的小型資料樣本，請使用 DataFrame.peek() 或 Series.peek() 方法。

如需使用 ordering_mode = "partial" 屬性的詳細教學課程，請參閱這個 BigQuery DataFrames Notebook，瞭解如何使用部分排序模式。

疑難排解

由於處於部分排序模式的 DataFrame 不一定有排序或索引，因此使用某些與 pandas 相容的方法時，可能會遇到下列問題。

需要訂單錯誤

部分功能需要排序，例如 DataFrame.head() 和 DataFrame.iloc 函式。如需必須排序的功能清單，請參閱「支援的 pandas API」中的「需要排序」欄。

如果物件沒有排序，作業會失敗，並顯示類似以下的 OrderRequiredError 訊息：

OrderRequiredError: Op iloc requires an ordering. Use .sort_values or .sort_index to provide an ordering.

如錯誤訊息所述，您可以使用 DataFrame.sort_values() 方法提供排序，依一或多個資料欄排序。其他作業 (例如 DataFrame.groupby() 作業) 會隱含地提供群組依鍵排序的總順序。

如果無法判斷排序是否為所有資料列的完全穩定總排序，後續作業可能會顯示類似以下的 AmbiguousWindowWarning 訊息，向您發出警告：

AmbiguousWindowWarning: Window ordering may be ambiguous, this can cause unstable results.

如果工作負載可接受非決定性結果，或您可以手動驗證提供的排序是否為全序，則可透過下列方式篩選 AmbiguousWindowWarning 訊息：

import warnings

import bigframes.exceptions

warnings.simplefilter(
    "ignore", category=bigframes.exceptions.AmbiguousWindowWarning
)
空值索引錯誤

部分功能需要索引，例如 DataFrame.unstack() 和 Series.interpolate() 屬性。如需索引的必要功能清單，請參閱「支援的 pandas API」中的「需要索引」欄。

如果您使用的作業需要採用部分排序模式的索引，作業會引發類似下列內容的 NullIndexError 訊息：

NullIndexError: DataFrame cannot perform interpolate as it has no index. Set an index using set_index.

如錯誤訊息所述，您可以使用 DataFrame.set_index() 方法提供索引，依一或多個資料欄排序。除非設定 as_index=False 參數，否則其他作業 (例如 DataFrame.groupby() 作業) 會根據索引鍵隱含提供群組的索引。

後續步驟