Laden Sie Unity-Katalogtabellen in PyTorch mit UCDataset

Important

UCDataset und UCVolumeDataset sind in der Beta-Phase.

UCDataset ist ein PyTorch IterableDataset , der Daten aus Unity-Katalogtabellen in eine Trainingsschleife auf AI Runtime streamt. Sie beschreiben, was als DataFrame gelesen werden soll: Wählen Sie eine Tabelle aus, wählen Sie dann Spalten aus und filtern Sie Zeilen. Der Datensatz liest die passenden Zeilen direkt aus den Datendateien der Tabelle im Cloud-Speicher, daher benötigen Sie weder eine Spark-Sitzung noch ein SQL-Warehouse. Es wendet die Löschvektoren der Tabelle beim Lesen an, verteilt die passenden Zeilen gleichmäßig auf GPUs und Data Loader-Arbeiter und liefert ein Wörterbuch pro Batch. Numerische und boolesche Spalten werden zu Tensoren. Andere Spalten werden zu Python-Listen.

Wählen Sie einen Datensatz basierend darauf, wo sich Ihre Trainingsdaten befinden:

Schulungsdaten Dataset
Zeilen in einer Unity-Katalogtabelle, zum Beispiel Feature- und Labelspalten in einer Delta Lake-Tabelle UCDataset (Beta)
Dateien in einem Unity-Katalog-Volume, wie Bilder, Audio oder Dokumente UCVolumeDataset (Beta)

Die beiden Datensätze arbeiten Seite an Seite. Zum Beispiel kann ein Trainingsauftrag Labels aus einer Tabelle mit UCDataset und die passenden Bilder aus einem Band mit UCVolumeDatasetlesen.

Für andere Daten verwenden Sie stattdessen folgende Optionen:

Requirements

  • Eine KI-Laufzeit-Workload. UCDataset ist überall dort verfügbar, wo AI Runtime verfügbar ist. Siehe KI-Laufzeitverfügbarkeit nach Geo.
  • Linux auf x86_64 mit Python 3.10 oder höher. Das Paket ist ausschließlich für x86_64 entwickelt. AI Runtime GPU Compute erfüllt diese Anforderung.
  • Eine im Unity-Katalog registrierte Delta Lake-Tabelle.
  • Das USE CATALOG Privileg im Katalog der Tabelle, das USE SCHEMA Privileg für ihr Schema und das SELECT Privileg auf der Tabelle.
  • Um auf mehr als einer GPU zu trainieren, ist ein Launcher wie z. B. torchrun erforderlich, der für jeden Prozess die Umgebungsvariablen RANK und WORLD_SIZE festlegt. Wenn keine der beiden Variablen gesetzt ist, etwa in einem AI Runtime-Notebook, liest UCDataset die Tabelle als einen einzelnen Shard. Wenn nur einer davon eingestellt ist, UCDataset löst einen Fehler aus.

Important

Wenn Sie eine Workload mit databricks air run, einreichen, starten Sie das Trainingsskript mit torchrun, selbst auf einer einzelnen GPU. AI Runtime setzt WORLD_SIZE für jede Workload, setzt aber nicht RANK, und UCDataset löst einen Fehler aus, wenn nur einer der beiden eingestellt ist. torchrun setzt beide für jeden Prozess. Siehe Einen Multi-Knoten-Job auf AI Runtime ausführen.

Lade eine Tabelle

  1. Installieren Sie das databricks-uc-dataset Paket. Für eine Workload, die Sie mit databricks air run übermitteln, fügen Sie das Paket environment.dependencies hinzu. Siehe Einen Multi-Knoten-Job auf KI-Laufzeit ausführen. Führen Sie in einem Notizbuch Folgendes aus:

    %pip install databricks-uc-dataset==0.0.1b1
    
  2. Wählen Sie die Tabelle, Spalten und Zeilen aus, die sie lesen möchten. table() Nimmt einen dreistufigen Tabellennamen, und das optionale version_as_of Argument liest eine bestimmte Tabellenversion:

    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. Erstellen Sie den Datensatz und packen Sie ihn in einen PyTorch DataLoader ein. Der Datensatz gibt bereits Batches zurück, also batch_size=None im Loader setzen. Wenn Sie mit PyTorch DistributedDataParallel (DDP) trainieren, rufen Sie torch.distributed.init_process_group() auf, bevor Sie den Datensatz erstellen. Rang 0 plant dann das Lesen einmalig und teilt den Plan mit den anderen Rängen:

    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. Um auf mehr als einer GPU zu trainieren, speichern Sie den Code als train.py und starten Sie ihn mit torchrun. Überspringen Sie diesen Schritt in einem Notizbuch. Um beispielsweise auf 8 GPUs an einem Knoten zu trainieren, führen Sie Folgendes aus:

    torchrun --nproc_per_node=8 train.py
    

Jeder Rang und jeder Worker liest seinen eigenen Shard der passenden Zeilen. Jeder Batch ist ein Wörterbuch, das jeden ausgewählten Spaltennamen einem Tensor oder einer Liste zuordnet.

Führen Sie einen Multi-Knoten-Job auf AI Runtime aus

Um auf mehr als einem Knoten zu trainieren, beschreiben Sie die Workload in workload.yaml und senden Sie sie mit databricks air run ein:

  • Setze environment.version auf databricks_ai_v6, was PyTorch einschließt, und füge environment.dependencies zu databricks-uc-dataset==0.0.1b1 hinzu.

  • Starte das Trainingsskript mit torchrun. AI Runtime führt den Befehl auf jedem Knoten aus und setzt NUM_NODES, NODE_RANK, LOCAL_WORLD_SIZE, MASTER_ADDR, und MASTER_PORT. torchrun verwendet sie, um für jeden Prozess festzulegen RANK :

    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"
    

Für eine vollständige Workload mit train.py, workload.yaml und einer Beispieltabelle siehe Click-through-rate-Modell auf einer Unity Catalog-Tabelle im AI Runtime Cookbook. Um auf mehr GPUs zu trainieren, ändern Sie num_accelerators in workload.yaml. train.py Ändert sich nicht.

Zeilen filtern

UCDataset wendet Filter an, während es die Dateien liest, sodass Zeilen, die nicht übereinstimmen, nicht in deine Trainingsschleife gelangen. Erstellen Sie einen Filter mit col() und den folgenden Ausdrücken:

Ausdruck Example
Vergleich col("amount") > 50. Außerdem ==, !=, <, <=, und >=.
Nullprüfung col("label").isNull(), col("label").isNotNull()
nullsichere Gleichheit col("region").eqNullSafe("us")
Boolesche Logik (col("a") > 1) & (col("b") == "x"). Außerdem \| (oder) und ~ (nicht).

Filter unterstützen keine SQL-Zeichenketten isin oder IN, BETWEEN, Zeichenkettenabgleich wie like oder contains, Arithmetik auf Spalten cast, oder benutzerdefinierte Funktionen (UDFs). Geben Sie jede Bedingung als Column Ausdruck aus und kombinieren Sie Bedingungen mit &, |, und ~. Ein Vergleich nimmt eine Spalte und einen literalen Wert in beliebiger Reihenfolge. Man kann keine zwei Spalten vergleichen. Um eine Liste von Werten abzugleichen, kombinieren == Sie Bedingungen mit |. Sehr lange Filter können ausfallen. Informationen finden Sie unter Einschränkungen.

Das folgende Beispiel liest Kaufereignisse aus einer festen Tabellenversion aus. Die Version muss existieren:

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

Ausgabeformat

Jeder Batch ist ein Python-Wörterbuch, das jedem ausgewählten Spaltennamen seine Werte zuordnet:

Spaltentyp Batch-Wert
Integer, ohne Nulls im Batch 1D-Tensor mit dem ganzzahligen Typ der Spalte, wie zum Beispiel int32
Integer, mit Nulls im Batch (außer 64-Bit) 1-D-Tensor float64, mit Nullwerte als NaN
Gleitkomma 1D-Tensor, mit Nullwerten als NaN
Boolean, ohne Nullwerte Boolescher Tensor
Binary Liste der bytes Objekte
Andere Typen, wie Zeichenketten, Arrays, Strukturen und Zeitstempel Python-Liste

Da der Typ einer ganzzahligen Spalte davon abhängt, ob der Batch einen Nullwert enthält, kann die Spalte den Typ von einem Batch zum nächsten wechseln. Wenn Ihr Modell einen festen Ganzzahltyp benötigt, etwa für Embedding-Nachschlagen oder Klassenbezeichnungen, filtern Sie die Nullen heraus oder ersetzen Sie sie in einer transform Funktion.

Wenn eine Spalte nicht konvertiert werden kann, ohne Daten zu verlieren, löst UCDataset einen Fehler aus. Dies geschieht für eine 64-Bit-Ganzzahlspalte, die Nullwerte enthält, und für eine boolesche Spalte, die Nullwerte enthält. Der Fehler tritt auf, wenn ein Batch mit einem Nullwert gelesen wird, sodass er mitten in einer Epoche auftreten kann. Um es zu vermeiden, filtern Sie die Nullwerte mit isNotNull() heraus oder ersetzen Sie sie in einer transform-Funktion.

Um das Batch-Layout oder das Handling von Nulls zu ändern, übergeben Sie eine transform Funktion. UCDataset ruft sie für jeden Batch als PyArrow RecordBatch auf, bevor irgendeine Umwandlung in Tensoren erfolgt, und liefert alles, was die Funktion zurückgibt, also konvertiere jede verwendete Spalte. Das folgende Beispiel gibt ein Tupel von Tensoren zurück:

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)

Das folgende Beispiel ersetzt Nullwerte in einer 64-Bit-Ganzzahlspalte durch 0, sodass die Spalte in jedem Batch bleibt int64 :

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)

Verteiltes Training und Shuffling

UCDataset teilt die Zeilen auf, die zu Ihrem Filter passen, über jeden Rang und jeden Data Loader-Arbeiter. Du brauchst keinen verteilten Sampler. Standardmäßig unterscheiden sich die Shardgrößen um höchstens eine Zeile.

Gleiche Shard-Größen garantieren keine gleiche Anzahl von Chargen. Ein Rang kann einen Batch mehr bekommen als ein anderer, zum Beispiel wenn einige Shards ein exaktes Vielfaches von batch_size Zeilen enthalten und andere eine Zeile mehr, oder wenn ein Filter weniger Zeilen beibehält als es Shards gibt. Bei DDP wartet der Rang mit dem zusätzlichen Batch dann auf einen Gradienten-All-Reduce, an dem die anderen Ränge nie teilnehmen, und der Lauf schlägt fehl. Damit Ränge eine Epoche zu unterschiedlichen Zeiten beenden können, wickeln Sie jede Epoche im PyTorch-Kontextmanager Join ein, wobei model das DDP-umwickelte Modell ist:

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() gibt die Anzahl der Zeilen zurück, die mit dem Filter übereinstimmen, über alle Ränge und Worker hinweg. len(dataset) und len(loader) lösen ein TypeError aus. Wenn eine Bibliothek die Anzahl der Schritte in einer Epoche benötigt, etwa einen Lernrate-Scheduler, schätzen Sie sie aus num_rows(), der Weltgröße und batch_size. Jeder Rang kann einen Batch mehr lesen als die geschätzte Anzahl, und jeder zusätzliche Data-Loader-Worker kann einen weiteren partiellen Batch hinzufügen.

UCDataset liest die Tabellendateien in einer festen, zufällig durchmischten Reihenfolge. Jede Epoche verwendet dieselbe Reihenfolge, ebenso wie ein neuer Datensatz bei einer unveränderten Tabelle. Man kann keinen Seed setzen, und die Dateien werden nicht zwischen den Epochen neu gemischt.

Authentication

UCDataset liest die Tabelle als Identität, die die Workload ausführt, und die Unity-Katalogberechtigungen auf der Tabelle gelten.

Der Unity-Katalog stellt keine Speicheranmeldeinformationen für Tabellen mit Zeilenfiltern oder Spaltenmasken aus, daher kann UCDataset sie nicht lesen. Die Erstellung des Datensatzes schlägt bei einem Fehler fehl, der die Meldung aus dem Unity-Katalog enthält.

Limitations

  • UCDataset liest nur Delta Lake-Tabellen im Unity-Katalog. Ansichten, materialisierte Ansichten und Streaming-Tabellen werden nicht unterstützt.
  • Tabellen mit Zeilenfiltern oder Spaltenmasken können nicht gelesen werden, da der Unity Catalog keine Speicheranmeldeinformationen für sie ausstellt.
  • Flache Klone können nicht gelesen werden, da ihre Datendateien in der Quelltabelle gespeichert werden. Um die Reihen für einen Trainingslauf zu pinnen, lesen Sie stattdessen die Quelltabelle mit version_as_of. Ein Klon startet seine eigene Versionshistorie, sodass er nicht die früheren Versionen der Quelltabelle hat.
  • Tabellen mit einer VARIANT Spalte können nicht gelesen werden, selbst wenn Sie diese Spalte nicht auswählen.
  • version_as_of nimmt eine Tabellenversionsnummer. Zeitstempel werden nicht unterstützt: version_as_of="2026-01-01" löst einen versionAsOf must be a non-negative integer-Fehler aus.
  • Wählen Sie mindestens eine Spalte aus, die keine Partitionsspalte ist. Die Auswahl nur von Partitionsspalten führt zu einem Fehler Delta reads require at least one non-partition column.
  • Ein Filter mit einer langen Kette von Bedingungen, wie viele == Vergleiche kombiniert mit |, kann mit einem failed to decode Spark Connect plan Fehler versagen. Wenn ja, verwende weniger Bedingungen.
  • Filter unterstützen nur die Ausdrücke in Filter rows.
  • Array-Spalten, wie zum Beispiel Embeddings, werden als Python-Listen zurückgegeben, was deutlich langsamer ist als numerische Spalten.
  • UCDataset speichert seine Leseposition nicht. Wenn das Training neu startet, startet der Datensatz von vorne am Anfang der Tabelle, und Sie können mitten in einer Epoche nicht weitermachen.

Um ein Problem zu melden oder während der Beta Feedback zu geben, wenden Sie sich an Ihr Azure Databricks-Account-Team.

Zusätzliche Ressourcen