Medii Python

Iadul dependențelor este real. Mediile virtuale sunt remediul.

Tip: Construire Limbaje: Shell Cerințe preliminare: Faza 0, lecția 01 Durată: ~30 de minute

Obiective de învățare

• Crearea unor medii virtuale izolate cu uv, venv sau conda
• Scrierea unui fișier pyproject.toml cu grupuri opționale de dependențe și generarea fișierelor lock pentru reproductibilitate
• Diagnosticarea și remedierea problemelor frecvente: instalări globale, combinarea pip cu conda și incompatibilități între versiunile CUDA
• Implementarea unei strategii de medii separate pentru fiecare fază în proiecte cu dependențe incompatibile

Problema

Instalați PyTorch 2.4 pentru un proiect de ajustare fină (fine-tuning). Săptămâna următoare, un alt proiect necesită PyTorch 2.1, deoarece versiunea sa compilată pentru CUDA este fixată. Faceți upgrade global, iar primul proiect nu mai funcționează. Faceți downgrade, iar al doilea proiect nu mai funcționează.

Acesta este iadul dependențelor. Apare permanent în proiectele de IA și învățare automată (ML), deoarece:

• PyTorch, JAX și TensorFlow includ fiecare propriile binding-uri CUDA
• Bibliotecile de modele fixează anumite versiuni ale frameworkurilor
• O comandă globală pip install suprascrie ceea ce era instalat înainte
• Versiunile compilate pentru CUDA 11.8 nu funcționează cu driverele CUDA 12.x (și invers)

Soluția: fiecare proiect primește propriul mediu izolat, cu propriile pachete.

Conceptul

Configurarea mediului

Opțiunea 1: uv venv (recomandată)

uv este cel mai rapid manager de pachete Python (de 10–100 de ori mai rapid decât pip). Gestionează mediile virtuale, versiunile Python și rezolvarea dependențelor într-un singur instrument.

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

uv python install 3.12

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

Instalați pachetele:

uv pip install torch numpy

Creați dintr-un singur pas un proiect cu pyproject.toml:

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

Opțiunea 2: venv (inclus în Python)

Dacă nu puteți instala uv, Python include venv:

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

pip install torch numpy

Este mai lent decât uv, dar funcționează oriunde este instalat Python.

Opțiunea 3: conda (când aveți nevoie de el)

Conda gestionează dependențe care nu sunt Python, precum seturile de instrumente CUDA, cuDNN și bibliotecile C. Utilizați-l atunci când:

• Aveți nevoie de o anumită versiune a setului de instrumente CUDA fără a o instala la nivelul întregului sistem
• Lucrați pe un cluster partajat pe care nu puteți instala pachete de sistem
• Instrucțiunile de instalare ale unei biblioteci spun „use 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

O singură regulă: dacă folosiți conda pentru un mediu, folosiți conda pentru toate pachetele din acel mediu. Utilizarea comenzii pip install într-un mediu conda provoacă conflicte între dependențe, care sunt dificil de depanat.

Pentru acest curs: strategie separată pentru fiecare fază

Ați putea crea un singur mediu pentru întregul curs. Nu faceți acest lucru. Fazele diferite au nevoie de dependențe diferite și, uneori, incompatibile.

Strategie:

ai-engineering-from-scratch/
├── .venv/                    <-- mediu comun minimal pentru fazele 0–3
├── phases/
│   ├── 04-neural-networks/
│   │   └── .venv/            <-- mediu PyTorch
│   ├── 05-cnns/
│   │   └── .venv/            <-- același mediu PyTorch (legătură simbolică sau mediu partajat)
│   ├── 08-transformers/
│   │   └── .venv/            <-- poate necesita versiuni diferite ale bibliotecii transformers
│   └── 11-llm-apis/
│       └── .venv/            <-- SDK-uri API, fără torch

Scriptul din code/env_setup.sh pregătește mediul de bază pentru acest curs.

Noțiuni de bază despre pyproject.toml

Fiecare proiect Python ar trebui să aibă un fișier pyproject.toml. Acesta înlocuiește setup.py, setup.cfg și requirements.txt cu un singur fișier.

[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"]

Apoi instalați:

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

Fișiere lock

Un fișier lock (lockfile) fixează fiecare dependență, inclusiv dependențele tranzitive, la o versiune exactă. Astfel este garantată reproductibilitatea: pornind de la fișierul lock, oricine obține exact aceleași pachete.

# 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

Includeți fișierul lock într-un commit Git. După clonarea depozitului, pachetele sunt instalate pe baza fișierului lock și au versiuni identice.

Greșeli frecvente

1. Instalarea globală

pip install torch  # BAD: installs to system Python

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

Verificați unde sunt instalate pachetele:

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

2. Combinarea pip cu 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

Dacă trebuie să utilizați pip în conda, deoarece unele pachete sunt disponibile numai prin pip, instalați mai întâi toate pachetele conda, apoi pachetele pip la final.

3. Omiterea activării

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

Promptul shell-ului ar trebui să afișeze numele mediului:

(.venv) $ python train.py

4. Adăugarea directorului .venv în Git

echo ".venv/" >> .gitignore

Mediile virtuale ocupă între 200 MB și 2 GB. Sunt locale și nu sunt portabile între calculatoare. Includeți în commit pyproject.toml și fișierul lock în locul lor.

5. Incompatibilitatea între versiunile 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.

Utilizarea mediului

Rulați scriptul de configurare pentru a crea mediul cursului:

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

Acesta pregătește un director .venv în rădăcina depozitului, cu dependențele de bază instalate și verificate.

Exerciții

1. Rulați env_setup.sh și verificați că toate verificările se finalizează cu succes
2. Creați un al doilea mediu virtual, instalați în el o versiune diferită de numpy și confirmați că cele două medii sunt izolate
3. Scrieți un fișier pyproject.toml pentru un proiect care necesită atât PyTorch, cât și SDK-ul Anthropic
4. Instalați intenționat un pachet la nivel global, fără să activați un mediu virtual, observați unde este instalat, apoi dezinstalați-l

Termeni-cheie

Termen	Formulare uzuală	Ce înseamnă de fapt
Mediu virtual	„Un venv”	Un director izolat care conține un interpretor Python și pachete, separat de Python-ul de sistem
Fișier lock	„Dependențe cu versiuni fixate”	Un fișier care enumeră fiecare pachet și versiunea sa exactă, garantând instalări identice pe calculatoare diferite
pyproject.toml	„Noul setup.py”	Fișierul standard de configurare a proiectelor Python, care înlocuiește setup.py/setup.cfg/requirements.txt
Dependență tranzitivă	„O dependență a unei dependențe”	Pachetul B depinde de C; dacă instalați A, care depinde de B, atunci C este o dependență tranzitivă a lui A
Incompatibilitate CUDA	„GPU-ul meu nu funcționează”	PyTorch a fost compilat pentru o versiune CUDA diferită de cea acceptată de driverul GPU

---

Sursă: Python Environments — original Navigare: înapoi: 00.05 — Notebookuri Jupyter · Faza 0 — Configurare și instrumente · Catalog complet · înainte: 00.07 — Docker pentru IA.