使用 BigQuery DataFrames

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

BigQuery DataFrames 提供三個程式庫：

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

必要的角色

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

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

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

此外，如果使用 BigQuery DataFrames 遠端函式或 BigQuery DataFrames ML 遠端模型，則需要 Project IAM 管理員角色 (roles/resourcemanager.projectIamAdmin) (如果使用預設 BigQuery 連線)，或 Browser 角色 (roles/browser) (如果使用預先設定的連線)。如要避免這項規定，請將 bigframes.pandas.options.bigquery.skip_bq_connection_check 選項設為 True，在這種情況下，系統會直接使用連線 (預設或預先設定)，不進行任何存在性或權限檢查。如果您使用預先設定的連線，並略過連線檢查，請確認下列事項：

  • 連線已在正確的位置建立。
  • 如果您使用 BigQuery DataFrames 遠端函式，服務帳戶在專案中具有 Cloud Run 叫用者角色 (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 的安全性和效能，並新增功能和重大變更。本文件將說明這些變更，並提供遷移指南。您可以使用最新的 BigQuery DataFrames 1.x 版本，在安裝 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 版中，GeminiTextGenerator 的預設 model_name 已更新為 "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 DataFrames 建立 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 支援下列 numpy 和 pandas dtype：

BigQuery BigQuery DataFrames 和 pandas
ARRAY pandas.ArrowDtype(pa.list_())
BOOL pandas.BooleanDtype()
DATE pandas.ArrowDtype(pa.date32())
DATETIME pandas.ArrowDtype(pa.timestamp("us"))
FLOAT64 pandas.Float64Dtype()
GEOGRAPHY

geopandas.array.GeometryDtype()

僅支援 to_pandas()
INT64 pandas.Int64Dtype()
JSON pandas.ArrowDtype(pa.json_(pa.string()) 在 pandas 3.0 以上版本和 pyarrow 19.0 以上版本中，否則 JSON 欄會顯示為 pandas.ArrowDtype(db_dtypes.JSONArrowType())。
STRING pandas.StringDtype(storage="pyarrow")
STRUCT pandas.ArrowDtype(pa.struct())
TIME pandas.ArrowDtype(pa.time64("us"))
TIMESTAMP pandas.ArrowDtype(pa.timestamp("us", tz="UTC"))

BigQuery DataFrames 不支援下列 BigQuery 資料類型：

  • NUMERIC

  • BIGNUMERIC

  • INTERVAL

  • RANGE

所有其他 BigQuery 資料類型都會顯示為物件類型。

資料操縱

以下各節說明 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() 陣列函式。

建立結構體序列

您可以使用 bigframes.bigquery 程式庫中的 bigframes.bigquery.struct() 函式，為 DataFrame 中的每個資料欄建立新的結構體序列，並加入子欄：

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 紀元

您可以使用 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 DataFrames 工作階段所在位置建立，並使用您在自訂函式定義中提供的名稱。如要查看及管理連線，請按照下列步驟操作：

  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. 在可用服務清單中篩選「Function Deployment type」。

  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 秒才能開始使用。其他套件依附元件可能會增加延遲時間。
  • 在函式程式碼中和周圍進行簡單變更 (例如變更變數名稱、在 Notebook 中插入新行或新儲存格) 後，重新執行遠端函式定義程式碼，可能會導致遠端函式重新建立，即使這些變更對函式的行為沒有影響也一樣。
  • 使用者程式碼會向具有 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) 模型。使用這些模型計算主成分，並用於對資料執行基礎變更。這項技術會將每個資料點投射到前幾個主成分上，以便取得較低維度的資料，同時盡可能保留資料變化。

集成模型

您可以使用 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 資源付費。不過，使用部分排序模式可在處理大型叢集資料表和分區資料表時降低成本，因為叢集和分區資料欄的資料行篩選器可減少所處理的位元組數。

用量

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

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 筆記本，瞭解如何使用部分排序模式。

疑難排解

由於部分排序模式中的 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() 方法提供索引，以便依據單一或多個資料欄排序。其他作業 (例如 DataFrame.groupby() 作業) 會依鍵值間接提供群組索引，除非已設定 as_index=False 參數。

圖表

bigframes.pandas API 是通往完整 Python 工具生態系統的入口。API 支援進階統計運算，您可以將 BigQuery DataFrames 產生的匯總資料視覺化。您也可以將 BigQuery DataFrames DataFrame 切換為內建取樣操作的 pandas DataFrame。

後續步驟