使用 BigQuery DataFrames

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

BigQuery DataFrames 提供了三个库：

  • bigframes.pandas 提供了一个 pandas API，可用于分析和操作 BigQuery 中的数据。只需更改一些导入项，就可以将许多工作负载从 pandas 迁移到 BigQuery 中。bigframes.pandas API 可以扩缩，支持处理 TB 级的 BigQuery 数据，并使用 BigQuery 查询引擎执行计算。
  • bigframes.bigquery 提供了许多可能没有 Pandas 等效项的 BigQuery SQL 函数。
  • bigframes.ml 提供类似于 scikit-learn API 的 ML 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 User角色 (roles/aiplatform.user)。

在笔记本、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 具有以下优势：

  • 运行向客户端返回结果的查询时，查询速度更快，创建的表更少，因为 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 模块

在 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")

数据操作

以下部分介绍了 BigQuery DataFrames 的数据操纵功能。您可以在 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() 数组函数。

创建结构体 Series 对象

您可以使用 bigframes.bigquery 库中的 bigframes.bigquery.struct() 函数创建新的结构体 Series 对象，其中包含 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

自定义 Python 函数

借助 BigQuery DataFrames，您可以将自定义 Python 函数转换为可以在 BigQuery DataFrames 对象上大规模运行的 BigQuery 制品。这种可扩展性支持使您可以执行超出 BigQuery DataFrames 和 SQL API 功能范围的操作，因此可以充分利用开源库。以下部分介绍了这种可扩展性机制的两种变体。

用户定义的函数 (UDF)

借助 UDF（预览版），您可以将自定义 Python 函数转换为 Python UDF。如需查看用法示例，请参阅创建永久性 Python UDF。

在 BigQuery DataFrames 中创建 UDF 会在指定的数据集中创建一个 BigQuery 例程作为 Python UDF。如需查看完整的受支持参数集，请参阅 udf。

清理

除了直接在 Google Cloud 控制台中或使用其他工具清理云制品之外，您还可以使用 bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id) 命令清理通过显式名称参数创建的 BigQuery DataFrames UDF。

要求

如需使用 BigQuery DataFrames UDF，请在项目中启用 BigQuery API。如果您在项目中提供 bigquery_connection 参数，还必须启用 BigQuery Connection API。

限制

  • UDF 中的代码必须是独立的，也就是说，不得包含对函数体外部定义的导入或变量的任何引用。
  • UDF 中的代码必须与 Python 3.11 兼容，因为这是代码在云端执行时所处的环境。
  • 在函数代码中进行细微更改（例如重命名变量或插入新行）后重新运行 UDF 定义代码会导致重新创建 UDF，即使这些更改对函数的行为无关紧要。
  • 具有 BigQuery 例程读取访问权限的用户可以查看用户代码，因此您应谨慎添加敏感内容。
  • 一个项目在一个 BigQuery 位置中一次最多可以拥有 1,000 个 Cloud Run 函数。

BigQuery DataFrames UDF 会部署用户定义的 BigQuery Python 函数，并且遵循相关的限制。

远程函数

借助 BigQuery DataFrames，您可以将自定义标量函数转换为 BigQuery 远程函数。如需查看用法示例，请参阅创建远程函数。 如需查看完整的受支持参数集，请参阅 remote_function。

在 BigQuery DataFrames 中创建远程函数会创建以下内容：

  • Cloud Run 函数。
  • BigQuery 连接。 默认情况下，系统会使用名为 bigframes-default-connection 的连接。如果您愿意，可以使用预配置的 BigQuery 连接，在这种情况下会跳过连接创建。系统会向默认连接的服务账号授予 Cloud Run 角色 (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 函数，请执行以下操作：

  1. 转到 Cloud Run 页面

    转到 Cloud Run

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

  3. 在可用服务列表中，按函数部署类型进行过滤。

  4. 如需识别由 BigQuery DataFrames 创建的函数，请查找以 bigframes 为前缀的函数名称。

清理

除了直接在 Google Cloud 控制台中或使用其他工具清理云制品之外，您还可以通过以下方式清理不是使用显式名称参数创建的 BigQuery 远程函数及其关联的 Cloud Run 函数：

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

您还可以使用 bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id) 命令清理使用显式名称参数创建的 BigQuery 远程函数及其关联的 Cloud Run 函数。

要求

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

限制

  • 首次创建远程函数时，大约需要 90 秒才能使用它们。其他软件包依赖项可能会增加延迟时间。
  • 在函数代码中及周围进行细微更改（例如重命名变量、插入新行或在笔记本中插入新单元）后重新运行远程函数定义代码可能会导致重新创建远程函数，即使这些更改对函数的行为无关紧要。
  • 具有 Cloud Run 函数读取访问权限的用户可以查看用户代码，因此您应谨慎添加敏感内容。
  • 一个项目在一个区域中一次最多可以拥有 1,000 个 Cloud Run 函数。如需了解详情，请参阅配额。

机器学习和 AI

以下部分介绍了 BigQuery DataFrame 的机器学习和 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。

使用 GeminiTextGenerator 类创建 Gemini 文本生成器模型。使用这些模型可执行文本生成任务。

使用 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 ML 远程模型（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 的转换流水线。

选择模型

使用 bigframes.ml.model_selection 模块拆分训练数据集和测试数据集，并选择最佳模型：

  • 使用 train_test_split 函数将数据拆分为训练集和测试（评估）集，如以下代码示例所示：

    X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)

  • 使用 KFold 类和 KFold.split 方法创建多折训练集和测试集以训练和评估模型，如以下代码示例所示。此功能对于小型数据集非常有用。

    kf = KFold(n_splits=5)
for i, (X_train, X_test, y_train, y_test) in enumerate(kf.split(X, y)):
# Train and evaluate models with training and testing sets

  • 使用 cross_validate 函数自动创建多折训练集和测试集，训练和评估模型，并获取每个折叠的结果，如以下代码示例所示：

    scores = cross_validate(model, X, y, cv=5)

后续步骤