چیت‌شیت

محیط توسعه پایتون برای هوش مصنوعی

Python Dev Environment for AI

نصب uv، ساخت یک venv برای هر پروژه، پین کردن با فایل‌های قفل، بررسی مسیر، تنظیم VS Code و جلوگیری از باگ‌های پنهان پایتون.

  • ۱۲ بخش
  • ۴ درس مرتبط
  • کد و دستورها عیناً از دوره‌ی اصلی
فهرست مطالب
  1. استک چهارلایه
  2. نصب زنجیره ابزار
  3. ساخت یک محیط مجازی
  4. ‏pyproject.toml همراه با extras
  5. بررسی مسیر
  6. نصب PyTorch و بررسی GPU
  7. تنظیمات VS Code
  8. عیب‌یابی
  9. باگ‌های پنهان پایتون
  10. پرسش‌ها
  11. نکات
  12. دستورات ویرایشگر و SSH

استک چهارلایه

معماری
اول نصب شود1. زیرساخت سیستمسیستم‌عامل، شل، git، ویرایشگر، درایورهای GPU2. مدیران بستهuv، pnpm، cargo، juliaup3. محیط‌های اجرای زبان‌هاپایتون 3.11+، نود 20+، Rust، Julia4. کتابخانه‌های هوش مصنوعی / یادگیری ماشینPyTorch، JAX، transformers

نصب زنجیره ابزار

دستورها
دستورعملکرد
xcode-select --installابزارهای بیلد و git در macOS
sudo apt install -y build-essential git curl wget unzipابزارهای پایه در اوبونتو یا دبیان
wsl --install -d Ubuntu-24.04ویندوز: استفاده از WSL2
curl -LsSf https://astral.sh/uv/install.sh \| shنصب uv
uv python install 3.12نصب پایتون 3.12
`fnm install 22` then `fnm use 22`‏Node.js 22 برای درس‌های تایپ‌اسکریپت
npm install -g pnpmنصب pnpm

ساخت یک محیط مجازی

کار و کد
وظیفهکد
‏uv venv (پیشنهادی)`uv venv` then `source .venv/bin/activate`
پروژه جدید با pyproject.toml`uv init my-ai-project` then `uv add torch numpy matplotlib`
‏venv پیش‌فرض پایتونpython3 -m venv .venv
فعال‌سازی در ویندوز.venv\Scripts\activate
محیط Conda`conda create -n myproject python=3.12` then `conda activate myproject`
نصب یک گروه extrauv pip install -e ".[torch,llm]"
ساخت فایل قفلuv pip compile pyproject.toml -o requirements.lock
نصب از روی فایل قفلuv pip install -r requirements.lock

‏pyproject.toml همراه با extras

کد
toml
[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"]  # uv pip install -e ".[torch]"
llm = ["anthropic>=0.39", "openai>=1.50"]    # uv pip install -e ".[llm]"

بررسی مسیر

دستورها
دستورعملکرد
verify.py --route beginnerمسیر پیش‌فرض. نیازمند python و git
--route ml-foundationsهمچنین نیازمند numpy
--route agent-skillsنیازمند python، git، node و npx
`--route llm-engineering`, `agents`, `mcp`, `certification`نیازمند python و git
--show-laterبررسی ابزارهای اختیاری و مراحل بعدی
`[PASS]`, `[FAIL]`, `[LATER]`وضعیت هر آزمون ارزیابی. کد خروج 1 در صورت FAIL
bash .../code/env_setup.shساخت .venv در ریشه مخزن و اعتبارسنجی آن

نصب PyTorch و بررسی GPU

کد
bash
nvidia-smi                                           # نسخه CUDA درایور
uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
uv pip install torch torchvision torchaudio          # ‏macOS: بیلد استاندارد با MPS
python -c "import torch; print(torch.version.cuda)"  # نسخه CUDA در PyTorch
python -c "import torch; print(torch.__version__)"   # نصب موفقیت‌آمیز بود
which python                                         # باید .venv/bin/python را نشان دهد

تنظیمات VS Code

پیش‌فرض‌ها
تنظیمپیش‌فرضیادداشت
python.analysis.typeCheckingMode"basic"شناسایی تایپ‌های اشتباه آرگومان‌ها قبل از اجرا
editor.formatOnSavetrueفرمت با Black در هر بار ذخیره
black-formatter.args["--line-length", "88"]شکستن خطوط Black در طول 88
editor.rulers[88, 120]علامت‌گذاری docstringهای طولانی در 120
notebook.output.scrollingtrueکوچک نگه‌داشتن خروجی طولانی آموزش
files.autoSave"afterDelay"مقدار files.autoSaveDelay برابر 1000 است
terminal.integrated.scrollback10000تعداد خطوط ذخیره‌شده در ترمینال
ruff.lint.run"onSave"بررسی Ruff در هر بار ذخیره

عیب‌یابی

عیب‌یابی
  • نبود بسته‌ها هنگام اجرا

    علت
    محیط venv فعال نیست
    راه‌حل
    source .venv/bin/activate
  • ‏which python مسیر /usr/bin/python را نشان می‌دهد

    علت
    نصب در سطح سیستم (سراسری)
    راه‌حل
    فعال‌سازی و سپس نصب مجدد
  • خراب شدن محیط Conda

    علت
    ترکیب pip install درون conda
    راه‌حل
    اول Conda، بسته‌های pip در انتها
  • عدم استفاده از GPU

    علت
    نسخه CUDA در PyTorch بالاتر از نسخه درایور است
    راه‌حل
    نسخه CUDA در PyTorch باید <= نسخه درایور باشد
  • خطای نصب Torch در مک

    علت
    ویل‌های --index-url .../cuXXX
    راه‌حل
    نصب بیلد استاندارد
  • Not installing fnm due to missing dependencies.

    علت
    نبود unzip
    راه‌حل
    sudo apt install -y unzip
  • Cannot install under Rosetta 2

    علت
    اجرای ترمینال با معماری i386
    راه‌حل
    arch -arm64 brew install fnm
  • دستور code در macOS یافت نشد

    علت
    دستور شل در PATH نیست
    راه‌حل
    گزینه "Install 'code' command in PATH"

باگ‌های پنهان پایتون

کد
python
independent = list(weights)                          # انتساب کپی نمی‌کند
grid = [[0] * 3 for _ in range(2)]                   # نه [[0] * 3] * 2
def add_good(item, bucket=None): ...                 # هرگز bucket=[] قرار ندهید
hidden: list[int] = field(default_factory=lambda: [64, 32])
random.Random(seed).shuffle(order)                   # ژنراتور اختصاصی
sum(x * y for x, y in zip(a, b, strict=True))        # خطای ValueError در عدم تطابق طول
for epoch in range(2):
    sizes = [len(b) for b in batches(range(10), 4)]  # ژنراتور جدید در هر epoch
raise ValueError(f"label must be an integer, got {text!r}") from None
if __name__ == "__main__":                           # تست‌ها بدون دموی اصلی import می‌شوند

پرسش‌ها

پرسش و پاسخ
یک محیط برای کل دوره؟
خیر. فازها وابستگی‌های متداخل دارند. از استراتژی تفکیک به ازای هر فاز استفاده کنید.
چه زمانی از conda استفاده کنیم؟
برای CUDA toolkit بدون نصب سیستمی، یا روی سرورهای اشتراکی.
فایل‌های .venv را commit کنیم؟
خیر. .venv/ را به .gitignore اضافه کنید. فقط pyproject.toml و فایل قفل را commit کنید.
عدم وجود CUDA در مک؟
طبیعی است. در مک از بک‌اند MPS برای گرافیک اپل استفاده می‌شود.
چرا ترکیب (3, 2) با (3,) خطا می‌دهد؟
ابعاد انتهایی 2 و 3 متفاوتند. از keepdims=True استفاده کنید.

نکات

نکته‌ها
  • تمام دستورات درس‌ها را از ریشه مخزن اجرا کنید.
  • قبل از رفتن به خط بعد، اولین خطای تست مقدماتی را برطرف کنید.
  • ابزارهای مراحل بعدی را فقط زمانی نصب کنید که در درس خواسته شود.
  • هنگام باز کردن هر فایل encoding="utf-8" بدهید. فایل‌های CSV را با newline="" باز کنید.
  • داده‌ها را قبل از استانداردسازی تفکیک کنید. آمارها را فقط روی داده‌های train برازش دهید.

دستورات ویرایشگر و SSH

دستورها
دستورعملکرد
code --install-extension <id>نصب یک اکستنشن با ID
code --list-extensionsفهرست ID اکستنشن‌های نصب‌شده
ssh-keygen -t ed25519 -C "<email>"ساخت کلید SSH
ssh-copy-id user@your-gpu-box-ipورود بدون رمز عبور به سیستم GPU
Remote-SSH: Connect to Hostباز کردن پوشه ریموت به‌صورت محلی
watch -n 1 nvidia-smiمانیتور GPU در یک ترمینال مجزا