Utilizza BigQuery DataFrames

BigQuery DataFrames fornisce un'API DataFrame e un'API di machine learning (ML) Pythonic basata sul motore BigQuery. BigQuery DataFrames è un pacchetto open source. Puoi eseguire pip install --upgrade bigframes per installare la versione più recente.

BigQuery DataFrames fornisce due librerie:

  • bigframes.pandas, che fornisce un'API compatibile con pandas per l'analisi.

  • bigframes.ml, che fornisce un'API simile a scikit-learn per il machine learning (ML).

Autorizzazioni obbligatorie

Opzioni

Dopo l'installazione, devi specificare la posizione e il progetto in cui vuoi utilizzare BigQuery DataFrames. Puoi definire la posizione e il progetto nel blocco note nel seguente modo: 
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

Se bf.options.bigquery.project non è impostato, viene utilizzata la variabile di ambiente $GOOGLE_CLOUD_PROJECT, impostata nel runtime del blocco note che gestisce i blocchi note di BigQuery Studio e Vertex AI.

Località di elaborazione dei dati

BigQuery DataFrames è progettato per la scalabilità, che mantiene i dati e l'elaborazione sul servizio BigQuery. Tuttavia, puoi inserire i dati nella memoria del tuo computer client chiamando .to_pandas() su un oggetto DataFrame o Series. Se scegli di farlo, verrà applicato il limite di memoria del tuo computer client.

Località sessione

BigQuery DataFrames utilizza un oggetto sessione locale per gestire internamente i metadati. Questa sessione è legata a una località. BigQuery DataFrames utilizza US (più regioni) come località predefinita, ma puoi utilizzare session_options.location per impostare una località diversa. Ogni query di una sessione viene eseguita nella località in cui è stata creata la sessione. BigQuery DataFrames compila automaticamente bf.options.bigquery.location con la posizione della tabella se l'utente inizia con read_gbq/read_gbq_table/read_gbq_query() e specifica una tabella, direttamente o in un'istruzione SQL.

Se vuoi reimpostare la posizione degli oggetti DataFrame o Series creati, puoi chiudere la sessione eseguendo bigframes.pandas.close_session(). Dopodiché, puoi riutilizzare bigframes.pandas.options.bigquery.location per specificare un'altra posizione.

read_gbq() richiede di specificare una località se il set di dati su cui stai eseguendo query non si trova nella località multiregionale US. Se provi a leggere una tabella da un'altra posizione, ricevi un'eccezione NotFound.

Tipi di dati

BigQuery DataFrames supporta i seguenti dtype numpy e pandas:

BigQuery DataFrame e panda di BigQuery
BOOL pandas.BooleanDtype()
DATE pandas.ArrowDtype(pa.date32())
DATETIME pandas.ArrowDtype(pa.timestamp("us"))
FLOAT64 pandas.Float64Dtype()
GEOGRAPHY

geopandas.array.GeometryDtype()

Supportata da 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 non supporta i seguenti tipi di dati BigQuery:

  • ARRAY

  • NUMERIC

  • BIGNUMERIC

  • INTERVAL

  • RANGE

  • JSON

Tutti gli altri tipi di dati BigQuery vengono visualizzati come tipo di oggetto.

Utilizzo della libreria bigframes.pandas

La libreria bigframes.pandas fornisce un'API simile a pandas che puoi utilizzare per analizzare e manipolare i dati in BigQuery. L'API bigframes.pandas è scalabile per supportare l'elaborazione di terabyte di dati BigQuery e utilizza il motore di query BigQuery per eseguire i calcoli.
L'API bigframes.pandas fornisce le seguenti funzionalità:

Input e output

Puoi accedere ai dati da una serie di origini, tra cui file CSV locali, file Cloud Storage, DataFrame pandas, modelli BigQuery e funzioni BigQuery, quindi caricarli in un DataFrame DataFrames di BigQuery. Puoi anche creare tabelle BigQuery da BigQuery DataFrames.

Manipolazione dei dati

Per lo sviluppo puoi utilizzare Python anziché SQL. Puoi sviluppare tutte le manipolazioni dei dati BigQuery in Python, eliminando la necessità di passare da un linguaggio all'altro e provare ad acquisire le istruzioni SQL come stringhe di testo. L'API bigframes.pandas offre oltre 750 funzioni pandas.

Ecosistema e visualizzazioni Python

L'API bigframes.pandas è un gateway all'intero ecosistema di strumenti Python. L'API supporta operazioni statistiche avanzate e puoi visualizzare le aggregazioni generate da BigQuery DataFrames. Puoi anche passare da un DataFrame DataFrames BigQuery a un DataFrame pandas con operazioni di campionamento integrate.

Funzioni Python personalizzate

BigQuery DataFrames offre la possibilità di trasformare le funzioni scalari personalizzate in funzioni remote di BigQuery . La creazione di una funzione remota in BigQuery DataFrames crea:

  1. Una funzione Cloud Functions (2a generazione).

  2. Una connessione BigQuery. Per impostazione predefinita, viene utilizzata una connessione denominata bigframes-default-connection. Se preferisci, puoi utilizzare una connessione BigQuery preconfigurata, nel qual caso la creazione della connessione viene saltata.

    All'account di servizio per la connessione predefinita viene concesso il ruolo IAM Invoker di Cloud Run (roles/run.invoker).

  3. Una funzione remota BigQuery che utilizza la funzione Cloud Functions (1) mediante la connessione BigQuery (2).

Per un esempio, vedi Creare una funzione remota.

Le connessioni BigQuery vengono create nella stessa posizione della sessione BigQuery DataFrames, utilizzando il nome fornito nella definizione della funzione personalizzata. Per visualizzare e gestire le connessioni, segui questi passaggi:

  1. Vai a BigQuery nella console Google Cloud.

  2. Seleziona il progetto in cui hai creato la funzione remota.

  3. Nel riquadro Explorer, espandi il progetto ed espandi Connessioni esterne.

Le funzioni remote di BigQuery vengono create nel set di dati specificato o in un tipo speciale di set di dati nascosto indicato nel codice come set di dati anonimo. Per visualizzare e gestire le funzioni remote create in un set di dati fornito dall'utente:

  1. Vai a BigQuery nella console Google Cloud.

  2. Seleziona il progetto in cui hai creato la funzione remota.

  3. Nel riquadro Explorer, espandi il progetto, espandi il set di dati in cui hai creato la funzione remota, quindi espandi le routine.

Per visualizzare e gestire le funzioni di Cloud Functions, usa la pagina Funzioni e usa il selettore di progetti per selezionare il progetto in cui hai creato la funzione. Per una facile identificazione, i nomi delle funzioni create da BigQuery DataFrames sono preceduti da bigframes.

Requisiti

Per utilizzare le funzioni remote di BigQuery DataFrames, devi abilitare le seguenti API:

Per utilizzare le funzioni remote di BigQuery DataFrames, devi disporre dei seguenti ruoli IAM nel progetto:

  • Editor dati BigQuery (roles/bigquery.dataEditor)

  • Amministratore connessione BigQuery (roles/bigquery.connectionAdmin)

  • Sviluppatore Cloud Functions (roles/cloudfunctions.developer)

  • Utente account di servizio (roles/iam.serviceAccountUser)

  • Visualizzatore oggetti Storage (roles/storage.objectViewer)

  • Amministratore IAM progetto (roles/resourcemanager.projectIamAdmin) se utilizzi una connessione BigQuery predefinita o Browser (ruoli/browser) se utilizzi una connessione preconfigurata. Questo requisito può essere evitato impostando l'opzione bigframes.pandas.options.bigquery.skip_bq_connection_check su True, nel qual caso la connessione (predefinita o preconfigurata) verrà utilizzata così com'è, senza alcun controllo dell'esistenza o delle autorizzazioni. Se utilizzi la connessione preconfigurata e salti il controllo della connessione, assicurati che la connessione sia stata creata nella località corretta e che l'account di servizio disponga del ruolo Invoker di Cloud Run (roles/run.invoker) per il progetto.

Limitazioni

  • Sono necessari circa 90 secondi prima che le funzioni remote diventino disponibili quando le crei per la prima volta.

  • Modifiche banali nel blocco note, ad esempio l'inserimento di una nuova cella o la ridenominazione di una variabile, potrebbero causare la nuova creazione della funzione remota, anche se queste modifiche non sono correlate al codice della funzione remota.

  • BigQuery DataFrames non distingue i dati personali che includi nel codice della funzione remota. Il codice della funzione remota è serializzato come una casella opaca per eseguirne il deployment come funzione Cloud Functions.

  • Le funzioni di Cloud Functions (2nd gen), le connessioni BigQuery e le funzioni remote BigQuery create da DataFrames BigQuery rimangono in Google Cloud. Se non vuoi conservare queste risorse, devi eliminarle separatamente utilizzando un'interfaccia Cloud Functions o BigQuery appropriata.

  • Un progetto può includere fino a 1000 funzioni di Cloud Functions (2nd gen) alla volta. Consulta le quote di Cloud Functions per tutti i limiti.

bigframes.pandas esempi

I seguenti esempi mostrano i modi più comuni di utilizzo di bigframes.pandas.

Carica i dati da una tabella o query BigQuery

Puoi creare un DataFrame da una tabella o query BigQuery nel seguente modo:

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

Carica i dati da un file CSV

Puoi creare un DataFrame da un file CSV locale o di Cloud Storage nel seguente modo:

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

Ispeziona e manipola i dati

Puoi utilizzare bigframes.pandas per eseguire operazioni di ispezione e calcolo dei dati.
Il seguente esempio di codice mostra l'uso di bigframes.pandas per controllare la colonna body_mass_g, calcolare la media body_mass e calcolare la media body_mass mediante 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)
)

Utilizzo della libreria bigframes.ml

Le funzionalità ML in BigQuery DataFrames consentono di pre-elaborare i dati e, quindi, di addestrare i modelli su questi dati. Puoi anche concatenare queste azioni per creare pipeline di dati.

Località ML

bigframes.ml supporta le stesse località di BigQuery ML. La previsione del modello BigQuery ML e altre funzioni ML sono supportate in tutte le regioni BigQuery. Il supporto per l'addestramento del modello varia a seconda della regione. Per saperne di più, consulta Località di BigQuery ML.

Pre-elabora dati

Crea trasformatori per preparare i dati da utilizzare negli strumenti di stima (modelli) utilizzando il modulo bigframes.ml.preprocessing e il modulo bigframes.ml.compose. BigQuery DataFrames offre le seguenti trasformazioni:

  • Utilizza la classe KBinsDiscretizer nel modulo bigframes.ml.preprocessing per associare i dati continui in intervalli.

  • Utilizza la classeLabelEncoder nel modulo bigframes.ml.preprocessing per normalizzare le etichette di destinazione come valori interi.

  • Utilizza la classe MaxAbsScaler nel modulo bigframes.ml.preprocessing per scalare ciascuna caratteristica nell'intervallo [-1, 1] in base al valore assoluto massimo.

  • Utilizza la classe MinMaxScaler nel modulo bigframes.ml.preprocessing per standardizzare le caratteristiche scalando ogni caratteristica nell'intervallo [0, 1].

  • Utilizza la classe StandardScaler nel modulo bigframes.ml.preprocessing per standardizzare le caratteristiche rimuovendo la media e scalando alla varianza delle unità.

  • Utilizza la classe OneHotEncoder nel modulo bigframes.ml.preprocessing per trasformare i valori categorici in formato numerico.

  • Utilizza la classe columnTransformer nel modulo bigframes.ml.compose per applicare i modelli di trasformazione alle colonne DataFrames.

addestramento dei modelli

Crea stimatori per addestrare modelli in BigQuery DataFrames.

Modelli di clustering

Crea stimatori per i modelli di clustering utilizzando il modulo bigframes.ml.cluster.

  • Utilizza la classe KMeans per creare modelli di clustering K-means. Utilizza questi modelli per la segmentazione dei dati. Ad esempio, identificare i segmenti di clienti. K-means è una tecnica di apprendimento non supervisionato, quindi l'addestramento di un modello non richiede etichette o dati suddivisi per l'addestramento o la valutazione.

Puoi usare il modulo bigframes.ml.cluster per creare stimatori per i modelli di clustering.

Il seguente esempio di codice mostra l'uso della classe bigframes.ml.cluster KMeans per creare un modello di clustering K-means per la segmentazione dei dati:

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)

Scomposizione modelli

Crea stimatori per la scomposizione dei modelli utilizzando il modulo bigframes.ml.decomposition.

  • Utilizza la classe PCA per creare modelli di analisi delle componenti principali (PCA). Utilizza questi modelli per calcolare i componenti principali e utilizzarli per eseguire una modifica di base sui dati. Ciò consente di ridurre la dimensionalità proiettando ciascun punto dati solo sui primi componenti principali per ottenere dati di dimensioni inferiori, preservando al contempo il maggior numero possibile di variazioni dei dati.

Modelli di insieme

Crea stime per i modelli insieme utilizzando il modulo bigframes.ml.ensemble.

  • Utilizza la classe RandomForestClassifier per creare modelli di classificazione casuali delle foreste. Usa questi modelli per creare strutture decisionali di più metodi di apprendimento per la classificazione.

  • Utilizza la classe RandomForestRegressor per creare modelli di regressione casuale delle foreste. Usa questi modelli per creare alberi decisionali di più metodi di apprendimento per la regressione.

  • Utilizza la classe XGBClassifier per creare modelli di classificazione degli alberi con gradiente di potenziamento. Usa questi modelli per creare in aggiunta più alberi decisionali dei metodi di apprendimento per la classificazione.

  • Utilizza la classe XGBRegressor per creare modelli di regressione con albero aumentato con gradiente. Questi modelli possono essere usati per costruire più alberi decisionali dei metodi di apprendimento per la regressione.

Modelli di previsione

Crea stimatori per i modelli di previsione utilizzando il modulo bigframes.ml.forecasting.

  • Utilizza la classe ARIMAPlus per creare modelli di previsione di serie temporali.

Modelli importati

Crea stimatori per i modelli importati utilizzando il modulo bigframes.ml.imported.

Modelli lineari

Creare stimatori per modelli lineari utilizzando il modulo bigframes.ml.linear_model.

  • Utilizza la classe di regressione lineare per creare modelli di regressione lineare. Utilizza questi modelli per le previsioni. Ad esempio, la previsione delle vendite di un articolo in un determinato giorno.

  • Utilizza la classe LogisticRegression per creare modelli di regressione logistica. Utilizza questi modelli per la classificazione di due o più valori possibili, ad esempio se un input è low-value, medium-value o high-value.

Il seguente esempio di codice mostra l'uso di bigframes.ml per:

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)

Modelli linguistici di grandi dimensioni

Crea stimatori per gli LLM utilizzando il modulo bigframes.ml.llm.

  • Utilizza la classe GeminiTextGenerator per creare modelli del generatore di testo Gemini. Usa questi modelli per le attività di generazione di testo.

  • Utilizza la classe PaLM2TextGenerator per creare modelli del generatore di testo PaLM2. Usa questi modelli per le attività di generazione di testo.

  • Utilizza la classe PaLM2TextEmbeddingGenerator per creare modelli del generatore di rappresentazioni distribuite di testo PaLM2. Utilizza questi modelli per le attività di generazione di incorporamenti del testo.

Puoi utilizzare il modulo bigframes.ml.llm per creare stimatori per i modelli linguistici di grandi dimensioni (LLM) remoti.
Il seguente esempio di codice mostra l'uso della classe bigframes.ml.llm GeminiTextGenerator per creare un modello Gemini per la generazione del codice:

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)

Modelli remoti

Per utilizzare i modelli remoti di BigQuery DataFrames ML (bigframes.ml.remote o bigframes.ml.llm), devi abilitare le API seguenti:

Devi inoltre disporre dei seguenti ruoli IAM nel progetto:

  • Amministratore connessione BigQuery (roles/bigquery.connectionAdmin)
  • Amministratore IAM progetto (roles/resourcemanager.projectIamAdmin) se utilizzi una connessione BigQuery predefinita oppure Browser (ruoli/browser) se utilizzi una connessione preconfigurata. Questo requisito può essere evitato impostando l'opzione bigframes.pandas.options.bigquery.skip_bq_connection_check su True, nel qual caso la connessione (predefinita o preconfigurata) verrà utilizzata così com'è, senza alcun controllo dell'esistenza o delle autorizzazioni. Se utilizzi la connessione preconfigurata e salti il controllo della connessione, assicurati che la connessione sia stata creata nella posizione corretta e che l'account di servizio abbia il ruolo Utente Vertex AI (roles/aiplatform.user) per il progetto.

La creazione di un modello remoto in DataFrames di BigQuery crea una connessione BigQuery. Per impostazione predefinita, viene utilizzata una connessione denominata bigframes-default-connection. Se preferisci, puoi utilizzare una connessione BigQuery preconfigurata, nel qual caso la creazione della connessione viene saltata. All'account di servizio per la connessione predefinita viene concesso il ruolo IAM Utente Vertex AI (roles/aiplatform.user).

Creazione di pipeline

Creare pipeline ML utilizzando bigframes.ml.pipeline module. Le pipeline ti consentono di assemblare diversi passaggi di ML da sottoporre a convalida incrociata, impostando parametri diversi. Ciò semplifica il codice e ti consente di eseguire il deployment dei passaggi di pre-elaborazione dei dati e di uno strumento di stima.

Utilizza la classe pipeline per creare una pipeline di trasformazioni con uno stimatore finale.

Passaggi successivi