Esegui la migrazione alla versione 2.0 di BigQuery DataFrames

La versione 2.0 di BigQuery DataFrames apporta miglioramenti alla sicurezza e alle prestazioni all'API BigQuery DataFrames, aggiunge nuove funzionalità e introduce modifiche che provocano un errore. Questo documento descrive le modifiche e fornisce indicazioni per la migrazione. Puoi applicare questi suggerimenti 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 viene impostato su False per impostazione predefinita. Questo design può ridurre i costi di archiviazione, soprattutto se utilizzi la fatturazione per byte fisici.
  • Sicurezza migliorata 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 provocano un errore, fissa 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 vuoi provare l'ultima versione, puoi eseguire pip install --upgrade bigframes per installare l'ultima versione di BigQuery DataFrames.

Utilizza l'opzione allow_large_results

BigQuery ha un limite massimo per le dimensioni della risposta 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 provocano un errore. 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)

Utilizza il decoratore @remote_function

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

Gli argomenti delle parole chiave vengono applicati per i parametri ambigui

Per evitare di passare valori a un parametro non previsto, BigQuery DataFrames versione 2.0 e successive impone l'utilizzo di argomenti di parole 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)

Imposta 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, segui questi passaggi:

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

Configura le impostazioni del traffico in entrata

A partire dalla versione 2.0, BigQuery DataFrames imposta le impostazioni di traffico in entrata delle funzioni Cloud Run di cui esegue il deployment su "internal-only". In precedenza, le impostazioni di traffico in entrata erano impostate su "all" per impostazione predefinita. Puoi modificare le impostazioni di traffico in entrata 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)

Utilizza endpoint personalizzati

Nelle versioni di BigQuery DataFrames precedenti alla 2.0, se una regione non supportava gli endpoint di servizio regionali e bigframes.pandas.options.bigquery.use_regional_endpoints = True, BigQuery DataFrames utilizzava gli endpoint di località. La versione 2.0 di BigQuery DataFrames rimuove questo comportamento di riserva. Per connetterti agli endpoint di località 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.

Utilizza il modulo bigframes.ml.llm

Ti consigliamo di fornire direttamente un model_name supportato (ad esempio "gemini-3.5-flash") per evitare interruzioni se il modello predefinito cambia in futuro.

import bigframes.ml.llm

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

Passaggi successivi