278 lines
12 KiB
Markdown
278 lines
12 KiB
Markdown
# راهنمای رفع مشکلات AI-For-Beginners
|
||
|
||
این راهنما به شما کمک میکند مشکلات رایج هنگام استفاده یا مشارکت در مخزن [AI-For-Beginners](https://github.com/microsoft/AI-For-Beginners) را حل کنید. هر مشکل شامل توضیحات، علائم، دلایل و راهحلهای گامبهگام است.
|
||
|
||
---
|
||
|
||
## فهرست مطالب
|
||
|
||
- [مشکلات عمومی](../..)
|
||
- [مشکلات نصب](../..)
|
||
- [مشکلات پیکربندی](../..)
|
||
- [اجرای نوتبوکها](../..)
|
||
- [مشکلات عملکرد](../..)
|
||
- [مشکلات وبسایت کتاب درسی](../..)
|
||
- [مشکلات مشارکت](../..)
|
||
- [سؤالات متداول](../..)
|
||
- [دریافت کمک](../..)
|
||
|
||
---
|
||
|
||
## مشکلات عمومی
|
||
|
||
### 1. مخزن به درستی کلون نمیشود
|
||
|
||
**توضیحات:** کلون کردن به شما امکان میدهد مخزن را به دستگاه خود کپی کنید.
|
||
|
||
**علائم:**
|
||
- خطا: `fatal: repository not found`
|
||
- خطا: `Permission denied (publickey)`
|
||
|
||
**دلایل احتمالی:**
|
||
- URL مخزن اشتباه است
|
||
- دسترسی کافی ندارید
|
||
- کلیدهای SSH پیکربندی نشدهاند
|
||
|
||
**راهحلها:**
|
||
1. **URL مخزن را بررسی کنید.**
|
||
از URL HTTPS استفاده کنید:
|
||
```
|
||
git clone https://github.com/microsoft/AI-For-Beginners.git
|
||
```
|
||
2. **اگر SSH شکست خورد، به HTTPS تغییر دهید.**
|
||
اگر خطای `Permission denied (publickey)` را مشاهده کردید، به جای SSH از لینک HTTPS بالا استفاده کنید.
|
||
3. **کلیدهای SSH را پیکربندی کنید (اختیاری).**
|
||
اگر میخواهید از SSH استفاده کنید، راهنمای [SSH گیتهاب](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) را دنبال کنید.
|
||
|
||
---
|
||
|
||
## مشکلات نصب
|
||
|
||
### 2. مشکلات محیط پایتون
|
||
|
||
**توضیحات:** این مخزن به پایتون و کتابخانههای مختلف وابسته است.
|
||
|
||
**علائم:**
|
||
- خطا: `ModuleNotFoundError: No module named '<package>'`
|
||
- خطاهای وارد کردن هنگام اجرای اسکریپتها یا نوتبوکها
|
||
|
||
**دلایل احتمالی:**
|
||
- وابستگیها نصب نشدهاند
|
||
- نسخه پایتون اشتباه است
|
||
|
||
**راهحلها:**
|
||
1. **یک محیط مجازی تنظیم کنید.**
|
||
```bash
|
||
python -m venv venv
|
||
source venv/bin/activate # On Windows: venv\Scripts\activate
|
||
```
|
||
2. **وابستگیها را نصب کنید.**
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
3. **نسخه پایتون را بررسی کنید.**
|
||
از پایتون 3.7 یا جدیدتر استفاده کنید.
|
||
```bash
|
||
python --version
|
||
```
|
||
|
||
### 3. Jupyter نصب نشده است
|
||
|
||
**توضیحات:** نوتبوکها منبع اصلی یادگیری هستند.
|
||
|
||
**علائم:**
|
||
- خطا: `jupyter: command not found`
|
||
- نوتبوکها اجرا نمیشوند
|
||
|
||
**دلایل احتمالی:**
|
||
- Jupyter نصب نشده است
|
||
|
||
**راهحلها:**
|
||
1. **Jupyter Notebook را نصب کنید.**
|
||
```bash
|
||
pip install notebook
|
||
```
|
||
یا اگر از Anaconda استفاده میکنید:
|
||
```bash
|
||
conda install notebook
|
||
```
|
||
2. **Jupyter Notebook را اجرا کنید.**
|
||
```bash
|
||
jupyter notebook
|
||
```
|
||
|
||
### 4. تضاد نسخه وابستگیها
|
||
|
||
**توضیحات:** پروژهها ممکن است در صورت عدم تطابق نسخههای بستهها خراب شوند.
|
||
|
||
**علائم:**
|
||
- خطاها یا هشدارهایی درباره نسخههای ناسازگار
|
||
|
||
**دلایل احتمالی:**
|
||
- بستههای قدیمی یا ناسازگار پایتون
|
||
|
||
**راهحلها:**
|
||
1. **در یک محیط تمیز نصب کنید.**
|
||
محیط venv/conda قدیمی را حذف کرده و یک محیط جدید ایجاد کنید.
|
||
2. **از نسخههای دقیق استفاده کنید.**
|
||
همیشه اجرا کنید:
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
اگر این شکست خورد، بستههای گمشده را به صورت دستی طبق README نصب کنید.
|
||
|
||
---
|
||
|
||
## مشکلات پیکربندی
|
||
|
||
### 5. متغیرهای محیطی تنظیم نشدهاند
|
||
|
||
**توضیحات:** برخی ماژولها ممکن است به کلیدها، توکنها یا تنظیمات پیکربندی نیاز داشته باشند.
|
||
|
||
**علائم:**
|
||
- خطا: `KeyError` یا هشدارهایی درباره تنظیمات گمشده
|
||
|
||
**دلایل احتمالی:**
|
||
- متغیرهای محیطی مورد نیاز تنظیم نشدهاند
|
||
|
||
**راهحلها:**
|
||
1. **فایل `.env.example` یا مشابه را بررسی کنید.**
|
||
2. **یک فایل `.env` ایجاد کرده و مقادیر مورد نیاز را پر کنید.**
|
||
3. **پس از تنظیم متغیرهای محیطی، ترمینال یا IDE خود را مجدداً بارگذاری کنید.**
|
||
|
||
---
|
||
|
||
## اجرای نوتبوکها
|
||
|
||
### 6. نوتبوک باز یا اجرا نمیشود
|
||
|
||
**توضیحات:** نوتبوکهای Jupyter نیاز به تنظیمات مناسب دارند.
|
||
|
||
**علائم:**
|
||
- نوتبوک اجرا نمیشود
|
||
- مرورگر به طور خودکار باز نمیشود
|
||
|
||
**دلایل احتمالی:**
|
||
- Jupyter نصب نشده است
|
||
- مشکلات پیکربندی مرورگر
|
||
|
||
**راهحلها:**
|
||
1. **Jupyter را نصب کنید (به مشکلات نصب بالا مراجعه کنید).**
|
||
2. **نوتبوکها را به صورت دستی باز کنید.**
|
||
- URL را از ترمینال کپی کنید (مثلاً `http://localhost:8888/?token=...`) و در مرورگر خود وارد کنید.
|
||
|
||
### 7. کرنل خراب یا متوقف میشود
|
||
|
||
**توضیحات:** کرنلهای نوتبوک ممکن است به دلیل محدودیت منابع یا خطاهای کد خراب شوند.
|
||
|
||
**علائم:**
|
||
- کرنل به طور مکرر میمیرد یا مجدداً راهاندازی میشود
|
||
- خطاهای کمبود حافظه
|
||
|
||
**دلایل احتمالی:**
|
||
- مجموعه دادههای بزرگ
|
||
- کد یا بستههای ناسازگار
|
||
|
||
**راهحلها:**
|
||
1. **کرنل را مجدداً راهاندازی کنید.**
|
||
از دکمه "Restart Kernel" در Jupyter استفاده کنید.
|
||
2. **مصرف حافظه را بررسی کنید.**
|
||
برنامههای غیرضروری را ببندید.
|
||
3. **نوتبوکها را در پلتفرمهای ابری اجرا کنید.**
|
||
از [Google Colab](https://colab.research.google.com/) یا [Azure Notebooks](https://notebooks.azure.com/) استفاده کنید.
|
||
|
||
---
|
||
|
||
## مشکلات عملکرد
|
||
|
||
### 8. نوتبوکها کند اجرا میشوند
|
||
|
||
**توضیحات:** برخی وظایف AI به حافظه و CPU قابل توجهی نیاز دارند.
|
||
|
||
**علائم:**
|
||
- اجرای کند
|
||
- صدای بلند فن لپتاپ
|
||
|
||
**دلایل احتمالی:**
|
||
- مجموعه دادهها یا مدلهای بزرگ
|
||
- منابع محدود سیستم
|
||
|
||
**راهحلها:**
|
||
1. **از یک پلتفرم ابری استفاده کنید.**
|
||
- نوتبوک را به Colab یا Azure Notebooks آپلود کنید.
|
||
2. **اندازه مجموعه داده را کاهش دهید.**
|
||
- از دادههای نمونه برای تمرین استفاده کنید.
|
||
3. **برنامههای غیرضروری را ببندید.**
|
||
- حافظه RAM سیستم را آزاد کنید.
|
||
|
||
---
|
||
|
||
## مشکلات وبسایت کتاب درسی
|
||
|
||
### 9. فصل بارگذاری نمیشود
|
||
|
||
**توضیحات:** کتاب درسی آنلاین درسها و فصلها را نمایش میدهد.
|
||
|
||
**علائم:**
|
||
- یک فصل (مثلاً Transformers/BERT) گم شده یا باز نمیشود
|
||
|
||
**مشکل شناختهشده:**
|
||
- [مشکل #303](https://github.com/microsoft/AI-For-Beginners/issues/303): "18 Transformers. BERT. نمیتوان در وبسایت کتاب درسی باز کرد." ناشی از خطای نام فایل (`READMEtransformers.md` به جای `README.md`).
|
||
|
||
**راهحلها:**
|
||
1. **خطاهای تغییر نام فایل را بررسی کنید.**
|
||
اگر شما یک مشارکتکننده هستید، مطمئن شوید فایلهای فصل به نام `README.md` نامگذاری شدهاند.
|
||
2. **فایلهای گمشده را گزارش دهید.**
|
||
یک مشکل گیتهاب با نام فصل و جزئیات خطا باز کنید.
|
||
|
||
---
|
||
|
||
## مشکلات مشارکت
|
||
|
||
### 10. PR پذیرفته نمیشود یا بیلدها شکست میخورند
|
||
|
||
**توضیحات:** مشارکتها باید تستها را بگذرانند و از دستورالعملها پیروی کنند.
|
||
|
||
**علائم:**
|
||
- درخواست کشش رد شده است
|
||
- خطاهای CI/CD
|
||
|
||
**دلایل احتمالی:**
|
||
- تستها شکست خوردهاند
|
||
- استانداردهای کدنویسی رعایت نشدهاند
|
||
|
||
**راهحلها:**
|
||
1. **راهنمای مشارکت را بخوانید.**
|
||
- از [CONTRIBUTING.md](https://github.com/microsoft/AI-For-Beginners/blob/main/CONTRIBUTING.md) مخزن پیروی کنید.
|
||
2. **تستها را به صورت محلی قبل از ارسال اجرا کنید.**
|
||
3. **قوانین linting یا الزامات قالببندی را بررسی کنید.**
|
||
|
||
---
|
||
|
||
## سؤالات متداول
|
||
|
||
### کجا میتوانم برای ماژولهای خاص کمک پیدا کنم؟
|
||
- هر ماژول معمولاً README مخصوص به خود را دارد. از آنجا برای نکات تنظیم و استفاده شروع کنید.
|
||
|
||
### چگونه میتوانم یک باگ گزارش کنم یا یک ویژگی درخواست کنم؟
|
||
- [یک مشکل گیتهاب باز کنید](https://github.com/microsoft/AI-For-Beginners/issues/new) با توضیح واضح و مراحل بازتولید.
|
||
|
||
### آیا میتوانم کمک بخواهم اگر مشکلم در لیست نیست؟
|
||
- بله! ابتدا مشکلات موجود را جستجو کنید و اگر مشکلتان را پیدا نکردید، یک مشکل جدید ایجاد کنید.
|
||
|
||
---
|
||
|
||
## دریافت کمک
|
||
|
||
- **بررسی مشکلات:** [مشکلات گیتهاب](https://github.com/microsoft/AI-For-Beginners/issues)
|
||
- **پرسیدن سؤال:** از Discussions گیتهاب استفاده کنید یا یک مشکل باز کنید.
|
||
- **جامعه:** لینکهای مخزن را برای گزینههای چت/فروم ببینید.
|
||
|
||
---
|
||
|
||
_آخرین بهروزرسانی: ۲۰۲۵-۰۹-۲۰_
|
||
|
||
---
|
||
|
||
**سلب مسئولیت**:
|
||
این سند با استفاده از سرویس ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما تلاش میکنیم دقت را حفظ کنیم، لطفاً توجه داشته باشید که ترجمههای خودکار ممکن است شامل خطاها یا نادرستیها باشند. سند اصلی به زبان اصلی آن باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حساس، توصیه میشود از ترجمه انسانی حرفهای استفاده کنید. ما مسئولیتی در قبال سوء تفاهمها یا تفسیرهای نادرست ناشی از استفاده از این ترجمه نداریم. |