GPU Perf Playbook для PyTorch и LLM-нагрузок

Исправляй медленное обучение, низкую утилизацию GPU, OOM, плохое масштабирование на несколько GPU и узкие места LLM-инференса.

English | 中文

Этот репозиторий предназначен для инженеров, которые уже знают, что их модель должна работать быстрее, но нуждаются в практическом пути к поиску и устранению узкого места.

Используй двумя способами:

• Читай плейбук, когда нужен приоритизированный чеклист оптимизации GPU.
• Установи включённый Claude-скилл, когда хочешь, чтобы Claude автоматически рассуждал на основе того же плейбука.

Если это сэкономит тебе время на отладку — поставь звезду репозиторию, чтобы больше людей его нашли.

Что это помогает исправить

• Циклы обучения, которые медленны несмотря на топовые GPU
• GPU, ожидающие CPU или DataLoader
• OOM из-за активаций, состояния оптимизатора или вариативности форм тензоров
• Многогпу-задачи с плохой эффективностью масштабирования
• LLM-инференс-стеки с плохой задержкой, пропускной способностью или стратегией KV-кэша
• Код-ревью, где баги производительности скрываются за «корректным» кодом

Философия: сначала измерь, классифицируй узкое место, примени наименьшее значимое исправление, затем проверь результат.

Что входит в репозиторий

Установка в Claude за 60 секунд

1. Скачай skill/best-gpu-perf.skill.
2. Открой Claude.ai -> Settings -> Skills.
3. Нажми Add Skill и загрузи файл.

Затем попробуй такие промпты:

• My training is slow on A100. Give me the highest-ROI things to check first.
• Review this PyTorch training loop for GPU performance issues.
• I'm hitting OOM on a 7B model. Walk me through the memory budget and likely fixes.
• My multi-GPU scaling falls off after 4 GPUs. What should I profile?
• Help me optimize LLM inference latency and throughput for a vLLM-style stack.

Если хочешь кастомизировать скилл, исходник находится в skill/SKILL.md. Пересобери упакованный артефакт командой:

С чего начать

Для кого это

• PyTorch-инженеры, которым нужно ускорить обучение без переписывания всего с нуля
• LLM-инфра и сервинг-инженеры, отлаживающие задержку, пропускную способность или поведение KV-кэша
• Исследователи, которым нужен дефолтный чеклист оптимизации перед написанием кастомных ядер
• Ревьюеры, которые хотят отлавливать регрессии производительности в PR

Структура репозитория

• docs/: тематические справочные руководства
• skill/SKILL.md: исходник Claude-скилла
• skill/best-gpu-perf.skill: упакованный артефакт скилла для загрузки
• scripts/build_skill.sh: пересобирает упакованный скилл из исходников репозитория

⚡ Быстрый старт: чеклист P0

Прежде чем делать что-либо ещё, убедись, что в твоём коде есть всё перечисленное. Это низкорисковые, высокодоходные практики, применимые почти к каждому PyTorch-проекту:

import torch, os
from torch.utils.data import DataLoader

# 1. Enable TF32 (free speed on Ampere+)
torch.set_float32_matmul_precision("high")

# 2. DataLoader: don't let GPU wait for data
loader = DataLoader(
    dataset,
    batch_size=batch_size,
    num_workers=4,                # NOT 0
    pin_memory=True,              # Faster CPU→GPU transfer
    persistent_workers=True,      # Don't re-fork every epoch
)

# 3. Compile the model
model = torch.compile(model.cuda())

# 4. Fused optimizer
optimizer = torch.optim.AdamW(model.parameters(), lr=1e-4, fused=True)

# 5. Training loop with AMP + best practices
for batch in loader:
    batch = {k: v.cuda(non_blocking=True) for k, v in batch.items()}
    optimizer.zero_grad(set_to_none=True)         # Not zero_grad()

    with torch.autocast("cuda", dtype=torch.bfloat16):  # 6. Mixed precision
        loss = model(**batch)

    loss.backward()
    optimizer.step()
    # ❌ Don't: print(loss), loss.item() every step, loss.cpu()

Также проверь:

• Скрытые размерности / размер словаря кратны 64
• Attention использует F.scaled_dot_product_attention, а не ручное QK^TV
• Eval использует @torch.inference_mode()
• Нет .item() / .cpu() / print(tensor) в горячем пути обучения

👉 Полный чеклист с 12 антипаттернами и шаблоном PR → docs/checklist.md

🧭 Деревья решений

Моё обучение медленное

(полное дерево решений доступно в репозитории)