Установка и настройка

Базовая настройка Python-интерпретатора и PyTorch-бэкендов для корректной работы проекта.

1. Фиксация версии Python (обязательно)

Проект поддерживает диапазон >=3.10, !=3.11.*, <3.13, но в реальной работе всегда фиксируется одна конкретная версия для воспроизводимости.

uv python pin 3.12   # создает/обновляет .python-version

Файл .python-version хранится в корне репозитория и читается uv, pyenv, asdf и другими инструментами.

Смена версии Python

# Обновляем pin
uv python pin 3.10

# Пересчитываем lock и переустанавливаем окружение
uv lock --extra cu124
uv sync --extra cu124

2. Выбор PyTorch backend (обязательно)

В проекте предусмотрены два CUDA-бэкенда:

Extra	CUDA	Описание
cu124	12.4 + cuDNN	Стабильная версия, рекомендуется
cu128	12.8 + cuDNN	Новейшая версия

Установка с выбранным backend

uv sync --extra cu124   # CUDA 12.4
uv sync --extra cu128   # CUDA 12.8

⚠️ Важно: обычный uv sync без --extra завершится ошибкой. PyTorch загружается только из официальных репозиториев https://download.pytorch.org/whl.

Проверка установки

# Проверить без изменения lock-файла
uv sync --check

# Проверить версии PyTorch
uv run python -c "import torch; print(f'PyTorch: {torch.__version__}, CUDA: {torch.version.cuda}')"

3. Быстрое переключение через переменную окружения

export UV_TORCH_BACKEND=cu128
uv sync --locked

Удобно для экспериментов, но для стабильной работы лучше использовать явный --extra.

4. Режимы работы (Profiles)

В проекте настроены три независимых окружения с помощью uv workspaces.

• Dev (по умолчанию): Пакеты в packages/ подключаются как редактируемые (editable). Используется текущий pyproject.toml.
• Staging: Используется для промежуточного тестирования. Внутренние пакеты фиксируются на dev-теги.
• Prod: Использует фиксированные стабильные версии пакетов (git tags).

Команды для переключения режимов

# Staging
uv lock --project staging
uv sync --project staging --extra cu124 --frozen

# Prod
uv lock --project prod
uv sync --project prod --extra cu124 --frozen

5. Чек-лист первичной настройки

1. Клонируем с submodules:

   git clone --recursive https://github.com/VLMHyperBenchTeam/vlmhyperbench_playground.git

2. Фиксируем Python:

   uv python pin 3.12

3. Выбираем CUDA и устанавливаем:

   uv sync --extra cu124

4. Проверяем работу:

   uv run python -c "import torch; print('OK')"

---

💡 Частые проблемы:

• uv sync без --extra → ошибка PyTorch
• Забыли uv python pin → разные версии Python в команде
• Не инициализированы submodules → отсутствуют пакеты в packages/