使用 BigQuery DataFrames

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

BigQuery DataFrames 提供两个库：

  • bigframes.pandas：提供与 Pandas 兼容的 API 以用于分析。

  • bigframes.ml：提供类似于 scikit-learn 的 API 以用于机器学习 (ML)。

所需权限

选项

安装完成后，您需要指定要在其中使用 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

如果未设置 bf.options.bigquery.project，则系统会使用 $GOOGLE_CLOUD_PROJECT 环境变量，该变量在提供 BigQuery Studio 和 Vertex AI 笔记本的笔记本运行时中设置。

数据处理位置

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 支持以下 numpy 和 pandas dtype：

BigQuery BigQuery DataFrames 和 Pandas
BOOL pandas.BooleanDtype()
DATE pandas.ArrowDtype(pa.date32())
DATETIME pandas.ArrowDtype(pa.timestamp("us"))
FLOAT64 pandas.Float64Dtype()
GEOGRAPHY

geopandas.array.GeometryDtype()

受 to_pandas() only 支持
INT64 pandas.Int64Dtype()
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 数据类型：

  • ARRAY

  • NUMERIC

  • BIGNUMERIC

  • INTERVAL

  • RANGE

  • JSON

所有其他 BigQuery 数据类型都显示为对象类型。

使用 bigframes.pandas 库

bigframes.pandas 库提供类似于 pandas 的 API，可用于分析和操作 BigQuery 中的数据。bigframes.pandas API 可以伸缩，支持处理 TB 级的 BigQuery 数据，并使用 BigQuery 查询引擎执行计算。
bigframes.pandas API 提供以下功能：

输入和输出

您可以从各种来源访问数据，包括本地 CSV 文件、Cloud Storage 文件、pandas DataFrame、BigQuery 模型和 BigQuery 函数，并将其加载到 BigQuery DataFrames DataFrame 中。您还可以从 BigQuery DataFrames 创建 BigQuery 表。

数据操作

您可以使用 Python（而不是 SQL）进行开发。您可以使用 Python 开发所有 BigQuery 数据操作，无需在语言之间切换并尝试以文本字符串形式捕获 SQL 语句。bigframes.pandas API 提供超过 750 个 pandas 函数。

Python 生态系统和可视化

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

自定义 Python 函数

借助 BigQuery DataFrames，您可以将自定义标量函数转换为 BigQuery 远程函数。在 BigQuery DataFrames 中创建远程函数会创建以下内容：

  1. Cloud Functions（第 2 代）函数。

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

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

  3. 通过 BigQuery 连接 (2) 使用 Cloud Functions 函数 (1) 的 BigQuery 远程函数。

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

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

  1. 在 Google Cloud 控制台中转至 BigQuery。

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

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

BigQuery 远程函数在您指定的数据集中创建，或在一种特殊类型的隐藏数据集（在代码中称为匿名数据集）中创建。如需查看和管理在用户提供的数据集中创建的远程函数，请执行以下操作：

  1. 在 Google Cloud 控制台中转至 BigQuery。

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

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

如需查看和管理 Cloud Functions 函数，请使用函数页面，并使用项目选择器选择您在其中创建了函数的项目。为便于识别，由 BigQuery DataFrames 创建的函数的名称以 bigframes 为前缀。

使用要求

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

如需使用 BigQuery DataFrames 远程函数，您必须在项目中被授予以下 IAM 角色：

限制

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

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

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

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

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

bigframes.pandas 示例

以下示例展示了使用 bigframes.pandas 的常见方式。

从 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()

检查和操纵数据

您可以使用 bigframes.pandas 执行数据检查和计算操作。
以下代码示例展示如何使用 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)
)

使用 bigframes.ml 库

借助 BigQuery DataFrames 中的机器学习功能，您可以预处理数据，然后基于该数据训练模型。您还可以将这些操作链接在一起以创建数据流水线。

机器学习位置

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)

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：

您还必须拥有项目的以下 IAM 角色：

  • BigQuery Connection Admin (roles/bigquery.connectionAdmin)
  • Project IAM Admin (roles/resourcemanager.projectIamAdmin)（如果使用默认 BigQuery 连接）或 Browser (roles/browser)（如果使用预配置连接）。可以通过将 bigframes.pandas.options.bigquery.skip_bq_connection_check 选项设置为 True 来避免此要求，在这种情况下，连接（默认连接或预配置连接）将按原样使用，不会进行任何存在或权限检查。如果您使用的是预配置连接并跳过连接检查，请确保在正确的位置创建连接并且其服务账号具有项目的 Vertex AI User (roles/aiplatform.user) 角色。

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

创建流水线

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

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

后续步骤