使用 BigQuery DataFrames

BigQuery DataFrames 提供由 BigQuery 引擎提供支持的 Pythonic DataFrame 和机器学习 (ML) API。BigQuery DataFrames 是一个开源软件包。您可以运行 pip install --upgrade bigframes 来安装最新版本。

BigQuery DataFrames 提供三个库：

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

所需的角色

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

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

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

此外，使用 BigQuery DataFrames 远程函数或 BigQuery DataFrames 机器学习远程模型时，如果您使用的是默认 BigQuery 连接，则需要 Project IAM Admin 角色 (roles/resourcemanager.projectIamAdmin)；如果您使用的是预配置连接，则需要 Browser 角色 (roles/browser)。可以通过将 bigframes.pandas.options.bigquery.skip_bq_connection_check 选项设置为 True 来避免此要求，在这种情况下，连接（默认连接或预配置连接）将按原样使用，不会进行任何存在或权限检查。如果您使用的是预配置连接并跳过连接检查，请确保：

  • 连接是在正确的位置创建的。
  • 如果您使用的是 BigQuery DataFrames 远程函数，则服务账号在项目中具有 Cloud Run Invoker 角色 (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-dec"  # @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 进行了安全性和性能改进，添加了新功能，并引入了一些重大变更。本文档介绍了这些变更，并提供了迁移指南。您可以在安装 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 不再默认为其部署的 Cloud Run 函数使用 Compute Engine 服务账号。如需限制您部署的函数的权限，请执行以下操作：

  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 模块

在 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 DataFrame 创建 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 DataFrames 支持以下 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 3.0 或更高版本和 pyarrow 19.0 或更高版本中的 pandas.ArrowDtype(pa.json_(pa.string())，否则 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 库提供了可能没有 Pandas 等效项的 BigQuery SQL 函数。以下部分介绍了一些示例。

处理数组值

您可以使用 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

自定义函数

通过使用 bigframes.pandas 库，您可以将自定义标量函数转换为 BigQuery 远程函数。在 BigQuery DataFrames 中创建远程函数会创建以下内容：

  • Cloud Run functions（第 2 代）函数。

  • BigQuery 连接。默认情况下，系统会使用名为 bigframes-default-connection 的连接。如果您愿意，可以使用预配置的 BigQuery 连接，在这种情况下会跳过连接创建。

    系统会向默认连接的服务账号授予 Cloud Run Invoker 角色 (roles/run.invoker)。

  • 通过 BigQuery 连接使用 Cloud Run 函数的 BigQuery 远程函数。

如需查看示例，请参阅创建远程函数。

系统会使用您在自定义函数定义中提供的名称在 BigQuery DataFrames 会话所在的相同位置创建 BigQuery 连接。如需查看和管理连接，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往 BigQuery 页面。

    转到 BigQuery

  2. 选择您在其中创建了远程函数的项目。

  3. 在“探索器”窗格中，展开该项目，然后展开“外部连接”。

BigQuery 远程函数在您指定的数据集中创建，或在匿名数据集（一种隐藏数据集类型）中创建。如果您在创建远程函数期间没有为其设置名称，BigQuery DataFrames 会应用以 bigframes 前缀开头的默认名称。如需查看和管理在用户指定的数据集中创建的远程函数，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往 BigQuery 页面。

    转到 BigQuery

  2. 选择您在其中创建了远程函数的项目。

  3. 在“探索器”窗格中，展开该项目，展开您在其中创建远程函数的数据集，然后展开“例程”。

如需了解如何查看和管理 Cloud Run 函数，请参阅使用 Google Cloud 控制台部署 Cloud Run 函数。如需识别由 BigQuery DataFrames 创建的函数，请查找名称以 bigframes 为前缀的函数。

您可以通过以下方式清理未命名的 BigQuery 远程函数及其关联的 Cloud Run functions 函数：

  • 对于 BigQuery DataFrames session，请使用 session.close()。
  • 对于默认的 BigQuery DataFrames 会话，请使用 bigframes.pandas.close_session()。
  • 对于具有 session_id 的过去会话，请使用 bigframes.pandas.clean_up_by_session_id(session_id)。

API 要求

如需使用 BigQuery DataFrames 远程函数，您必须启用以下 API：

限制

  • 首次创建远程函数时，大约需要 90 秒才能使用它们。

  • 笔记本中的细微更改（例如插入新单元或重命名变量）可能会导致重新创建远程函数，即使这些更改与远程函数代码无关。

  • BigQuery DataFrames 不会区分您在远程函数代码中添加的任何个人数据。远程函数代码会序列化为不透明盒子，以便部署为 Cloud Run functions 函数。

  • BigQuery DataFrames 创建的 Cloud Run functions（第 2 代）函数、BigQuery 连接和 BigQuery 远程函数仍保留在Google Cloud中。如果您不想保留这些资源，则必须使用适当的 Cloud Run functions 或 BigQuery 界面单独删除它们。

  • 一个项目一次最多可以有 1000 个 Cloud Run functions（第 2 代）函数。如需了解所有限制，请参阅 Cloud Run functions 配额。

机器学习和 AI

以下部分介绍了 BigQuery DataFrame 的 ML 和 AI 功能。这些功能使用 bigframes.ml 库。

机器学习位置

bigframes.ml 库支持与 BigQuery ML 相同的位置。所有 BigQuery 区域都支持 BigQuery ML 模型预测和其他机器学习函数。对模型训练的支持因区域而异。如需了解详情，请参阅 BigQuery ML 位置。

预处理数据

使用 bigframes.ml.preprocessing 模块和 bigframes.ml.compose 模块创建 Transformer（转换器），以便准备好数据以用于 Estimator（模型）。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 类将 Transformer 应用于 DataFrame 列。

训练模型

您可以创建 Estimator 以在 BigQuery DataFrames 中训练模型。

聚类模型

您可以使用 bigframes.ml.cluster 模块为聚类模型创建 Estimator。

  • 使用 KMeans 类创建 K-means 聚类模型。使用这些模型进行数据细分。例如，标识客户细分。K-means 是一种非监督式学习技术，因此模型训练不需要标签，也不需要为训练或评估拆分数据。

您可以使用 bigframes.ml.cluster 模块为聚类模型创建 Estimator。

以下代码示例展示了如何使用 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 模块为分解模型创建 Estimator。

  • 使用 PCA 类创建主成分分析 (PCA) 模型。使用这些模型计算主成分并使用主成分对数据执行基转换。这样便可实现降维，具体方法是将每个数据点仅投影到前几个主成分上，以获得维度较低的数据，并保留尽可能多的数据差异性。

集成学习模型

您可以使用 bigframes.ml.ensemble 模块为集成学习模型创建 Estimator。

  • 使用 RandomForestClassifier 类创建随机森林分类器模型。使用这些模型构建多个学习方法决策树以用于分类。

  • 使用 RandomForestRegressor 类创建随机森林回归模型。使用这些模型构建多个学习方法决策树以用于回归。

  • 使用 XGBClassifier 类创建梯度提升树分类器模型。使用这些模型以累加方式构建多个学习方法决策树以用于分类。

  • 使用 XGBRegressor 类创建梯度提升树回归模型。使用这些模型以累加方式构建多个学习方法决策树以用于回归。

预测模型

您可以使用 bigframes.ml.forecasting 模块为预测模型创建 Estimator。

导入的模型

您可以使用 bigframes.ml.imported 模块为导入的模型创建 Estimator。

线性模型

使用 bigframes.ml.linear_model 模块为线性模型创建 Estimator。

  • 使用 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 创建 Estimator。

使用 bigframes.ml.llm 模块为远程大语言模型 (LLM) 创建 Estimator。
以下代码示例展示如何使用 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 机器学习远程模型 (bigframes.ml.remote 或 bigframes.ml.llm)，您必须启用以下 API：

在 BigQuery DataFrames 中创建远程模型会创建 BigQuery 连接。默认情况下，系统会使用名为 bigframes-default-connection 的连接。如果您愿意，可以使用预配置的 BigQuery 连接，在这种情况下会跳过连接创建。系统会向默认连接的服务账号授予项目的 Vertex AI User 角色 (roles/aiplatform.user)。

创建流水线

您可以使用 bigframes.ml.pipeline 模块创建机器学习流水线。借助流水线，您可以在设置不同的参数时组合多个要进行交叉验证的机器学习步骤。这样可简化代码，并且允许您一起部署数据预处理步骤和 Estimator。

使用流水线类创建具有最终 Estimator 的转换流水线。

性能优化

本部分介绍了优化 BigQuery DataFrames 性能的方法。

部分排序模式

BigQuery DataFrames 提供了排序模式功能。将 ordering_mode 属性设置为 partial 可生成更高效的查询。

partial 排序模式与默认的 strict 模式形成对比，后者会对所有行创建总排序。总排序可使用 DataFrame.iloc 属性提供基于顺序的行访问，从而使 BigQuery DataFrames 与 pandas 更兼容。不过，总排序和针对该排序的默认顺序索引意味着，除非将列过滤条件和行过滤条件作为参数应用于 read_gbq 和 read_gbq_table 函数，否则这些过滤条件都不会减少扫描的字节数量。为了对 DataFrame 中的所有行提供总排序，BigQuery DataFrames 会创建所有行的哈希。这可能会导致进行忽略行和列过滤条件的完整数据扫描。

将 ordering_mode 属性设为 partial 后，BigQuery DataFrames 便不会对所有行生成总排序。部分排序模式还会关闭需要对所有行进行总排序的功能，例如 DataFrame.iloc 属性。部分排序模式会将 DefaultIndexKind 类设置为 null 索引，而不是针对排列的顺序索引。

在将 ordering_mode 属性设置为 partial 的情况下过滤 DataFrame 时，BigQuery DataFrames 无需再计算顺序索引中缺少哪些行，因此生成的查询速度更快且效率更高。BigQuery DataFrames API 仍然类似于 pandas，就像使用严格排序模式时的默认体验一样。不过，部分排序模式与常见的 pandas 行为不同，例如，部分排序模式不会按索引执行隐式联接。

对于部分排序模式和严格排序模式，您都需要为所使用的 BigQuery 资源付费。不过，在处理大型聚簇表和分区表时，使用部分排序模式可以降低成本，因为针对聚簇列和分区列的行过滤条件可以减少处理的字节数量。

用法

如需使用部分排序，请先将 ordering_mode 属性设置为 partial，然后再使用 BigQuery DataFrames 执行任何其他操作，如以下代码示例所示：

import bigframes.pandas as bpd

bpd.options.bigquery.ordering_mode = "partial"

由于部分排序模式没有顺序索引，因此不相关的 BigQuery DataFrames 不会隐式联接。相反，您必须明确调用 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
)
Null 索引错误

某些功能（例如 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() 方法提供索引，以便按一个或多个列进行排序。除非设置 as_index=False 参数，否则其他操作（例如 DataFrame.groupby() 操作）会按键隐式提供针对组的索引。

可视化

bigframes.pandas API 是完整的 Python 工具生态系统的网关。此 API 支持高级统计操作，您可以直观呈现从 BigQuery DataFrames 生成的汇总。您还可以使用内置的采样操作从 BigQuery DataFrames DataFrame 切换到 pandas DataFrame。

后续步骤