遷移至 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 已更新為 "gemini-2.0-flash-001"。model_nameGeminiTextGenerator建議您提供 model_name，以免日後預設模型變更時發生中斷。

import bigframes.ml.llm

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

後續步驟