Carregar tabelas do Catálogo Unity no PyTorch com UCDataset

Importante

UCDataset e UCVolumeDataset estão em Beta.

UCDataset é um PyTorch IterableDataset que transmite dados das tabelas do Catálogo Unity para um ciclo de treinamento no AI Runtime. Você descreve o que ler como um DataFrame: escolha uma tabela, depois selecione colunas e filtre linhas. O conjunto de dados lê as linhas correspondentes diretamente dos arquivos de dados da tabela no armazenamento na nuvem, então você não precisa de uma sessão Spark ou de um repositório SQL. Ele aplica os vetores de exclusão da tabela enquanto ela lê, divide as linhas correspondentes de forma uniforme entre GPUs e trabalhadores do carregador de dados, e gera um dicionário por lote. Colunas numéricas e booleanas tornam-se tensores. Outras colunas se tornam listas em Python.

Escolha um conjunto de dados com base em onde seus dados de treinamento estão:

Dados de treinamento Dataset
Linhas em uma tabela do Catálogo Unity, como colunas de características e etiquetas em uma tabela Delta Lake UCDataset (Beta)
Arquivos em um volume do Catálogo Unity, como imagens, áudio ou documentos UCVolumeDataset (Beta)

Os dois conjuntos de dados trabalham lado a lado. Por exemplo, uma tarefa de treinamento pode ler rótulos de uma tabela com UCDataset e as imagens correspondentes de um volume com UCVolumeDataset.

Para outros dados, use estas opções em vez disso:

Requirements

  • Uma carga de trabalho em tempo de execução de IA. UCDataset está disponível onde quer que o AI Runtime esteja. Veja a disponibilidade do AI Runtime por Geo.
  • Linux em x86_64 com Python 3.10 ou superior. O pacote foi feito apenas para x86_64. AI Runtime GPU compute atende a esse requisito.
  • Uma tabela Delta Lake registrada no Unity Catalog.
  • O USE CATALOG privilégio no catálogo da tabela, o USE SCHEMA privilégio no seu esquema e o SELECT privilégio na tabela.
  • Para treinar em mais de uma GPU, um lançador que define as RANK variáveis de ambiente WORLD_SIZE e para cada processo, como torchrun. Se nenhuma das variáveis for definida, como em um caderno de notas AI Runtime, UCDataset lê a tabela como um único fragmento. Se apenas um deles for configurado, UCDataset gera um erro.

Importante

Quando você enviar uma carga de trabalho com databricks air run, inicie o script de treinamento com torchrun, mesmo em uma única GPU. O AI Runtime define WORLD_SIZE para cada carga de trabalho, mas não define RANK, e UCDataset gera um erro quando apenas um dos dois está configurado. torchrun define ambos para cada processo. Veja Executar um trabalho multi-nó no AI Runtime.

Carregar uma tabela

  1. Instale o pacote databricks-uc-dataset. Para uma carga de trabalho que você envia com databricks air run, adicione o pacote ao environment.dependencies. Veja como executar um trabalho multi-nó no AI Runtime. Em um notebook, execute o seguinte:

    %pip install databricks-uc-dataset==0.0.1b1
    
  2. Selecione a tabela, as colunas e as linhas para ler. table() aceita um nome de tabela de três níveis, e o argumento opcional version_as_of lê uma versão específica da tabela:

    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. Crie o conjunto de dados e o envolva em um PyTorch DataLoader. O conjunto de dados já retorna lotes, então configure batch_size=None no carregador. Se você treinar com PyTorch DistributedDataParallel (DDP), chame torch.distributed.init_process_group() antes de criar o conjunto de dados. O rank 0 então planeja a leitura uma vez e compartilha o plano com os outros ranks:

    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. Para treinar em mais de uma GPU, salve o código como train.py e inicie-o com torchrun. Em um notebook, pule esta etapa. Por exemplo, para treinar em 8 GPUs em um só nó, execute o seguinte:

    torchrun --nproc_per_node=8 train.py
    

Cada posto e trabalhador lê seu próprio fragmento das linhas correspondentes. Cada lote é um dicionário que mapeia o nome de cada coluna selecionada para um tensor ou uma lista.

Execute um trabalho multi-nó no AI Runtime

Para treinar em mais de um nó, descreva a carga de trabalho em workload.yaml e envie-a com databricks air run:

  • Defina environment.version como databricks_ai_v6, que inclui PyTorch, e adicione databricks-uc-dataset==0.0.1b1 a environment.dependencies.

  • Inicie o script de treinamento com torchrun. AI Runtime executa o comando em cada nó e define NUM_NODES, NODE_RANK, LOCAL_WORLD_SIZE, MASTER_ADDR, e MASTER_PORT. torchrun Usa-as para definir RANK para cada processo:

    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"
    

Para uma carga de trabalho completa com train.py, workload.yaml, e uma tabela de exemplo, veja Modelo de taxa de clique em uma tabela do Catálogo Unity no AI Runtime Cookbook. Para treinar em mais GPUs, altere num_accelerators em workload.yaml. train.py não muda.

Filtrar linhas

UCDataset Aplica filtros enquanto lê os arquivos, para que as linhas que não coincidam não cheguem ao seu ciclo de treinamento. Construa um filtro com col() e as seguintes expressões:

Expression Example
Comparison col("amount") > 50. Também ==, !=, <, <=, e >=.
Verificação de nulo col("label").isNull(), col("label").isNotNull()
Igualdade segura para null col("region").eqNullSafe("us")
Lógica booleana (col("a") > 1) & (col("b") == "x"). Também \| (ou) e ~ (não).

Filtros não suportam strings SQL, isin nem IN, BETWEEN, correspondência de string como like ou contains, aritmética em colunas, cast, ou funções definidas pelo usuário (UDFs). Passe cada condição como uma Column expressão, e combine condições com &, |, e ~. Uma comparação toma uma coluna e um valor literal, em qualquer ordem. Você não pode comparar duas colunas. Para fazer correspondência com uma lista de valores, combine == condições com |. Filtros muito longos podem falhar. Confira Limitações.

O exemplo a seguir lê eventos de compra de uma versão fixa da tabela. A versão deve existir:

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

Formato da saída

Cada lote é um dicionário Python que mapeia cada nome de coluna selecionada para seus valores:

Tipo de coluna Valor do lote
Inteiro, sem nulos no lote Tensor 1D com o tipo inteiro da coluna, como int32
Inteiro, com valores nulos no lote (exceto 64 bits) tensor 1-D float64 , com nulos como NaN
Ponto flutuante tensor 1-D, com nulos como NaN
Booleano, sem nulos Tensor boolean
Binário Lista de bytes objetos
Outros tipos, como strings, arrays, structs e timestamps lista em Python

Como o tipo de uma coluna inteira depende de o lote conter ou não um nulo, a coluna pode mudar de tipo de um lote para o seguinte. Se seu modelo precisar de um tipo inteiro fixo, como para embedding de buscas ou rótulos de classe, filtre os nulos ou substitua-os em uma transform função.

Se uma coluna não puder ser convertida sem perder dados, UCDataset gera um erro. Isso acontece para uma coluna inteira de 64 bits que contém valores nulos e para uma coluna booleana que contém valores nulos. O erro aparece quando um lote com um valor nulo é lido, então pode ocorrer no meio de uma época. Para evitar isso, filtre os nulos por isNotNull(), ou substitua-os em uma transform função.

Para alterar o layout do lote ou lidar com valores nulos, passe uma função transform. UCDataset a chama em cada lote como um PyArrow RecordBatch, antes de qualquer conversão para tensores, e gera o que a função retorna, então converta cada coluna que você usar. O exemplo a seguir retorna uma tupla de tensores:

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)

O exemplo a seguir substitui nulos em uma coluna inteira de 64 bits por 0, de modo que a coluna permaneça int64 em cada lote:

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)

Treinamento distribuído e embaralhamento

UCDataset divide as linhas que correspondem ao seu filtro entre cada rank e cada trabalhador do carregador de dados. Você não precisa de um sampler distribuído. Por padrão, os tamanhos dos fragmentos diferem no máximo em uma linha.

Tamanhos iguais de fragmentos não garantem a mesma contagem de lotes. Um rank pode receber um lote a mais do que outro, por exemplo, quando alguns fragmentos contêm um múltiplo exato de batch_size linhas e outros contêm uma linha a mais, ou quando um filtro mantém menos linhas do que há de fragmentos. Com DDP, o rank com o lote extra então espera por um gradiente all-reduce que os outros ranks nunca se juntam, e o trabalho falha. Para permitir que os ranks terminem uma epoch em tempos diferentes, envolva cada epoch no gerenciador de contexto do PyTorch Join, em que model é o modelo encapsulado em 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() retorna o número de linhas que correspondem ao filtro, em todos os ranks e workers. len(dataset) e len(loader) levantam um TypeError. Se uma biblioteca precisar do número de etapas em uma época, como um escalonador de taxa de aprendizagem, estime a partir de num_rows(), o tamanho do mundo e batch_size. Cada rank pode ler um lote a mais do que a estimativa, e cada operador adicional do carregador de dados pode adicionar outro lote parcial.

UCDataset Lê os arquivos da tabela em uma ordem fixa e embaralhada. Cada época usa a mesma ordem, e assim também um novo conjunto de dados em uma tabela inalterada. Você não pode definir uma semente, e os arquivos não são reembaralhados entre épocas.

Authentication

UCDataset lê a tabela como a identidade que executa a carga de trabalho, e as permissões do Catálogo Unity na tabela se aplicam.

O Unity Catalog não emite credenciais de armazenamento para tabelas com filtros de linha ou máscaras de coluna, portanto UCDataset não é possível lê-las. A criação do conjunto de dados falha com um erro que inclui a mensagem do Unity Catalog.

Limitations

  • UCDataset lê apenas tabelas Delta Lake no Catálogo Unity. Views, materialized views e tabelas de streaming não são suportados.
  • Tabelas com filtros de linha ou máscaras de coluna não podem ser lidas, porque o Unity Catalog não emite credenciais de armazenamento para elas.
  • shallow clones não podem ser lidos, porque seus arquivos de dados são armazenados na tabela de origem. Para fixar as linhas para uma execução de treinamento, leia a tabela de origem com version_as_of em vez disso. Um clone inicia seu próprio histórico de versões, então ele não tem as versões anteriores da tabela de origem.
  • Tabelas com uma coluna com VARIANT não podem ser lidas, mesmo que você não selecione essa coluna.
  • version_as_of aceita um número de versão da tabela. Carimbos de data e hora não são suportados: version_as_of="2026-01-01" gera um versionAsOf must be a non-negative integer erro.
  • Selecione pelo menos uma coluna que não seja uma coluna de partição. Selecionar apenas colunas de partição gera um Delta reads require at least one non-partition column erro.
  • Um filtro com uma longa cadeia de condições, como muitas == comparações combinadas com |, pode falhar com um failed to decode Spark Connect plan erro. Se acontecer, use menos condições.
  • Os filtros suportam apenas as expressões em Filter rows.
  • Colunas de array, como embeddings, são retornadas como listas Python, o que é muito mais lento do que colunas numéricas.
  • UCDataset Não faz checkpoint na posição de leitura. Se o treinamento reiniciar, o conjunto de dados recomeça do início da tabela e você não pode retomar no meio de uma época.

Para relatar um problema ou dar feedback durante a versão beta, entre em contato com a equipe da sua conta do Azure Databricks.

Recursos adicionais