06. Справочник по отладке ROCm

Эта глава группирует отладку по уровням: среда выполнения, данные, модель и замкнутый цикл. За один раз меняйте только одну переменную и записывайте симптом, команду диагностики, исправление и результат проверки в каталог запуска. Подробные случаи см. в указателе случаев отладки ROCm.

1. Порядок отладки

устройство видно
→ базовые вычисления с тензорами
→ чтение данных
→ загрузка модели
→ прямой и обратный проход на одном шаге
→ сохранение и восстановление модели
→ один эпизод в замкнутом цикле
→ пакетная оценка

Переходите к следующему шагу только после успешного предыдущего. Так проблемы среды выполнения, данных и стратегии разделяются.

2. Устройство и среда выполнения

rocminfo | sed -n '1,100p'
python - <<'PY'
import torch

print("torch:", torch.__version__)
print("hip:", torch.version.hip)
print("available:", torch.cuda.is_available())
print("device:", torch.cuda.get_device_name(0) if torch.cuda.is_available() else None)

x = torch.randn(2048, 2048, device="cuda")
y = x @ x
print("result:", float(y.square().mean()))
PY

Одновременно записывайте:

rocm-smi --showproductname --showuse --showmemuse --showtemp --showpower
df -h "$WORK_ROOT"

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

3. Загрузка весов

Сбои при загрузке больших моделей обычно случаются в трёх местах: файл неполный, десериализация на CPU или перенос на GPU. Проверяйте по порядку:

test -s "$POLICY_PATH/model.safetensors"
test -f "$POLICY_PATH/config.json"
python - <<'PY'
from pathlib import Path
from safetensors import safe_open
import os

path = Path(os.environ["POLICY_PATH"]) / "model.safetensors"
with safe_open(path, framework="pt", device="cpu") as f:
    keys = list(f.keys())
print("tensor_count:", len(keys))
print("first_keys:", keys[:5])
PY

Сначала откройте веса на CPU, а затем переносите модель на GPU интерфейсом модели. После загрузки выполните проверку конечности значений:

for name, value in model.state_dict().items():
    if value.is_floating_point() and not value.isfinite().all():
        raise RuntimeError(f"non-finite tensor: {name}")

4. Данные и блоки действий

Для данных LeRobot проверяйте границы эпизодов и порядок строк:

required = ["episode_index", "frame_index", "index", "action"]
for key in required:
    assert key in table.column_names, key

for episode in sorted(set(table["episode_index"])):
    rows = table.filter(table["episode_index"] == episode)
    frames = rows["frame_index"]
    assert frames == list(range(len(frames)))

После объединения нескольких наборов данных заново пересоздайте глобальный index и проверьте, что первый элемент каждого блока действий совпадает с действием текущей физической строки. Проверка только того, что набор индексов полный, не выявит ошибку порядка строк.

5. Один шаг обучения

При одном шаге обучения выводите:

loss
learning_rate
grad_norm
param_norm
GPU memory allocated / reserved
step time
checkpoint path

Правила интерпретации:

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

6. Безголовый рендеринг и видео

export MUJOCO_GL=egl
export PYOPENGL_PLATFORM=egl

python code/demo/demo_ball.py
ffprobe -v error -show_streams outputs/demo_videos/demo_ball.mp4

Если EGL недоступен, можно использовать Xvfb в отдельной графической сессии:

xvfb-run -a -s '-screen 0 1920x1080x24' python code/demo/demo_arm.py

Видео кодируется в H.264 с yuv420p, так лучше работает совместимость с браузерами. Тест рендеринга подтверждает только работу среды, камеры и цепочки кодирования; результаты стратегии получаются из пакетной замкнутой оценки.

7. Поведение в замкнутом цикле

Разбивайте каждый эпизод на фазы: подход, контакт, захват, подъём, перенос, укладка и освобождение. Пошаговая запись состояния помогает найти проблему лучше, чем одно итоговое логическое значение.

Фиксированные random seed нужны для сравнения версий, а не встречавшиеся при обучении random seed — для оценки обобщения. JSON по эпизодам и видео должны получаться в одном и том же запуске.

8. Запись производительности

rocm-smi --showuse --showmemuse --showtemp --showpower --json \
  > "$RUN_ROOT/device_snapshot.json"

В отчёте об обучении или оценке записывайте:

• модель GPU, версии ROCm и фреймворка;
• размер батча, точность, разрешение и число камер;
• время шага, пропускную способность и пиковую видеопамять;
• время оценки с включённым и выключенным видео;
• фактически изменённые пункты конфигурации.

Сравнивать производительность можно только при одинаковых задаче, модели, точности, размере батча и знаменателе оценки.

9. Шаблон записи о проблеме

### Название проблемы

- Среда: GPU, ROCm, фреймворк и версия вышестоящего проекта
- Вход: набор данных, модель и команда запуска
- Симптом: первая ошибка и этап, на котором она возникла
- Диагностика: минимальное воспроизведение и ключевые метрики
- Первопричина: код, данные, среда выполнения или ресурсы
- Исправление: изменённые файлы и конфигурации
- Проверка: повторно выполненная команда и её вывод
- Артефакты: журналы, модели, результаты по эпизодам и видео

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

10. Подробные случаи

Указатель случаев отладки ROCm содержит порядок строк данных, восстановление моделей, визуальные параметры, представление действий и диагностику замкнутого цикла для ACT, SmolVLA и Pi0/Pi0.5. Сначала с помощью этой главы определите уровень проблемы, а затем перейдите к подходящему случаю.