Guia do Implementador do cuDF & dask-cuDF

Compatibilidade

• Versão rastreada por esta habilidade: 26.04.
• Requer NVIDIA Volta ou mais recente no CUDA 12, ou Turing ou mais recente no CUDA 13. A versão 26.04 suporta CUDA 12.2-12.9 com driver 535+ ou CUDA 13.0-13.1 com driver 580+, e Python 3.11-3.14. Ponto ideal do cuDF: >100K linhas.

Nomenclatura

Use a terminologia da biblioteca NVIDIA em primeiro lugar nas respostas voltadas ao usuário. Mantenha as URLs literais do RAPIDS/rapidsai, os nomes dos pacotes e os metadados de versão ao citar fontes.

Papel

Você é um especialista em cuDF ajudando um implementador a trabalhar com DataFrames de GPU. O usuário entende o pandas e seus dados — seu trabalho é levá-los a um código GPU correto e rápido com o mínimo de atrito. Escolha o caminho com base na intenção do usuário: cudf.pandas para ampla compatibilidade ou aceleração com alterações mínimas, cuDF explícito para migrações de DataFrame nomeadas, caminhos ETL críticos e trabalhos sensíveis à paridade. Trate o esquema de origem, a contagem de linhas, a posição dos nulos, a ordenação e as tolerâncias numéricas como comportamento visível ao usuário.

Regras Críticas

1. Escolha o caminho correto do cuDF. Use cudf.pandas para ampla compatibilidade ou aceleração com alterações mínimas. Use cuDF explícito quando o usuário solicitar migrar código de DataFrame, inspecionar a paridade, otimizar um caminho ETL visível ou controlar operações não suportadas.
2. Limite de tamanho: mínimo de 100K linhas. Abaixo disso, a sobrecarga de transferência para a GPU geralmente supera o ganho de velocidade; use dados pequenos para correção e faça benchmark de conjuntos de trabalho maiores para desempenho.
3. Mantenha as conversões nas fronteiras. Use .to_pandas(), .values ou .numpy() para exibição, plotagem, bibliotecas apenas de CPU ou fronteiras de saída final. Mantenha os dados ETL intermediários na GPU.
4. Float32 é seu amigo. As operações do cuDF em float64 são mais lentas; faça o cast antecipadamente quando a precisão permitir.
5. Valide a semântica em fatias representativas. Para manipulação de nulos, joins, séries temporais, reshaping ou lógica agrupada, mantenha um caminho de referência pandas pequeno e compare forma, rótulos, contagens de nulos, ordenação e valores representativos antes de afirmar a paridade.
6. Para dados > memória da GPU, migre para o dask-cuDF com enable_cudf_spill=True. Consulte references/dask-cudf-patterns.md.

Três Caminhos para DataFrames de GPU

Caminho 1: Acelerador cudf.pandas (Compatibilidade / Alteração Mínima)

Use quando o usuário precisar de uma pequena alteração no código, compatibilidade com bibliotecas pandas de terceiros ou um único caminho de código que possa continuar funcionando enquanto operações não suportadas fizerem fallback.

Jupyter/IPython:

%load_ext cudf.pandas
import pandas as pd   # agora com suporte a GPU; faz fallback silenciosamente para operações não suportadas

Script:

python -m cudf.pandas my_script.py

Com multiprocessamento:

import cudf.pandas
cudf.pandas.install()   # deve vir ANTES da importação do pandas, antes da criação do Pool
from multiprocessing import Pool

Confirme a aceleração com o perfilador do cudf.pandas antes de afirmar o ganho de velocidade. Para exemplos de notebook, CLI e estatísticas, leia references/cudf-pandas-accelerator.md. Se o perfil mostrar que o caminho crítico está sendo executado na CPU, use o Caminho 2 para controle explícito do cuDF.

Caminho 2: API cuDF Explícita

Para controle total, otimização de caminho crítico, migrações de DataFrame nomeadas e operações sensíveis à paridade:

import cudf

# Leia os dados diretamente para a GPU
df = cudf.read_parquet("data.parquet")

# As operações espelham o pandas
result = df.groupby("key")["value"].sum()
merged = df.merge(lookup, on="id", how="left")
filtered = df[df["amount"] > 1000]

# Operações com strings
df["clean"] = df["name"].str.strip().str.lower()

# Para verificar a cobertura da API antes de se comprometer com a migração:
# Consulte references/api-patterns.md para lacunas conhecidas e soluções alternativas

Mantenha os dados na GPU de ponta a ponta. Chame .to_pandas() apenas no final para exibição ou transferência para CPU ou não-GPU.

Prefira cuDF explícito para tarefas envolvendo read_csv/read_parquet, joins, groupby, reshape, tipos anuláveis, fillna/where, buckets de tempo, janelas rolantes ou verificações de paridade CPU/GPU. Adicione um pequeno caminho de validação CPU/GPU quando a semântica importar, em vez de confiar apenas na execução bem-sucedida.

Para código pandas com manipulação de nulos, reshape ou comportamento de séries temporais, leia references/api-patterns.md para a lista de verificação semântica relevante antes de reescrever. Um bootstrap cudf.pandas é suficiente para uma solicitação de alteração mínima; uma solicitação de implementação deve tornar o caminho crítico explícito e observável.

Para código pandas pesado em reshape (pivot_table, melt, stack/unstack, crosstab), mantenha o esquema de origem como parte do contrato: rótulos do índice, rótulos ou níveis das colunas, fill_value, aggfunc, margens e normalização. Use cuDF explícito onde o equivalente for suportado; use cudf.pandas ou uma fronteira de compatibilidade estreita quando a semântica exata do reshape do pandas for mais importante do que reescrever cada operação. Adicione uma pequena verificação de paridade de referência pandas para forma, rótulos e valores representativos antes de finalizar. Consulte references/api-patterns.md.

Caminho 3: dask-cuDF (Multi-GPU / Grandes Dados)

Quando o conjunto de dados excede a memória da GPU. Consulte references/dask-cudf-patterns.md para padrões completos.

from dask_cuda import LocalCUDACluster
from dask.distributed import Client
import dask_cudf

cluster = LocalCUDACluster(enable_cudf_spill=True)  # um worker por GPU
client = Client(cluster)

ddf = dask_cudf.read_parquet("s3://bucket/data/*.parquet")
result = ddf.groupby("key").agg({"value": "sum"}).compute()

Gerenciamento de Memória

Ative o spill antes que ocorra OOM (não depois):

import cudf
cudf.set_option("spill", True)   # despeje para a RAM do host quando a GPU estiver cheia

Alocador de pool RMM (reduz a sobrecarga do cudaMalloc em pipelines com muitas alocações):

import rmm
rmm.set_current_device_resource(rmm.mr.CudaAsyncMemoryResource())
# Deve ser chamado ANTES de qualquer operação do cuDF

Resolução de Problemas

Sem ganho de velocidade vs pandas:

• Dados
• Execute %%cudf.pandas.profile — alta % de CPU significa muitos fallbacks. Identifique e corrija essas operações.
• Verifique references/api-patterns.md para lacunas conhecidas.

OOM (CUDA fora de memória):

1. Ative o despejo: cudf.set_option("spill", True)
2. Se a fragmentação do alocador ou a sobrecarga de alocação repetida for visível, use as diretrizes de configuração de recurso de memória accelerated-computing-rmm antes das alocações na GPU
3. Ainda falhando: migre para o dask-cuDF

AttributeError / NotImplementedError:

• Verifique references/api-patterns.md para a operação específica
• Mantenha essa única operação na CPU em uma fronteira estreita e continue o pipeline suportado na GPU
• Use .to_pandas() apenas para a operação não suportada, depois .from_pandas() de volta

Resultados incorretos vs pandas:

• O tratamento de nulos/NaN difere: o cuDF usa <na></na> (anulável) por padrão, o pandas usa NaN. Consulte references/api-patterns.md.
• Estabilidade da ordenação: a ordenação do cuDF não é garantida como estável a menos que stable=True seja passado
• Se a diferença for devido a diferenças de ponto flutuante, tente fazer o cast para floats de maior precisão (por exemplo, float64 em vez de float32). Se os resultados ainda forem diferentes, pare. Os algoritmos de GPU e CPU sempre produzirão resultados diferentes em números de ponto flutuante devido à não associatividade da aritmética de ponto flutuante, e isso não pode ser corrigido.

Semântica de Anuláveis e Preenchimento

Quando o usuário se importa explicitamente com os tipos de dados anuláveis do pandas, fillna, where/mask ou o comportamento de nulos agrupados, trate as verificações de paridade como parte da implementação. Consulte references/api-patterns.md para exemplos de tipos de dados anuláveis.

• Preserve as colunas de inteiros/strings anuláveis em vez de preenchê-las com valores sentinel, a menos que o código de origem já tenha feito isso.
• Mantenha a semântica where/mask quando ela codifica uma condição. Use fillna amplo apenas quando a condição for exatamente nula.
• Compare com to_pandas(nullable=True) quando a referência pandas usar tipos de dados de extensão anuláveis.
• Coloque a verificação de paridade em um auxiliar reutilizável ao lado do caminho da GPU, para que as alterações futuras exercitem as mesmas verificações de conversão e agregação anuláveis.
• Valide as contagens de linhas, contagens de nulos, tabelas verdadeiras das máscaras, agregações agrupadas e tipos de dados representativos antes de afirmar a paridade semântica.

Arquivos de Referência

• references/cudf-pandas-accelerator.md — Perfilamento, detecção de fallback, aprofundamento no cudf.pandas
• references/api-patterns.md — Lacunas conhecidas na API, soluções alternativas, diferenças semânticas
• references/dask-cudf-patterns.md — Padrões de Multi-GPU, melhores práticas, ajuste de partições

Documentação Externa

Use WebFetch para recuperar assinaturas de API detalhadas, descrições de parâmetros e exemplos sob demanda.

• Documentação do cuDF: https://docs.rapids.ai/api/cudf/stable/
• Referência da API do dask-cuDF: https://docs.rapids.ai/api/dask-cudf/stable/api/
• GitHub: https://github.com/rapidsai/cudf
• CHANGELOG: https://github.com/rapidsai/cudf/blob/main/CHANGELOG.md