Parquet Content-Defined Chunking com Xet Storage no Hugging Face Hub

Visão geral

Content-Defined Chunking (CDC) de Parquet está disponível para PyArrow e Pandas, permitindo a deduplicação eficiente de arquivos Parquet sobre a camada de armazenamento Xet da Hugging Face. CDC deduplica dados no nível de páginas ou blocos de conteúdo definidos, de modo que ao enviar ou receber Parquet, apenas os dados alterados são transferidos. Isso pode reduzir drasticamente o tráfego e o custo de armazenamento, especialmente para grandes conjuntos de dados hospedados no Hub. Xet é uma camada de armazenamento projetada para deduplicar blocos entre repositórios e arquivos. O layout do Parquet — blocos de colunas e páginas de dados com compressão — pode produzir representações byte-level diferentes para pequenas alterações. CDC resolve isso chunkificando os dados com base no conteúdo, alinhando o processo de deduplicação com os dados lógicos. Para desenvolvedores, você pode ativar o CDC passando use_content_defined_chunking=True para a função write_parquet (PyArrow). O Pandas também suporta esse recurso. Com PyArrow, é possível ler e escrever dados Parquet para o Hugging Face Hub via hf:// URIs quando o pyarrow é instalado na versão >= 21.0.0. O Hub coleta estatísticas de armazenamento e demonstra que os dados enviados podem ser significativamente menores com CDC. O blog demonstra cenários como adicionar ou remover colunas, alterar tipos de colunas e acrescentar linhas. Ele mostra a deduplicação entre repositórios e entre arquivos, bem como o impacto de diferentes tamanhos de row-group. A conclusão é que Parquet CDC, em combinação com o Xet, possibilita fluxos de trabalho de dados mais eficientes e escaláveis no Hub.

Principais características

• Chunking definido pelo conteúdo opera no nível de páginas de dados/parquet (blocos de coluna) para melhorar a granularidade da deduplicação.
• Funciona com PyArrow e Pandas, permitindo CDC em gravações Parquet.
• Deduplicação entre repositórios e entre arquivos, não apenas dentro de um único arquivo.
• Integração com a camada de armazenamento Hugging Face Xet para reduzir bytes transferidos e a pegada de armazenamento.
• Suporte a edições comuns de Parquet (adição/remocão de colunas, mudança de tipos) com menor movimentação de dados.
• Compatibilidade com hf:// URIs, possibilitando leitura/escrita direta no Hub quando pyarrow >= 21.0.0.
• O desempenho de deduplicação varia conforme mudanças nos dados e restrições de leitura/escrita; o tamanho dos row-groups pode influenciar os resultados.
• Observação de que downloads também podem se beneficiar do CDC ao usar as APIs do Hub (hf_hub_download, datasets.load_dataset).

Casos de uso comuns

• Grandes conjuntos de Parquet armazenados no Xet onde os dados evoluem ao longo do tempo e você quer evitar reenviar dados não alterados.
• Fluxos de trabalho colaborativos entre vários repositórios, compartilhando colunas ou linhas atualizadas com transferência mínima.
• Cenários de evolução de esquema (adição/remição de colunas, alteração de tipos) em que apenas as partes afetadas são transferidas.
• pipelines de dados que dependem da organização colunar do Parquet e desejam otimizar armazenamento e largura de banda entre backends semelhantes a nuvem.

Setup & instalação

Para usar Parquet CDC, você precisará do PyArrow 21.0.0 ou superior e do ecossistema Pandas. Instale os pacotes necessários e depois execute gravações com CDC.

# Instale dependências principais com suporte a CDC
pip install "pyarrow>=21.0.0" pandas

# Opcional: instale ferramentas adicionais da Hugging Face para acesso a datasets
pip install huggingface_hub datasets

# Exemplo PyArrow: escrever uma tabela com CDC ativado
import pyarrow as pa
import pyarrow.parquet as pq
# tabela simples
tbl = pa.Table.from_pydict({"id": [1, 2, 3], "valor": [100, 200, 300]})
# habilitar chunking definido pelo conteúdo
pq.write_table(tbl, "hf://meu-repo/data.parquet", use_content_defined_chunking=True)

# Exemplo Pandas: escrever um DataFrame com CDC ativado
import pandas as pd
df = pd.DataFrame({"id": [1, 2, 3], "valor": [100, 200, 300]})
df.to_parquet("hf://meu-repo/data.parquet", use_content_defined_chunking=True)

Observação: CDC requer o pyarrow >= 21.0.0 para habilitar entradas hf:// para I/O direto no Hub.

Quick start

O fluxo mínimo a seguir demonstra a escrita com CDC, seguida de leitura, ilustrando como o Hub pode deduplicar dados e oferecer I/O rápido.

import pyarrow as pa
import pyarrow.parquet as pq
# 1) Criar e escrever dados iniciais
tbl1 = pa.Table.from_pydict({"id": [1, 2, 3], "valor": [100, 200, 300]})
pq.write_table(tbl1, "hf://meu-repo/data.parquet", use_content_defined_chunking=True)
# 2) Ler de volta
print(pq.read_table("hf://meu-repo/data.parquet"))
# 3) Modificar dados (ex.: adicionar coluna)
tbl2 = tbl1.append_column("extra", pa.array([1, 1, 1]))
pq.write_table(tbl2, "hf://meu-repo/data.parquet", use_content_defined_chunking=True)
# 4) Ler dados atualizados
print(pq.read_table("hf://meu-repo/data.parquet"))

Este fluxo demonstra a escrita com CDC e a leitura posterior do Hub. A gravação com CDC transfere apenas as páginas de dados novas ou modificadas quando apropriado.

Prós e contras

• Prós
• Reduções substanciais no tamanho de uploads/downloads para conjuntos de Parquet onde mudanças são incrementais.
• Deduplicação entre repositórios e entre arquivos, permitindo compartilhamento de dados de forma eficiente.
• Funciona com fluxos Parquet padrão via PyArrow e Pandas, com I/O direto ao Hub via hf:// URIs.
• Suporte a edições comuns de Parquet com menos movimentação de dados.
• Contras
• O desempenho de deduplicação depende de como as mudanças nos dados se refletem nas páginas do Parquet; algumas edições podem reduzir os ganhos.
• Resultados ótimos podem exigir ajuste do tamanho de row-group para a carga de trabalho.
• Requer que os escritores de Parquet suportem CDC (gravações habilitadas para CDC).

Alternativas (comparações breves)

| Abordagem | Dedup entre repositórios | Suporte a CDC | Notas |---|---|---|---| | Parquet sem CDC no Xet | Deduplicação limitada a nível de arquivo | Não | Reenvia conteúdo inalterado na prática. |Parquet CDC com Xet (Hub) | Sim | Sim | Reduz transferência de dados; depende de escritores com CDC. |Armazenamento tradicional em nuvem sem Xet | Não | Não | Transfere dados inteiros com mais frequência. |

Pricing ou Licença

Detalhes de preços e licenciamento não são especificados no material de referência.

Referências

https://huggingface.co/blog/parquet-cdc