Phase 00 - Lesson 06

Ambientes Python

O inferno de dependências é real. Ambientes virtuais são a cura.

Tipo: Build Linguagens: Python Pré-requisitos: Fase 0, Lição 01 Tempo: ~30 minutos

Objetivos de Aprendizagem

• Criar ambientes virtuais isolados usando uv, venv ou conda
• Escrever um pyproject.toml com grupos de dependências opcionais e gerar lockfiles para reprodutibilidade
• Diagnosticar e corrigir armadilhas comuns: instalações globais, mistura de pip/conda, incompatibilidades de versão do CUDA
• Implementar uma estratégia de ambiente por fase para projetos com dependências conflitantes

O Problema

Você instala o PyTorch 2.4 para um projeto de fine-tuning. Na semana seguinte, um projeto diferente precisa do PyTorch 2.1 porque o build de CUDA dele está fixado. Você atualiza globalmente e o primeiro projeto quebra. Você faz o downgrade e o segundo quebra.

Isso é o inferno de dependências. Acontece o tempo todo no trabalho com IA/ML porque:

• PyTorch, JAX e TensorFlow cada um traz seus próprios bindings de CUDA
• Bibliotecas de modelos fixam versões específicas de frameworks
• Um pip install global sobrescreve o que estava lá antes
• Builds de CUDA 11.8 não funcionam com drivers de CUDA 12.x (e vice-versa)

A correção: todo projeto ganha seu próprio ambiente isolado com seus próprios pacotes.

O Conceito

graph TD
    subgraph without["Without virtual environments"]
        SP[System Python] --> T24["torch 2.4.0 (CUDA 12.4)
Project A needs this"]
        SP --> T21["torch 2.1.0 (CUDA 11.8)
Project B needs this"]
        SP --> CONFLICT["CONFLICT: only one
torch version can exist"]
    end

    subgraph with["With virtual environments"]
        PA["Project A (.venv/)"] --> PA1["torch 2.4.0 (CUDA 12.4)"]
        PA --> PA2["transformers 4.44"]
        PB["Project B (.venv/)"] --> PB1["torch 2.1.0 (CUDA 11.8)"]
        PB --> PB2["diffusers 0.28"]
    end

Build It

Opção 1: uv venv (Recomendado)

uv é o gerenciador de pacotes Python mais rápido (10-100x mais rápido que o pip). Ele lida com ambientes virtuais, versões do Python e resolução de dependências em uma única ferramenta.

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

uv python install 3.12

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

Instale pacotes:

uv pip install torch numpy

Crie um projeto com pyproject.toml em um passo:

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

Opção 2: venv (Embutido)

Se você não puder instalar o uv, o Python já vem com o venv:

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

pip install torch numpy

Mais lento que o uv, mas funciona em qualquer lugar onde o Python esteja instalado.

Opção 3: conda (Quando você precisa)

O conda gerencia dependências não-Python como toolkits de CUDA, cuDNN e bibliotecas C. Use-o quando:

• Você precisar de uma versão específica do toolkit de CUDA sem instalá-la em todo o sistema
• Você estiver em um cluster compartilhado onde não pode instalar pacotes do sistema
• As instruções de instalação de uma biblioteca disserem "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

Uma regra: se você usar conda para um ambiente, use conda para todos os pacotes desse ambiente. Misturar pip install em um ambiente conda causa conflitos de dependência dolorosos de depurar.

Para Este Curso: Estratégia por Fase

Você poderia criar um único ambiente para o curso inteiro. Não faça isso. Fases diferentes precisam de dependências diferentes (às vezes conflitantes).

Estratégia:

ai-engineering-from-scratch/
├── .venv/                    <-- shared lightweight env for phases 0-3
├── phases/
│   ├── 04-neural-networks/
│   │   └── .venv/            <-- PyTorch env
│   ├── 05-cnns/
│   │   └── .venv/            <-- same PyTorch env (symlink or shared)
│   ├── 08-transformers/
│   │   └── .venv/            <-- might need different transformer versions
│   └── 11-llm-apis/
│       └── .venv/            <-- API SDKs, no torch needed

O script em code/env_setup.sh cria o ambiente base para este curso.

Fundamentos do pyproject.toml

Todo projeto Python deveria ter um pyproject.toml. Ele substitui setup.py, setup.cfg e requirements.txt em um único arquivo.

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

Depois instale:

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

Lockfiles

Um lockfile fixa cada dependência (incluindo as transitivas) em versões exatas. Isso garante reprodutibilidade: qualquer um que instale a partir do lockfile recebe exatamente os mesmos pacotes.

# 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

Commite seu lockfile no git. Quando alguém clonar o repositório, instalará a partir do lockfile e obterá versões idênticas.

Erros Comuns

1. Instalar globalmente

pip install torch  # BAD: installs to system Python

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

Verifique para onde seus pacotes vão:

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

2. Misturar pip e 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

Se você precisar usar pip dentro do conda (alguns pacotes são só de pip), instale primeiro todos os pacotes conda e depois os pacotes pip por último.

3. Esquecer de ativar

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

O prompt do seu shell deve mostrar o nome do ambiente:

(.venv) $ python train.py

4. Commitar o .venv no git

echo ".venv/" >> .gitignore

Ambientes virtuais têm de 200MB a 2GB. São locais, não portáteis entre máquinas. Commite o pyproject.toml e o lockfile em vez disso.

5. Incompatibilidade de versão do 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.

Use It

Execute o script de setup para criar o ambiente do seu curso:

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

Isso cria um .venv na raiz do repositório com as dependências principais instaladas e verificadas.

Exercícios

1. Execute o env_setup.sh e verifique se todas as checagens passam
2. Crie um segundo ambiente virtual, instale uma versão diferente do numpy nele e confirme que os dois ambientes estão isolados
3. Escreva um pyproject.toml para um projeto que precise tanto do PyTorch quanto do Anthropic SDK
4. Instale deliberadamente um pacote globalmente (sem ativar um venv), repare para onde ele vai e depois desinstale-o

Termos-chave