Charger les tables du catalogue Unity dans PyTorch avec UCDataset

Important

UCDataset et UCVolumeDataset sont en Bêta.

UCDataset est un IterableDataset PyTorch qui transmet les données en flux des tables du catalogue Unity vers une boucle d’entraînement sur AI Runtime. Vous décrivez ce qu’il faut lire sous forme de DataFrame : choisissez une table, puis sélectionnez les colonnes et filtrez les lignes. L’ensemble de données lit les lignes correspondantes directement à partir des fichiers de données de la table dans le stockage cloud, vous n’avez donc pas besoin d’une session Spark ni d’un entrepôt SQL. Il applique les vecteurs de suppression de la table au fur et à mesure de sa lecture, répartit les lignes correspondantes de manière égale entre les GPU et les travailleurs du chargeur de données, et produit un dictionnaire par lot. Les colonnes numériques et booléennes deviennent des tenseurs. D’autres colonnes deviennent des listes Python.

Choisissez un ensemble de données en fonction de l’endroit où se trouvent vos données d’entraînement :

Données de formation Dataset
Lignes dans une table du catalogue Unity, telles que les colonnes de caractéristiques et d’étiquettes dans une table Delta Lake UCDataset (bêta)
Fichiers dans un volume Unity Catalog, tels que des images, des fichiers audio ou des documents UCVolumeDataset (bêta)

Les deux ensembles de données fonctionnent côte à côte. Par exemple, une tâche d’entraînement peut lire des étiquettes d’un tableau avec UCDataset et les images correspondantes d’un volume avec UCVolumeDataset.

Pour les autres données, utilisez plutôt ces options :

Spécifications

  • Une charge de travail d’exécution IA. UCDataset est disponible partout où se trouve AI Runtime. Voir la disponibilité d’AI Runtime par géo.
  • Linux sur x86_64 avec Python 3.10 ou version ultérieure. Le package est conçu uniquement pour x86_64. Le calcul GPU en temps d’exécution IA répond à cette exigence.
  • Une table Delta Lake enregistrée dans le catalogue Unity.
  • Le USE CATALOG privilège sur le catalogue de la table, le USE SCHEMA privilège sur son schéma, et le SELECT privilège sur la table.
  • Pour s’entraîner sur plus d’un GPU, un lanceur qui définit les variables d’environnement RANK et WORLD_SIZE pour chaque processus, par torchrunexemple . Si aucune variable n’est définie, comme dans un bloc-notes AI Runtime, UCDataset lit la table comme un seul fragment. Si un seul d’entre eux est réglé, UCDataset cela génère une erreur.

Important

Lorsque vous soumettez une charge de travail avec databricks air run, lancez le script d’entraînement avec torchrun, même sur un seul GPU. AI Runtime définit WORLD_SIZE pour chaque charge de travail mais ne le RANKdéfinit pas , et UCDataset génère une erreur lorsqu’une seule des deux est définie. torchrun définit les deux pour chaque processus. Voir Exécuter un travail multi-nœud sur AI Runtime.

Charger une table

  1. Installez le package databricks-uc-dataset. Pour une charge de travail que vous soumettez avec databricks air run, ajoutez le paquet à environment.dependencies. Voir Exécuter un travail multi-nœud sur AI Runtime. Dans un bloc-notes, exécutez ce qui suit :

    %pip install databricks-uc-dataset==0.0.1b1
    
  2. Sélectionnez la table, les colonnes et les lignes à lire. table() prend un nom de table à trois niveaux, et l’argument optionnel version_as_of lit une version spécifique de la table :

    from databricks.uc_dataset.beta.dataframe import table, col
    
    df = (
        table("main.ml.clicks")
        .select("features", "label")
        .filter(col("label").isNotNull() & col("features").isNotNull())
    )
    
  3. Créez l’ensemble de données et encapsulez-le dans un DataLoader PyTorch. Le jeu de données renvoie déjà des lots, donc réglez batch_size=None sur le chargeur. Si vous vous entraînez avec PyTorch DistributedDataParallel (DDP), appelez torch.distributed.init_process_group() avant de créer l’ensemble de données. Le rang 0 planifie alors la lecture une fois et partage le plan avec les autres rangs :

    import torch
    from torch.utils.data import DataLoader
    from databricks.uc_dataset.beta import UCDataset
    
    dataset = UCDataset(df=df, batch_size=256)
    loader = DataLoader(dataset, batch_size=None, num_workers=4)
    
    for epoch in range(num_epochs):
        for batch in loader:
            # Array columns arrive as Python lists, and a NULL array arrives as None.
            # Convert the lists before you train.
            features = torch.as_tensor(batch["features"], dtype=torch.float32)
            label = batch["label"]
            train_step(features, label)
    
  4. Pour s’entraîner sur plus d’un GPU, enregistrez le code sous train.py et lancez-le avec torchrun. Dans un notebook, sautez cette étape. Par exemple, pour effectuer l’entraînement sur 8 GPU sur un seul nœud, exécutez la commande suivante :

    torchrun --nproc_per_node=8 train.py
    

Chaque processus et chaque worker lit son propre fragment des lignes correspondantes. Chaque lot est un dictionnaire qui associe chaque nom de colonne sélectionné à un tenseur ou à une liste.

Exécuter une tâche multi-nœuds sur AI Runtime

Pour s’entraîner sur plus d’un nœud, décrivez la charge de travail dans workload.yaml et soumettez-la avec databricks air run:

  • Réglez environment.version sur databricks_ai_v6, qui inclut PyTorch, et ajoutez databricks-uc-dataset==0.0.1b1 à environment.dependencies.

  • Commencez le script d’entraînement avec torchrun. AI Runtime exécute la commande sur chaque nœud et définit NUM_NODES, NODE_RANK, LOCAL_WORLD_SIZE, MASTER_ADDR, et MASTER_PORT. torchrun les utilise pour définir RANK pour chaque processus :

    command: |
      torchrun --nnodes=$NUM_NODES --node_rank=$NODE_RANK --nproc_per_node=$LOCAL_WORLD_SIZE \
        --master_addr=$MASTER_ADDR --master_port=$MASTER_PORT "$CODE_SOURCE_PATH/train.py"
    

Pour une charge de travail complète avec train.py, workload.yaml, et un tableau d’exemple, voir Modèle de taux de clics sur une table du catalogue Unity dans le livre de recettes AI Runtime. Pour entraîner sur plus de GPU, changez num_accelerators dans workload.yaml. train.py Ça ne change pas.

Filtrer les lignes

UCDataset applique des filtres pendant qu’il lit les fichiers, de sorte que les lignes qui ne correspondent pas n’atteignent pas votre boucle d’entraînement. Créez un filtre avec col() et les expressions suivantes :

Expression Example
Comparison col("amount") > 50. Également ==, !=, <, <=, et >=.
Vérification de valeur nulle col("label").isNull(), col("label").isNotNull()
Égalité null-sûre col("region").eqNullSafe("us")
Logique booléenne (col("a") > 1) & (col("b") == "x"). Aussi \| (ou) et ~ (non).

Les filtres ne supportent pas les chaînes SQL, isin ni IN, BETWEEN, le matching de chaînes comme like ou contains, arithmétique sur les colonnes, cast, ni les fonctions définies par l’utilisateur (UDF). Passez chaque condition comme expression Column , et combinez les conditions avec &, |, et ~. Une comparaison prend une colonne et une valeur littérale, dans l’un ou l’autre ordre. On ne peut pas comparer deux colonnes. Pour faire correspondre une liste de valeurs, combinez des conditions avec == et |. Des filtres très longs peuvent échouer. Consultez Limitations.

L’exemple suivant lit les événements d’achat à partir d’une version fixe d’une table. La version doit exister :

df = (
    table("main.ml.events", version_as_of=120)
    .filter((col("event_type") == "purchase") & (col("amount") > 50))
    .select("user_id", "amount", "label")
)

Format de sortie

Chaque lot est un dictionnaire Python qui associe chaque nom de colonne sélectionnée à ses valeurs :

Type de colonne Valeur du lot
Entier, sans nulls dans le lot Tenseur 1D avec le type entier de la colonne, tel que int32
Entier, avec les valeurs nulles dans le batch (sauf 64 bits) Tenseur 1-D float64 , avec des nulls comme NaN
à virgule flottante Tenseur 1-D, avec des valeurs nulles représentées par NaN
Booléen, sans nulls Tenseur booléen
Binary Liste des bytes objets
D’autres types, tels que chaînes, tableaux, structures et horodatages liste Python

Parce que le type d’une colonne entière dépend du fait que le lot contienne ou non un null, la colonne peut changer de type d’un lot à l’autre. Si votre modèle nécessite un type entier fixe, par exemple pour l’intégration de recherches ou d’étiquettes de classe, filtrez les nulls ou remplacez-les dans une transform fonction.

Si une colonne ne peut pas être convertie sans perdre des données, UCDataset génère une erreur. Cela se produit pour une colonne entière de 64 bits contenant des valeurs nulles et pour une colonne booléenne contenant des valeurs nulles. L’erreur apparaît lorsqu’un lot avec un null est lu, ce qui peut se produire en cours d’une époque. Pour l’éviter, filtrez les nulls par isNotNull(), ou remplacez-les dans une transform fonction.

Pour modifier la disposition du lot ou gérer les nulls, passez une fonction transform. UCDataset l’appelle à chaque lot comme un PyArrow RecordBatch, avant toute conversion en tenseurs, et donne ce que la fonction renvoie ; donc convertissez chaque colonne que vous utilisez. L’exemple suivant renvoie un tuple de tenseurs :

import torch

def to_features_and_label(batch):
    features = torch.as_tensor(batch.column("features").to_pylist(), dtype=torch.float32)
    label = torch.from_numpy(batch.column("label").to_numpy(zero_copy_only=False))
    return features, label

dataset = UCDataset(df=df, transform=to_features_and_label)

L’exemple suivant remplace les nulls dans une colonne entière de 64 bits par 0, de sorte que la colonne reste int64 dans chaque lot :

import pyarrow.compute as pc
import torch

def fill_nulls(batch):
    user_ids = pc.fill_null(batch.column("user_id"), 0)
    return {"user_id": torch.tensor(user_ids.to_numpy())}

dataset = UCDataset(df=df, transform=fill_nulls)

Formation répartie et remaniement

UCDataset Divise les lignes correspondant à votre filtre entre chaque rang et chaque travailleur de chargement de données. Vous n’avez pas besoin d’un échantillonneur distribué. Par défaut, les tailles des fragments diffèrent d’au plus une ligne.

Des tailles de fragments égales ne garantissent pas un nombre de lots égal. Un rang peut obtenir un lot de plus qu’un autre, par exemple lorsque certains fragments contiennent un multiple exact de batch_size lignes et d’autres en contiennent une de plus, ou lorsqu’un filtre conserve moins de lignes que de fragments. Avec DDP, le rang avec le lot supplémentaire attend alors un all-reduce de gradient auquel les autres rangs ne participent jamais, et l’exécution échoue. Pour permettre aux rangs de terminer une époque à des moments différents, encapsulez chaque époque dans le gestionnaire de contextes PyTorch Join , où model est le modèle encapsulé en DDP :

from torch.distributed.algorithms.join import Join

for epoch in range(num_epochs):
    with Join([model]):
        for batch in loader:
            train_step(batch)

dataset.num_rows() Renvoie le nombre de lignes correspondant au filtre, pour tous les rangs et travailleurs. len(dataset) et len(loader) lancer un TypeError. Si une bibliothèque a besoin du nombre d’étapes dans une époque, comme un planificateur de taux d’apprentissage, estimez-le à partir de num_rows(), la taille du monde, et batch_size. Chaque rang peut lire un lot de plus que l’estimation, et chaque travailleur supplémentaire du chargeur de données peut ajouter un lot partiel supplémentaire.

UCDataset lit les fichiers de la table dans un ordre fixe et mélangé. Chaque époque utilise le même ordre, tout comme un nouvel ensemble de données sur une table inchangée. Vous ne pouvez pas définir une graine, et les fichiers ne sont pas remélangés entre les époques.

Authentication

UCDataset lit la table en utilisant l’identité qui exécute la charge de travail, et les autorisations d’Unity Catalog sur la table s’appliquent.

Le catalogue Unity n’émet pas d’identifiants de stockage pour les tables avec filtres de ligne ou masques de colonne, donc UCDataset ne peut pas les lire. La création du jeu de données échoue avec une erreur incluant le message de Unity Catalog.

Limitations

  • UCDataset ne lit que les tables Delta Lake dans Unity Catalog. Les vues, les vues matérialisées et les tables de streaming ne sont pas prises en charge.
  • Les tables avec filtres de ligne ou masques de colonne ne peuvent pas être lues, car le catalogue Unity n’émet pas d’identifiants de stockage pour celles-ci.
  • Les clones superficiels ne peuvent pas être lus, car leurs fichiers de données sont stockés avec la table source. Pour épingler les lignes pour une exécution d’entraînement, lisez plutôt le tableau source avec version_as_of. Un clone lance son propre historique de versions, donc il n’a pas les versions antérieures de la table source.
  • Les tables comportant une colonne VARIANT ne peuvent pas être lues, même si vous ne sélectionnez pas cette colonne.
  • version_as_of prend un numéro de version de table. Les horodatages ne sont pas pris en charge : version_as_of="2026-01-01" déclenche une versionAsOf must be a non-negative integer erreur.
  • Sélectionnez au moins une colonne qui n’est pas une colonne de partition. Sélectionner uniquement les colonnes de partition génère une Delta reads require at least one non-partition column erreur.
  • Un filtre avec une longue chaîne de conditions, comme de nombreuses == comparaisons combinées avec |, peut échouer avec une failed to decode Spark Connect plan erreur. Si c’est le cas, utilisez moins de conditions.
  • Les filtres ne prennent en charge que les expressions dans Filter rows.
  • Les colonnes de tableau, telles que les embeddings, sont retournées sous forme de listes Python, ce qui est beaucoup plus lent que les colonnes numériques.
  • UCDataset n’enregistre pas sa position de lecture. Si l’entraînement redémarre, le jeu de données recommence depuis le début de la table, et vous ne pouvez pas reprendre au milieu d’un epoch.

Pour signaler un problème ou donner un retour lors de la Bêta, contactez votre équipe de compte Azure Databricks.

Ressources supplémentaires