Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Charger les tables du catalogue Unity dans PyTorch avec
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 :
- Pour les petites tables qui tiennent en mémoire, ou pour les requêtes nécessitant des jointures ou des agrégations, utilisez Spark Connect.
- Pour les charges de travail Ray, utilisez
ray.data.read_databricks_tables().
Spécifications
- Une charge de travail d’exécution IA.
UCDatasetest 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 CATALOGprivilège sur le catalogue de la table, leUSE SCHEMAprivilège sur son schéma, et leSELECTprivilège sur la table. - Pour s’entraîner sur plus d’un GPU, un lanceur qui définit les variables d’environnement
RANKetWORLD_SIZEpour chaque processus, partorchrunexemple . Si aucune variable n’est définie, comme dans un bloc-notes AI Runtime,UCDatasetlit la table comme un seul fragment. Si un seul d’entre eux est réglé,UCDatasetcela 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
Installez le package
databricks-uc-dataset. Pour une charge de travail que vous soumettez avecdatabricks 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.1b1Sélectionnez la table, les colonnes et les lignes à lire.
table()prend un nom de table à trois niveaux, et l’argument optionnelversion_as_oflit 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()) )Créez l’ensemble de données et encapsulez-le dans un
DataLoaderPyTorch. Le jeu de données renvoie déjà des lots, donc réglezbatch_size=Nonesur le chargeur. Si vous vous entraînez avec PyTorch DistributedDataParallel (DDP), appeleztorch.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)Pour s’entraîner sur plus d’un GPU, enregistrez le code sous
train.pyet lancez-le avectorchrun. 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.versionsurdatabricks_ai_v6, qui inclut PyTorch, et ajoutezdatabricks-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éfinitNUM_NODES,NODE_RANK,LOCAL_WORLD_SIZE,MASTER_ADDR, etMASTER_PORT.torchrunles utilise pour définirRANKpour 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
-
UCDatasetne 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
VARIANTne peuvent pas être lues, même si vous ne sélectionnez pas cette colonne. -
version_as_ofprend un numéro de version de table. Les horodatages ne sont pas pris en charge :version_as_of="2026-01-01"déclenche uneversionAsOf must be a non-negative integererreur. - 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 columnerreur. - Un filtre avec une longue chaîne de conditions, comme de nombreuses
==comparaisons combinées avec|, peut échouer avec unefailed to decode Spark Connect planerreur. 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.
-
UCDatasetn’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.