Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Carregar tabelas do Catálogo Unity no PyTorch com
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:
- Para tabelas pequenas que cabem na memória, ou para consultas que precisam de joins ou agregações, use o Spark Connect.
- Para cargas de trabalho Ray, use
ray.data.read_databricks_tables().
Requirements
- Uma carga de trabalho em tempo de execução de IA.
UCDatasetestá 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 CATALOGprivilégio no catálogo da tabela, oUSE SCHEMAprivilégio no seu esquema e oSELECTprivilégio na tabela. - Para treinar em mais de uma GPU, um lançador que define as
RANKvariáveis de ambienteWORLD_SIZEe para cada processo, comotorchrun. Se nenhuma das variáveis for definida, como em um caderno de notas AI Runtime,UCDatasetlê a tabela como um único fragmento. Se apenas um deles for configurado,UCDatasetgera 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
Instale o pacote
databricks-uc-dataset. Para uma carga de trabalho que você envia comdatabricks air run, adicione o pacote aoenvironment.dependencies. Veja como executar um trabalho multi-nó no AI Runtime. Em um notebook, execute o seguinte:%pip install databricks-uc-dataset==0.0.1b1Selecione a tabela, as colunas e as linhas para ler.
table()aceita um nome de tabela de três níveis, e o argumento opcionalversion_as_oflê 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()) )Crie o conjunto de dados e o envolva em um PyTorch
DataLoader. O conjunto de dados já retorna lotes, então configurebatch_size=Noneno carregador. Se você treinar com PyTorch DistributedDataParallel (DDP), chametorch.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)Para treinar em mais de uma GPU, salve o código como
train.pye inicie-o comtorchrun. 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.versioncomodatabricks_ai_v6, que inclui PyTorch, e adicionedatabricks-uc-dataset==0.0.1b1aenvironment.dependencies.Inicie o script de treinamento com
torchrun. AI Runtime executa o comando em cada nó e defineNUM_NODES,NODE_RANK,LOCAL_WORLD_SIZE,MASTER_ADDR, eMASTER_PORT.torchrunUsa-as para definirRANKpara 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
-
UCDatasetlê 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_ofem 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
VARIANTnão podem ser lidas, mesmo que você não selecione essa coluna. -
version_as_ofaceita 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 umversionAsOf must be a non-negative integererro. - 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 columnerro. - Um filtro com uma longa cadeia de condições, como muitas
==comparações combinadas com|, pode falhar com umfailed to decode Spark Connect planerro. 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.
-
UCDatasetNã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.