Eseguire la migrazione a BigQuery DataFrames versione 2.0

La versione 2.0 di BigQuery DataFrames apporta 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.

BigQuery DataFrames versione 2.0 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. Questo design 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 eseguire l'override dell'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 service account

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, procedi nel seguente modo:

  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)

Impostare le impostazioni del traffico in entrata

A partire dalla versione 2.0, BigQuery DataFrames imposta le impostazioni di ingresso delle funzioni Cloud Run che vengono implementate 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 eseguiva il failover sugli endpoint basati sulla località. La versione 2.0 di BigQuery DataFrames rimuove questo comportamento di fallback. Per connetterti agli endpoint di localizzazione 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")

Passaggi successivi