Usa BigQuery DataFrames

BigQuery DataFrames proporciona un DataFrame de Python y una API de aprendizaje automático (AA) con la tecnología del 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 dos bibliotecas:

  • bigframes.pandas, que proporcina una API compatible con Pandas para estadísticas.

  • bigframes.ml, que proporciona una API similar a scikit-learn para el aprendizaje automático (AA).

Permisos necesarios

Opciones

Después de la instalación, debes especificarubicación yproyecto en la que desea usar BigQuery DataFrames. Puedes definir la ubicación y el proyecto en tu notebook de la siguiente manera: 
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

Si bf.options.bigquery.project no está configurado, se usa la variable de entorno $GOOGLE_CLOUD_PROJECT, que se configura en el entorno de ejecución del notebook que entrega los notebooks de BigQuery Studio y Vertex AI.

Ubicación del procesamiento de datos

BigQuery DataFrames está diseñado para el escalamiento, lo que lo logra a través de la conservación de los datos y el procesamiento en el servicio de BigQuery. Sin embargo, puedes incorporar datos a la memoria de tu máquina cliente si llamas a .to_pandas() en un objeto de DataFrame o de serie. Si eliges hacerlo, se aplica la limitación de memoria de la máquina cliente.

Ubicación de la sesión

BigQuery DataFrames usa un objeto de sesión local para administrar metadatos de forma interna. Esta sesión está vinculada a una ubicación. BigQuery DataFrames usa la multirregional US como la ubicación predeterminada, pero puedes usar session_options.location para establecer una ubicación diferente. Cada consulta en una sesión se ejecuta en la ubicación en la que se creó la sesión. BigQuery DataFrames propaga automáticamente bf.options.bigquery.location con la ubicación de la tabla si el usuario comienza con read_gbq/read_gbq_table/read_gbq_query() y especifica una tabla, ya sea directamente o en una instrucción de SQL.

Si deseas restablecer la ubicación de los objetos DataFrame o de serie creados, puedes cerrar la sesión mediante la ejecución de bigframes.pandas.close_session(). Después de eso, puedes volver a usar bigframes.pandas.options.bigquery.location para especificar otra ubicación.

read_gbq() requiere que especifiques una ubicación si el conjunto de datos que consultas no está en la multirregional US. Si intentas leer una tabla desde otra ubicación, obtendrás una excepción NotFound.

Tipos de datos

BigQuery DataFrames es compatible con los siguientes dtypes de NumPy y Pandas:

BigQuery BigQuery DataFrames y 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()

Admitida por 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 no es compatible con los siguientes tipos de datos de BigQuery:

  • NUMERIC

  • BIGNUMERIC

  • INTERVAL

  • RANGE

  • JSON

Todos los demás tipos de datos de BigQuery se muestran como el tipo de objeto.

Uso de la biblioteca bigframes.pandas

La biblioteca bigframes.pandas proporciona una API similar a pandas que puedes usar para analizar y manipular datos en BigQuery. La API de bigframes.pandas es escalable para admitir el procesamiento de terabytes de datos de BigQuery y usa el motor de consulta de BigQuery para realizar cálculos.
La API de bigframes.pandas proporciona las siguientes funciones:

INPUT y OUTPUT

Puedes acceder a los datos de una variedad de fuentes, incluidos los archivos CSV locales, los archivos de Cloud Storage, los DataFrames pandas, los modelos de BigQuery y las funciones de BigQuery, y cargarlos en un DataFrame de BigQuery. También puedes crear tablas de BigQuery DataFrames de BigQuery.

Manipulación de datos

Puedes usar Python en lugar de SQL para tu desarrollo. Puedes desarrollar todas las manipulaciones de datos de BigQuery en Python, lo que elimina la necesidad de cambiar entre lenguajes y de capturar instrucciones de SQL como cadenas de texto. La API bigframes.pandas ofrece más de 750 funciones pandas.

Ecosistema y visualizaciones de Python

La API de bigframes.pandas es una puerta de enlace al ecosistema completo de herramientas de Python. La API es compatible con operaciones estadísticas avanzadas, y puedes visualizar las agregaciones generadas a partir de BigQuery DataFrames. También puedes cambiar de un DataFrame de BigQuery DataFrames a un DataFrame pandas con operaciones de muestreo integradas.

Funciones personalizadas de Python

BigQuery DataFrames te permite convertir tus funciones escalares personalizadas en funciones remotas de BigQuery. Cuando se crea una función remota en BigQuery DataFrames, se crea lo siguiente:

  1. Una función de Cloud Run (2nd gen)

  2. 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 cuyo caso se omite la creación de la conexión.

    A la cuenta de servicio para la conexión predeterminada se le otorga el rol de IAM de invocador de Cloud Run (roles/run.invoker).

  3. Una función remota de BigQuery que usa la función de Cloud Functions (1) con la conexión de BigQuery (2).

Para ver un ejemplo, consulta Crea una función remota.

Las conexiones de BigQuery se crean en la misma ubicación que la sesión de BigQuery DataFrames, con el nombre que proporcionas en la definición de la función personalizada. Para ver y administrar conexiones, haz lo siguiente:

  1. Ve a BigQuery en la consola de Google Cloud.

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

  3. En el panel Explorador, expande ese proyecto y, luego, Conexiones externas.

Las funciones remotas de BigQuery se crean en el conjunto de datos que especificas, o en un conjunto de datos anónimo, un tipo de conjunto de datos oculto. Si no estableces un nombre para una función remota durante su creación, BigQuery DataFrames aplica un nombre predeterminado que comienza con el prefijo bigframes. Para ver y administrar funciones remotas creadas en un conjunto de datos especificado por el usuario, haz lo siguiente:

  1. Ve a BigQuery en la consola de Google Cloud.

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

  3. En el panel Explorador, expande ese proyecto, expande el conjunto de datos en el que creaste la función remota y, luego, expande Rutinas.

Para ver y administrar las funciones de Cloud Run, usa la página Funciones y usa el selector de proyectos para seleccionar el proyecto en el que creaste la función. Para una identificación fácil, los nombres de las funciones creadas por BigQuery DataFrames tienen el prefijo bigframes.

Puedes limpiar las funciones remotas de BigQuery sin nombre y sus funciones asociadas de Cloud Run de las siguientes maneras:

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

Requisitos

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

Para usar las funciones remotas de BigQuery DataFrames, debes tener los siguientes roles de IAM en el proyecto:

  • Editor de datos de BigQuery (roles/bigquery.dataEditor)

  • Administrador de conexión de BigQuery (roles/bigquery.connectionAdmin)

  • Desarrollador de Cloud Functions (roles/cloudfunctions.developer)

  • Usuario de la cuenta de servicio (roles/iam.serviceAccountUser)

  • Visualizador de objetos de Storage (roles/storage.objectViewer)

  • Administrador de IAM del proyecto (roles/resourcemanager.projectIamAdmin) si usas la conexión de BigQuery predeterminada o navegador (roles/navegador) si usas una conexión preconfigurada. Este requisito se puede evitar si se configura la opción bigframes.pandas.options.bigquery.skip_bq_connection_check en True, en cuyo caso la conexión (predeterminada o preconfigurada) se usará tal como está sin ninguna existencia o permiso. Si usas la conexión preconfigurada y omites la verificación de conexión, asegúrate de que la conexión se cree en la ubicación correcta y que su cuenta de servicio tenga el rol de invocador de Cloud Run (roles/run.invoker) en el proyecto.

Limitaciones

  • Las funciones remotas tardan unos 90 segundos en estar disponibles cuando las creas por primera vez.

  • Los cambios simples en el notebook, como insertar una celda nueva o cambiar el nombre de una variable, pueden provocar que se vuelva a crear la función remota, incluso si estos cambios no están relacionados con el código de la función remota.

  • BigQuery DataFrames no diferencia ningún dato personal que incluyas en el código de función remota. El código de la función remota se serializa como un cuadro opaco para implementarlo como una función de Cloud Run.

  • Las funciones de Cloud Run (2nd gen), las conexiones de BigQuery y las funciones remotas de BigQuery creadas por BigQuery DataFrames persisten en Google Cloud. Si no deseas conservar estos recursos, debes borrarlos por separado mediante una interfaz de funciones de Cloud Run o BigQuery adecuada.

  • Un proyecto puede tener hasta 1,000 funciones de Cloud Run (2nd gen) a la vez. Consulta las cuotas de funciones de Cloud Run para conocer todos los límites.

Ejemplos de bigframes.pandas

En los siguientes ejemplos, se muestran formas comunes de usar bigframes.pandas.

Carga datos desde una tabla o consulta de BigQuery

Puedes crear un DataFrame a partir de una consulta o tabla de BigQuery de la siguiente manera:

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

Carga datos desde un archivo CSV

Puedes crear un DataFrame desde un archivo CSV local o de Cloud Storage de la siguiente manera:

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

Inspecciona y manipula datos

Puedes usar bigframes.pandas para realizar operaciones de inspección y cálculo de datos.
En el siguiente ejemplo de código, se muestra bigframes.pandas para inspeccionar la columna body_mass_g, calcula la media body_mass y calcula 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)
)

Uso de la biblioteca bigframes.ml

Las funciones del AA en BigQuery DataFrames te permiten procesar previamente los datos y, luego, entrenar modelos en esos datos. También puedes encadenar estas acciones para crear canalizaciones de datos.

Ubicaciones de AA

bigframes.ml admite las mismas ubicaciones que BigQuery ML. La predicción de modelos de BigQuery ML y otras funciones del AA son compatibles con todas las regiones de BigQuery. La compatibilidad de la capacitación de modelos varía según la región. Para obtener más información, consulta Ubicaciones de BigQuery ML.

Preprocesar datos

Crear transformadores para preparar datos para usar en 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 en el módulo bigframes.ml.preprocessing para agrupar datos continuos en intervalos.

  • Usa la clase LabelEncoder en el módulo bigframes.ml.preprocessing para normalizar las etiquetas de destino como valores de números enteros.

  • Usa la clase MaxAbsScaler en el módulo bigframes.ml.preprocessing para escalar cada atributo al rango [-1, 1] según su valor absoluto máximo.

  • Usa la clase MinMaxScaler en el módulo bigframes.ml.preprocessing para estandarizar atributos mediante el escalamiento de cada atributo al rango [0, 1].

  • Usa la clase StandardScaler en el módulo bigframes.ml.preprocessing para estandarizar atributos mediante la eliminación de la media y la varianza de unidades.

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

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

Entrenar modelos

Crear estimadores para entrenar modelos en BigQuery DataFrames.

Agrupa modelos en clústeres

Crea estimadores para los modelos de agrupamiento en clústeres mediante el módulo bigframes.ml.cluster.

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

Puedes usar el módulo bigframes.ml.cluster para crear estimadores para los modelos de agrupamiento en clústeres.

En la siguiente muestra de código, se usa la clase bigframes.ml.cluster KMeans para crear un modelo de agrupamiento en clústeres de k-means 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

Crea estimadores para los modelos de descomposición mediante el módulo bigframes.ml.decomposition.

  • Usa la clase PCA para crear modelos de análisis de componentes principales (PCA). Usa estos modelos para calcular los componentes principales y usarlos a fin de realizar un cambio de base en los datos. Esto proporciona una reducción de la dimensionalidad mediante la proyección de cada dato a los primeros componentes principales para obtener datos de menor dimensión y, al mismo tiempo, conservar la mayor variación posible de los datos.

Ensamblar modelos

Crea estimadores para modelos de ensamble con el módulo bigframes.ml.ensemble.

  • Usa la clase RandomForestClassifier para crear modelos clasificadores de bosque aleatorios. Usa estos modelos a fin de construir 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 aleatorios. Usa estos modelos para construir varios árboles de decisión de métodos de aprendizaje para la regresión.

  • Usa la clase XGBClassifier para crear modelos clasificadores de árbol mejorado con gradiente. 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 mejorado con gradiente. 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

Crea estimadores para los modelos de previsión mediante el módulo bigframes.ml.forecasting.

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

Modelos importados

Crea estimadores para modelos importados mediante el módulo bigframes.ml.imported.

Modelos lineales

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

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

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

En la siguiente muestra de código, se usa 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 grandes

Crea estimadores para LLM con 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 la clase PaLM2TextGenerator para crear modelos de generador de texto de PaLM2. Usa estos modelos para tareas de generación de texto.

  • Usa la clase PaLM 2TextEmbeddingGenerator para crear modelos de generador de incorporaciones de texto de PaLM2. Usa estos modelos para las tareas de generación de embedding de texto.

Puedes usar el módulo bigframes.ml.llm para crear estimadores para modelos remotos de lenguaje grande (LLM).
En la siguiente muestra de código, se usa 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)

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 los modelos remotos de BigQuery DataFrames (bigframes.ml.remote o bigframes.ml.llm), debes habilitar las siguientes APIs:

También debes tener los siguientes roles de IAM en el proyecto:

  • Administrador de conexión de BigQuery (roles/bigquery.connectionAdmin)
  • Administrador de IAM del proyecto (roles/resourcemanager.projectIamAdmin) si usas la conexión de BigQuery predeterminada o navegador (roles/navegador) si usas una conexión preconfigurada. Este requisito se puede evitar si se configura la opción bigframes.pandas.options.bigquery.skip_bq_connection_check en True, en cuyo caso la conexión (predeterminada o preconfigurada) se usará tal como está sin ninguna existencia o permiso. Si usas la conexión preconfigurada y omites la verificación de conexión, asegúrate de que la conexión se cree en la ubicación correcta y que su cuenta de servicio tenga el rol de usuario de Vertex AI (roles/aiplatform.user) en el proyecto.

Cuando se crea 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 cuyo caso se omite la creación de la conexión. A la cuenta de servicio para la conexión predeterminada se le otorga el rol de IAM de usuario de Vertex AI (roles/aiplatform.user).

Crear canalizaciones

Crear canalizaciones de AA con el módulo bigframes.ml.pipeline. Las canalizaciones te permiten ensamblar varios pasos del AA para realizar una validación cruzada mientras se configuran diferentes parámetros. Esto simplifica tu código y te permite implementar pasos de procesamiento previo de datos y un estimador juntos.

Usar la clase de canalización para crear una canalización de transformaciones con un estimador final.

¿Qué sigue?