遷移至 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 DataFrames 部署的遠端函式預設會提升安全性。

安裝 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 部署的 Cloud Run 函式，預設不再使用 Compute Engine 服務帳戶。如要限制部署函式的權限，請按照下列步驟操作：

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

例如：

@remote_function(
  cloud_function_service_account="my-service-account@my-project.s3ns.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 會將部署的 Cloud Run functions 輸入設定設為 "internal-only"。先前，輸入設定預設為 "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 模組

建議您直接提供支援的 model_name (例如 "gemini-3.5-flash")，以免日後預設模型變更時發生中斷。

import bigframes.ml.llm

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

後續步驟