UCDataset を使用して Unity カタログテーブルを PyTorch に読み込む

Important

UCDataset UCVolumeDatasetはまだベータ版です。

UCDataset は、Unity カタログのテーブルからデータを AI ランタイム上のトレーニングループにストリーミングする PyTorch IterableDataset です。 DataFrameとして何を読み取るかを説明しています:表を選び、次に列を選択し、行をフィルターします。 データセットはクラウドストレージ内のテーブルのデータファイルから一致する行を直接読み込むため、SparkセッションやSQLウェアハウスは必要ありません。 読み取り時にテーブルの削除ベクトルを適用し、対応する行をGPUとデータローダーワーカー間で均等に分割し、バッチごとに1つの辞書を生成します。 数値列とブール列はテンソルになります。 他の列はPythonリストになります。

トレーニングデータがどこにあるかに基づいてデータセットを選択してください:

トレーニング データ Dataset
Unity Catalog テーブル内の行(Delta Lake テーブル内のフィーチャー列やラベル列など) UCDataset (ベータ)
Unity Catalog ボリューム内のファイル(画像、音声、文書など) UCVolumeDataset (ベータ)

この2つのデータセットは並行して動作します。 例えば、トレーニングジョブは UCDataset のテーブルからラベルを読み取り、 UCVolumeDatasetのボリュームから対応する画像を読み取ることができます。

その他のデータについては、代わりに以下のオプションを使用してください:

Requirements

  • AI ランタイムのワークロード。 UCDataset は、AI ランタイムが利用可能な場所ならどこでも利用可能です。 GeoごとのAIランタイムの利用可能性をご覧ください。
  • Python 3.10 以上を搭載した x86_64 上の Linux。 このパッケージはx86_64専用に作られています。 AI Runtime GPU コンピュートはこの要件を満たします。
  • Unity カタログに登録されている Delta Lake テーブル。
  • テーブルのカタログ上の USE CATALOG 権限、スキーマ上の USE SCHEMA 権限、テーブル上の SELECT 権限です。
  • 複数のGPUを使用してトレーニングするには、WORLD_SIZEのように、すべてのプロセスに対してtorchrunおよびRANK環境変数を設定するランチャーが必要です。 AIランタイムノートブックのように、いずれの変数も設定されていない場合、 UCDataset テーブルを単一のシャードとして読み取ります。 そのうち1つだけが設定されている場合、UCDataset はエラーを発生させます。

Important

databricks air runでワークロードを送信するときは、たとえ1つのGPUでもtorchrunからトレーニングスクリプトを開始してください。 AI ランタイムはすべてのワークロードに対して WORLD_SIZE を設定しますが、RANK は設定せず、2つのうち1つだけが設定されていると、UCDataset はエラーを出します。 torchrun 各プロセスごとに両方を設定します。 「 AI ランタイムでマルチノードジョブを実行する」を参照してください。

テーブルを読み込む

  1. databricks-uc-dataset パッケージをインストールします。 databricks air run を使用して送信するワークロードについては、パッケージを environment.dependencies に追加してください。 「 AI ランタイムでマルチノードジョブを実行する」を参照してください。 ノートブックで、次を実行します。

    %pip install databricks-uc-dataset==0.0.1b1
    
  2. 読み取りするテーブル、列、行を選択します。 table() は3レベルのテーブル名を受け取り、オプションの version_as_of 引数は特定のテーブルバージョンを読み込みます:

    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. データセットを作成し、PyTorch の DataLoader でラップします。 データセットはすでにバッチを返しているので、ローダーには batch_size=None を設定してください。 PyTorch DistributedDataParallel (DDP) でトレーニングする場合は、データセットを作成する前に torch.distributed.init_process_group() を呼び出してください。 ランク0は1回だけ読み込みを計画し、そのプランを他のランクと共有します。

    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. 複数のGPUでトレーニングする場合は、コードを train.py として保存し、 torchrunで起動してください。 ノートブックではこのステップを飛ばしてください。 例えば、1つのノードで8つのGPUで学習するには、次のコマンドを実行します。

    torchrun --nproc_per_node=8 train.py
    

各ランクとワーカーは、対応する行のシャードをそれぞれ読み取る。 各バッチは、選択した各列名をテンソルまたはリストに対応付ける辞書です。

AI ランタイムでマルチノードジョブを実行する

複数のノードでトレーニングする場合は、workload.yaml でワークロードを記述し、databricks air run を使用して送信してください。

  • environment.versionをPyTorchを含むdatabricks_ai_v6に設定し、databricks-uc-dataset==0.0.1b1にenvironment.dependenciesを追加します。

  • トレーニングスクリプトを torchrunで始めてください。 AI Runtime はすべてのノードでコマンドを実行し、NUM_NODES、NODE_RANK、LOCAL_WORLD_SIZE、MASTER_ADDR、MASTER_PORT を設定します。 torchrun は、各プロセスの 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"
    

train.py、workload.yaml、およびサンプルテーブルを含む完全なワークロードについては、AI Runtime Cookbook のUnity Catalog テーブル上のクリックスルー率モデルを参照してください。 より多くのGPUでトレーニングするには、num_accelerators内のworkload.yamlを変更してください。 train.py は変わりません。

行のフィルター

UCDataset ファイルを読み込む間にフィルターを適用するため、一致しない行はトレーニングループに到達しません。 col() と以下の式を使ってフィルターを作成します:

Expression 例
Comparison col("amount") > 50。 また、 ==、 !=、 <、 <=、 >=もあります。
Null チェック col("label").isNull()、col("label").isNotNull()
null 安全な等価比較 col("region").eqNullSafe("us")
ブール論理 (col("a") > 1) & (col("b") == "x")。 また、\|(または)と~(not)もあります。

フィルターは、SQL 文字列、 isin または IN、 BETWEEN、 like や contains のような文字列マッチング、列の算術、 cast、ユーザー定義関数(UDF)をサポートしていません。 各条件を Column 式として渡し、条件を &、 |、 ~と組み合わせます。 比較は、列とリテラル値のいずれかを、どちらの順番でも受け取る。 2つの列を比較することはできません。 値のリストに一致するには、 == 条件を |と組み合わせます。 非常に長いフィルターは機能しないことがあります。 制限事項を参照してください。

次の例は、固定テーブルバージョンから購入イベントを読み取ります。 バージョンは存在しなければなりません:

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

出力形式

各バッチは、選択した各列名をその値に対応付ける Python 辞書です:

列のタイプ バッチ値
バッチに null なしの整数 列の整数型を持つ1次元テンソル(例: int32
バッチにヌルを含む整数(64ビットを除く) 1次元 float64 テンソル(null を NaN として持つ)
浮動小数点 null を NaN とする1次元テンソル
ヌルなしのブール値 ブールテンソル
Binary bytesオブジェクト一覧
文字列、配列、構造体、タイムスタンプなどのその他のタイプ Pythonリスト

整数列の型はバッチに null が含まれているかどうかによって決まるため、列はあるバッチから次のバッチへタイプを変更できます。 モデルが固定整数型(例えばルックアップの埋め込みやクラスラベルなど)が必要な場合は、nullをフィルターで除外するか、 transform 関数内で置き換えてください。

カラムがデータを失わずに変換できない場合、UCDataset エラーが発生します。 これは、null を含む 64 ビット整数列と、null を含む boolean 列で発生します。 このエラーは、null を含むバッチが読み取られたときに発生するため、エポックの途中で発生することがあります。 これを回避するには、isNotNull()でヌルをフィルタリングするか、transform関数でヌルを置き換えてください。

バッチレイアウトを変更したり、nullを処理したりするには、transform 関数を渡してください。 UCDataset は各バッチに対して、テンソルに変換する前に PyArrow RecordBatch としてそれを呼び出し、関数が返すものをそのまま返します。そのため、使う各列を変換してください。 次の例はテンソルのタプルを返します:

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)

次の例では、64 ビット整数型の列内の NULL を 0 に置き換えることで、各バッチでその列の型が常に 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)

分散型トレーニングとシャッフル

UCDataset すべてのランクとすべてのデータローダーワーカーで、フィルターに一致する行を分割します。 分散型サンプラーは必要ありません。 デフォルトでは、シャードサイズは最大で1行しか差しません。

同じシャードサイズがあってもバッチ数が同じとは限りません。 例えば、あるシャードが batch_size 行の正確な倍数を保持し、別のシャードが1行多く保持する場合、あるフィルターがシャード数よりも少ない行数を保持する場合など、あるランクが別の列より多くバッチを持てる場合があります。 DDPの場合、追加ロットを持つランクは他のランクが参加しない勾配の全減りを待機し、ジョブは失敗します。 rank ごとにエポックの完了時刻が異なっても、各エポックを PyTorch Join コンテキストマネージャでラップします。ここで model は 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() すべてのランクとワーカーにまたがる、フィルターに一致する行数を返します。 len(dataset) と len(loader) は TypeError を送出します。 図書館がエポックのステップ数(学習率スケジューラなど)が必要な場合は、 num_rows()、世界サイズ、 batch_sizeから推定します。 各ランクは推定値より1バッチ多く読み取ることができ、追加のデータローダーワーカーはさらに1バッチを追加できます。

UCDataset テーブルのファイルを、固定されたシャッフルされた順番で読み上げます。 すべてのエポックは同じ順序を使い、変更されていないテーブルに対する新しいデータセットも同じです。 シードを設定することはできませんし、エポック間でファイルが再シャッフルされることもありません。

Authentication

UCDataset は、ワークロードを実行する ID としてテーブルを読み取り、そのテーブルに対する Unity Catalog の権限が適用されます。

Unity Catalog は行フィルターや列マスク付きのテーブルに対してストレージ認証情報を発行しないため、 UCDataset それらを読み取ることができません。 データセットの作成が失敗し、Unity カタログからのメッセージを含むエラーが発生します。

Limitations

  • UCDataset Unity カタログ内の Delta Lake テーブルのみを読み取ります。 ビュー、マテリアライズドビュー、ストリーミングテーブルはサポートされていません。
  • 行フィルターや列マスク付きのテーブルは、Unity Catalog がそれらに対してストレージ資格情報を発行しないため、読み取りできません。
  • 浅いクローンは読み取りできません。なぜなら、そのデータファイルはソーステーブルと一緒に保存されているからです。 トレーニングランの行をピン留めするには、代わりにソーステーブルをversion_as_ofで読み取ります。 クローンは自分のバージョン履歴を開始するため、ソーステーブルの以前のバージョンは持っていません。
  • VARIANT列の表は、その列を選択しなくても読み取れません。
  • version_as_of テーブルのバージョン番号を取ります。 タイムスタンプはサポートされていません: version_as_of="2026-01-01" を実行すると versionAsOf must be a non-negative integer エラーが発生します。
  • 少なくとも1つのパーティションカラムではないカラムを選択してください。 パーティション列のみを選択すると Delta reads require at least one non-partition column エラーが発生します。
  • 多くの == 比較と |の組み合わせなど、長い条件の連鎖を持つフィルタは、 failed to decode Spark Connect plan 誤差で失敗することがあります。 そうであれば、条件を減らしましょう。
  • フィルターはFilter rows内の式のみをサポートします。
  • 埋め込みなどの配列列は Python リストとして返されますが、数値列よりもはるかに遅いです。
  • UCDataset 読み取り位置をチェックポイントしません。 トレーニングが再起動されると、データセットはテーブルの最初から再開され、エポックの途中で再開することはできません。

ベータ期間中に問題を報告したりフィードバックを送ったりするには、Azure Databricks アカウントチームにお問い合わせください。

追加リソース