AI-For-Beginners/translations/fa/AGENTS.md

AGENTS.md

نمای کلی پروژه

AI for Beginners یک برنامه آموزشی جامع ۱۲ هفته‌ای و ۲۴ درس است که اصول هوش مصنوعی را پوشش می‌دهد. این مخزن آموزشی شامل درس‌های عملی با استفاده از Jupyter Notebooks، آزمون‌ها و آزمایش‌های عملی است. این برنامه آموزشی موارد زیر را شامل می‌شود:

• هوش مصنوعی نمادین با نمایش دانش و سیستم‌های خبره
• شبکه‌های عصبی و یادگیری عمیق با TensorFlow و PyTorch
• تکنیک‌ها و معماری‌های بینایی کامپیوتری
• پردازش زبان طبیعی (NLP) شامل ترانسفورمرها و BERT
• موضوعات تخصصی: الگوریتم‌های ژنتیک، یادگیری تقویتی، سیستم‌های چندعاملی
• اصول اخلاق هوش مصنوعی و هوش مصنوعی مسئولانه

فناوری‌های کلیدی: Python 3، Jupyter Notebooks، TensorFlow، PyTorch، Keras، OpenCV، Vue.js (برای اپلیکیشن آزمون)

معماری: مخزن محتوای آموزشی با Jupyter Notebooks که بر اساس موضوعات سازماندهی شده است، همراه با یک اپلیکیشن آزمون مبتنی بر Vue.js و پشتیبانی گسترده چندزبانه.

دستورات راه‌اندازی

محیط توسعه اصلی (Python/Jupyter)

برنامه آموزشی برای اجرا با Python و Jupyter Notebooks طراحی شده است. روش پیشنهادی استفاده از miniconda است:

# Clone the repository
git clone https://github.com/microsoft/ai-for-beginners
cd ai-for-beginners

# Create and activate conda environment
conda env create --name ai4beg --file environment.yml
conda activate ai4beg

# Start Jupyter Notebook
jupyter notebook
# OR
jupyter lab

جایگزین: استفاده از devcontainer

# Open in VS Code and select "Reopen in Container" when prompted
# The devcontainer will automatically set up the environment

راه‌اندازی اپلیکیشن آزمون

اپلیکیشن آزمون یک اپلیکیشن جداگانه Vue.js است که در مسیر etc/quiz-app/ قرار دارد:

cd etc/quiz-app
npm install
npm run serve  # Development server
npm run build  # Production build
npm run lint   # Lint and fix files

جریان کاری توسعه

کار با Jupyter Notebooks

1. توسعه محلی:

   • فعال کردن محیط conda: conda activate ai4beg
   • شروع Jupyter: jupyter notebook یا jupyter lab
   • به پوشه‌های درس بروید و فایل‌های .ipynb را باز کنید
   • سلول‌ها را به صورت تعاملی اجرا کنید تا درس‌ها را دنبال کنید

2. VS Code با افزونه Python:

   • مخزن را در VS Code باز کنید
   • افزونه Python را نصب کنید
   • VS Code به طور خودکار محیط conda را شناسایی و استفاده می‌کند
   • فایل‌های .ipynb را مستقیماً در VS Code باز کنید

3. توسعه ابری:

   • GitHub Codespaces: روی "Code" → "Codespaces" → "Create codespace on main" کلیک کنید
   • Binder: از نشان Binder در README برای اجرا در مرورگر استفاده کنید
   • توجه: Binder منابع محدودی دارد و برخی محدودیت‌های دسترسی به وب اعمال می‌شود

پشتیبانی GPU برای درس‌های پیشرفته

درس‌های بعدی به طور قابل توجهی از شتاب GPU بهره‌مند می‌شوند:

• Azure Data Science VM: از VMهای سری NC با پشتیبانی GPU استفاده کنید
• Azure Machine Learning: از ویژگی‌های نوت‌بوک با محاسبات GPU استفاده کنید
• Google Colab: نوت‌بوک‌ها را به صورت جداگانه آپلود کنید (پشتیبانی رایگان GPU دارد)

توسعه اپلیکیشن آزمون

cd etc/quiz-app
npm run serve  # Hot-reload development server at http://localhost:8080

دستورالعمل‌های تست

این مخزن آموزشی بر محتوای یادگیری تمرکز دارد و نه تست نرم‌افزار. هیچ مجموعه تست سنتی وجود ندارد.

روش‌های اعتبارسنجی:

1. Jupyter Notebooks: سلول‌ها را به ترتیب اجرا کنید تا مطمئن شوید مثال‌های کد کار می‌کنند
2. تست اپلیکیشن آزمون: تست دستی از طریق سرور توسعه
3. اعتبارسنجی ترجمه: محتوای ترجمه شده در پوشه translations/ را بررسی کنید
4. Linting اپلیکیشن آزمون: npm run lint در etc/quiz-app/ اجرا کنید

اجرای مثال‌های کد:

# Activate environment first
conda activate ai4beg

# Run Python scripts directly
python lessons/4-ComputerVision/07-ConvNets/pytorchcv.py

# Or execute notebooks
jupyter notebook lessons/3-NeuralNetworks/03-Perceptron/Perceptron.ipynb

سبک کدنویسی

سبک کدنویسی Python

• کنوانسیون‌های استاندارد Python برای کد آموزشی
• کد واضح و خوانا که یادگیری را بر بهینه‌سازی اولویت می‌دهد
• توضیحات در کامنت‌ها برای مفاهیم کلیدی
• مناسب برای Jupyter Notebook: سلول‌ها باید تا حد امکان مستقل باشند
• هیچ الزامی برای linting سختگیرانه برای محتوای درس وجود ندارد

JavaScript/Vue.js (اپلیکیشن آزمون)

• پیکربندی ESLint در etc/quiz-app/package.json
• اجرای npm run lint برای بررسی و رفع خودکار مشکلات
• کنوانسیون‌های Vue 2.x
• معماری مبتنی بر کامپوننت

سازماندهی فایل‌ها

lessons/
  ├── 0-course-setup/          # Setup instructions
  ├── 1-Intro/                 # Introduction to AI
  ├── 2-Symbolic/              # Symbolic AI
  ├── 3-NeuralNetworks/        # Neural Networks basics
  ├── 4-ComputerVision/        # Computer Vision
  ├── 5-NLP/                   # Natural Language Processing
  ├── 6-Other/                 # Other AI techniques
  ├── 7-Ethics/                # AI Ethics
  └── X-Extras/                # Additional content

etc/
  ├── quiz-app/                # Vue.js quiz application
  └── quiz-src/                # Quiz source files

translations/                  # Multi-language translations

ساخت و استقرار

محتوای Jupyter

فرآیند ساخت لازم نیست - Jupyter Notebooks مستقیماً اجرا می‌شوند.

اپلیکیشن آزمون

cd etc/quiz-app

# Development
npm run serve

# Production build
npm run build  # Outputs to etc/quiz-app/dist/

# Deploy to Azure Static Web Apps
# Azure automatically creates GitHub Actions workflow
# See etc/quiz-app/README.md for detailed deployment instructions

سایت مستندات

این مخزن از Docsify برای مستندات استفاده می‌کند:

• index.html به عنوان نقطه ورود عمل می‌کند
• هیچ ساختی لازم نیست - مستقیماً از طریق GitHub Pages ارائه می‌شود
• دسترسی در: https://microsoft.github.io/AI-For-Beginners/

دستورالعمل‌های مشارکت

فرآیند Pull Request

1. فرمت عنوان: عناوین واضح و توصیفی که تغییر را توضیح می‌دهند
2. الزام CLA: باید توافق‌نامه Microsoft CLA امضا شود (بررسی خودکار)
3. دستورالعمل‌های محتوا:
   • تمرکز آموزشی و رویکرد مناسب برای مبتدیان را حفظ کنید
   • تمام مثال‌های کد در نوت‌بوک‌ها را تست کنید
   • اطمینان حاصل کنید که نوت‌بوک‌ها به صورت کامل اجرا می‌شوند
   • در صورت تغییر محتوای انگلیسی، ترجمه‌ها را به‌روزرسانی کنید
4. تغییرات اپلیکیشن آزمون: قبل از کامیت npm run lint را اجرا کنید

مشارکت در ترجمه‌ها

• ترجمه‌ها به صورت خودکار از طریق GitHub Actions با استفاده از co-op-translator انجام می‌شوند
• ترجمه‌های دستی در translations/<language-code>/ قرار می‌گیرند
• ترجمه‌های آزمون در etc/quiz-app/src/assets/translations/ قرار دارند
• زبان‌های پشتیبانی شده: بیش از ۴۰ زبان (لیست کامل در README)

حوزه‌های فعال مشارکت

به etc/CONTRIBUTING.md برای نیازهای فعلی مراجعه کنید:

• بخش‌های یادگیری تقویتی عمیق
• بهبودهای تشخیص اشیا
• مثال‌های شناسایی موجودیت‌های نام‌دار
• نمونه‌های آموزش جاسازی‌های سفارشی

پیکربندی محیط

وابستگی‌های مورد نیاز

# Core Python packages (from requirements.txt)
tensorflow==2.17.0
torch (via conda)
torchvision (via conda)
keras==3.5.0
opencv (via conda)
scikit-learn
numpy==1.26
pandas==2.2.2
matplotlib==3.9
jupyter

متغیرهای محیطی

برای استفاده پایه هیچ متغیر محیطی خاصی لازم نیست.

برای استقرارهای Azure (اپلیکیشن آزمون):

• AZURE_STATIC_WEB_APPS_API_TOKEN (به طور خودکار توسط Azure تنظیم می‌شود)

اشکال‌زدایی و رفع مشکلات

مشکلات رایج

مشکل: ایجاد محیط Conda شکست می‌خورد

• راه‌حل: ابتدا Conda را به‌روزرسانی کنید: conda update conda -y
• اطمینان حاصل کنید که فضای دیسک کافی دارید (۵۰ گیگابایت توصیه می‌شود)

مشکل: هسته Jupyter پیدا نمی‌شود

• راه‌حل:

  conda activate ai4beg
  python -m ipykernel install --user --name ai4beg
  

مشکل: GPU در نوت‌بوک‌ها شناسایی نمی‌شود

• راه‌حل:
  • نصب CUDA را بررسی کنید: nvidia-smi
  • GPU در PyTorch را بررسی کنید: python -c "import torch; print(torch.cuda.is_available())"
  • GPU در TensorFlow را بررسی کنید: python -c "import tensorflow as tf; print(tf.config.list_physical_devices('GPU'))"

مشکل: اپلیکیشن آزمون شروع نمی‌شود

• راه‌حل:

  cd etc/quiz-app
  rm -rf node_modules package-lock.json
  npm install
  npm run serve
  

مشکل: Binder زمان‌سنجی می‌شود یا دانلودها را مسدود می‌کند

• راه‌حل: از GitHub Codespaces یا تنظیمات محلی برای دسترسی بهتر به منابع استفاده کنید

مشکلات حافظه

برخی درس‌ها به RAM قابل توجهی نیاز دارند (۸ گیگابایت یا بیشتر توصیه می‌شود):

• از VMهای ابری برای درس‌های پرمصرف منابع استفاده کنید
• برنامه‌های دیگر را هنگام آموزش مدل‌ها ببندید
• اندازه دسته‌ها را در نوت‌بوک‌ها کاهش دهید اگر حافظه کافی ندارید

یادداشت‌های اضافی

برای مربیان دوره

• به lessons/0-course-setup/for-teachers.md برای راهنمایی تدریس مراجعه کنید
• درس‌ها مستقل هستند و می‌توانند به ترتیب یا به صورت انتخابی تدریس شوند
• زمان تخمینی: ۱۲ هفته با ۲ درس در هفته

منابع ابری

• Azure for Students: اعتبار رایگان برای دانشجویان در دسترس است
• Microsoft Learn: مسیرهای یادگیری مکمل در طول دوره لینک شده‌اند
• Binder: رایگان اما منابع محدود و برخی محدودیت‌های شبکه دارد

گزینه‌های اجرای کد

1. محلی (توصیه‌شده): کنترل کامل، بهترین عملکرد، پشتیبانی GPU
2. GitHub Codespaces: VS Code مبتنی بر ابر، مناسب برای دسترسی سریع
3. Binder: Jupyter مبتنی بر مرورگر، رایگان اما محدود
4. Azure ML Notebooks: گزینه سازمانی با پشتیبانی GPU
5. Google Colab: نوت‌بوک‌ها را به صورت جداگانه آپلود کنید، سطح GPU رایگان در دسترس است

کار با نوت‌بوک‌ها

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

ملاحظات عملکرد

• درس‌های بینایی کامپیوتری بعدی (CNNها، GANها) از GPU بهره‌مند می‌شوند
• درس‌های ترانسفورمر NLP ممکن است به RAM قابل توجهی نیاز داشته باشند
• آموزش از ابتدا آموزشی است اما زمان‌بر است
• مثال‌های یادگیری انتقالی زمان آموزش را به حداقل می‌رسانند

---

سلب مسئولیت:
این سند با استفاده از سرویس ترجمه هوش مصنوعی Co-op Translator ترجمه شده است. در حالی که ما تلاش می‌کنیم دقت را حفظ کنیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نادرستی‌ها باشند. سند اصلی به زبان اصلی آن باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حساس، ترجمه حرفه‌ای انسانی توصیه می‌شود. ما مسئولیتی در قبال سوء تفاهم‌ها یا تفسیرهای نادرست ناشی از استفاده از این ترجمه نداریم.