Установка cuPyNumeric (пользователь)

Цель

Используйте этот навык для установки cuPyNumeric с целью использования из Python и для проверки работоспособности установки (включая использование GPU). Применяйте его в тех случаях, когда пользователь хочет запустить cuPyNumeric через conda или pip. Не используйте его для компиляции из исходного кода (для модификации или внесения вкладов) — это выходит за рамки данного руководства.

Обязательные правила

• Никогда не запускайте установку. Не запускайте команды pip install, conda install или любые установщики. Выведите команду на экран; пусть пользователь запустит её сам.
• Всегда изолируйте. Не устанавливайте в базовую среду conda, системный Python или общие глобальные среды.
• Проверяйте, прежде чем давать рекомендации. Проверки --version в режиме «только для чтения» вполне допустимы.

Предварительные условия

Перед тем как рекомендовать любую установку, убедитесь в соответствии следующим системным требованиям:

• GPU: вычислительная способность ≥ 7.0 (Volta+). Также поддерживается использование только CPU.
• CUDA: 12.2+.
• ОС: Linux (x86_64 / aarch64), macOS aarch64 (только для пакетов pip в формате wheel), Windows через WSL.
• Python: версии от 3.11 до 3.14 в Linux; версии от 3.11 до 3.13 в macOS aarch64.
• conda: ≥ 24.1 (только в конфигурации conda).
• Менеджер пакетов: conda (рекомендуется разработчиками) или pip. Если ни один из них отсутствует, сначала установите один из них (см. инструкции).

Инструкции

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

Что нужно уточнить перед установкой

1. Управляющий пакеты? Проверьте ` conda --version ` и `pip --version`. Предпочтительно использовать conda (рекомендуется разработчиками); в качестве запасного варианта — pip.
2. Целевая среда? Машина с GPU, ноутбук только с CPU, облако, контейнер или удалённая машина/сервер.
3. Версия CUDA? Спрашивайте только при принудительном использовании варианта с GPU на хосте без видимого графического процессора. Проверьте с помощью nvidia-smi / nvcc --version.

Начальная настройка — сначала установите менеджер пакетов

Если ни conda, ни pip недоступны, установите один из них. Укажите команду и ссылку на документацию; не запускайте её — для выполнения команды ` curl | bash ` требуется доверие пользователя.

Рекомендуется: Miniforge (полная версия conda, по умолчанию conda-forge)

curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash "Miniforge3-$(uname)-$(uname -m).sh"

Документация: https://github.com/conda-forge/miniforge

Альтернатива: Python + pip

Установите Python с помощью менеджера пакетов вашей ОС (apt/dnf/brew) или по адресу https://www.python.org/downloads/. Если pip отсутствует в уже установленном Python: python -m ensurepip --upgrade.

После установки откройте новую оболочку, чтобы бинарный файл оказался в PATH.

Установка — путь conda

conda create -n cupynumeric -c conda-forge -c legate cupynumeric
conda activate cupynumeric

В существующую среду: conda install -c conda-forge -c legate cupynumeric.

conda автоматически выбирает вариант с GPU или CPU в зависимости от того, работает ли nvidia-smi во время установки. Чтобы переопределить этот выбор, см. ниже.

Принудительный выбор варианта с GPU

Установите CONDA_OVERRIDE_CUDA только в том случае, если на момент установки графический процессор не обнаруживается (например, при сборке контейнера для хоста с графическим процессором). Используйте версию CUDA хоста, на котором будет выполняться приложение:

CONDA_OVERRIDE_CUDA="12.2" conda install -c conda-forge -c legate cupynumeric

Ежедневная сборка (менее тщательно проверена)

conda install -c conda-forge -c legate-nightly cupynumeric

Установка — путь pip

python -m venv .venv
source .venv/bin/activate
pip install nvidia-cupynumeric

Проверка

Тест работоспособности (запускать всегда)

Запустите автономный скрипт через лаунчер Legate — проверка репозитория не требуется.

TMP=$(mktemp -d)
cat > "$TMP/smoke.py" <<'EOF'
import cupynumeric as np
a = np.arange(10)
b = np.ones((4, 4))
print("sum:", a.sum())            # ожидаемый результат: 45
print("matmul:", (b @ b).sum())   # ожидаемый результат: 64.0
EOF
legate "$TMP/smoke.py"
rm -rf "$TMP"

Ожидаемые результаты: sum: 45 и matmul: 64.0. Если команда `legate` отсутствует, среда не активирована — см. раздел «Устранение неполадок».

Проверка использования GPU (обязательна при наличии поддерживаемого GPU)

Успешное прохождение теста smoke не доказывает использование GPU — установка версии для CPU на компьютере с GPU также даёт правильные результаты. Выполните оба шага.

1. Принудительный запуск на GPU. Команда `legate --gpus N ` запрашивает N графических процессоров; быстро завершается с ошибкой, если графические процессоры не обнаружены или установлена версия для ЦП.

TMP=$(mktemp -d)
cat > "$TMP/check.py" <<'EOF'
import cupynumeric as np
print(np.ones((4096, 4096)).sum())
EOF
legate --gpus 1 "$TMP/check.py"
rm -rf "$TMP"

Ожидаемый результат: 16777216,0. Если обнаружен драйвер CUDA, libcudart или отсутствуют доступные графические процессоры, значит установлен вариант для ЦП; переустановите с параметром CONDA_OVERRIDE_CUDA.

2. Убедитесь, что GPU задействован. Запустите цикл умножения матриц с ограничением по времени вместе с nvidia-smi, всё из одного терминала — без гонки за вторым терминалом:

TMPDIR_GPU=$(mktemp -d)
SCRIPT="$TMPDIR_GPU/cupynumeric_gpu_check.py"
cat > "$SCRIPT" <<'EOF'
import cupynumeric as np, time
a = np.ones((10000, 10000))
deadline = time.time() + 20
iters = 0
while time.time() < deadline:
    b = a @ a
    _ = float(b.sum())   # принудительная синхронизация, чтобы матричное умножение действительно выполнялось
    iters += 1
print("iters:", iters)
EOF
legate --gpus 1 "$SCRIPT" &
WORKLOAD=$!
sleep 5                                     # буфер для запуска Legate
for _ in $(seq 10); do                      # 10 выборок с интервалом 1 с — для учета медленного запуска
  nvidia-smi --query-gpu=utilization.gpu,memory.used --format=csv,noheader
  sleep 1
done
wait "$WORKLOAD"
rm -rf "$TMPDIR_GPU"

Ожидается, что показатель memory.used в большинстве выборок будет в диапазоне GiB, а показатель utilization.gpu — в нескольких выборок будет значительным. Если оба показателя остаются на базовом уровне во всех выборках, значит, вариант с GPU не установлен — проверьте conda list cupynumeric на наличие *_gpu (а не *_cpu).

Более подробные инструкции

См. файл verification_examples.md для проверок работы с несколькими GPU, переключения на CPU, работы в контейнерах и устранения неполадок.

Ограничения

• Не смешивайте conda и pip в одной среде. Смешивание приводит к переопределению первой установки и сбоям при импорте. Чтобы переключиться, сначала запустите pip uninstall nvidia-cupynumeric или conda remove cupynumeric.
• Используйте запускатель legate для запусков с несколькими GPU или в многоранговом режиме. Обычный Python запускается в однопроцессном режиме: legate --gpus 2 script.py.
• Принудительно включите вариант для GPU на хосте, использующем только ЦП, с помощью CONDA_OVERRIDE_CUDA. В противном случае conda автоматически выбирает вариант для ЦП или GPU на основе данных nvidia-smi во время установки.
• Требуется Volta или более поздняя версия. Pascal (GTX 10xx / P100) не поддерживается.
• Убедитесь, что версия conda --version ≥ 24.1. Более старые версии незаметно нарушают выбор варианта.
• Рассматривайте многоузловые системы / MPI / UCX как выходящие за рамки данного руководства. Обратитесь к документации по https://docs.nvidia.com/legate/latest/networking-wheels.html и https://docs.nvidia.com/legate/latest/mpi-wrapper.html.

Устранение неполадок

• ModuleNotFoundError: Нет модуля с именем 'cupynumeric' → Запустите which python и pip list | grep cupynumeric (или conda list | grep cupynumeric) в том же терминале, чтобы найти несоответствие среды.
• ImportError с упоминанием CUDA / libcudart → Переустановите с параметром CONDA_OVERRIDE_CUDA=""; используется версия для ЦП на системе с GPU или версии CUDA не совпадают.
• legate: команда не найдена → Активируйте среду, затем выполните команду `which legate ` для подтверждения.
• Работает медленнее, чем NumPy на ноутбуке → Это нормально для небольших задач (накладные расходы Legate на каждую задачу). См. FAQ по cuPyNumeric.

См. также

• references/verification_examples.md — примеры проверки и устранения неполадок.
• Документация исходного проекта: https://docs.nvidia.com/cupynumeric/latest/installation.html
• Требования к Legate: https://docs.nvidia.com/legate/latest/installation.html