迁移到 BigQuery DataFrames 版本 2.0

BigQuery DataFrames 2.0 版对 BigQuery DataFrames API 进行了安全性和性能改进，添加了新功能，并引入了破坏性更改。本文档介绍了这些变更并提供了迁移指南。您可以在安装 2.0 版本之前，使用最新 1.x 版本的 BigQuery DataFrames 应用这些建议。

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 默认不再使用 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 函数的入站流量设置。以前，默认情况下，入站流量设置会设置为 "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")

后续步骤