Utilizza BigQuery DataFrames

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

BigQuery DataFrames fornisce tre librerie:

  • bigframes.pandas fornisce un'API pandas che puoi utilizzare per analizzare e manipolare i dati in BigQuery. È possibile eseguire la migrazione di molti carichi di lavoro da pandas a bigframes modificando solo alcuni import. 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.
  • bigframes.bigquery fornisce molte funzioni SQL BigQuery che potrebbero non avere un equivalente pandas.
  • bigframes.ml fornisce un'API simile all'API scikit-learn per il machine learning. Le funzionalità di ML in BigQuery DataFrames ti consentono di preelaborare i dati e poi addestrare i modelli su questi dati. Puoi anche concatenare queste azioni per creare pipeline di dati.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per completare le attività descritte in questo documento, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Inoltre, quando utilizzi le funzioni remote di BigQuery DataFrames o i modelli remoti BigQuery DataFrames ML, devi disporre del ruolo Amministratore IAM progetto (roles/resourcemanager.projectIamAdmin) se utilizzi una connessione BigQuery predefinita o del ruolo Browser (roles/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) viene utilizzata così com'è senza alcun controllo di esistenza o autorizzazione. Se utilizzi la connessione preconfigurata e salti il controllo della connessione, verifica quanto segue:

  • La connessione viene creata nella posizione corretta.
  • Se utilizzi le funzioni remote di BigQuery DataFrames, il service account ha il ruolo Invoker Cloud Run (roles/run.invoker) nel progetto.
  • Se utilizzi modelli remoti BigQuery DataFrames ML, il service account ha il ruolo Utente Vertex AI (roles/aiplatform.user) nel progetto.

Quando esegui l'autenticazione dell'utente finale in un ambiente interattivo come un notebook, Python REPL o la riga di comando, BigQuery DataFrames richiede l'autenticazione, se necessario. In caso contrario, consulta la sezione Come configurare le credenziali predefinite dell'applicazione per vari ambienti.

Configura le opzioni di installazione

Dopo aver installato BigQuery DataFrames, puoi specificare le seguenti opzioni.

Posizione e progetto

Devi specificare la posizione e il progetto in cui vuoi utilizzare BigQuery DataFrames.

Puoi definire la posizione e il progetto nel notebook nel seguente modo:

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

Posizione di trattamento dei dati

BigQuery DataFrames è progettato per la scalabilità, che raggiunge mantenendo i dati e l'elaborazione sul servizio BigQuery. Tuttavia, puoi importare i dati nella memoria della macchina client chiamando .to_pandas() su un oggetto DataFrame o Series. Se scegli di farlo, si applica la limitazione di memoria della macchina client.

Località sessione

BigQuery DataFrames utilizza internamente un oggetto sessione locale per gestire i metadati. Questa sessione è associata a una posizione. BigQuery DataFrames utilizza la multiregione US come località predefinita, ma puoi utilizzare session_options.location per impostare una località diversa. Ogni query in 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 una query non si trova nella regione multiregionale US. Se provi a leggere una tabella da un'altra posizione, ricevi un'eccezione NotFound.

Eseguire la migrazione a BigQuery DataFrames versione 2.0

La versione 2.0 di BigQuery DataFrames introduce miglioramenti alla sicurezza e alle prestazioni dell'API BigQuery DataFrames, aggiunge nuove funzionalità e introduce modifiche che causano interruzioni. Questo documento descrive le modifiche e fornisce indicazioni per la migrazione. Puoi applicare questi consigli prima di installare la versione 2.0 utilizzando l'ultima versione 1.x di BigQuery DataFrames.

La versione 2.0 di BigQuery DataFrames offre i seguenti vantaggi:

  • Quando esegui query che restituiscono risultati al client, vengono create query più veloci e meno tabelle, perché allow_large_results è impostato su False per impostazione predefinita. Ciò può ridurre i costi di archiviazione, soprattutto se utilizzi la fatturazione in base ai byte fisici.
  • Maggiore sicurezza per impostazione predefinita nelle funzioni remote di cui è stato eseguito il deployment da BigQuery DataFrames.

Installa BigQuery DataFrames versione 2.0

Per evitare modifiche che causano interruzioni, blocca una versione specifica di BigQuery DataFrames nel file requirements.txt (ad esempio, bigframes==1.42.0) o nel file pyproject.toml (ad esempio, dependencies = ["bigframes = 1.42.0"]). Quando è tutto pronto per provare l'ultima versione, puoi eseguire pip install --upgrade bigframes per installare l'ultima versione di BigQuery DataFrames.

Utilizzare l'opzione allow_large_results

BigQuery ha un limite massimo per le dimensioni delle risposte per i job di query. A partire dalla versione 2.0 di BigQuery DataFrames, BigQuery DataFrames applica questo limite per impostazione predefinita nei metodi che restituiscono risultati al client, come peek(), to_pandas() e to_pandas_batches(). Se il job restituisce risultati di grandi dimensioni, puoi impostare allow_large_results su True nell'oggetto BigQueryOptions per evitare modifiche che causano interruzioni. Questa opzione è impostata su False per impostazione predefinita in BigQuery DataFrames versione 2.0.

import bigframes.pandas as bpd

bpd.options.bigquery.allow_large_results = True

Puoi ignorare l'opzione allow_large_results utilizzando il parametro allow_large_results in to_pandas() e altri metodi. Ad esempio:

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

Utilizzare il decoratore @remote_function

BigQuery DataFrames versione 2.0 apporta alcune modifiche al comportamento predefinito del decoratore @remote_function.

Gli argomenti delle parole chiave vengono applicati ai parametri ambigui

Per evitare di passare valori a un parametro non previsto, BigQuery DataFrames versione 2.0 e successive impone l'utilizzo di argomenti parola chiave per i seguenti parametri:

  • 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

Quando utilizzi questi parametri, fornisci il nome del parametro. Ad esempio:

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

Impostare un account di servizio

A partire dalla versione 2.0, BigQuery DataFrames non utilizza più l'account di servizio Compute Engine per impostazione predefinita per le funzioni Cloud Run di cui esegue il deployment. Per limitare le autorizzazioni della funzione di cui esegui il deployment:

  1. Crea un service account con autorizzazioni minime.
  2. Fornisci l'indirizzo email del account di servizio al parametro cloud_function_service_account del decoratore @remote_function.

Ad esempio:

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

Se vuoi utilizzare il account di servizio Compute Engine, puoi impostare il parametro cloud_function_service_account del decoratore @remote_function su "default". Ad esempio:

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

Configurare le impostazioni traffico in entrata

A partire dalla versione 2.0, BigQuery DataFrames imposta le impostazioni di ingresso delle funzioni Cloud Run che esegue il deployment su "internal-only". In precedenza, le impostazioni di ingresso erano impostate su "all" per impostazione predefinita. Puoi modificare le impostazioni di ingresso impostando il parametro cloud_function_ingress_settings del decoratore @remote_function. Ad esempio:

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

Utilizzare endpoint personalizzati

Nelle versioni di BigQuery DataFrames precedenti alla 2.0, se una regione non supportava endpoint di servizio regionali e bigframes.pandas.options.bigquery.use_regional_endpoints = True, BigQuery DataFrames tornava agli endpoint basati sulla località. La versione 2.0 di BigQuery DataFrames rimuove questo comportamento di fallback. Per connetterti agli endpoint basati sulla posizione nella versione 2.0, imposta l'opzione bigframes.pandas.options.bigquery.client_endpoints_override. Ad esempio:

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

Sostituisci LOCATION con il nome della località BigQuery a cui vuoi connetterti.

Utilizzare il modulo bigframes.ml.llm

Nella versione 2.0 di BigQuery DataFrames, il valore predefinito di model_name per GeminiTextGenerator è stato aggiornato a "gemini-2.0-flash-001". Ti consigliamo di fornire un model_name direttamente per evitare interruzioni se il modello predefinito cambia in futuro.

import bigframes.ml.llm

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

Input e output

Utilizzando la libreria bigframes.pandas, puoi accedere ai dati di varie fonti, tra cui file CSV locali, file Cloud Storage, DataFrame pandas, modelli BigQuery e funzioni BigQuery. Puoi caricare questi dati in un DataFrame BigQuery DataFrames. Puoi anche creare tabelle BigQuery da BigQuery DataFrames.

Caricare i dati da una tabella o query BigQuery

Puoi creare un DataFrame da una tabella o una 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)

Caricare i dati da un file CSV

Puoi creare un DataFrame da un file CSV locale o 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()

Tipi di dati

BigQuery DataFrames supporta i seguenti tipi di dati numpy e pandas:

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

Supportata solo da to_pandas()
INT64 pandas.Int64Dtype()
JSON pandas.ArrowDtype(pa.json_(pa.string()) nella versione di pandas 3.0 o successive e nella versione di pyarrow 19.0 o successive, altrimenti le colonne JSON vengono esposte come pandas.ArrowDtype(db_dtypes.JSONArrowType()).
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:

  • NUMERIC

  • BIGNUMERIC

  • INTERVAL

  • RANGE

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

Manipolazione dei dati

Le seguenti sezioni descrivono le funzionalità di manipolazione dei dati per BigQuery DataFrames. Puoi trovare le funzioni descritte nella libreria bigframes.bigquery.

pandas API

Una caratteristica notevole di BigQuery DataFrames è che l'API bigframes.pandas è progettata per essere simile alle API della libreria pandas. Questo design ti consente di utilizzare pattern di sintassi familiari per le attività di manipolazione dei dati. Le operazioni definite tramite l'API BigQuery DataFrames vengono eseguite lato server, operando direttamente sui dati archiviati in BigQuery ed eliminando la necessità di trasferire i set di dati al di fuori di BigQuery.

Per verificare quali API pandas sono supportate da BigQuery DataFrames, consulta la sezione API pandas supportate.

Ispezionare e manipolare i dati

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

Libreria BigQuery

La libreria BigQuery fornisce funzioni SQL di BigQuery che potrebbero non avere un equivalente in pandas. Le sezioni seguenti presentano alcuni esempi.

Elaborare i valori dell'array

Puoi utilizzare la funzione bigframes.bigquery.array_agg() nella libreria bigframes.bigquery per aggregare i valori dopo un'operazione 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]

Puoi anche utilizzare le funzioni di array array_length() e array_to_string().

Creare una serie strutturata

Puoi utilizzare la funzione bigframes.bigquery.struct() nella libreria bigframes.bigquery per creare una nuova serie di struct con sottocampi per ogni colonna di 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]

Convertire i timestamp in epoca Unix

Puoi utilizzare la funzione bigframes.bigquery.unix_micros() nella libreria bigframes.bigquery per convertire i timestamp in microsecondi 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

Puoi anche utilizzare le funzioni temporali unix_seconds() e unix_millis().

Utilizzare la funzione scalare SQL

Puoi utilizzare la funzione bigframes.bigquery.sql_scalar() nella libreria bigframes.bigquery per accedere a una sintassi SQL arbitraria che rappresenta un'espressione di una singola colonna:

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

Funzioni Python personalizzate

BigQuery DataFrames ti consente di trasformare le tue funzioni Python personalizzate in artefatti BigQuery che puoi eseguire su oggetti BigQuery DataFrames su larga scala. Questo supporto dell'estensibilità ti consente di eseguire operazioni che vanno oltre quelle possibili con le API BigQuery DataFrames e SQL, in modo da poter sfruttare potenzialmente le librerie open source. Le due varianti di questo meccanismo di estensibilità sono descritte nelle sezioni seguenti.

Funzioni definite dall'utente

Con le funzioni definite dall'utente (anteprima), puoi trasformare la tua funzione Python personalizzata in una funzione definita dall'utente Python. Per un esempio di utilizzo, vedi Crea una UDF Python persistente.

La creazione di una funzione definita dall'utente in BigQuery DataFrames crea una routine BigQuery come funzione definita dall'utente Python nel set di dati specificato. Per un insieme completo di parametri supportati, consulta udf.

Esegui la pulizia

Oltre a ripulire gli artefatti cloud direttamente nella console Google Cloud o con altri strumenti, puoi ripulire le UDF BigQuery DataFrames create con un argomento nome esplicito utilizzando il comando bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

Requisiti

Per utilizzare una UDF BigQuery DataFrames, abilita l'API BigQuery nel tuo progetto. Se fornisci il parametro bigquery_connection nel tuo progetto, devi anche abilitare l'API BigQuery Connection.

Limitazioni

  • Il codice nella UDF deve essere autonomo, ovvero non deve contenere riferimenti a un'importazione o a una variabile definita al di fuori del corpo della funzione.
  • Il codice nella UDF deve essere compatibile con Python 3.11, poiché questo è l'ambiente in cui il codice viene eseguito nel cloud.
  • La riesecuzione del codice di definizione della UDF dopo modifiche banali nel codice della funzione, ad esempio la ridenominazione di una variabile o l'inserimento di una nuova riga, comporta la ricreazione della UDF, anche se queste modifiche sono irrilevanti per il comportamento della funzione.
  • Il codice utente è visibile agli utenti con accesso in lettura alle routine BigQuery, pertanto devi includere contenuti sensibili solo con cautela.
  • Un progetto può avere fino a 1000 funzioni Cloud Run contemporaneamente in una posizione BigQuery.

La UDF BigQuery DataFrames esegue il deployment di una funzione Python BigQuery definita dall'utente e si applicano le limitazioni correlate.

Funzioni remote

BigQuery DataFrames consente di trasformare le funzioni scalari personalizzate in funzioni remote BigQuery. Per un esempio di utilizzo, vedi Crea una funzione remota. Per un insieme completo di parametri supportati, vedi remote_function.

La creazione di una funzione remota in BigQuery DataFrames crea quanto segue:

  • Una funzione Cloud Run.
  • 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 ignorata. Al account di servizio per la connessione predefinita viene concesso il ruolo Cloud Run (roles/run.invoker).
  • Una funzione remota BigQuery che utilizza la funzione Cloud Run creata con la connessione BigQuery.

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:

  1. Nella console Google Cloud , vai alla pagina BigQuery.

    Vai a BigQuery

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

  3. Nel riquadro Explorer, espandi il progetto e poi Connessioni esterne.

Le funzioni remote BigQuery vengono create nel set di dati specificato oppure in un set di dati anonimo, che è un tipo di set di dati nascosto. Se non imposti un nome per una funzione remota durante la creazione, BigQuery DataFrames applica un nome predefinito che inizia con il prefisso bigframes. Per visualizzare e gestire le funzioni remote create in un set di dati specificato dall'utente:

  1. Nella console Google Cloud , vai alla pagina BigQuery.

    Vai a BigQuery

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

  3. Nel riquadro Explorer, espandi il progetto, il set di dati in cui hai creato la funzione remota e poi Routine.

Per visualizzare e gestire le funzioni Cloud Run:

  1. Vai alla pagina Cloud Run.

    Vai a Cloud Run

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

  3. Filtra in base a Tipo di deployment della funzione nell'elenco dei servizi disponibili.

  4. Per identificare le funzioni create da BigQuery DataFrames, cerca i nomi delle funzioni con il prefisso bigframes.

Esegui la pulizia

Oltre a ripulire gli artefatti cloud direttamente nella Google Cloud console o con altri strumenti, puoi ripulire le funzioni remote BigQuery create senza un argomento nome esplicito e le relative funzioni Cloud Run nei seguenti modi:

  • Per una sessione BigQuery DataFrames, utilizza il comando session.close().
  • Per la sessione predefinita di BigQuery DataFrames, utilizza il comando bigframes.pandas.close_session().
  • Per una sessione precedente con session_id, utilizza il comando bigframes.pandas.clean_up_by_session_id(session_id).

Puoi anche eliminare le funzioni remote BigQuery create con un argomento nome esplicito e le relative funzioni Cloud Run utilizzando il comando bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

Requisiti

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

Limitazioni

  • Le funzioni remote impiegano circa 90 secondi per diventare utilizzabili dopo la creazione. Dipendenze aggiuntive del pacchetto potrebbero aumentare la latenza.
  • Se esegui di nuovo il codice di definizione della funzione remota dopo modifiche banali nel codice della funzione e intorno a questo, ad esempio rinominando una variabile, inserendo una nuova riga o inserendo una nuova cella nel blocco note, la funzione remota potrebbe essere ricreata, anche se queste modifiche sono irrilevanti per il comportamento della funzione.
  • Il codice utente è visibile agli utenti con accesso in lettura alle funzioni Cloud Run, pertanto devi includere contenuti sensibili solo con cautela.
  • Un progetto può avere fino a 1000 funzioni Cloud Run contemporaneamente in una regione. Per ulteriori informazioni, consulta Quote.

ML e AI

Le seguenti sezioni descrivono le funzionalità di ML e AI per BigQuery DataFrames. Queste funzionalità utilizzano la libreria bigframes.ml.

Località ML

La libreria 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 in base alla regione. Per ulteriori informazioni, vedi Località BigQuery ML.

Pre-elaborare i dati

Crea trasformatori per preparare i dati da utilizzare negli stimatori (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 raggruppare i dati continui in intervalli.

  • Utilizza la classe LabelEncoder 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 ogni funzionalità nell'intervallo [-1, 1] in base al suo valore assoluto massimo.

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

  • Utilizza la classe StandardScaler nel modulo bigframes.ml.preprocessing per standardizzare le funzionalità rimuovendo la media e scalando la varianza unitaria.

  • 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 trasformatori alle colonne DataFrame.

addestramento dei modelli

Puoi creare stimatori per addestrare i modelli in BigQuery DataFrames.

Modelli di clustering

Puoi creare 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, l'identificazione dei segmenti di clienti. K-means è una tecnica di apprendimento non supervisionato, quindi l'addestramento del modello non richiede etichette o la suddivisione dei dati per l'addestramento o la valutazione.

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

Il seguente esempio di codice mostra l'utilizzo 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)

Modelli di scomposizione

Puoi creare stimatori per i modelli di scomposizione utilizzando il modulo bigframes.ml.decomposition.

  • Utilizza la classe PCA per creare modelli di analisi delle componenti principali (PCA). Utilizza questi modelli per calcolare le componenti principali e utilizzarli per eseguire un cambio di base sui dati. In questo modo si ottiene una riduzione della dimensionalità proiettando ogni punto dati solo sui primi componenti principali per ottenere dati a dimensioni inferiori, preservando il più possibile la variazione dei dati.

Modelli di insieme

Puoi creare stimatori per i modelli di insieme utilizzando il modulo bigframes.ml.ensemble.

  • Utilizza la classe RandomForestClassifier per creare modelli di classificatori di foreste casuali. Utilizza questi modelli per costruire più alberi decisionali per i metodi di apprendimento per la classificazione.

  • Utilizza la classe RandomForestRegressor per creare modelli di regressione foresta casuale. Utilizza questi modelli per costruire più alberi decisionali del metodo di apprendimento per la regressione.

  • Utilizza la classe XGBClassifier per creare modelli di classificatori ad albero potenziati dal gradiente. Utilizza questi modelli per costruire in modo additivo più alberi decisionali del metodo di apprendimento per la classificazione.

  • Utilizza la classe XGBRegressor per creare modelli di regressione basati su Gradient Boosted Decision Tree. Utilizza questi modelli per costruire in modo additivo più alberi decisionali del metodo di apprendimento per la regressione.

Modelli di previsione

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

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

Modelli importati

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

Modelli lineari

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

  • Utilizza la classe LinearRegression per creare modelli di regressione lineare. Utilizza questi modelli per le previsioni. Ad esempio, prevedere le 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'utilizzo di bigframes.ml per eseguire le seguenti operazioni:

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

Puoi creare stimatori per i modelli LLM utilizzando il modulo bigframes.ml.llm.

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

Utilizza il modulo bigframes.ml.llm per creare stimatori per modelli linguistici di grandi dimensioni (LLM) remoti.
Il seguente esempio di codice mostra l'utilizzo della classe bigframes.ml.llm GeminiTextGenerator per creare un modello Gemini per la generazione di 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, 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)

Modelli remoti

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

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

Crea pipeline

Puoi creare pipeline ML utilizzando il modulo bigframes.ml.pipeline. Le pipeline ti consentono di assemblare diversi passaggi ML da convalidare in modo incrociato insieme impostando parametri diversi. In questo modo il codice viene semplificato e puoi eseguire il deployment dei passaggi di pre-elaborazione dei dati e di uno strumento di stima insieme.

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

Seleziona modelli

Utilizza il modulo bigframes.ml.model_selection per dividere i set di dati di addestramento e test e selezionare i modelli migliori:

  • Utilizza la funzione train_test_split per suddividere i dati in set di addestramento e test (valutazione), come mostrato nel seguente esempio di codice:

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

  • Utilizza la classe KFold e il metodo KFold.split per creare set di addestramento e test multi-fold per addestrare e valutare i modelli, come mostrato nel seguente esempio di codice. Questa funzionalità è utile per i piccoli set di dati.

    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

  • Utilizza la funzione cross_validate per creare automaticamente set di addestramento e test multi-fold, addestrare e valutare il modello e ottenere il risultato di ogni fold, come mostrato nel seguente esempio di codice:

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

Ottimizzazione delle prestazioni

Questa sezione presenta alcuni modi per ottimizzare le prestazioni di BigQuery DataFrames.

Modalità di ordinamento parziale

BigQuery DataFrames fornisce una funzionalità di modalità di ordinamento. Imposta la proprietà ordering_mode su partial per generare query più efficienti.

La modalità di ordinamento partial è in contrasto con la modalità strict predefinita, che crea un ordinamento totale su tutte le righe. Un ordinamento totale rende BigQuery DataFrames più compatibile con pandas fornendo l'accesso basato sull'ordine alle righe con la proprietà DataFrame.iloc. Tuttavia, l'ordinamento totale e l'indice sequenziale predefinito su questo ordinamento fanno sì che né i filtri delle colonne né quelli delle righe riducano il numero di byte scansionati, a meno che questi filtri non vengano applicati come parametri alle funzioni read_gbq e read_gbq_table. Per fornire un ordinamento totale di tutte le righe del DataFrame, BigQuery DataFrames crea un hash di tutte le righe. Ciò può comportare una scansione completa dei dati che ignora i filtri di righe e colonne.

Se imposti la proprietà ordering_mode su partial, BigQuery DataFrames non genera un ordinamento totale di tutte le righe. La modalità di ordinamento parziale disattiva anche le funzionalità che richiedono un ordinamento totale di tutte le righe, come la proprietà DataFrame.iloc. La modalità di ordinamento parziale imposta la classe DefaultIndexKind su un indice nullo, anziché su un indice sequenziale rispetto all'ordinamento.

Quando filtri un DataFrame con la proprietà ordering_mode impostata su partial, BigQuery DataFrames non deve più calcolare quali righe mancano nell'indice sequenziale, quindi genera query più rapide ed efficienti. L'API BigQuery DataFrames è ancora la familiare API pandas, proprio come l'esperienza predefinita con la modalità di ordinamento rigoroso. Tuttavia, la modalità di ordinamento parziale differirà dal comportamento comune di pandas. Ad esempio, la modalità di ordinamento parziale non esegue join impliciti per indice.

Con le modalità di ordinamento parziale e rigoroso, paghi le risorse BigQuery che utilizzi. Tuttavia, l'utilizzo della modalità di ordinamento parziale può ridurre i costi quando si lavora con tabelle in cluster di grandi dimensioni e tabelle partizionate, perché i filtri delle righe sulle colonne del cluster e della partizione riducono il numero di byte elaborati.

Utilizzo

Per utilizzare l'ordinamento parziale, imposta la proprietà ordering_mode su partial prima di eseguire qualsiasi altra operazione con BigQuery DataFrames, come mostrato nel seguente esempio di codice:

import bigframes.pandas as bpd

bpd.options.bigquery.ordering_mode = "partial"

Poiché non esiste un indice sequenziale con la modalità di ordinamento parziale, i DataFrame BigQuery non correlati non vengono uniti implicitamente. Devi invece chiamare esplicitamente il metodo DataFrame.merge per unire due BigQuery DataFrames derivati da espressioni di tabelle diverse.

Le funzionalità Series.unique() e Series.drop_duplicates() non sono compatibili con la modalità di ordinamento parziale. Utilizza invece il metodo groupby per trovare valori univoci in questo modo:

# Avoid order dependency by using groupby instead of drop_duplicates.
unique_col = df.groupby(["column"], as_index=False).size().drop(columns="size")

Con la modalità di ordinamento parziale, l'output delle funzioni DataFrame.head(n) e Series.head(n) non è idempotente in tutte le invocazioni. Per scaricare un piccolo campione arbitrario dei dati, utilizza i metodi DataFrame.peek() o Series.peek().

Per un tutorial dettagliato in cui utilizzi la proprietà ordering_mode = "partial", consulta questo blocco note BigQuery DataFrames che mostra l'utilizzo della modalità di ordinamento parziale.

Risoluzione dei problemi

Poiché i DataFrame in modalità di ordinamento parziale non hanno sempre un ordinamento o un indice, potresti riscontrare i seguenti problemi quando utilizzi alcuni metodi compatibili con pandas.

Errore Ordine richiesto

Alcune funzionalità richiedono un ordinamento, ad esempio le funzioni DataFrame.head() e DataFrame.iloc. Per un elenco delle funzionalità che richiedono l'ordinamento, consulta la colonna Richiede ordinamento in API pandas supportate.

Quando non è presente alcun ordinamento nell'oggetto, l'operazione non riesce e viene visualizzato un messaggio OrderRequiredError simile al seguente:

OrderRequiredError: Op iloc requires an ordering. Use .sort_values or .sort_index to provide an ordering.

Come descritto nel messaggio di errore, puoi fornire un ordinamento utilizzando il metodo DataFrame.sort_values() per ordinare in base a una o più colonne. Altre operazioni, come l'operazione DataFrame.groupby(), forniscono implicitamente un ordinamento totale delle chiavi di raggruppamento.

Se non è possibile determinare che l'ordinamento sia un ordinamento totale completamente stabile su tutte le righe, le operazioni successive potrebbero avvisarti con un messaggio AmbiguousWindowWarning come il seguente:

AmbiguousWindowWarning: Window ordering may be ambiguous, this can cause unstable results.

Se il tuo carico di lavoro può gestire risultati non deterministici o puoi verificare manualmente che l'ordinamento che fornisci sia un ordinamento totale, puoi filtrare il messaggio AmbiguousWindowWarning in questo modo:

import warnings

import bigframes.exceptions

warnings.simplefilter(
    "ignore", category=bigframes.exceptions.AmbiguousWindowWarning
)
Errore di indice nullo

Alcune funzionalità richiedono un indice, ad esempio le proprietà DataFrame.unstack() e Series.interpolate(). Per un elenco delle funzionalità che richiedono un indice, consulta la colonna Richiede indice in API pandas supportate.

Quando utilizzi un'operazione che richiede un indice con la modalità di ordinamento parziale, l'operazione genera un messaggio NullIndexError simile al seguente:

NullIndexError: DataFrame cannot perform interpolate as it has no index. Set an index using set_index.

Come descritto nel messaggio di errore, puoi fornire un indice utilizzando il metodo DataFrame.set_index() per ordinare in base a una o più colonne. Altre operazioni, come l'operazione DataFrame.groupby(), forniscono implicitamente un indice sulle chiavi di raggruppamento, a meno che non sia impostato il parametro as_index=False.

Passaggi successivi