چیتشیت
محیط توسعه پایتون برای هوش مصنوعی
Python Dev Environment for AI
نصب uv، ساخت یک venv برای هر پروژه، پین کردن با فایلهای قفل، بررسی مسیر، تنظیم VS Code و جلوگیری از باگهای پنهان پایتون.
فهرست مطالب
استک چهارلایه
معمارینصب زنجیره ابزار
دستورها| دستور | عملکرد |
|---|---|
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` |
| نصب یک گروه extra | uv 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.formatOnSave | true | فرمت با Black در هر بار ذخیره |
black-formatter.args | ["--line-length", "88"] | شکستن خطوط Black در طول 88 |
editor.rulers | [88, 120] | علامتگذاری docstringهای طولانی در 120 |
notebook.output.scrolling | true | کوچک نگهداشتن خروجی طولانی آموزش |
files.autoSave | "afterDelay" | مقدار files.autoSaveDelay برابر 1000 است |
terminal.integrated.scrollback | 10000 | تعداد خطوط ذخیرهشده در ترمینال |
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 در یک ترمینال مجزا |