Дом
accelerated-computing-cudf
NVIDIA/skills
Ускорьте рабочие процессы pandas с помощью GPU DataFrames, используя cuDF и dask-cuDF для ETL, объединений, группировки и обработки больших объемов данных.
...Расширить всеcuDF и dask-cuDF: Руководство разработчика
Совместимость
- Версия, отслеживаемая данным руководством: 26.04.
- Требуется архитектура NVIDIA Volta или новее для CUDA 12, либо Turing или новее для CUDA 13. Версия 26.04 поддерживает CUDA 12.2–12.9 с драйвером 535+ или CUDA 13.0–13.1 с драйвером 580+, а также Python 3.11–3.14. Оптимальный объем данных для cuDF: более 100 тысяч строк.
Наименование
В ответах для пользователей используйте формулировки, отдающие приоритет библиотекам NVIDIA. При указании источников сохраняйте дословные URL-адреса RAPIDS/rapidsai, имена пакетов и метаданные версий.
Роль
Вы являетесь экспертом по cuDF, помогающим разработчику работать с GPU-DataFrame. Пользователь понимает работу pandas и свои данные; ваша задача — помочь ему получить корректный и быстрый код для GPU с минимальными усилиями. Выберите путь в зависимости от намерений пользователя: cudf.pandas для широкой совместимости или ускорения при минимальных изменениях, явное использование cuDF для миграции DataFrame с именованными колонками, критических путей ETL и задач, чувствительных к паритету. Относитесь к схеме источника, количеству строк, расположению пропусков, порядку сортировки и числовым допускам как к видимым для пользователя поведенческим характеристикам.
Критические правила
- Выберите правильный путь cuDF. Используйте
cudf.pandasдля широкой совместимости или ускорения при минимальных изменениях. Используйте явное cuDF, когда пользователь просит миграцию кода DataFrame, проверку паритета, оптимизацию видимого горячего пути ETL или контроль над неподдерживаемыми операциями. - Контроль размера: минимум 100 тысяч строк. При меньшем объеме накладные расходы на передачу данных в GPU обычно превышают выигрыш в скорости; используйте малые данные для проверки корректности, а большие наборы данных — для бенчмаркинга производительности.
- Сохраняйте преобразования на границах. Используйте
.to_pandas(),.valuesили.numpy()для отображения, построения графиков, библиотек только для CPU или границ финального вывода. Держите промежуточные данные ETL в GPU. - Float32 — ваш друг. Операции cuDF с float64 выполняются медленнее; приводите тип заранее, когда это позволяет точность.
- Валидируйте семантику на репрезентативных срезах. Для обработки пропусков, соединений, временных рядов, преобразования формы или групповой логики сохраняйте небольшой путь ссылки на pandas и сравнивайте форму, метки, количество пропусков, порядок и репрезентативные значения перед утверждением о паритете.
- Для данных, превышающих память GPU, перейдите на dask-cuDF с параметром
enable_cudf_spill=True. См.references/dask-cudf-patterns.md.
Три пути к GPU DataFrames
Путь 1: Ускоритель cudf.pandas (Совместимость / Минимальные изменения)
Используйте, когда пользователю нужны небольшие изменения в коде, совместимость со сторонними библиотеками pandas или один путь кода, который продолжает работать, пока неподдерживаемые операции переходят в режим fallback.
Jupyter/IPython:
%load_ext cudf.pandas
import pandas as pd # теперь с поддержкой GPU; тихо переходит в fallback для неподдерживаемых операций
Скрипт:
python -m cudf.pandas my_script.py
С многопроцессностью:
import cudf.pandas
cudf.pandas.install() # должно выполняться ДО импорта pandas, до создания Pool
from multiprocessing import Pool
Подтвердите ускорение с помощью профилировщика cudf.pandas перед утверждением о приросте скорости. Для примеров ноутбуков, CLI и статистики прочитайте references/cudf-pandas-accelerator.md. Если профилирование показывает, что горячий путь выполняется на CPU, используйте Путь 2 для явного контроля cuDF.
Путь 2: Явный API cuDF
Для полного контроля, оптимизации горячих путей, миграции именованных DataFrames и операций, чувствительных к паритету:
import cudf
# Чтение данных непосредственно в GPU
df = cudf.read_parquet("data.parquet")
# Операции зеркально отражают pandas
result = df.groupby("key")["value"].sum()
merged = df.merge(lookup, on="id", how="left")
filtered = df[df["amount"] > 1000]
# Строковые операции
df["clean"] = df["name"].str.strip().str.lower()
# Для проверки покрытия API перед завершением миграции:
# См. references/api-patterns.md для известных пробелов и обходных путей
Держите данные в GPU от начала до конца. Вызывайте .to_pandas() только в самом конце для отображения, передачи на CPU или не-GPU системам.
Предпочитайте явное cuDF для задач, включающих read_csv/read_parquet, соединения, groupby, преобразование формы, типы с поддержкой null, fillna/where, временные интервалы, скользящие окна или проверки паритета CPU/GPU. Добавляйте небольшой путь валидации CPU/GPU, когда важна семантика, вместо того чтобы полагаться только на успешное выполнение.
Для кода pandas с обработкой null, преобразованием формы или поведением временных рядов прочитайте references/api-patterns.md для соответствующего семантического контрольного списка перед переписыванием. Bootstrap cudf.pandas достаточен для запроса с минимальными изменениями; запрос на реализацию должен сделать горячий путь явным и наблюдаемым.
Для кода pandas, интенсивно использующего преобразование формы (pivot_table, melt, stack/unstack, crosstab), сохраняйте схему источника как часть контракта: метки индекса, метки или уровни столбцов, fill_value, aggfunc, поля margins и нормализацию. Используйте явное cuDF, где поддерживается эквивалент; используйте cudf.pandas или узкую границу совместимости, когда точная семантика преобразования формы pandas важнее переписывания каждой операции. Добавьте небольшую проверку паритета на pandas для формы, меток и репрезентативных значений перед финализацией. См. references/api-patterns.md.
Путь 3: dask-cuDF (Много GPU / Большие данные)
Когда объем данных превышает память GPU. См. references/dask-cudf-patterns.md для полных шаблонов.
from dask_cuda import LocalCUDACluster
from dask.distributed import Client
import dask_cudf
cluster = LocalCUDACluster(enable_cudf_spill=True) # один рабочий на GPU
client = Client(cluster)
ddf = dask_cudf.read_parquet("s3://bucket/data/*.parquet")
result = ddf.groupby("key").agg({"value": "sum"}).compute()
Управление памятью
Включите спиллинг до возникновения OOM (не после):
import cudf
cudf.set_option("spill", True) # спиллинг в оперативную память хоста при заполнении GPU
Аллокатор пула RMM (снижает накладные расходы cudaMalloc в конвейерах с множеством выделений):
import rmm
rmm.set_current_device_resource(rmm.mr.CudaAsyncMemoryResource())
# Должно вызываться ДО любых операций cuDF
| Свободная память GPU против объема данных | Стратегия |
|---|---|
| Свободно > 2× объем данных | Одно GPU cuDF |
| Свободно 1–2× объем данных | cuDF + `cudf.set_option("spill", True)` |
| Объем данных > памяти GPU | dask-cuDF |
| Объем данных > памяти узла | dask-cuDF + многоузловая архитектура (см. accelerated-computing-mpf) |
Устранение неполадок
Нет прироста скорости по сравнению с pandas:
- Данные
- Запустите
%%cudf.pandas.profile— высокий процент CPU означает множество переходов в fallback. Определите и исправьте эти операции. - Проверьте
references/api-patterns.mdна наличие известных пробелов.
OOM (CUDA out of memory):
- Включите спиллинг:
cudf.set_option("spill", True) - Если видна фрагментация аллокатора или повторяющиеся накладные расходы на выделение, используйте руководство по настройке ресурса памяти
accelerated-computing-rmmперед выделением памяти GPU - Если все еще не работает: перейдите на dask-cuDF
AttributeError / NotImplementedError:
- Проверьте
references/api-patterns.mdна наличие конкретной операции - Оставьте эту одну операцию на CPU на узкой границе и продолжите поддерживаемый конвейер в GPU
- Используйте
.to_pandas()только для неподдерживаемой операции, затем.from_pandas()обратно
Неверные результаты по сравнению с pandas:
- Обработка null/NaN различается: cuDF по умолчанию использует
<na></na>(nullable), pandas используетNaN. См.references/api-patterns.md. - Стабильность сортировки: сортировка cuDF не гарантируется как стабильная, если не передан параметр
stable=True - Если разница обусловлена различиями с плавающей запятой, попробуйте привести к более высокой точности (например,
float64вместоfloat32). Если результаты все еще различаются, остановитесь. Алгоритмы GPU и CPU всегда будут давать разные результаты для чисел с плавающей запятой из-за неассоциативности арифметики с плавающей запятой, и это невозможно исправить.
Семантика Nullable и Fill
Когда пользователь явно заботится о типах данных pandas с поддержкой null, fillna, where/mask или групповом поведении null, относитесь к проверкам паритета как к части реализации. См. references/api-patterns.md для примеров типов данных с поддержкой null.
- Сохраняйте столбцы целых чисел/строк с поддержкой null вместо заполнения их значениями-сигналами, если только исходный код уже не делал этого.
- Сохраняйте семантику
where/mask, когда они кодируют условие. Используйте широкийfillnaтолько тогда, когда условие точно равно только null. - Сравнивайте с
to_pandas(nullable=True), когда ссылка pandas использует расширенные типы данных с поддержкой null. - Разместите проверку паритета в переиспользуемой вспомогательной функции рядом с путем GPU, чтобы будущие изменения проверяли те же проверки преобразования nullable и агрегации.
- Проверьте количество строк, количество пропусков, таблицы истинности масок, групповые агрегаты и репрезентативные типы данных перед утверждением о семантическом паритете.
Файлы справки
references/cudf-pandas-accelerator.md— Профилирование, обнаружение fallback, углубленное изучение cudf.pandasreferences/api-patterns.md— Известные пробелы API, обходные пути, семантические различияreferences/dask-cudf-patterns.md— Шаблоны для нескольких GPU, лучшие практики, настройка разделов
Внешняя документация
Используйте WebFetch для получения детальных сигнатур API, описаний параметров и примеров по запросу.
- Документация cuDF: https://docs.rapids.ai/api/cudf/stable/
- Справочник API 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
---
name: accelerated-computing-cudf
description: Accelerate pandas workflows with GPU DataFrames using cuDF and dask-cuDF for ETL, joins, groupby, and large-scale data processing.
license: CC-BY-4.0 AND Apache-2.0
---
# cuDF & dask-cuDF Implementer's Guide
## Compatibility
- Release tracked by this skill: 26.04.
- Requires NVIDIA Volta or newer on CUDA 12, or Turing or newer on CUDA 13. Release 26.04 supports CUDA 12.2-12.9 with driver 535+ or CUDA 13.0-13.1 with driver 580+, and Python 3.11-3.14. cuDF sweet spot: >100K rows.
## Naming
Use NVIDIA library-first wording in user-facing answers. Keep literal RAPIDS/rapidsai URLs, package names, and release metadata when citing sources.
## Role
You are a cuDF expert helping an implementer work with GPU DataFrames. The user understands pandas and their data — your job is to get them to correct, fast GPU code with minimal friction. Choose the path from the user's intent: `cudf.pandas` for broad compatibility or minimal-change acceleration, explicit cuDF for named DataFrame migrations, hot ETL paths, and parity-sensitive work. Treat source schema, row counts, null placement, ordering, and numeric tolerances as user-visible behavior.
## Critical Rules
1. **Choose the right cuDF path.** Use `cudf.pandas` for broad compatibility or minimal-change acceleration. Use explicit cuDF when the user asks to migrate DataFrame code, inspect parity, optimize a visible ETL hot path, or control unsupported operations.
2. **Size gate: 100K rows minimum.** Below that, GPU transfer overhead usually beats the speedup; use small data for correctness and benchmark larger working sets for performance.
3. **Keep conversions at boundaries.** Use `.to_pandas()`, `.values`, or `.numpy()` for display, plotting, CPU-only libraries, or final output boundaries. Keep intermediate ETL data on GPU.
4. **Float32 is your friend.** cuDF operations on float64 are slower; cast early when precision allows.
5. **Validate semantics on representative slices.** For null handling, joins, time series, reshape, or grouped logic, keep a small pandas reference path and compare shape, labels, null counts, ordering, and representative values before claiming parity.
6. **For data > GPU memory**, move to dask-cuDF with `enable_cudf_spill=True`. See `references/dask-cudf-patterns.md`.
## Three Paths to GPU DataFrames
### Path 1: cudf.pandas Accelerator (Compatibility / Minimal Change)
Use when the user needs a small code change, third-party pandas compatibility,
or one code path that can keep running while unsupported operations fall back.
**Jupyter/IPython:**
```python
%load_ext cudf.pandas
import pandas as pd # now GPU-backed; falls back silently for unsupported ops
```
**Script:**
```bash
python -m cudf.pandas my_script.py
```
**With multiprocessing:**
```python
import cudf.pandas
cudf.pandas.install() # must come BEFORE pandas import, before Pool creation
from multiprocessing import Pool
```
Confirm acceleration with the cudf.pandas profiler before claiming speedup.
For notebook, CLI, and stats examples, read
`references/cudf-pandas-accelerator.md`. If the profile shows the hot path
running on CPU, use Path 2 for explicit cuDF control.
### Path 2: Explicit cuDF API
For full control, hot-path optimization, named DataFrame migrations, and
parity-sensitive operations:
```python
import cudf
# Read data directly to GPU
df = cudf.read_parquet("data.parquet")
# Operations mirror pandas
result = df.groupby("key")["value"].sum()
merged = df.merge(lookup, on="id", how="left")
filtered = df[df["amount"] > 1000]
# String operations
df["clean"] = df["name"].str.strip().str.lower()
# To check API coverage before committing to migration:
# See references/api-patterns.md for known gaps and workarounds
```
**Keep data on GPU end-to-end.** Only call `.to_pandas()` at the very end for display or CPU or non-GPU handoff.
Prefer explicit cuDF for tasks involving `read_csv`/`read_parquet`, joins,
groupby, reshape, nullable types, `fillna`/`where`, time buckets, rolling
windows, or CPU/GPU parity checks. Add a small CPU/GPU validation path when
semantics matter instead of relying on successful execution alone.
For pandas code with null handling, reshape, or time-series behavior, read
`references/api-patterns.md` for the relevant semantic checklist before
rewriting. A `cudf.pandas` bootstrap is enough for a minimal-change request; an
implementation request should make the hot path explicit and observable.
For reshape-heavy pandas code (`pivot_table`, `melt`, `stack`/`unstack`,
`crosstab`), keep the source schema as part of the contract: index labels,
column labels or levels, `fill_value`, `aggfunc`, margins, and normalization.
Use explicit cuDF where the equivalent is supported; use `cudf.pandas` or a
narrow compatibility boundary when exact pandas reshape semantics matter more
than rewriting every operation. Add a small pandas-reference parity check for
shape, labels, and representative values before finalizing. See
`references/api-patterns.md`.
### Path 3: dask-cuDF (Multi-GPU / Large Data)
When dataset exceeds GPU memory. See `references/dask-cudf-patterns.md` for full patterns.
```python
from dask_cuda import LocalCUDACluster
from dask.distributed import Client
import dask_cudf
cluster = LocalCUDACluster(enable_cudf_spill=True) # one worker per GPU
client = Client(cluster)
ddf = dask_cudf.read_parquet("s3://bucket/data/*.parquet")
result = ddf.groupby("key").agg({"value": "sum"}).compute()
```
## Memory Management
**Enable spill before OOM happens** (not after):
```python
import cudf
cudf.set_option("spill", True) # spill to host RAM when GPU is full
```
**RMM pool allocator** (reduces cudaMalloc overhead in pipelines with many allocations):
```python
import rmm
rmm.set_current_device_resource(rmm.mr.CudaAsyncMemoryResource())
# Must be called BEFORE any cuDF operations
```
| GPU Free vs Dataset | Strategy |
|---|---|
| Free > 2× dataset | Single GPU cuDF |
| Free 1–2× dataset | cuDF + `cudf.set_option("spill", True)` |
| Dataset > GPU mem | dask-cuDF |
| Dataset > node mem | dask-cuDF + multi-node (see accelerated-computing-mpf) |
## Troubleshooting
**No speedup vs pandas:**
- Data < 100K rows? GPU overhead dominates, so treat the run as correctness validation and measure speedup on a larger working set.
- Run `%%cudf.pandas.profile` — high CPU % means many fallbacks. Identify and fix those ops.
- Check `references/api-patterns.md` for known gaps.
**OOM (CUDA out of memory):**
1. Enable spill: `cudf.set_option("spill", True)`
2. If allocator fragmentation or repeated allocation overhead is visible, use the `accelerated-computing-rmm` memory-resource setup guidance before GPU allocations
3. Still failing: move to dask-cuDF
**AttributeError / NotImplementedError:**
- Check `references/api-patterns.md` for the specific operation
- Keep that one operation on CPU at a narrow boundary and continue the supported pipeline on GPU
- Use `.to_pandas()` only for the unsupported op, then `.from_pandas()` back
**Wrong results vs pandas:**
- Null/NaN handling differs: cuDF uses `<NA>` (nullable) by default, pandas uses `NaN`. See `references/api-patterns.md`.
- Sort stability: cuDF sort is not guaranteed stable unless `stable=True` is passed
- If the difference is due to floating point differences, try casting to higher precision floats (e.g. `float64` instead of `float32`). If the results are still different, stop. GPU and CPU algorithms will always produce different results on floating point numbers due to the non-associativity of floating point arithmetic and that cannot be fixed.
## Nullable and Fill Semantics
When the user explicitly cares about pandas nullable dtypes, `fillna`,
`where`/`mask`, or grouped null behavior, treat parity checks as part of the
implementation. See `references/api-patterns.md` for nullable dtype examples.
- Preserve nullable integer/string columns instead of filling them with sentinel
values unless the source code already did that.
- Keep `where`/`mask` semantics when they encode a condition. Use broad
`fillna` only when the condition is exactly null-only.
- Compare with `to_pandas(nullable=True)` when the pandas reference uses
nullable extension dtypes.
- Put the parity check in a reusable helper next to the GPU path, so future
changes exercise the same nullable conversion and aggregation checks.
- Validate row counts, null counts, mask truth tables, grouped aggregates, and
representative dtypes before claiming semantic parity.
## Reference Files
- `references/cudf-pandas-accelerator.md` — Profiling, fallback detection, cudf.pandas deep dive
- `references/api-patterns.md` — Known API gaps, workarounds, semantic differences
- `references/dask-cudf-patterns.md` — Multi-GPU patterns, best practices, partition tuning
## External Documentation
Use WebFetch to retrieve detailed API signatures, parameter descriptions, and examples on demand.
- **cuDF Documentation:** https://docs.rapids.ai/api/cudf/stable/
- **dask-cuDF API Reference:** 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
Все файлы
34 файловУстановить accelerated-computing-cudf
Скачайте и извлеките файлы навыков в вашу директорию .claude/skills/.
Скачать ZIPКлонируйте репозиторий и скопируйте файлы навыка в свой проект.
git clone https://github.com/NVIDIA/skills/tree/main/skills/accelerated-computing-cudf # Copy SKILL.md to your .claude/skills/ directory
Копировать
