安装 BigQuery DataFrames

BigQuery DataFrames 是一个开源软件包，可让您使用熟悉的 Python API 执行数据分析和机器学习 (ML) 任务。安装此软件包后，您可以使用 BigQuery 引擎来扩缩 pandas 和 scikit-learn 工作流，以处理海量数据集。

安装 BigQuery DataFrames

如需安装最新版本的 BigQuery DataFrames，请运行 pip install --upgrade bigframes。

可用的库

BigQuery DataFrames 提供三个库：

• bigframes.pandas 提供了一个 pandas API，可用于分析和操作 BigQuery 中的数据。只需更改一些导入，即可将许多工作负载从 pandas 迁移到 bigframes。bigframes.pandas API 可以扩缩，支持处理 TB 级的 BigQuery 数据，并使用 BigQuery 查询引擎执行计算。
• bigframes.bigquery 提供了许多可能没有 pandas 等效项的 BigQuery SQL 函数。
• bigframes.ml 提供了一个类似于 scikit-learn API 的 API，用于机器学习。 借助 BigQuery DataFrames 中的机器学习功能，您可以预处理数据，然后基于该数据训练模型。您还可以将这些操作链接在一起以创建数据流水线。

所需的角色

如需获得完成本文档中的任务所需的权限，请让您的管理员为您授予项目的以下 IAM 角色：

• BigQuery Job User (roles/bigquery.jobUser)
• BigQuery Read Session User (roles/bigquery.readSessionUser)
• 在 BigQuery 笔记本中使用 BigQuery DataFrames：
  • BigQuery User (roles/bigquery.user)
  • Notebook Runtime User (roles/aiplatform.notebookRuntimeUser)
  • Code Creator (roles/dataform.codeCreator)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

在笔记本、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 版本 2.0

BigQuery DataFrames 2.0 版对 BigQuery DataFrames API 进行了安全性和性能改进，添加了新功能，并引入了破坏性更改。以下各部分介绍了这些变更并提供了迁移指南。您可以在安装 2.0 版本之前，使用最新 1.x 版本的 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 参数来替换此选项：

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.",
  ...
)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

如需使用 Compute Engine 服务账号，您可以将 @remote_function 修饰器的 cloud_function_service_account 参数设置为 "default"。仅当您有特定原因需要使用 Compute Engine 服务账号时，才使用此选项。例如：

@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 functions 的入站流量设置。以前，默认情况下，入站流量设置会设置为 "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")

后续步骤

• 了解如何使用 BigQuery DataFrames 处理数据。
• 了解如何使用 Gemini 生成 BigQuery DataFrames 代码。
• 了解如何使用 BigQuery DataFrames 分析通过 PyPI 进行的软件包下载情况。
• 在 GitHub 上查看 BigQuery DataFrames 的源代码、示例笔记本和示例。
• 探索 BigQuery DataFrames API 参考文档。