Usar BigQuery DataFrames

BigQuery DataFrames proporciona una API de Python para DataFrames y aprendizaje automático (ML) basada en el motor de BigQuery. BigQuery DataFrames es un paquete de código abierto. Puedes ejecutar pip install --upgrade bigframes para instalar la versión más reciente.

BigQuery DataFrames proporciona tres bibliotecas:

  • bigframes.pandas proporciona una API de pandas que puedes usar para analizar y manipular datos en BigQuery. Muchas cargas de trabajo se pueden migrar de pandas a bigframes con solo cambiar algunas importaciones. La API bigframes.pandas es escalable para admitir el procesamiento de terabytes de datos de BigQuery y usa el motor de consultas de BigQuery para realizar cálculos.
  • bigframes.bigquery proporciona muchas funciones de BigQuery SQL que puede que no tengan un equivalente en pandas.
  • bigframes.ml proporciona una API similar a la API de scikit-learn para el aprendizaje automático. Las funciones de aprendizaje automático de los DataFrames de BigQuery te permiten preprocesar datos y, a continuación, entrenar modelos con esos datos. También puedes encadenar estas acciones para crear flujos de datos.

Roles obligatorios

Para obtener los permisos que necesitas para completar las tareas de este documento, pide a tu administrador que te asigne los siguientes roles de gestión de identidades y accesos en tu proyecto:

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Además, cuando se usan funciones remotas de DataFrames de BigQuery o modelos remotos de ML de DataFrames de BigQuery, se necesita el rol Administrador de gestión de identidades y accesos del proyecto (roles/resourcemanager.projectIamAdmin) si se usa una conexión predeterminada de BigQuery, o el rol Navegador (roles/browser) si se usa una conexión preconfigurada. Este requisito se puede evitar si se define la opción bigframes.pandas.options.bigquery.skip_bq_connection_check como True. En ese caso, la conexión (predeterminada o preconfigurada) se usa tal cual, sin comprobar si existe o si tiene permisos. Si usas la conexión preconfigurada y te saltas la comprobación de la conexión, verifica lo siguiente:

  • La conexión se crea en la ubicación correcta.
  • Si usas funciones remotas de DataFrames de BigQuery, la cuenta de servicio tiene el rol de invocador de Cloud Run (roles/run.invoker) en el proyecto.
  • Si usas modelos remotos de aprendizaje automático de DataFrames de BigQuery, la cuenta de servicio tiene el rol de usuario de Vertex AI (roles/aiplatform.user) en el proyecto.

Cuando realizas la autenticación de usuarios finales en un entorno interactivo, como un cuaderno, un REPL de Python o la línea de comandos, BigQuery DataFrames te pide que te autentiques si es necesario. Si no, consulta cómo configurar las credenciales predeterminadas de la aplicación en distintos entornos.

Configurar las opciones de instalación

Después de instalar BigQuery DataFrames, puede especificar las siguientes opciones.

Ubicación y proyecto

Debe especificar la ubicación y el proyecto en los que quiera usar los DataFrames de BigQuery.

Puedes definir la ubicación y el proyecto en tu cuaderno de la siguiente manera:

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

Ubicación del tratamiento de datos

BigQuery DataFrames se ha diseñado para ofrecer escalabilidad, lo que consigue manteniendo los datos y el procesamiento en el servicio de BigQuery. Sin embargo, puedes introducir datos en la memoria de tu máquina cliente llamando a .to_pandas() en un objeto DataFrame o Series. Si decides hacerlo, se aplicará la limitación de memoria de tu máquina cliente.

Migrar a la versión 2.0 de BigQuery DataFrames

La versión 2.0 de BigQuery DataFrames mejora la seguridad y el rendimiento de la API BigQuery DataFrames, añade nuevas funciones e introduce cambios incompatibles. En este documento se describen los cambios y se ofrecen directrices para la migración. Puedes aplicar estas recomendaciones antes de instalar la versión 2.0 usando la versión 1.x más reciente de BigQuery DataFrames.

La versión 2.0 de BigQuery DataFrames ofrece las siguientes ventajas:

  • Las consultas son más rápidas y se crean menos tablas cuando ejecutas consultas que devuelven resultados al cliente, porque allow_large_results tiene el valor predeterminado False. Esto puede reducir los costes de almacenamiento, sobre todo si usas la facturación por bytes físicos.
  • Seguridad mejorada de forma predeterminada en las funciones remotas implementadas por los DataFrames de BigQuery.

Instalar la versión 2.0 de BigQuery DataFrames

Para evitar cambios que provoquen errores, fija una versión específica de BigQuery DataFrames en tu archivo requirements.txt (por ejemplo, bigframes==1.42.0) o en tu archivo pyproject.toml (por ejemplo, dependencies = ["bigframes = 1.42.0"]). Cuando quieras probar la versión más reciente, puedes ejecutar pip install --upgrade bigframes para instalarla.

Usa la opción allow_large_results

BigQuery tiene un límite de tamaño de respuesta máximo para las tareas de consulta. A partir de la versión 2.0 de BigQuery DataFrames, BigQuery DataFrames aplica este límite de forma predeterminada en los métodos que devuelven resultados al cliente, como peek(), to_pandas() y to_pandas_batches(). Si tu trabajo devuelve resultados de gran tamaño, puedes definir allow_large_results como True en tu objeto BigQueryOptions para evitar cambios incompatibles. Esta opción está activada Falsede forma predeterminada en la versión 2.0 de BigQuery DataFrames.

import bigframes.pandas as bpd

bpd.options.bigquery.allow_large_results = True

Puede anular la opción allow_large_results mediante el parámetro allow_large_results en to_pandas() y otros métodos. Por ejemplo:

bf_df = bpd.read_gbq(query)
# ... other operations on bf_df ...
pandas_df = bf_df.to_pandas(allow_large_results=True)

Usar el decorador @remote_function

La versión 2.0 de BigQuery DataFrames introduce algunos cambios en el comportamiento predeterminado del decorador @remote_function.

Se aplican argumentos de palabras clave a los parámetros ambiguos

Para evitar que se pasen valores a un parámetro no deseado, BigQuery DataFrames 2.0 y versiones posteriores obligan a usar argumentos de palabras clave para los siguientes parámetros:

  • 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

Cuando utilice estos parámetros, indique el nombre del parámetro. Por ejemplo:

@remote_function(
  name="my_remote_function",
  ...
)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

Definir una cuenta de servicio

Desde la versión 2.0, BigQuery DataFrames ya no usa la cuenta de servicio de Compute Engine de forma predeterminada para las funciones de Cloud Run que implementa. Para limitar los permisos de la función que despliegues,

  1. Crea una cuenta de servicio con los permisos mínimos.
  2. Proporciona el correo de la cuenta de servicio al parámetro cloud_function_service_account del decorador @remote_function.

Por ejemplo:

@remote_function(
  cloud_function_service_account="my-service-account@my-project.iam.gserviceaccount.com",
  ...
)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

Si quieres usar la cuenta de servicio de Compute Engine, puedes definir el parámetro cloud_function_service_account del decorador @remote_function en "default". Por ejemplo:

# 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)

Definir la configuración de Ingress

A partir de la versión 2.0, BigQuery DataFrames define los ajustes de entrada de las funciones de Cloud Run que implementa en "internal-only". Antes, los ajustes de entrada se definían como "all" de forma predeterminada. Para cambiar la configuración de entrada, define el parámetro cloud_function_ingress_settings del decorador @remote_function. Por ejemplo:

@remote_function(cloud_function_ingress_settings="internal-and-gclb", ...)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

Usar endpoints personalizados

En las versiones de BigQuery DataFrames anteriores a la 2.0, si una región no admitía endpoints de servicio regionales y bigframes.pandas.options.bigquery.use_regional_endpoints = True, BigQuery DataFrames recurría a endpoints de ubicación. La versión 2.0 de BigQuery DataFrames elimina este comportamiento alternativo. Para conectarte a los endpoints de ubicación en la versión 2.0, define la opción bigframes.pandas.options.bigquery.client_endpoints_override. Por ejemplo:

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",
}

Sustituye LOCATION por el nombre de la ubicación de BigQuery a la que quieras conectarte.

Usar el módulo bigframes.ml.llm

En la versión 2.0 de BigQuery DataFrames, el valor predeterminado de model_name para GeminiTextGenerator se ha actualizado a "gemini-2.0-flash-001". Te recomendamos que proporciones un model_name directamente para evitar que se produzcan errores si el modelo predeterminado cambia en el futuro.

import bigframes.ml.llm

model = bigframes.ml.llm.GeminiTextGenerator(model_name="gemini-2.0-flash-001")

Manipulación de datos

En las siguientes secciones se describen las funciones de manipulación de datos de los DataFrames de BigQuery. Puedes encontrar las funciones que se describen en la biblioteca bigframes.bigquery.

API de pandas

Una característica destacable de BigQuery DataFrames es que la API bigframes.pandas se ha diseñado para que sea similar a las APIs de la biblioteca pandas. Este diseño te permite usar patrones de sintaxis conocidos para las tareas de manipulación de datos. Las operaciones definidas a través de la API BigQuery DataFrames se ejecutan del lado del servidor, operando directamente en los datos almacenados en BigQuery y eliminando la necesidad de transferir conjuntos de datos fuera de BigQuery.

Para consultar qué APIs de pandas son compatibles con BigQuery DataFrames, consulta APIs de pandas compatibles.

Inspeccionar y manipular datos

Puedes usar la API bigframes.pandas para realizar operaciones de inspección y cálculo de datos. En el siguiente código de ejemplo se usa la biblioteca bigframes.pandas para inspeccionar la columna body_mass_g, calcular la media body_mass y calcular la media body_mass por species:

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

Biblioteca de BigQuery

La biblioteca de BigQuery proporciona funciones de SQL de BigQuery que puede que no tengan un equivalente en pandas. En las siguientes secciones se muestran algunos ejemplos.

Procesar valores de matriz

Puedes usar la función bigframes.bigquery.array_agg() de la biblioteca bigframes.bigquery para agregar valores después de una operación 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]

También puedes usar las funciones de matriz array_length() y array_to_string().

Crear un objeto Series struct

Puedes usar la función bigframes.bigquery.struct() de la biblioteca bigframes.bigquery para crear un objeto Series struct con subcampos para cada columna de un 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]

Convertir marcas de tiempo en épocas de Unix

Puedes usar la función bigframes.bigquery.unix_micros() de la biblioteca bigframes.bigquery para convertir marcas de tiempo en microsegundos de 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

También puedes usar las funciones de tiempo unix_seconds() y unix_millis().

Usar la función escalar de SQL

Puedes usar la función bigframes.bigquery.sql_scalar() de la biblioteca bigframes.bigquery para acceder a una sintaxis SQL arbitraria que represente una expresión de una sola columna:

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

Funciones de Python personalizadas

BigQuery DataFrames te permite convertir tus funciones de Python personalizadas en artefactos de BigQuery que puedes ejecutar a gran escala en objetos de BigQuery DataFrames. Esta compatibilidad con la extensibilidad te permite realizar operaciones que no son posibles con las APIs de BigQuery DataFrames y SQL, por lo que puedes aprovechar las bibliotecas de código abierto. Las dos variantes de este mecanismo de extensibilidad se describen en las secciones siguientes.

Funciones definidas por el usuario (UDF)

Con las funciones definidas por el usuario (vista previa), puedes convertir tu función de Python personalizada en una función definida por el usuario de Python. Para ver un ejemplo de uso, consulta Crear una FDU de Python persistente.

Al crear una UDF en BigQuery DataFrames, se crea una rutina de BigQuery como UDF de Python en el conjunto de datos especificado. Para ver el conjunto completo de parámetros admitidos, consulta udf.

Limpieza

Además de limpiar los artefactos de la nube directamente en la Google Cloud consola o con otras herramientas, puedes limpiar las funciones definidas por el usuario de DataFrames de BigQuery que se hayan creado con un argumento de nombre explícito mediante el comando bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

Requisitos

Para usar una función definida por el usuario de BigQuery DataFrames, habilita la API de BigQuery en tu proyecto. Si proporciona el parámetro bigquery_connection en su proyecto, también debe habilitar la API de conexión de BigQuery.

Limitaciones

  • El código de la UDF debe ser autónomo, es decir, no debe contener ninguna referencia a una importación o variable definida fuera del cuerpo de la función.
  • El código de la función definida por el usuario debe ser compatible con Python 3.11, ya que es el entorno en el que se ejecuta el código en la nube.
  • Si se vuelve a ejecutar el código de definición de la función definida por el usuario después de hacer cambios triviales en el código de la función (por ejemplo, cambiar el nombre de una variable o insertar una línea nueva), se volverá a crear la función definida por el usuario, aunque estos cambios no tengan importancia para el comportamiento de la función.
  • Los usuarios con acceso de lectura a las rutinas de BigQuery pueden ver el código de usuario, por lo que debes incluir contenido sensible con precaución.
  • Un proyecto puede tener hasta 1000 funciones de Cloud Run a la vez en una ubicación de BigQuery.

La función definida por el usuario de BigQuery DataFrames implementa una función de Python de BigQuery definida por el usuario, por lo que se aplican las limitaciones relacionadas.

Funciones remotas

BigQuery DataFrames te permite convertir tus funciones escalares personalizadas en funciones remotas de BigQuery. Para ver un ejemplo de uso, consulta Crear una función remota. Para ver el conjunto completo de parámetros admitidos, consulta remote_function.

Al crear una función remota en BigQuery DataFrames, se crea lo siguiente:

  • Una función de Cloud Run.
  • Una conexión de BigQuery. De forma predeterminada, se usa una conexión llamada bigframes-default-connection. Si lo prefieres, puedes usar una conexión de BigQuery preconfigurada. En ese caso, se omitirá la creación de la conexión. Se concede el rol de Cloud Run (roles/run.invoker) a la cuenta de servicio de la conexión predeterminada.
  • Una función remota de BigQuery que usa la función de Cloud Run que se ha creado con la conexión de BigQuery.

Las conexiones de BigQuery se crean en la misma ubicación que la sesión de DataFrame de BigQuery, con el nombre que proporcione en la definición de la función personalizada. Para ver y gestionar las conexiones, sigue estos pasos:

  1. En la Google Cloud consola, ve a la página BigQuery.

    Ir a BigQuery

  2. Selecciona el proyecto en el que has creado la función remota.

  3. En el panel Explorador, despliega el proyecto y, a continuación, Conexiones externas.

Las funciones remotas de BigQuery se crean en el conjunto de datos que especifiques o en un conjunto de datos anónimo, que es un tipo de conjunto de datos oculto. Si no asignas un nombre a una función remota durante su creación, BigQuery DataFrames le asignará un nombre predeterminado que empieza por el prefijo bigframes. Para ver y gestionar las funciones remotas creadas en un conjunto de datos especificado por el usuario, siga estos pasos:

  1. En la Google Cloud consola, ve a la página BigQuery.

    Ir a BigQuery

  2. Selecciona el proyecto en el que has creado la función remota.

  3. En el panel Explorador, expande el proyecto, el conjunto de datos en el que has creado la función remota y, a continuación, Rutinas.

Para ver y gestionar funciones de Cloud Run, haz lo siguiente:

  1. Ve a la página Cloud Run.

    Ir a Cloud Run

  2. Selecciona el proyecto en el que has creado la función.

  3. Filtra por Tipo de implementación de función en la lista de servicios disponibles.

  4. Para identificar las funciones creadas por BigQuery DataFrames, busca nombres de funciones con el prefijo bigframes.

Limpieza

Además de eliminar los artefactos de la nube directamente en la Google Cloud consola o con otras herramientas, puedes eliminar las funciones remotas de BigQuery que se hayan creado sin un argumento de nombre explícito y sus funciones de Cloud Run asociadas de las siguientes formas:

  • Para una sesión de BigQuery DataFrames, usa el comando session.close().
  • Para la sesión predeterminada de BigQuery DataFrames, usa el comando bigframes.pandas.close_session().
  • Para una sesión anterior con session_id, usa el comando bigframes.pandas.clean_up_by_session_id(session_id).

También puedes eliminar las funciones remotas de BigQuery que se hayan creado con un argumento de nombre explícito y sus funciones de Cloud Run asociadas mediante el comando bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

Requisitos

Para usar las funciones remotas de los DataFrames de BigQuery, debes habilitar las siguientes APIs:

Limitaciones

  • Las funciones remotas tardan unos 90 segundos en estar disponibles cuando las creas por primera vez. Las dependencias de paquetes adicionales pueden aumentar la latencia.
  • Si vuelves a ejecutar el código de definición de la función remota después de hacer cambios triviales en el código de la función o en su entorno (por ejemplo, cambiar el nombre de una variable, insertar una línea nueva o insertar una celda nueva en el cuaderno), es posible que se vuelva a crear la función remota, aunque estos cambios no tengan consecuencias en el comportamiento de la función.
  • El código de usuario es visible para los usuarios con acceso de lectura en las funciones de Cloud Run, por lo que solo debes incluir contenido sensible con precaución.
  • Un proyecto puede tener hasta 1000 funciones de Cloud Run a la vez en una región. Para obtener más información, consulta Cuotas.

Aprendizaje automático e IA

En las siguientes secciones se describen las funciones de aprendizaje automático e IA de los DataFrames de BigQuery. Estas funciones usan la biblioteca bigframes.ml.

Ubicaciones de aprendizaje automático

La biblioteca bigframes.ml admite las mismas ubicaciones que BigQuery ML. Las predicciones de modelos de BigQuery ML y otras funciones de aprendizaje automático se admiten en todas las regiones de BigQuery. La asistencia para el entrenamiento de modelos varía según la región. Para obtener más información, consulta las ubicaciones de BigQuery ML.

Preprocesar datos

Crea transformadores para preparar los datos que se van a usar en los estimadores (modelos) mediante el módulo bigframes.ml.preprocessing y el módulo bigframes.ml.compose. BigQuery DataFrames ofrece las siguientes transformaciones:

  • Usa la clase KBinsDiscretizer del módulo bigframes.ml.preprocessing para agrupar datos continuos en intervalos.

  • Usa la clase LabelEncoder del módulo bigframes.ml.preprocessing para normalizar las etiquetas de destino como valores enteros.

  • Usa la clase MaxAbsScaler del módulo bigframes.ml.preprocessing para escalar cada característica al intervalo [-1, 1] por su valor absoluto máximo.

  • Usa la clase MinMaxScaler del módulo bigframes.ml.preprocessing para estandarizar las funciones. Para ello, escala cada función al intervalo [0, 1].

  • Usa la clase StandardScaler del módulo bigframes.ml.preprocessing para estandarizar las características quitando la media y escalando a la varianza de unidad.

  • Usa la clase OneHotEncoder del módulo bigframes.ml.preprocessing para transformar valores categóricos en formato numérico.

  • Usa la clase ColumnTransformer del módulo bigframes.ml.compose para aplicar transformadores a las columnas de DataFrames.

Entrenar modelos

Puedes crear estimadores para entrenar modelos en BigQuery DataFrames.

Modelos de clústeres

Puedes crear estimadores para modelos de clustering con el módulo bigframes.ml.cluster.

  • Usa la clase KMeans para crear modelos de clústeres de k-medias. Usa estos modelos para segmentar datos. Por ejemplo, identificar segmentos de clientes. K-means es una técnica de aprendizaje no supervisado, por lo que el entrenamiento del modelo no requiere etiquetas ni datos divididos para el entrenamiento o la evaluación.

Puedes usar el módulo bigframes.ml.cluster para crear estimadores de modelos de clustering.

En el siguiente ejemplo de código se muestra cómo usar la clase bigframes.ml.cluster KMeans para crear un modelo de clústeres de k-medias para la segmentación de datos:

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)

Modelos de descomposición

Puedes crear estimadores para modelos de descomposición usando el módulo bigframes.ml.decomposition.

  • Usa la clase PCA para crear modelos de análisis de componentes principales (ACP). Usa estos modelos para calcular los componentes principales y usarlos para realizar un cambio de base en los datos. De esta forma, se reduce la dimensionalidad proyectando cada punto de datos en los primeros componentes principales para obtener datos de menor dimensión y, al mismo tiempo, conservar la mayor parte posible de la variación de los datos.

Modelos de conjunto

Puedes crear estimadores para modelos de conjunto mediante el módulo bigframes.ml.ensemble.

  • Usa la clase RandomForestClassifier para crear modelos de clasificador de bosque aleatorio. Usa estos modelos para crear varios árboles de decisión de métodos de aprendizaje para la clasificación.

  • Usa la clase RandomForestRegressor para crear modelos de regresión de bosque aleatorio. Usa estos modelos para crear varios árboles de decisión de métodos de aprendizaje para la regresión.

  • Usa la clase XGBClassifier para crear modelos de clasificador de árbol de gradiente reforzado. Usa estos modelos para construir de forma aditiva varios árboles de decisión de métodos de aprendizaje para la clasificación.

  • Usa la clase XGBRegressor para crear modelos de regresión de árbol de gradiente reforzado. Usa estos modelos para construir de forma aditiva varios árboles de decisión de métodos de aprendizaje para la regresión.

Modelos de previsión

Puedes crear estimadores para modelos de previsión con el módulo bigframes.ml.forecasting.

  • Usa la clase ARIMAPlus para crear modelos de previsión de series temporales.

Modelos importados

Puedes crear estimadores para modelos importados usando el módulo bigframes.ml.imported.

Modelos lineales

Crea estimadores para modelos lineales con el módulo bigframes.ml.linear_model.

  • Usa la clase LinearRegression para crear modelos de regresión lineal. Usa estos modelos para hacer previsiones. Por ejemplo, predecir las ventas de un artículo en un día concreto.

  • Usa la clase LogisticRegression para crear modelos de regresión logística. Usa estos modelos para clasificar dos o más valores posibles, como si una entrada es low-value, medium-value o high-value.

En el siguiente código de ejemplo se muestra cómo usar bigframes.ml para hacer lo siguiente:

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)

Modelos de lenguaje extensos

Puedes crear estimadores para LLMs usando el módulo bigframes.ml.llm.

Usa la clase GeminiTextGenerator para crear modelos de generador de texto de Gemini. Usa estos modelos para tareas de generación de texto.

Usa el módulo bigframes.ml.llm para crear estimadores de modelos de lenguaje extensos (LLMs) remotos.
En el siguiente ejemplo de código se muestra cómo usar la clase bigframes.ml.llm GeminiTextGenerator para crear un modelo de Gemini para la generación de código:

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)

Modelos remotos

Para usar modelos remotos de BigQuery DataFrames ML (bigframes.ml.remote o bigframes.ml.llm), debes habilitar las siguientes APIs:

Al crear un modelo remoto en BigQuery DataFrames, se crea una conexión de BigQuery. De forma predeterminada, se usa una conexión con el nombre bigframes-default-connection. Si lo prefieres, puedes usar una conexión de BigQuery preconfigurada. En ese caso, se omitirá la creación de la conexión. La cuenta de servicio de la conexión predeterminada tiene asignado el rol Usuario de Vertex AI (roles/aiplatform.user) en el proyecto.

Crear flujos de procesamiento

Puedes crear flujos de procesamiento de aprendizaje automático con el módulo bigframes.ml.pipeline. Las canalizaciones te permiten combinar varios pasos de aprendizaje automático para validarlos conjuntamente y, al mismo tiempo, definir diferentes parámetros. De esta forma, el código se simplifica y puedes implementar los pasos de preprocesamiento de datos y un estimador juntos.

Usa la clase Pipeline para crear un flujo de procesamiento de transformaciones con un estimador final.

Seleccionar modelos

Usa el módulo bigframes.ml.model_selection para dividir tus conjuntos de datos de entrenamiento y de prueba, y seleccionar los mejores modelos:

  • Usa la función train_test_split para dividir los datos en conjuntos de entrenamiento y de prueba (evaluación), como se muestra en el siguiente ejemplo de código:

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

  • Usa la clase KFold y el método KFold.split para crear conjuntos de entrenamiento y de pruebas de varios pliegues con los que entrenar y evaluar modelos, tal como se muestra en el siguiente ejemplo de código. Esta función es muy útil para conjuntos de datos pequeños.

    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

  • Usa la función cross_validate para crear automáticamente conjuntos de entrenamiento y de prueba de varios pliegues, entrenar y evaluar el modelo, y obtener el resultado de cada pliegue, tal como se muestra en el siguiente ejemplo de código:

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

Siguientes pasos