# NVIDIA_VISIBLE_DEVICES и CUDA_VISIBLE_DEVICES: почему номера GPU не совпадают

Диагностика: NVIDIA_VISIBLE_DEVICES и CUDA_VISIBLE_DEVICES: почему номера GPU не совпадают. Признаки, последовательность проверки, рабочий пример и критерии восстановления.

Автор: Команда Retrivium
Обновлено: 2026-11-01
Канонический URL: https://retrivium.ai/ru/journal/nvidia-visible-vs-cuda-visible-devices/
Language: ru

NVIDIA_VISIBLE_DEVICES задаёт, какие GPU runtime предоставляет контейнеру. CUDA_VISIBLE_DEVICES фильтрует и переупорядочивает устройства для CUDA-приложения внутри доступной среды. Поэтому номер устройства в процессе может отличаться от индекса на хосте, не означая ошибку назначения карты.

## Начните с устойчивой идентичности

На хосте сохраните GPU UUID и соответствующие индексы. Затем получите список устройств в контейнере и отдельно в CUDA-процессе. Индекс — локальная позиция в перечислении, UUID помогает связать наблюдения между областями. Не считайте карту номер ноль всегда одним физическим устройством на всех узлах и после любых изменений. Если используется MIG, дополнительно зафиксируйте идентификатор инстанса и поддерживаемые ограничения перечисления в установленной версии CUDA.


[Официальный источник 1](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/docker-specialized.html).

## Проверьте уровень runtime

Для Docker возможны --gpus, NVIDIA runtime environment и CDI, в зависимости от выбранного режима и версии. NVIDIA_VISIBLE_DEVICES управляет инъекцией доступных GPU и имеет специальные значения all, none и void с разным поведением. Не переносите эти значения автоматически на CUDA_VISIBLE_DEVICES. Сохраните фактические параметры контейнера, runtime mode и device list. Переменная внутри приложения не создаёт устройство, которое runtime вообще не передал, и не заменяет права доступа к нему.


[Официальный источник 2](https://docs.nvidia.com/cuda/cuda-programming-guide/05-appendices/environment-variables.html).

## Разберите локальную нумерацию

В условном CUDA-примере CUDA_VISIBLE_DEVICES=2,1 оставляет доступными указанные устройства и меняет порядок: локальный ordinal 0 соответствует первому выбранному устройству. Пример предполагает, что эти идентификаторы доступны в рассматриваемой среде. Для контейнера сначала восстановите его собственный список, а затем применяйте фильтр процесса. Не подставляйте хостовые номера без сопоставления, если контейнер уже получил только часть карт. UUID позволяет сделать связь более явной.

| Область | Что сохранять |
| --- | --- |
| Хост | Индекс, UUID и список GPU |
| Контейнер | Переданные runtime устройства |
| CUDA-процесс | Фильтр и локальные ordinal |
| Планировщик | Какое назначение ожидалось |

## Проверьте команду запуска процесса

Переменные интерактивного shell могут отличаться от env службы или ENTRYPOINT. Сохраните окружение только по разрешённым ключам, не выгружая секреты целиком. Проверьте, не переопределяет ли wrapper CUDA_VISIBLE_DEVICES после запуска контейнера. Для нескольких worker определите назначение каждого процесса отдельно. Изменение видимости не является механизмом полной изоляции памяти или квотой производительности: оно задаёт область устройств, а совместное использование требует своей политики и проверки.

## Подтвердите назначение вычислением

Сопоставьте UUID ожидаемого устройства с фактическим запуском небольшой согласованной CUDA-задачи. Nvidiа-smi и CUDA enumeration отвечают на разные вопросы, поэтому фиксируйте оба наблюдения без предположения, что одно заменяет другое. Артефакт содержит host UUID, контейнерную конфигурацию и process mapping. При повторном развёртывании проверяйте связь снова, особенно после изменения состава устройств. Корректная локальная нумерация помогает устранить путаницу, но не подтверждает доступность нужного объёма VRAM или совместимость всего модельного стека.

При нескольких процессах добавьте в таблицу PID и команду каждого worker. Одинаковый local ordinal в двух процессах может обозначать разные выбранные устройства при разных фильтрах окружения, что само по себе ожидаемо.

Связанные разборы: [vllm docker first launch](/ru/journal/vllm-docker-first-launch/); [gpu containers vs vms](/ru/journal/gpu-containers-vs-vms/).