Environment Pinning: uv + pyproject.toml, CUDA Version Matrix, and Container Recipes

# === FTC Lab başlangıç sequence'i (her ders için aynı) ===
mkdir ftc-ders-XX && cd ftc-ders-XX
 
# 1. pyproject.toml oluştur (Python 3.11 — cookbook standart)
uv init --python 3.11
 
# 2. Bağımlılıkları ekle — RTX 4090 + CUDA 12.4 stack
uv add torch==2.5.1 --index https://download.pytorch.org/whl/cu124
uv add transformers==4.46.3
uv add accelerate==1.1.1
uv add peft==0.13.2
uv add trl==0.12.2
uv add bitsandbytes==0.44.1
uv add datasets==3.1.0
uv add tokenizers==0.20.3
uv add tensorboard wandb
 
# 3. Dev araçları
uv add --dev pytest ruff mypy
 
# 4. Run — uv otomatik venv ile çalıştırır
uv run python train.py
 
# Sonuç: uv.lock dosyası — tüm bağımlılıkları **tam hash** ile pinler
cat uv.lock | head -20

# === pyproject.toml: cookbook'un her Lab'ı için baseline ===
[project]
name = "ftc-lab-template"
version = "0.1.0"
description = "Fine-Tuning Cookbook Lab — RTX 4090 baseline"
requires-python = ">=3.11,<3.13"
 
dependencies = [
  # Core
  "torch==2.5.1",                # CUDA 12.4 wheel
  "transformers==4.46.3",        # Llama 3.3, Qwen 2.5, Gemma 3 desteği
  "accelerate==1.1.1",
  "peft==0.13.2",                # LoRA, QLoRA, DoRA
  "trl==0.12.2",                 # SFTTrainer, DPOTrainer, GRPOTrainer
  "bitsandbytes==0.44.1",        # NF4, 8-bit AdamW
  "datasets==3.1.0",
  "tokenizers==0.20.3",
  "sentencepiece>=0.2.0",
  "safetensors>=0.4.5",
  "huggingface_hub>=0.26.0",
 
  # Optimization
  "flash-attn==2.7.0.post2",     # binary wheel için cu124 zorunlu
  "xformers==0.0.28.post3",
  "ninja",                       # CUDA kernel build için
 
  # Tracking & evaluation
  "tensorboard>=2.18",
  "wandb>=0.18",
  "lm-eval==0.4.5",              # benchmark
  "evaluate>=0.4.3",
  "rouge-score",
  "sacrebleu",
 
  # Utility
  "tyro>=0.9",                   # CLI parsing (Llama-Factory'nin de tercih ettiği)
  "hydra-core>=1.3",             # config management
  "pydantic>=2.9",
]
 
[project.optional-dependencies]
unsloth = ["unsloth==2024.11", "unsloth-zoo==2024.11"]
serving = ["vllm==0.6.4.post1", "sglang==0.3.4"]
quant = ["auto-gptq==0.7.1", "autoawq==0.2.6"]
 
[tool.uv]
# RTX 4090 + cu124 wheel index
extra-index-url = ["https://download.pytorch.org/whl/cu124"]
 
[tool.ruff]
line-length = 100
target-version = "py311"

# === FTC.Dockerfile — Fine-Tuning Cookbook standart container ===
# Base: NVIDIA CUDA 12.4 + cuDNN + Ubuntu 22.04
FROM nvidia/cuda:12.4.1-cudnn-devel-ubuntu22.04
 
ENV DEBIAN_FRONTEND=noninteractive \
    PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1 \
    CUBLAS_WORKSPACE_CONFIG=:4096:8 \
    HF_HUB_ENABLE_HF_TRANSFER=1
 
# System libs
RUN apt-get update && apt-get install -y --no-install-recommends \
    python3.11 python3.11-venv python3-pip \
    git git-lfs curl wget tini build-essential \
    libgl1 libglib2.0-0 && \
    rm -rf /var/lib/apt/lists/*
 
# uv
RUN curl -LsSf https://astral.sh/uv/install.sh | sh && \
    mv /root/.local/bin/uv /usr/local/bin/uv
 
# Workdir
WORKDIR /workspace
 
# Bağımlılıkları ayrı bir layer'da pin'le — image caching için optimize
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev
 
# Source code
COPY . .
 
# Defaults
ENV TRANSFORMERS_CACHE=/workspace/.cache/huggingface \
    HF_HOME=/workspace/.cache/huggingface
 
ENTRYPOINT ["/usr/bin/tini", "--"]
CMD ["uv", "run", "python", "train.py"]