Utiliser BigQuery DataFrames

BigQuery DataFrames fournit un DataFrame en Python et une API de machine learning (ML) basés sur le moteur BigQuery. BigQuery DataFrames est un package Open Source. Vous pouvez exécuter pip install --upgrade bigframes pour installer la dernière version.

BigQuery DataFrames fournit trois bibliothèques :

  • bigframes.pandas fournit une API pandas que vous pouvez utiliser pour analyser et manipuler des données dans BigQuery. De nombreuses charges de travail peuvent être migrées de pandas vers bigframes en modifiant simplement quelques importations. L'API bigframes.pandas est évolutive et permet de traiter des téraoctets de données BigQuery. Elle utilise le moteur de requête BigQuery pour effectuer les calculs.
  • bigframes.bigquery fournit de nombreuses fonctions SQL BigQuery qui n'ont peut-être pas d'équivalent dans pandas.
  • bigframes.ml fournit une API semblable à l'API scikit-learn pour le ML. Les fonctionnalités de ML de BigQuery DataFrames vous permettent de prétraiter les données, puis d'entraîner des modèles sur ces données. Vous pouvez également enchaîner ces actions pour créer des pipelines de données.

Rôles requis

Pour obtenir les autorisations nécessaires pour effectuer les tâches décrites dans ce document, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

De plus, lorsque vous utilisez des fonctions distantes BigQuery DataFrames ou des modèles distants BigQuery DataFrames ML, vous avez besoin du rôle Administrateur de projet IAM (roles/resourcemanager.projectIamAdmin) si vous utilisez une connexion BigQuery par défaut, ou du rôle Navigateur (roles/browser) si vous utilisez une connexion préconfigurée. Cette exigence peut être évitée en définissant l'option bigframes.pandas.options.bigquery.skip_bq_connection_check sur True. Dans ce cas, la connexion (par défaut ou préconfigurée) est utilisée telle quelle, sans aucune vérification d'existence ni d'autorisation. Si vous utilisez la connexion préconfigurée et que vous ignorez la vérification de connexion, vérifiez les points suivants :

  • La connexion est créée au bon endroit.
  • Si vous utilisez les fonctions distantes BigQuery DataFrames, le compte de service dispose du rôle d'invocateur Cloud Run (roles/run.invoker) dans le projet.
  • Si vous utilisez des modèles distants BigQuery DataFrames ML, le compte de service dispose du rôle Utilisateur Vertex AI (roles/aiplatform.user) dans le projet.

Lorsque vous effectuez l'authentification d'un utilisateur final dans un environnement interactif tel qu'un notebook, un REPL Python ou la ligne de commande, BigQuery DataFrames vous invite à procéder à une authentification si nécessaire. Sinon, consultez Configurer les identifiants par défaut de l'application pour différents environnements.

Configurer les options d'installation

Après avoir installé BigQuery DataFrames, vous pouvez spécifier les options suivantes.

Emplacement et projet

Vous devez spécifier l'emplacement et le projet dans lesquels vous souhaitez utiliser BigQuery DataFrames.

Vous pouvez définir l'emplacement et le projet dans votre notebook de la manière suivante :

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

Emplacement de traitement des données

BigQuery DataFrames est conçu pour la mise à l'échelle, ce qu'il réalise en conservant les données et le traitement sur le service BigQuery. Toutefois, vous pouvez importer des données dans la mémoire de votre machine cliente en appelant .to_pandas() sur un DataFrame ou un objet Series. Si vous choisissez de le faire, les limites de mémoire de votre machine cliente s'appliquent.

Migrer vers BigQuery DataFrames version 2.0

La version 2.0 de BigQuery DataFrames apporte des améliorations en termes de sécurité et de performances à l'API BigQuery DataFrames, ajoute de nouvelles fonctionnalités et introduit des modifications incompatibles. Ce document décrit les modifications et fournit des conseils de migration. Vous pouvez appliquer ces recommandations avant d'installer la version 2.0 en utilisant la dernière version 1.x de BigQuery DataFrames.

BigQuery DataFrames version 2.0 présente les avantages suivants :

  • Les requêtes sont plus rapides et moins de tables sont créées lorsque vous exécutez des requêtes qui renvoient des résultats au client, car allow_large_results est défini par défaut sur False. Cela peut réduire les coûts de stockage, en particulier si vous utilisez la facturation par octet physique.
  • Sécurité améliorée par défaut dans les fonctions distantes déployées par BigQuery DataFrames.

Installer BigQuery DataFrames version 2.0

Pour éviter les modifications incompatibles, épinglez une version spécifique de BigQuery DataFrames dans votre fichier requirements.txt (par exemple, bigframes==1.42.0) ou dans votre fichier pyproject.toml (par exemple, dependencies = ["bigframes = 1.42.0"]). Lorsque vous êtes prêt à essayer la dernière version, vous pouvez exécuter pip install --upgrade bigframes pour installer la dernière version de BigQuery DataFrames.

Utiliser l'option allow_large_results

BigQuery applique une limite de taille de réponse maximale pour les tâches de requête. À partir de la version 2.0 de BigQuery DataFrames, cette limite est appliquée par défaut dans les méthodes qui renvoient des résultats au client, telles que peek(), to_pandas() et to_pandas_batches(). Si votre tâche renvoie des résultats volumineux, vous pouvez définir allow_large_results sur True dans votre objet BigQueryOptions pour éviter les modifications incompatibles. Cette option est définie sur False par défaut dans BigQuery DataFrames version 2.0.

import bigframes.pandas as bpd

bpd.options.bigquery.allow_large_results = True

Vous pouvez remplacer l'option allow_large_results en utilisant le paramètre allow_large_results dans to_pandas() et d'autres méthodes. Exemple :

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

Utiliser le décorateur @remote_function

La version 2.0 de BigQuery DataFrames apporte quelques modifications au comportement par défaut du décorateur @remote_function.

Les arguments de mots clés sont appliqués pour les paramètres ambigus

Pour éviter de transmettre des valeurs à un paramètre non prévu, BigQuery DataFrames version 2.0 et ultérieures imposent l'utilisation d'arguments de mot clé pour les paramètres suivants :

  • 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

Lorsque vous utilisez ces paramètres, indiquez leur nom. Exemple :

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

Définir un compte de service

Depuis la version 2.0, BigQuery DataFrames n'utilise plus le compte de service Compute Engine par défaut pour les fonctions Cloud Run qu'il déploie. Pour limiter les autorisations de la fonction que vous déployez,

  1. Créez un compte de service avec des autorisations minimales.
  2. Fournissez l'adresse e-mail du compte de service au paramètre cloud_function_service_account du décorateur @remote_function.

Exemple :

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

Si vous souhaitez utiliser le compte de service Compute Engine, vous pouvez définir le paramètre cloud_function_service_account du décorateur @remote_function sur "default". Exemple :

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

Définir les paramètres d'entrée

À partir de la version 2.0, BigQuery DataFrames définit les paramètres d'entrée des fonctions Cloud Run qu'il déploie sur "internal-only". Auparavant, les paramètres d'entrée étaient définis sur "all" par défaut. Vous pouvez modifier les paramètres d'entrée en définissant le paramètre cloud_function_ingress_settings du décorateur @remote_function. Exemple :

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

Utiliser des points de terminaison personnalisés

Dans les versions de BigQuery DataFrames antérieures à 2.0, si une région n'acceptait pas les points de terminaison de service régionaux et bigframes.pandas.options.bigquery.use_regional_endpoints = True, BigQuery DataFrames revenait aux points de terminaison géographiques. La version 2.0 de BigQuery DataFrames supprime ce comportement de secours. Pour vous connecter aux points de terminaison de localisation dans la version 2.0, définissez l'option bigframes.pandas.options.bigquery.client_endpoints_override. Exemple :

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

Remplacez LOCATION par le nom de l'emplacement BigQuery auquel vous souhaitez vous connecter.

Utiliser le module bigframes.ml.llm

Dans la version 2.0 de BigQuery DataFrames, la model_name par défaut pour GeminiTextGenerator a été remplacée par "gemini-2.0-flash-001". Nous vous recommandons de fournir un model_name directement pour éviter les problèmes si le modèle par défaut change à l'avenir.

import bigframes.ml.llm

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

Manipulation de données

Les sections suivantes décrivent les fonctionnalités de manipulation des données pour les DataFrames BigQuery. Vous trouverez les fonctions décrites dans la bibliothèque bigframes.bigquery.

API pandas

Une fonctionnalité notable de BigQuery DataFrames est que l'API bigframes.pandas est conçue pour être semblable aux API de la bibliothèque pandas. Cette conception vous permet d'utiliser des modèles de syntaxe familiers pour les tâches de manipulation de données. Les opérations définies via l'API BigQuery DataFrames sont exécutées côté serveur, directement sur les données stockées dans BigQuery. Il n'est donc pas nécessaire de transférer les ensembles de données hors de BigQuery.

Pour vérifier quelles API pandas sont compatibles avec BigQuery DataFrames, consultez API pandas compatibles.

Inspecter et manipuler des données

Vous pouvez utiliser l'API bigframes.pandas pour effectuer des opérations d'inspection et de calcul des données. L'exemple de code suivant utilise la bibliothèque bigframes.pandas pour inspecter la colonne body_mass_g, calculer la moyenne body_mass et calculer la moyenne body_mass par 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)
)

Bibliothèque BigQuery

La bibliothèque BigQuery fournit des fonctions SQL BigQuery qui n'ont peut-être pas d'équivalent dans pandas. Les sections suivantes présentent quelques exemples.

Traiter les valeurs de tableau

Vous pouvez utiliser la fonction bigframes.bigquery.array_agg() dans la bibliothèque bigframes.bigquery pour agréger des valeurs après une opération 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]

Vous pouvez également utiliser les fonctions de tableau array_length() et array_to_string().

Créer un objet struct Series

Vous pouvez utiliser la fonction bigframes.bigquery.struct() dans la bibliothèque bigframes.bigquery pour créer un objet Series struct avec des sous-champs pour chaque colonne d'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]

Convertir des codes temporels en époques Unix

Vous pouvez utiliser la fonction bigframes.bigquery.unix_micros() dans la bibliothèque bigframes.bigquery pour convertir les codes temporels en microsecondes 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

Vous pouvez également utiliser les fonctions temporelles unix_seconds() et unix_millis().

Utiliser la fonction scalaire SQL

Vous pouvez utiliser la fonction bigframes.bigquery.sql_scalar() dans la bibliothèque bigframes.bigquery pour accéder à une syntaxe SQL arbitraire représentant une expression de colonne unique :

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

Fonctions Python personnalisées

BigQuery DataFrames vous permet de transformer vos fonctions Python personnalisées en artefacts BigQuery que vous pouvez exécuter à grande échelle sur des objets BigQuery DataFrames. Cette compatibilité avec l'extensibilité vous permet d'effectuer des opérations qui ne sont pas possibles avec les API BigQuery DataFrames et SQL. Vous pouvez ainsi potentiellement tirer parti des bibliothèques Open Source. Les deux variantes de ce mécanisme d'extensibilité sont décrites dans les sections suivantes.

Fonctions définies par l'utilisateur

Les UDF (aperçu) vous permettent de transformer votre fonction Python personnalisée en UDF Python. Pour obtenir un exemple d'utilisation, consultez Créer une UDF Python persistante.

La création d'une UDF dans BigQuery DataFrames crée une routine BigQuery en tant qu'UDF Python dans l'ensemble de données spécifié. Pour obtenir la liste complète des paramètres acceptés, consultez udf.

Effectuer un nettoyage

En plus de nettoyer les artefacts cloud directement dans la console Google Cloud ou avec d'autres outils, vous pouvez nettoyer les UDF BigQuery DataFrames qui ont été créées avec un argument de nom explicite à l'aide de la commande bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

Conditions requises

Pour utiliser une UDF BigQuery DataFrames, activez l'API BigQuery dans votre projet. Si vous fournissez le paramètre bigquery_connection dans votre projet, vous devez également activer l'API BigQuery Connection.

Limites

  • Le code de l'UDF doit être autonome, c'est-à-dire qu'il ne doit contenir aucune référence à une importation ou à une variable définie en dehors du corps de la fonction.
  • Le code de l'UDF doit être compatible avec Python 3.11, car il s'agit de l'environnement dans lequel le code est exécuté dans le cloud.
  • Si vous réexécutez le code de définition de l'UDF après avoir apporté des modifications mineures au code de la fonction (par exemple, en renommant une variable ou en insérant une nouvelle ligne), l'UDF est recréée, même si ces modifications n'ont aucune incidence sur le comportement de la fonction.
  • Le code utilisateur est visible par les utilisateurs disposant d'un accès en lecture aux routines BigQuery. Vous devez donc inclure du contenu sensible avec prudence.
  • Un projet peut contenir jusqu'à 1 000 fonctions Cloud Run à la fois dans un emplacement BigQuery.

La fonction définie par l'utilisateur BigQuery DataFrames déploie une fonction Python BigQuery définie par l'utilisateur. Les limitations associées s'appliquent.

Fonctions à distance

BigQuery DataFrames vous permet de transformer vos fonctions scalaires personnalisées en fonctions distantes BigQuery. Pour obtenir un exemple d'utilisation, consultez Créer une fonction distante. Pour obtenir la liste complète des paramètres compatibles, consultez remote_function.

La création d'une fonction distante dans BigQuery DataFrames crée les éléments suivants :

  • une fonction Cloud Run ;
  • une connexion BigQuery. Par défaut, une connexion nommée bigframes-default-connection est utilisée. Si vous le souhaitez, vous pouvez utiliser une connexion BigQuery préconfigurée. Dans ce cas, la création de la connexion est ignorée. Le compte de service de la connexion par défaut se voit attribuer le rôle Cloud Run (roles/run.invoker).
  • Fonction distante BigQuery qui utilise la fonction Cloud Run créée avec la connexion BigQuery.

Les connexions BigQuery sont créées au même emplacement que la session BigQuery DataFrames, en utilisant le nom que vous fournissez dans la définition de la fonction personnalisée. Pour afficher et gérer les connexions, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page BigQuery.

    Accéder à BigQuery

  2. Sélectionnez le projet dans lequel vous avez créé la fonction à distance.

  3. Dans le volet Explorateur, développez le projet, puis Connexions externes.

Les fonctions distantes BigQuery sont créées dans l'ensemble de données que vous spécifiez ou dans un ensemble de données anonyme, qui est un type d'ensemble de données masqué. Si vous ne définissez pas de nom pour une fonction distante lors de sa création, BigQuery DataFrames applique un nom par défaut commençant par le préfixe bigframes. Pour afficher et gérer les fonctions distantes créées dans un ensemble de données spécifié par l'utilisateur, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page BigQuery.

    Accéder à BigQuery

  2. Sélectionnez le projet dans lequel vous avez créé la fonction à distance.

  3. Dans le volet Explorateur, développez le projet, l'ensemble de données dans lequel vous avez créé la fonction distante, puis Routines.

Pour afficher et gérer les fonctions Cloud Run, procédez comme suit :

  1. Accédez à la page Cloud Run

    Accédez à Cloud Run

  2. Sélectionnez le projet dans lequel vous avez créé la fonction.

  3. Filtrez la liste des services disponibles sur le type de déploiement de fonction.

  4. Pour identifier les fonctions créées par BigQuery DataFrames, recherchez les noms de fonctions avec le préfixe bigframes.

Effectuer un nettoyage

En plus de nettoyer les artefacts cloud directement dans la console Google Cloud ou avec d'autres outils, vous pouvez nettoyer les fonctions distantes BigQuery qui ont été créées sans argument de nom explicite et leurs fonctions Cloud Run Functions associées de la manière suivante :

  • Pour une session BigQuery DataFrames, utilisez la commande session.close().
  • Pour la session BigQuery DataFrames par défaut, utilisez la commande bigframes.pandas.close_session().
  • Pour une session passée avec session_id, utilisez la commande bigframes.pandas.clean_up_by_session_id(session_id).

Vous pouvez également nettoyer les fonctions distantes BigQuery créées avec un argument de nom explicite et leurs fonctions Cloud Run associées à l'aide de la commande bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

Conditions requises

Pour utiliser les fonctions distantes BigQuery DataFrames, vous devez activer les API suivantes :

Limites

  • Les fonctions distantes sont disponibles en environ 90 secondes lorsque vous les créez. Des dépendances de package supplémentaires peuvent augmenter la latence.
  • Si vous réexécutez le code de définition de la fonction distante après des modifications mineures dans et autour du code de la fonction (par exemple, en renommant une variable, en insérant une nouvelle ligne ou en insérant une nouvelle cellule dans le notebook), la fonction distante peut être recréée, même si ces modifications n'ont aucune incidence sur le comportement de la fonction.
  • Le code utilisateur est visible par les utilisateurs disposant d'un accès en lecture aux fonctions Cloud Run. Vous devez donc n'inclure du contenu sensible qu'avec précaution.
  • Un projet peut contenir jusqu'à 1 000 fonctions Cloud Run à la fois dans une région. Pour en savoir plus, consultez la page consacrée aux quotas.

ML et IA

Les sections suivantes décrivent les fonctionnalités de ML et d'IA pour les DataFrames BigQuery. Ces fonctionnalités utilisent la bibliothèque bigframes.ml.

Emplacements de ML

La bibliothèque bigframes.ml est compatible avec les mêmes emplacements que BigQuery ML. La prédiction de modèle BigQuery ML et d'autres fonctions de ML sont acceptées dans toutes les régions BigQuery. La compatibilité de l'entraînement de modèle varie selon les régions. Pour en savoir plus, consultez la page Emplacements BigQuery ML.

Procéder au prétraitement des données

Créez des transformateurs pour préparer les données à utiliser dans des estimateurs (modèles) à l'aide des modules bigframes.ml.preprocessing et bigframes.ml.compose. BigQuery DataFrames propose les transformations suivantes :

  • Utilisez la classe KBinsDiscretizer dans le module bigframes.ml.preprocessing pour regrouper des données continues en intervalles.

  • Utilisez la classe LabelEncoder dans le module bigframes.ml.preprocessing pour normaliser les étiquettes cibles sous forme de valeurs entières.

  • Utilisez la classe MaxAbsScaler dans le module bigframes.ml.preprocessing pour adapter chaque caractéristique à la plage [-1, 1] en fonction de sa valeur absolue maximale.

  • Utilisez la classe MinMaxScaler dans le module bigframes.ml.preprocessing pour standardiser les caractéristiques en les ajustant à la plage [0, 1].

  • Utilisez la classe StandardScaler dans le module bigframes.ml.preprocessing pour standardiser les caractéristiques en supprimant la moyenne et en effectuant un scaling à la hausse de la variance unitaire.

  • Utilisez la classe OneHotEncoder dans le module bigframes.ml.preprocessing pour transformer les valeurs catégorielles en format numérique.

  • Utilisez la classe ColumnTransformer dans le module bigframes.ml.compose pour appliquer des transformateurs aux colonnes DataFrames.

Entraîner des modèles

Vous pouvez créer des estimateurs pour entraîner des modèles dans BigQuery DataFrames.

Modèles de clustering

Vous pouvez créer des estimateurs pour les modèles de clustering à l'aide du module bigframes.ml.cluster.

  • Utilisez la classe KMeans pour créer des modèles de clustering en k-moyennes. Utilisez ces modèles pour segmenter les données. Par exemple, pour identifier des segments de clientèle. Les k-moyennes étant une technique d'apprentissage non supervisée, l'entraînement ou l'évaluation du modèle ne nécessitent pas d'étiquettes ni de données fractionnées.

Vous pouvez utiliser le module bigframes.ml.cluster pour créer des estimateurs pour les modèles de clustering.

L'exemple de code suivant montre comment utiliser la classe bigframes.ml.cluster KMeans pour créer un modèle de clustering en k-moyennes pour la segmentation des données :

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)

Modèles de décomposition

Vous pouvez créer des estimateurs pour les modèles de décomposition à l'aide du module bigframes.ml.decomposition.

  • Utilisez la classe PCA pour créer des modèles d'analyse des composants principaux (ACP). Utilisez ces modèles pour calculer les composants principaux et les utiliser pour effectuer un changement de base sur les données. Cela permet de réduire la dimensionnalité en ne projetant chaque point de données que sur les premiers composants principaux afin d'obtenir des données de dimension inférieure tout en conservant autant que possible les variations de données.

Modèles ensemblistes

Vous pouvez créer des estimateurs pour les modèles d'ensemble à l'aide du module bigframes.ml.ensemble.

  • Utilisez la classe RandomForestClassifier pour créer des modèles de classificateur de forêt d'arbres décisionnels. Utilisez ces modèles pour créer plusieurs arbres de décision de méthode d'apprentissage pour la classification.

  • Utilisez la classe RandomForestRegressor pour créer des modèles de régression de forêt d'arbres décisionnels. Utilisez ces modèles pour créer plusieurs arbres de décision de méthode d'apprentissage pour la régression.

  • Utilisez la classe XGBClassifier pour créer des modèles de classificateur d'arbre de décision à boosting de gradient. Utilisez ces modèles pour créer de manière additive plusieurs arbres de décision de méthode d'apprentissage pour la classification.

  • Utilisez la classe XGBRegressor pour créer des modèles de régression d'arbre de décision à boosting de gradient. Utilisez ces modèles pour créer de manière additive plusieurs arbres de décision de méthode d'apprentissage pour la régression.

Modèles de prévision

Vous pouvez créer des estimateurs pour les modèles de prévision à l'aide du module bigframes.ml.forecasting.

  • Utilisez la classe ARIMAPlus pour créer des modèles de prévision de séries temporelles.

Modèles importés

Vous pouvez créer des estimateurs pour les modèles importés à l'aide du module bigframes.ml.imported.

Modèles linéaires

Créez des estimateurs pour les modèles linéaires à l'aide du module bigframes.ml.linear_model.

  • Utilisez la classe LinearRegression pour créer des modèles de régression linéaire. Utilisez ces modèles pour les prévisions. Par exemple, pour prévoir les ventes d'un article un jour donné.

  • Utilisez la classe LogisticRegression pour créer des modèles de régression logistique. Utilisez ces modèles pour classer au moins deux valeurs possibles (par exemple, si une entrée est low-value, medium-value ou high-value).

L'exemple de code suivant montre comment utiliser bigframes.ml pour effectuer les opérations suivantes :

  • Charger des données à partir de BigQuery
  • Nettoyer et préparer les données d'entraînement
  • Créer et appliquer un modèle de régression bigframes.ml.LinearRegression
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)

Grands modèles de langage

Vous pouvez créer des estimateurs pour les LLM à l'aide du module bigframes.ml.llm.

Utilisez la classe GeminiTextGenerator pour créer des modèles génératifs de texte Gemini. Utilisez ces modèles pour les tâches de génération de texte.

Utilisez le module bigframes.ml.llm pour créer des estimateurs pour les grands modèles de langage (LLM) distants.
L'exemple de code suivant montre comment utiliser la classe GeminiTextGenerator bigframes.ml.llm pour créer un modèle Gemini pour la génération de code :

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)

Modèles distants

Pour utiliser des modèles distants de DataFrame BigQuery ML (bigframes.ml.remote ou bigframes.ml.llm), vous devez activer les API suivantes :

La création d'un modèle distant dans BigQuery DataFrames crée une connexion BigQuery. Par défaut, une connexion nommée bigframes-default-connection est utilisée. Si vous préférez, vous pouvez utiliser une connexion BigQuery préconfigurée. Dans ce cas, la création de la connexion est ignorée. Le compte de service pour la connexion par défaut se voit attribuer le rôle Utilisateur Vertex AI (roles/aiplatform.user) sur le projet.

Créer des pipelines

Vous pouvez créer des pipelines de ML à l'aide du module bigframes.ml.pipeline. Les pipelines vous permettent de combiner plusieurs étapes de ML pour qu'elles puissent faire l'objet d'une validation croisée tout en définissant différents paramètres. Cela simplifie votre code et vous permet de déployer ensemble les étapes de prétraitement des données et un estimateur.

Utilisez la classe Pipeline pour créer un pipeline de transformations avec un estimateur final.

Sélectionner des modèles

Utilisez le module bigframes.ml.model_selection pour diviser vos ensembles de données d'entraînement et de test, et sélectionner les meilleurs modèles :

  • Utilisez la fonction train_test_split pour répartir les données entre les ensembles d'entraînement et de test (évaluation), comme indiqué dans l'exemple de code suivant :

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

  • Utilisez la classe KFold et la méthode KFold.split pour créer des ensembles d'entraînement et de test à plusieurs plis afin d'entraîner et d'évaluer les modèles, comme indiqué dans l'exemple de code suivant. Cette fonctionnalité est utile pour les petits ensembles de données.

    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

  • Utilisez la fonction cross_validate pour créer automatiquement des ensembles d'entraînement et de test multicouches, entraîner et évaluer le modèle, et obtenir le résultat de chaque pli, comme indiqué dans l'exemple de code suivant :

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

Optimisation des performances

Cette section présente différentes façons d'optimiser les performances de vos DataFrames BigQuery.

Mode de tri partiel

BigQuery DataFrames fournit une fonctionnalité de mode de tri. Définissez la propriété ordering_mode sur partial pour générer des requêtes plus efficaces.

Le mode de tri partial est différent du mode strict par défaut, qui crée un tri total sur toutes les lignes. Un tri total rend les BigQuery DataFrames plus compatible avec pandas en fournissant un accès basé sur le tri aux lignes avec la propriété DataFrame.iloc. Toutefois, le tri total et l'index séquentiel par défaut de ce tri signifient que ni les filtres de colonne ni les filtres de ligne ne réduisent le nombre d'octets analysés, sauf si ces filtres sont appliqués en tant que paramètres aux fonctions read_gbq et read_gbq_table. Pour fournir un tri total sur toutes les lignes du DataFrame, BigQuery DataFrames crée un hachage de toutes les lignes. Cela peut entraîner une analyse complète des données qui ignore les filtres de lignes et de colonnes.

Si vous définissez la propriété ordering_mode sur partial, BigQuery DataFrames ne génère pas de tri total des lignes. Le mode de tri partiel désactive également les fonctionnalités qui nécessitent un tri total sur toutes les lignes, comme la propriété DataFrame.iloc. Le mode de tri partiel définit la classe DefaultIndexKind sur un index nul, au lieu d'un index séquentiel basé sur le tri.

Lorsque vous filtrez un DataFrame avec la propriété ordering_mode définie sur partial, BigQuery DataFrames n'a plus besoin de calculer les lignes manquantes dans l'index séquentiel. Il génère donc des requêtes plus rapides et plus efficaces. L'API BigQuery DataFrames est toujours l'API pandas que vous connaissez, tout comme l'expérience par défaut avec le mode de tri strict. Toutefois, le mode de tri partiel diffère du comportement habituel de pandas. Par exemple, il n'effectue pas de jointures implicites par index.

Avec les modes de tri partiel et strict, vous payez les ressources BigQuery que vous utilisez. Toutefois, l'utilisation du mode de tri partiel peut réduire les coûts lorsque vous utilisez des tables volumineuses regroupées et partitionnées, car les filtres de ligne sur les colonnes de cluster et de partition réduisent le nombre d'octets traités.

Utilisation

Pour utiliser le tri partiel, définissez la propriété ordering_mode sur partial avant d'effectuer toute autre opération avec BigQuery DataFrames, comme illustré dans l'exemple de code suivant :

import bigframes.pandas as bpd

bpd.options.bigquery.ordering_mode = "partial"

Comme il n'existe pas d'index séquentiel avec le mode de tri partiel, les dataframes BigQuery DataFrames non associés ne sont pas joints implicitement. Vous devez plutôt appeler explicitement la méthode DataFrame.merge pour joindre deux dataframes BigQuery DataFrames qui proviennent de différentes expressions de table.

Les fonctionnalités Series.unique() et Series.drop_duplicates() ne sont pas compatibles avec le mode de tri partiel. Utilisez plutôt la méthode groupby pour rechercher des valeurs uniques de cette manière :

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

Avec le mode de tri partiel, le résultat des fonctions DataFrame.head(n) et Series.head(n) n'est pas idempotent pour toutes les invocations. Pour télécharger un petit échantillon arbitraire des données, utilisez les méthodes DataFrame.peek() ou Series.peek().

Pour un tutoriel détaillé dans lequel vous utilisez la propriété ordering_mode = "partial", consultez ce notebook BigQuery DataFrames qui montre comment utiliser le mode de tri partiel.

Dépannage

Étant donné que les DataFrames en mode de tri partiel n'ont pas toujours d'ordre ni d'index, vous pouvez rencontrer les problèmes suivants lorsque vous utilisez certaines méthodes compatibles avec pandas.

Erreur : tri requis

Certaines fonctionnalités nécessitent d'être triées, comme les fonctions DataFrame.head() et DataFrame.iloc. Pour obtenir la liste des fonctionnalités qui nécessitent d'être triées, consultez la colonne Tri nécessaire dans la section API pandas compatibles.

En l'absence de tri sur l'objet, l'opération échoue et un message OrderRequiredError semblable au suivant s'affiche :

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

Comme l'indique le message d'erreur, vous pouvez effectuer un tri à l'aide de la méthode DataFrame.sort_values() pour trier par colonne ou par colonnes. D'autres opérations, telles que l'opération DataFrame.groupby(), fournissent implicitement un tri total sur les clés de regroupement.

Si le tri ne peut pas être déterminé comme un tri total entièrement stable sur toutes les lignes, les opérations suivantes peuvent vous avertir par un message AmbiguousWindowWarning semblable à celui-ci :

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

Si votre charge de travail peut accepter des résultats non déterministes ou si vous pouvez vérifier manuellement que le tri que vous fournissez est un tri total, vous pouvez filtrer le message AmbiguousWindowWarning de la manière suivante :

import warnings

import bigframes.exceptions

warnings.simplefilter(
    "ignore", category=bigframes.exceptions.AmbiguousWindowWarning
)
Erreur d'index nul

Certaines fonctionnalités nécessitent un index, comme les propriétés DataFrame.unstack() et Series.interpolate(). Pour obtenir la liste des fonctionnalités qui nécessitent un index, consultez la colonne Nécessite un index dans la section API pandas compatibles.

Lorsque vous utilisez une opération qui nécessite un index avec le mode de tri partiel, l'opération génère un message NullIndexError semblable à celui-ci :

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

Comme l'indique le message d'erreur, vous pouvez fournir un index à l'aide de la méthode DataFrame.set_index() pour trier par colonne ou par colonnes. D'autres opérations, telles que l'opération DataFrame.groupby(), fournissent implicitement un index sur les clés de regroupement, sauf si le paramètre as_index=False est défini.

Étapes suivantes