Окружения Python

Ад зависимостей существует. Виртуальные окружения — лекарство от него.

Тип: Практика Языки: Shell Предварительные требования: Фаза 0, урок 01 Время: около 30 минут

Цели обучения

• Создавать изолированные виртуальные окружения с помощью uv, venv или conda.
• Составлять pyproject.toml с необязательными группами зависимостей и создавать lock-файлы для воспроизводимости.
• Диагностировать и устранять распространённые проблемы: глобальные установки, смешивание pip и conda, несовпадение версий CUDA.
• Реализовать стратегию отдельных окружений для фаз проекта с конфликтующими зависимостями.

Проблема

Для проекта тонкой настройки вы устанавливаете PyTorch 2.4. Через неделю другому проекту требуется PyTorch 2.1, потому что его сборка привязана к определённой версии CUDA. Вы глобально обновляете PyTorch — и первый проект ломается. Понижаете версию — ломается второй.

Это ад зависимостей. В работе с AI и машинным обучением он встречается постоянно, потому что:

• PyTorch, JAX и TensorFlow поставляются со своими привязками к CUDA;
• библиотеки моделей закрепляют определённые версии фреймворков;
• глобальный pip install перезаписывает ранее установленную версию;
• сборки для CUDA 11.8 не работают с драйверами CUDA 12.x, и наоборот.

Решение: каждый проект получает собственное изолированное окружение со своими пакетами.

[!note] Примечание переводчика Утверждения о совместимости CUDA и рекомендуемых способах установки сохранены из исходной ревизии от 25 июня 2026 года. Перед подбором сборки сверяйтесь с актуальными матрицами совместимости PyTorch, CUDA и драйвера NVIDIA.

Концепция

Собираем сами

Вариант 1. uv venv — рекомендуется

uv — быстрый менеджер пакетов Python, работающий в 10–100 раз быстрее pip. Один инструмент управляет виртуальными окружениями, версиями Python и разрешением зависимостей.

curl -LsSf https://astral.sh/uv/install.sh | sh

uv python install 3.12

cd your-project
uv venv
source .venv/bin/activate

Установите пакеты:

uv pip install torch numpy

Создайте проект с pyproject.toml одной последовательностью команд:

uv init my-ai-project
cd my-ai-project
uv add torch numpy matplotlib

Вариант 2. venv — встроенный инструмент

Если установить uv невозможно, Python поставляется с venv:

python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

pip install torch numpy

Он медленнее uv, но работает везде, где установлен Python.

Вариант 3. conda — когда она действительно нужна

Conda управляет не относящимися к Python зависимостями: наборами инструментов CUDA, cuDNN и библиотеками C. Используйте её, когда:

• нужна определённая версия CUDA Toolkit без общесистемной установки;
• вы работаете в общем кластере, где нельзя устанавливать системные пакеты;
• в инструкции библиотеки прямо сказано использовать conda.

# Install miniconda (not the full Anaconda)
curl -LsSf https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -o miniconda.sh
bash miniconda.sh -b

conda create -n myproject python=3.12
conda activate myproject

conda install pytorch torchvision torchaudio pytorch-cuda=12.4 -c pytorch -c nvidia

Одно правило: если для окружения используется conda, устанавливайте через неё все пакеты этого окружения. Смешивание pip install с conda приводит к конфликтам зависимостей, которые трудно отлаживать.

Для этого курса: стратегия окружения на каждую фазу

Можно было бы создать одно окружение для всего курса. Не делайте этого. Разным фазам требуются разные, иногда конфликтующие зависимости.

Стратегия:

ai-engineering-from-scratch/
├── .venv/                    <-- общее лёгкое окружение для фаз 0–3
├── phases/
│   ├── 04-neural-networks/
│   │   └── .venv/            <-- окружение PyTorch
│   ├── 05-cnns/
│   │   └── .venv/            <-- то же окружение PyTorch (ссылка или общее)
│   ├── 08-transformers/
│   │   └── .venv/            <-- могут потребоваться другие версии transformers
│   └── 11-llm-apis/
│       └── .venv/            <-- SDK для API, torch не нужен

Скрипт code/env_setup.sh создаёт базовое окружение для этого курса.

Основы pyproject.toml

У каждого проекта Python должен быть pyproject.toml. Один этот файл заменяет setup.py, setup.cfg и requirements.txt.

[project]
name = "ai-engineering-from-scratch"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "numpy>=1.26",
    "matplotlib>=3.8",
    "jupyter>=1.0",
    "scikit-learn>=1.4",
]

[project.optional-dependencies]
torch = ["torch>=2.3", "torchvision>=0.18"]
llm = ["anthropic>=0.39", "openai>=1.50"]

Затем установите зависимости:

uv pip install -e ".[torch]"    # base + PyTorch
uv pip install -e ".[llm]"     # base + LLM SDKs
uv pip install -e ".[torch,llm]" # everything

Lock-файлы

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

# uv generates uv.lock automatically when using uv add
uv add numpy

# pip-tools approach
uv pip compile pyproject.toml -o requirements.lock
uv pip install -r requirements.lock

Добавляйте lock-файл в Git. После клонирования репозитория другой пользователь установит зависимости из этого файла и получит идентичные версии.

Распространённые ошибки

1. Глобальная установка

pip install torch  # BAD: installs to system Python

source .venv/bin/activate
pip install torch  # GOOD: installs to virtual environment

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

which python       # should show .venv/bin/python, not /usr/bin/python
which pip           # should show .venv/bin/pip

2. Смешивание pip и conda

conda create -n myenv python=3.12
conda activate myenv
conda install pytorch -c pytorch
pip install some-other-package   # BAD: can break conda's dependency tracking
conda install some-other-package # GOOD: let conda manage everything

Если pip внутри conda всё же необходим, потому что некоторые пакеты доступны только через pip, сначала установите все пакеты conda и лишь затем — пакеты pip.

3. Забыли активировать окружение

python train.py           # uses system Python, missing packages
source .venv/bin/activate
python train.py           # uses project Python, packages found

В приглашении оболочки должно отображаться имя окружения:

(.venv) $ python train.py

4. Добавление .venv в Git

echo ".venv/" >> .gitignore

Виртуальные окружения занимают от 200 МБ до 2 ГБ. Они локальны и не переносятся между компьютерами. Вместо них добавляйте в репозиторий pyproject.toml и lock-файл.

5. Несовпадение версий CUDA

nvidia-smi                # shows driver CUDA version (e.g., 12.4)
python -c "import torch; print(torch.version.cuda)"  # shows PyTorch CUDA version

# These must be compatible.
# PyTorch CUDA version must be <= driver CUDA version.

Используем готовое

Запустите скрипт настройки, чтобы создать окружение курса:

bash phases/00-setup-and-tooling/06-python-environments/code/env_setup.sh

Он создаёт .venv в корне репозитория, устанавливает основные зависимости и проверяет их.

Упражнения

1. Запустите env_setup.sh и убедитесь, что все проверки пройдены.
2. Создайте второе виртуальное окружение, установите в него другую версию NumPy и убедитесь, что два окружения изолированы.
3. Напишите pyproject.toml для проекта, которому нужны PyTorch и Anthropic SDK.
4. Намеренно установите пакет глобально без активации venv, посмотрите, куда он попал, а затем удалите его.

Ключевые термины

Термин	Как обычно говорят	Что это означает на самом деле
Виртуальное окружение (virtual environment)	«venv»	Изолированный каталог с интерпретатором Python и пакетами, отделённый от системного Python
Lock-файл (lockfile)	«Закреплённые зависимости»	Файл со всеми пакетами и их точными версиями, гарантирующий одинаковую установку на разных компьютерах
pyproject.toml	«Новый setup.py»	Стандартный файл конфигурации проекта Python, заменяющий setup.py, setup.cfg и requirements.txt
Транзитивная зависимость	«Зависимость зависимости»	Пакет B зависит от C; если установить A, зависящий от B, то C будет транзитивной зависимостью A
Несовпадение CUDA	«Мой GPU не работает»	PyTorch скомпилирован для версии CUDA, отличающейся от поддерживаемой драйвером GPU

---

Источник: Python Environments — оригинал Навигация: назад: 00.05 — Блокноты Jupyter · Фаза 0 — Настройка и инструменты · Полный каталог · далее: 00.07 — Docker для AI.