آموزش Anaconda و Miniconda؛ نصب، مدیریت محیط پایتون و پروژه هوش مصنوعی

نصب Python معمولاً ساده است؛ اما با بزرگ‌ترشدن پروژه، مدیریت نسخه پایتون، کتابخانه‌ها و وابستگی‌های ناسازگار به یکی از مشکلات اصلی برنامه‌نویسان تبدیل می‌شود.

ممکن است یک پروژه به Python 3.12 و نسخه مشخصی از Pandas نیاز داشته باشد، پروژه دیگر با نسخه متفاوتی از PyTorch اجرا شود و یک Notebook قدیمی فقط با مجموعه‌ای خاص از پکیج‌ها کار کند. اگر همه این ابزارها را داخل یک محیط مشترک نصب کنید، دیر یا زود با خطاهای ناسازگاری مواجه می‌شوید.

Anaconda، Miniconda و ابزار Conda برای حل همین مسئله ساخته شده‌اند. با Conda می‌توانید برای هر پروژه یک محیط کاملاً مجزا بسازید، نسخه پایتون را تعیین کنید، کتابخانه‌ها را نصب کنید و مشخصات محیط را برای اجرای مجدد روی سیستم دیگری ذخیره کنید.

در این آموزش با تفاوت Anaconda، Miniconda، Conda، pip و venv آشنا می‌شویم. سپس نصب در Windows، Linux و macOS، ساخت Environment، نصب پکیج، اتصال به JupyterLab، استفاده در VS Code و آماده‌سازی یک پروژه واقعی متصل به API هوش مصنوعی درواره را بررسی می‌کنیم.

Anaconda چیست؟

Anaconda Distribution یک توزیع آماده از Python و ابزارهای Data Science است. با نصب Anaconda مجموعه‌ای از ابزارها و کتابخانه‌های پرکاربرد در اختیار شما قرار می‌گیرد؛ از جمله:

• Python
• Conda
• Anaconda Navigator
• Jupyter Notebook
• JupyterLab
• NumPy
• Pandas
• Matplotlib
• Scikit-learn
• ابزارهای تحلیل داده و محاسبات علمی

هدف Anaconda این است که کاربر بتواند بدون نصب جداگانه تعداد زیادی پکیج، یک محیط نسبتاً کامل برای تحلیل داده، Machine Learning و محاسبات علمی داشته باشد.

این روش برای افرادی که تازه وارد پایتون و تحلیل داده شده‌اند ساده است؛ اما حجم نصب اولیه آن بیشتر است و تعداد زیادی پکیج را دریافت می‌کند که شاید در پروژه شما استفاده نشوند.

Miniconda چیست؟

Miniconda نسخه سبک‌تر و حداقلی اکوسیستم Conda است. Miniconda معمولاً فقط اجزای ضروری زیر را نصب می‌کند:

• Conda
• Python
• pip
• وابستگی‌های پایه

بعد از نصب Miniconda، کتابخانه‌های موردنیاز هر پروژه را خودتان انتخاب و نصب می‌کنید.

برای بیشتر برنامه‌نویسانی که می‌خواهند روی نسخه پایتون و پکیج‌های هر پروژه کنترل داشته باشند، Miniconda انتخاب مناسب‌تری است.

Conda چیست؟

Conda یک Package Manager و Environment Manager است.

Package Manager بودن یعنی می‌تواند پکیج‌ها و وابستگی‌های آن‌ها را نصب، به‌روزرسانی و مدیریت کند.

Environment Manager بودن یعنی می‌تواند چند محیط جداگانه روی یک سیستم بسازد. هر محیط می‌تواند نسخه مستقل Python و مجموعه متفاوتی از پکیج‌ها داشته باشد.

برای مثال:

System
├── base
├── data-analysis
│   ├── Python 3.12
│   ├── Pandas
│   └── Plotly
├── machine-learning
│   ├── Python 3.11
│   ├── Scikit-learn
│   └── XGBoost
└── ai-api
    ├── Python 3.12
    ├── Requests
    ├── FastAPI
    └── python-dotenv

پکیج‌های نصب‌شده در محیط data-analysis روی محیط ai-api تأثیر نمی‌گذارند. این جداسازی احتمال تداخل وابستگی‌ها را کاهش می‌دهد.

تفاوت Anaconda، Miniconda و Conda

این سه نام به یک مفهوم واحد اشاره نمی‌کنند.

Conda موتور اصلی مدیریت محیط است. Anaconda و Miniconda دو روش متفاوت برای نصب و شروع استفاده از آن هستند.

Anaconda بهتر است یا Miniconda؟

انتخاب به نوع استفاده شما بستگی دارد.

Anaconda را انتخاب کنید اگر:

• تازه کار با پایتون و Data Science را شروع کرده‌اید.
• نمی‌خواهید پکیج‌ها را جداگانه نصب کنید.
• فضای ذخیره‌سازی کافی دارید.
• استفاده از رابط گرافیکی Anaconda Navigator را ترجیح می‌دهید.
• یک محیط آموزشی آماده می‌خواهید.

Miniconda را انتخاب کنید اگر:

• می‌خواهید فقط پکیج‌های ضروری نصب شوند.
• چند پروژه با وابستگی‌های متفاوت دارید.
• کنترل بیشتر روی Environment می‌خواهید.
• روی سرور یا سیستم دارای فضای محدود کار می‌کنید.
• محیطی ساده‌تر و قابل بازتولید می‌خواهید.
• بیشتر از Terminal یا VS Code استفاده می‌کنید.

برای Workflow حرفه‌ای توسعه نرم‌افزار و هوش مصنوعی، معمولاً Miniconda انتخاب سبک‌تر و منعطف‌تری است.

تفاوت Conda با pip و venv

یکی از پرسش‌های متداول این است که آیا Conda جایگزین pip است؟

پاسخ کوتاه این است که Conda و pip هم‌پوشانی دارند، اما یکسان نیستند.

venv فقط یک محیط مجازی بر اساس Python فعلی می‌سازد. pip پکیج‌های Python را از PyPI نصب می‌کند. Conda علاوه بر ساخت Environment می‌تواند نسخه Python و تعدادی از وابستگی‌های سیستمی را نیز مدیریت کند.

اگر پروژه معمولی Python یا Web Development دارید، ترکیب venv و pip معمولاً کافی است. اگر با Data Science، محاسبات علمی، Machine Learning یا چند نسخه متفاوت Python کار می‌کنید، Conda می‌تواند مدیریت محیط را ساده‌تر کند.

Channel در Conda چیست؟

پکیج‌های Conda از مخزن‌هایی به نام Channel دریافت می‌شوند.

دو نامی که زیاد مشاهده می‌کنید عبارت‌اند از:

• defaults
• conda-forge

defaults به مخزن پیش‌فرض تنظیم‌شده در Anaconda و Miniconda اشاره می‌کند.

conda-forge یک Channel جامعه‌محور است که تعداد زیادی پکیج برای Python، Data Science و ابزارهای چندسکویی ارائه می‌دهد.

برای نصب یک پکیج از Channel مشخص می‌توانید بنویسید:

conda install -c conda-forge pandas

یکی از علت‌های رایج ناسازگاری، ترکیب بدون برنامه چند Channel در یک Environment است. بهتر است برای هر پروژه سیاست مشخصی داشته باشید و از تغییر مداوم اولویت Channelها خودداری کنید.

استفاده از Repositoryها و Package Channelها ممکن است تابع شرایط فعلی ارائه‌دهنده باشد. به‌خصوص برای استفاده سازمانی، شرایط به‌روز منبع انتخاب‌شده را در وب‌سایت رسمی آن بررسی کنید.

پیش‌نیازهای نصب

برای نصب Anaconda یا Miniconda به موارد زیر نیاز دارید:

• Windows، Linux یا macOS پشتیبانی‌شده
• فضای کافی روی دیسک
• دسترسی معمولی کاربر
• Terminal یا PowerShell
• اینترنت برای دانلود Installer و پکیج‌ها

طبق مستندات رسمی نصب Conda، اگر مسیر نصب برای کاربر قابل نوشتن باشد، معمولاً به دسترسی Administrator یا root نیاز ندارید.

پیش از دانلود، معماری سیستم را مشخص کنید:

• Windows 64-bit
• Linux x86_64
• Linux aarch64
• macOS Intel
• macOS Apple Silicon

انتخاب Installer اشتباه می‌تواند باعث اجرا نشدن برنامه یا خطاهای معماری شود.

نصب Miniconda در Windows

برای بیشتر کاربران Windows، استفاده از Graphical Installer ساده‌ترین روش است.

مرحله اول: دانلود Miniconda

وارد صفحه رسمی نصب Anaconda و Miniconda شوید و Installer متناسب با Windows 64-bit را دریافت کنید.

فایل نصب را فقط از منبع رسمی دانلود کنید.

مرحله دوم: اجرای Installer

Installer را اجرا کنید و مراحل نصب را ادامه دهید.

در نصب تک‌کاربره، گزینه Just Me معمولاً کافی است و نیاز به دسترسی Administrator را کاهش می‌دهد.

در انتخاب مسیر نصب، از مسیری استفاده کنید که متعلق به حساب کاربری خودتان باشد.

مرحله سوم: تنظیم PATH

Installer ممکن است گزینه‌ای برای افزودن Conda به PATH نشان دهد. افزودن خودکار PATH همیشه برای همه سیستم‌ها مناسب نیست؛ زیرا ممکن است با Pythonهای دیگر تداخل ایجاد کند.

روش ساده‌تر این است که پس از نصب از یکی از این ابزارها استفاده کنید:

• Anaconda Prompt
• Miniconda Prompt
• PowerShell پس از اجرای conda init

مرحله چهارم: بررسی نصب

Miniconda Prompt یا Anaconda Prompt را باز کرده و اجرا کنید:

conda --version

سپس اطلاعات نصب را ببینید:

conda info

فعال‌کردن Conda در PowerShell

اگر دستور conda activate در PowerShell شناخته نمی‌شود، از Miniconda Prompt اجرا کنید:

conda init powershell

سپس تمام پنجره‌های PowerShell را ببندید و یک پنجره جدید باز کنید.

بررسی کنید:

conda --version

در صورت استفاده از Command Prompt می‌توانید اجرا کنید:

conda init cmd.exe

نصب Miniconda در Linux

ابتدا Installer متناسب با معماری سیستم را از صفحه رسمی دریافت کنید.

برای سیستم‌های رایج Intel و AMD با معماری x86_64، نام فایل معمولاً مشابه زیر است:

Miniconda3-latest-Linux-x86_64.sh

بعد از دانلود، در پوشه فایل اجرا کنید:

bash Miniconda3-latest-Linux-x86_64.sh

شرایط نمایش‌داده‌شده توسط Installer را مطالعه کنید، مسیر نصب را انتخاب کرده و اجازه دهید Conda برای Shell مقداردهی اولیه شود.

اگر مقداردهی اولیه انجام نشده است:

~/miniconda3/bin/conda init bash

سپس Terminal را ببندید و دوباره باز کنید یا تنظیمات Shell را بارگذاری کنید:

source ~/.bashrc

نسخه Conda را بررسی کنید:

conda --version

اگر از Zsh استفاده می‌کنید:

~/miniconda3/bin/conda init zsh

سپس:

source ~/.zshrc

برای سیستم‌های ARM باید Installer مخصوص معماری aarch64 را دریافت کنید و از فایل x86_64 استفاده نکنید.

نصب Miniconda در macOS

ابتدا معماری Mac را بررسی کنید:

uname -m

خروجی‌های رایج:

arm64

برای Apple Silicon مانند M1، M2، M3 و نسل‌های بعدی.

x86_64

برای Macهای Intel.

Installer متناسب با معماری را از صفحه رسمی دریافت کنید. سپس فایل Shell Installer را اجرا کنید. برای Apple Silicon نام فایل معمولاً مشابه زیر است:

bash Miniconda3-latest-MacOSX-arm64.sh

برای Macهای Intel:

bash Miniconda3-latest-MacOSX-x86_64.sh

بعد از نصب، Conda را برای Zsh آماده کنید:

~/miniconda3/bin/conda init zsh

Terminal را ببندید و دوباره باز کنید، سپس اجرا کنید:

conda --version

نصب Anaconda Distribution

اگر به‌جای Miniconda نسخه کامل Anaconda را می‌خواهید، از صفحه رسمی دانلود Anaconda Installer مربوط به سیستم‌عامل و معماری خود را دریافت کنید.

مراحل نصب از نظر کلی مشابه Miniconda است، اما Anaconda تعداد بیشتری پکیج و ابزار را از ابتدا نصب می‌کند.

پس از نصب می‌توانید از Terminal استفاده کنید:

conda --version

یا Anaconda Navigator را باز کنید.

Anaconda Navigator چیست؟

Anaconda Navigator یک رابط گرافیکی برای مدیریت Environmentها و اجرای بعضی ابزارها است.

با Navigator می‌توانید:

• Environment جدید بسازید.
• نسخه Python را انتخاب کنید.
• پکیج‌ها را جست‌وجو و نصب کنید.
• JupyterLab را اجرا کنید.
• Environmentها را حذف یا مدیریت کنید.
• بعضی برنامه‌های موجود را بدون Terminal باز کنید.

Navigator برای شروع مناسب است، اما یادگیری دستورهای Conda اهمیت بیشتری دارد؛ زیرا همان دستورها روی Windows، Linux، macOS، سرور و محیط‌های خودکار قابل استفاده‌اند.

آشنایی با محیط base

بعد از نصب Conda معمولاً محیطی به نام base در اختیار شما قرار می‌گیرد.

اگر ابتدای Terminal این عبارت را می‌بینید:

(base)

یعنی محیط base فعال است.

بهتر است کتابخانه‌های همه پروژه‌ها را در base نصب نکنید. محیط base را برای ابزار اصلی Conda نگه دارید و برای هر پروژه Environment جداگانه بسازید.

اگر نمی‌خواهید base هنگام بازشدن Terminal خودکار فعال شود:

conda config --set auto_activate_base false

در صورت نیاز می‌توانید آن را دستی فعال کنید:

conda activate base

به‌روزرسانی Conda

برای مشاهده نسخه فعلی:

conda --version

برای به‌روزرسانی Conda در محیط base:

conda activate base
conda update conda

قبل از ارتقای بزرگ ابزارها در محیط کاری، مستندات نسخه و سازگاری پروژه‌ها را بررسی کنید.

ساخت اولین Conda Environment

برای پروژه هوش مصنوعی یک Environment با Python 3.12 می‌سازیم:

conda create \
  --name darvareh-ai \
  python=3.12

در Windows PowerShell می‌توانید دستور را در یک خط بنویسید:

conda create --name darvareh-ai python=3.12

Conda فهرست پکیج‌ها و تغییرات پیشنهادی را نمایش می‌دهد. پس از بررسی، نصب را تأیید کنید.

برای اجرای غیرتعاملی می‌توان از -y استفاده کرد:

conda create --name darvareh-ai python=3.12 -y

فعال‌کردن Environment

conda activate darvareh-ai

پس از فعال‌شدن باید نام محیط را ابتدای Terminal ببینید:

(darvareh-ai)

نسخه Python را بررسی کنید:

python --version

مسیر مفسر فعال:

در Linux و macOS:

which python

در Windows:

where python

مسیر باید به Environment با نام darvareh-ai اشاره کند.

غیرفعال‌کردن Environment

برای خروج از محیط فعال:

conda deactivate

اگر چند Environment روی هم فعال شده باشند، ممکن است لازم باشد دستور را بیش از یک بار اجرا کنید.

مشاهده فهرست Environmentها

conda env list

یا:

conda info --envs

علامت ستاره کنار نام یک Environment نشان می‌دهد که همان محیط فعال است.

ساخت Environment در مسیر پروژه

به‌جای نام سراسری می‌توانید Environment را در مسیر مشخصی بسازید:

conda create \
  --prefix ./env \
  python=3.12

فعال‌سازی آن:

conda activate ./env

این روش Environment را نزدیک پروژه نگه می‌دارد، اما مسیر کامل آن ممکن است در Prompt نمایش داده شود. همچنین نباید پوشه Environment را در Git ثبت کنید.

در .gitignore بنویسید:

env/
.conda/
.env
__pycache__/
.ipynb_checkpoints/

برای بسیاری از کاربران، Environment نام‌دار مانند darvareh-ai ساده‌تر است.

نصب پکیج با Conda

ابتدا Environment پروژه را فعال کنید:

conda activate darvareh-ai

سپس پکیج‌های موردنیاز را نصب کنید:

conda install pandas numpy jupyterlab ipykernel

نصب از Channel مشخص:

conda install \
  -c conda-forge \
  pandas \
  numpy \
  jupyterlab \
  ipykernel

در PowerShell:

conda install -c conda-forge pandas numpy jupyterlab ipykernel

نصب چند پکیج در یک دستور

بهتر است پکیج‌های مرتبط را تا حد امکان در یک دستور نصب کنید:

conda install \
  -c conda-forge \
  pandas \
  numpy \
  matplotlib \
  plotly \
  scikit-learn

وقتی همه درخواست‌ها هم‌زمان به Solver داده شوند، Conda فرصت بهتری برای انتخاب مجموعه نسخه‌های سازگار دارد.

جست‌وجوی پکیج

conda search pandas

جست‌وجو در Channel مشخص:

conda search -c conda-forge pandas

مشاهده پکیج‌های نصب‌شده

conda list

جست‌وجو در فهرست پکیج‌های Environment:

conda list pandas

مشاهده نسخه از داخل Python:

import pandas as pd

print(pd.__version__)

نصب نسخه مشخص یک پکیج

conda install pandas=2.3

این نسخه فقط یک نمونه است. پیش از تعیین نسخه، سازگاری آن را با Python و سایر کتابخانه‌های پروژه بررسی کنید.

برای محدودکردن نسخه در یک بازه می‌توان از عبارت نقل‌قول‌شده استفاده کرد:

conda install "pandas>=2.2,<3"

به‌روزرسانی یک پکیج

conda update pandas

Conda ممکن است برای حفظ سازگاری، تغییرات دیگری را نیز پیشنهاد دهد. پیش از تأیید، فهرست تغییرات را بخوانید.

به‌روزرسانی تمام پکیج‌ها در پروژه واقعی می‌تواند تغییرات گسترده‌ای ایجاد کند:

conda update --all

این دستور را بدون بررسی و تست روی Environment مهم اجرا نکنید. برای پروژه پایدار، ساخت Environment آزمایشی و اجرای تست‌ها پیش از ارتقای کلی روش مطمئن‌تری است.

حذف یک پکیج

conda remove pandas

پیش از تأیید، بررسی کنید Conda چه پکیج‌های وابسته دیگری را حذف خواهد کرد.

استفاده از pip داخل Conda Environment

همه پکیج‌های Python لزوماً در Channel انتخابی Conda موجود نیستند. در این وضعیت می‌توانید داخل Environment از pip استفاده کنید.

ابتدا pip را داخل Environment نصب کنید:

conda install pip

سپس:

python -m pip install requests python-dotenv

استفاده از python -m pip کمک می‌کند مطمئن شوید pip متعلق به Python همان Environment است.

مسیر Python را بررسی کنید:

python -c "import sys; print(sys.executable)"

مسیر pip:

python -m pip --version

هر دو باید به Environment فعال مربوط باشند.

ترتیب مناسب استفاده از Conda و pip

یک Workflow قابل پیش‌بینی:

1. Environment جدید بسازید.
2. پکیج‌های موجود را ابتدا با Conda نصب کنید.
3. پکیج‌های باقیمانده را با pip نصب کنید.
4. بعد از نصب pip، از تغییرات گسترده Conda در همان Environment خودداری کنید.
5. در صورت ایجاد ناسازگاری پیچیده، Environment را از فایل مشخصات دوباره بسازید.

مثال:

conda create --name darvareh-ai python=3.12 -y
conda activate darvareh-ai

conda install \
  -c conda-forge \
  pandas \
  numpy \
  jupyterlab \
  ipykernel \
  pip

python -m pip install requests python-dotenv

نصب تصادفی یک پکیج با Conda و نسخه دیگری از همان پکیج با pip می‌تواند محیط را غیرقابل پیش‌بینی کند.

ساخت Environment مخصوص JupyterLab

conda create \
  --name jupyter-data \
  -c conda-forge \
  python=3.12 \
  jupyterlab \
  ipykernel \
  pandas \
  numpy \
  plotly

فعال‌سازی:

conda activate jupyter-data

اجرای JupyterLab:

jupyter lab

ثبت Conda Environment به‌عنوان Jupyter Kernel

Environment پروژه را فعال کنید:

conda activate darvareh-ai

مطمئن شوید ipykernel نصب است:

conda install -c conda-forge ipykernel

سپس Environment را به‌عنوان Kernel ثبت کنید:

python -m ipykernel install \
  --user \
  --name darvareh-ai \
  --display-name "Python (Darvareh AI)"

اکنون در JupyterLab می‌توانید Kernel زیر را انتخاب کنید:

Python (Darvareh AI)

فهرست Kernelها:

jupyter kernelspec list

داخل Notebook مسیر Python فعال را بررسی کنید:

import sys

print(sys.executable)
print(sys.version)

اگر مسیر به Environment موردنظر اشاره نمی‌کند، Kernel اشتباه انتخاب شده است.

استفاده از Conda Environment در VS Code

برای استفاده در VS Code:

1. پوشه پروژه را در VS Code باز کنید.
2. Command Palette را با Ctrl + Shift + P باز کنید.
3. دستور Python: Select Interpreter را انتخاب کنید.
4. مفسر مربوط به darvareh-ai را انتخاب کنید.
5. یک Terminal جدید در VS Code باز کنید.
6. نسخه Python را بررسی کنید.

python --version

اگر Environment در فهرست ظاهر نشد، مسیر آن را پیدا کنید:

conda env list

سپس Interpreter را با مسیر کامل انتخاب کنید.

برای فایل‌های Notebook نیز Kernel بالای صفحه را جداگانه بررسی کنید. Python Interpreter فایل‌های .py و Kernel فایل‌های .ipynb ممکن است انتخاب‌های متفاوتی داشته باشند.

ساخت فایل environment.yml

فایل environment.yml مشخص می‌کند پروژه به چه Python، Channel و پکیج‌هایی نیاز دارد.

در ریشه پروژه فایل زیر را بسازید:

name: darvareh-ai

channels:
  - conda-forge

dependencies:
  - python=3.12
  - jupyterlab
  - ipykernel
  - pandas
  - numpy
  - plotly
  - pip
  - pip:
      - requests
      - python-dotenv

ساخت Environment از روی فایل:

conda env create \
  --file environment.yml

فعال‌سازی:

conda activate darvareh-ai

این روش برای تیم‌ها، آموزش‌ها و پروژه‌های قابل انتشار بسیار مناسب‌تر از ارائه فهرستی از دستورهای پراکنده است.

به‌روزرسانی Environment از روی فایل

اگر environment.yml تغییر کرد:

conda env update \
  --file environment.yml \
  --prune

گزینه --prune پکیج‌هایی را که دیگر در تعریف محیط وجود ندارند حذف می‌کند. قبل از استفاده روی Environment مهم، تغییرات فایل و وابستگی‌ها را بررسی کنید.

Export کردن Environment موجود

برای ثبت پکیج‌هایی که مستقیماً درخواست کرده‌اید:

conda env export \
  --from-history \
  > environment.yml

این خروجی معمولاً ساده‌تر و قابل‌انتقال‌تر است، اما ممکن است تمام جزئیات مربوط به پکیج‌های نصب‌شده با pip را پوشش ندهد. پس فایل را بررسی و در صورت نیاز بخش pip را تکمیل کنید.

برای ثبت جزئیات کامل‌تر Environment:

conda env export > environment-full.yml

خروجی کامل ممکن است شامل نسخه‌های وابسته به سیستم‌عامل و اطلاعاتی باشد که انتقال آن به پلتفرم دیگر را دشوار می‌کند.

در صورت وجود خطی با prefix در انتهای فایل Export، معمولاً بهتر است پیش از انتشار فایل آن را حذف کنید؛ زیرا مسیر محلی سیستم شما برای سایر کاربران کاربردی نیست.

ساخت کپی از Environment

برای آزمایش ارتقا بدون تغییر محیط اصلی:

conda create \
  --name darvareh-ai-test \
  --clone darvareh-ai

سپس:

conda activate darvareh-ai-test

حالا می‌توانید پکیج‌ها را در محیط آزمایشی ارتقا دهید و پروژه را تست کنید.

این کار به‌خصوص برای Environmentهای Machine Learning که وابستگی‌های سنگین دارند مفید است.

حذف Environment آزمایشی

ابتدا از آن خارج شوید:

conda deactivate

سپس:

conda env remove \
  --name darvareh-ai-test

پیش از اجرای دستور، نام دقیق محیط را بررسی کنید:

conda env list

پروژه عملی: آماده‌سازی محیط تحلیل داده و API هوش مصنوعی

در این بخش یک پروژه کوچک اما واقعی می‌سازیم که:

• داخل Conda Environment اجرا می‌شود.
• نسخه Python و پکیج‌ها مشخص هستند.
• تنظیمات حساس را از .env می‌خواند.
• داده نمونه را با Pandas تحلیل می‌کند.
• خلاصه داده را به API هوش مصنوعی درواره می‌فرستد.
• نتیجه را بدون افشای API Key نمایش می‌دهد.

ساخت پوشه پروژه

mkdir conda-darvareh-project
cd conda-darvareh-project

ساختار پروژه:

conda-darvareh-project/
├── .env
├── .gitignore
├── environment.yml
├── app.py
└── data/

تعریف Environment

محتوای environment.yml:

name: darvareh-report

channels:
  - conda-forge

dependencies:
  - python=3.12
  - pandas
  - pip
  - pip:
      - requests
      - python-dotenv

محیط را بسازید:

conda env create -f environment.yml

فعال کنید:

conda activate darvareh-report

تنظیم فایل .env

DARVAREH_API_KEY=YOUR_DARVAREH_API_KEY
DARVAREH_MODEL_ID=YOUR_MODEL_ID

برای دریافت کلید، در درواره ثبت‌نام کنید. Model ID قابل استفاده را از صفحه مدل‌ها و قیمت‌های درواره انتخاب کنید.

ساخت .gitignore

.env
__pycache__/
*.pyc
data/*.csv

نوشتن برنامه

محتوای فایل app.py:

import json
import os
import sys

import pandas as pd
import requests
from dotenv import load_dotenv


DARVAREH_CHAT_URL = (
    "https://api.darvareh.ir/v1/chat/completions"
)


def validate_environment() -> None:
    print(f"Python executable: {sys.executable}")
    print(f"Python version: {sys.version.split()[0]}")
    print(f"Pandas version: {pd.__version__}")


def create_sample_data() -> pd.DataFrame:
    return pd.DataFrame(
        {
            "channel": [
                "Organic Search",
                "Direct",
                "Social",
                "Email",
            ],
            "sessions": [
                18_500,
                12_400,
                9_800,
                7_200,
            ],
            "orders": [
                1_120,
                640,
                410,
                520,
            ],
            "revenue": [
                5_760_000_000,
                3_100_000_000,
                1_840_000_000,
                2_950_000_000,
            ],
        }
    )


def prepare_summary(
    data: pd.DataFrame,
) -> list[dict]:
    required_columns = {
        "channel",
        "sessions",
        "orders",
        "revenue",
    }

    missing_columns = required_columns.difference(
        data.columns
    )

    if missing_columns:
        raise ValueError(
            f"Missing columns: {sorted(missing_columns)}"
        )

    if data.empty:
        raise ValueError("Input data is empty.")

    if (data["sessions"] <= 0).any():
        raise ValueError(
            "Sessions must be greater than zero."
        )

    summary = data.copy()

    summary["conversion_rate"] = (
        summary["orders"]
        / summary["sessions"]
        * 100
    ).round(2)

    summary["revenue_per_session"] = (
        summary["revenue"]
        / summary["sessions"]
    ).round(0)

    summary = summary.sort_values(
        "revenue",
        ascending=False,
    )

    return summary.to_dict(orient="records")


def generate_report(
    records: list[dict],
    api_key: str,
    model_id: str,
) -> str:
    prompt = f"""
داده زیر خلاصه محاسبه‌شده عملکرد کانال‌های جذب است:

{json.dumps(records, ensure_ascii=False, indent=2)}

یک گزارش کوتاه فارسی تولید کن که شامل این موارد باشد:
1. کانال دارای بیشترین درآمد
2. کانال دارای بالاترین نرخ تبدیل
3. یک فرصت قابل بررسی
4. سه پیشنهاد اجرایی

فقط از داده موجود استفاده کن.
عدد جدید تولید نکن.
بین واقعیت داده و پیشنهاد تحلیلی تفاوت قائل شو.
"""

    response = requests.post(
        DARVAREH_CHAT_URL,
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json={
            "model": model_id,
            "messages": [
                {
                    "role": "system",
                    "content": (
                        "تو یک تحلیلگر دقیق داده هستی. "
                        "هیچ عددی را حدس نزن."
                    ),
                },
                {
                    "role": "user",
                    "content": prompt,
                },
            ],
            "temperature": 0.2,
        },
        timeout=60,
    )

    try:
        response.raise_for_status()
    except requests.HTTPError as error:
        preview = response.text[:500]

        raise RuntimeError(
            "Darvareh API request failed: "
            f"{response.status_code} - {preview}"
        ) from error

    result = response.json()

    try:
        return result["choices"][0]["message"]["content"]
    except (KeyError, IndexError, TypeError) as error:
        raise RuntimeError(
            "Unexpected API response structure."
        ) from error


def main() -> None:
    load_dotenv()

    api_key = os.getenv("DARVAREH_API_KEY")
    model_id = os.getenv("DARVAREH_MODEL_ID")

    if not api_key:
        raise RuntimeError(
            "DARVAREH_API_KEY is missing."
        )

    if not model_id:
        raise RuntimeError(
            "DARVAREH_MODEL_ID is missing."
        )

    validate_environment()

    data = create_sample_data()
    summary = prepare_summary(data)

    print("\nCalculated summary:")
    print(
        json.dumps(
            summary,
            ensure_ascii=False,
            indent=2,
        )
    )

    report = generate_report(
        records=summary,
        api_key=api_key,
        model_id=model_id,
    )

    print("\nAI report:")
    print(report)


if __name__ == "__main__":
    main()

اجرای پروژه

python app.py

ابتدای خروجی، مسیر Python و نسخه پکیج‌ها نمایش داده می‌شود. مسیر Python باید به Environment با نام darvareh-report مربوط باشد.

این بررسی ساده کمک می‌کند متوجه شوید برنامه واقعاً در محیط موردنظر اجرا شده است.

اجرای دستور بدون فعال‌کردن Environment

گاهی در Scriptهای خودکار نمی‌خواهید ابتدا conda activate اجرا کنید. می‌توانید از conda run استفاده کنید:

conda run \
  --name darvareh-report \
  python app.py

این دستور برای اجرای Taskهای مشخص، آزمایش محیط و بعضی Pipelineهای خودکار مفید است.

ساخت Environment برای Data Science

conda create \
  --name data-science \
  -c conda-forge \
  python=3.12 \
  numpy \
  pandas \
  scipy \
  matplotlib \
  seaborn \
  plotly \
  jupyterlab

فعال‌سازی:

conda activate data-science

اجرای Jupyter:

jupyter lab

ساخت Environment برای Machine Learning

conda create \
  --name machine-learning \
  -c conda-forge \
  python=3.12 \
  numpy \
  pandas \
  scikit-learn \
  xgboost \
  jupyterlab \
  ipykernel

برای کتابخانه‌های GPU مانند PyTorch یا TensorFlow از دستور نصب عمومی و ثابت استفاده نکنید. ترکیب نسخه Python، سیستم‌عامل، معماری پردازنده، Driver و نسخه CUDA اهمیت دارد. دستور مناسب را از مستندات رسمی همان Framework و بر اساس سخت‌افزار خود انتخاب کنید.

چرا نصب همه پکیج‌ها در base اشتباه است؟

نصب پکیج‌های پروژه داخل base ممکن است ابتدا ساده به نظر برسد، اما در ادامه مشکلاتی ایجاد می‌کند:

• وابستگی پروژه‌ها با هم ترکیب می‌شود.
• ارتقای یک پکیج ممکن است ابزارهای دیگر را مختل کند.
• مشخص نیست هر پروژه به چه نسخه‌ای وابسته است.
• بازسازی محیط روی سیستم دیگر دشوار می‌شود.
• حذف یک پکیج ممکن است روی چند پروژه اثر بگذارد.
• عیب‌یابی خطاهای Import پیچیده‌تر می‌شود.

قاعده ساده:

base = ابزار مدیریت Conda
هر پروژه = یک Environment جداگانه

مدیریت Cache و فضای دیسک

Conda فایل‌های دانلودشده و Cache پکیج‌ها را نگه می‌دارد. برای مشاهده عملیات پاک‌سازی احتمالی بدون انجام آن:

conda clean --all --dry-run

ابتدا خروجی را بررسی کنید. اگر تصمیم به پاک‌سازی گرفتید:

conda clean --all

پاک‌کردن Cache معمولاً Environmentهای نصب‌شده را حذف نمی‌کند، اما می‌تواند فایل‌های قابل استفاده برای نصب مجدد آفلاین یا Rollback را از بین ببرد. این دستور را صرفاً برای آزادکردن فضای جزئی و بدون بررسی اجرا نکنید.

خطاهای رایج Conda و راه‌حل آن‌ها

خطای conda is not recognized

در Windows:

'conda' is not recognized as an internal or external command

راه‌حل‌های پیشنهادی:

1. از Miniconda Prompt یا Anaconda Prompt استفاده کنید.
2. محل نصب را بررسی کنید.
3. در Prompt مخصوص Conda اجرا کنید:

conda init powershell

4. Terminal را کامل ببندید و دوباره باز کنید.

خطای conda: command not found در Linux یا macOS

ابتدا بررسی کنید Miniconda در مسیر معمول نصب شده است:

ls ~/miniconda3/bin/conda

اگر فایل موجود است:

~/miniconda3/bin/conda init

سپس Terminal را دوباره باز کنید.

دستور conda activate کار نمی‌کند

خطایی شبیه زیر ممکن است دیده شود:

CondaError: Run 'conda init' before 'conda activate'

اجرا کنید:

conda init

یا Shell را مشخص کنید:

conda init bash

conda init zsh

conda init powershell

بعد از آن Terminal جدیدی باز کنید.

حل وابستگی‌ها بسیار طول می‌کشد

علت‌های احتمالی:

• Environment قدیمی و شلوغ است.
• محدودیت نسخه‌ها با هم سازگار نیستند.
• چند Channel با اولویت نامشخص ترکیب شده‌اند.
• تعداد زیادی پکیج در یک محیط تغییر می‌کنند.
• Python انتخاب‌شده با پکیج موردنظر سازگار نیست.

راه‌حل‌های عملی:

• یک Environment کوچک و تازه بسازید.
• فقط پکیج‌های مستقیم پروژه را مشخص کنید.
• Channelها را محدود و اولویت آن‌ها را روشن کنید.
• نسخه‌های غیرضروری را Pin نکنید.
• پیش از نصب، سازگاری نسخه Python را بررسی کنید.
• تغییرات بزرگ را در Clone محیط آزمایش کنید.

PackagesNotFoundError

نمونه خطا:

PackagesNotFoundError

ابتدا نام پکیج و Channel را بررسی کنید:

conda search -c conda-forge package-name

اگر پکیج Conda موجود نیست، پس از فعال‌کردن Environment و نصب pip می‌توانید نسخه PyPI آن را بررسی کنید:

python -m pip install package-name

نام پکیج در Conda و PyPI همیشه یکسان نیست.

پکیج نصب است اما Import نمی‌شود

مسیر Python را ببینید:

python -c "import sys; print(sys.executable)"

سپس پکیج را بررسی کنید:

conda list package-name

اگر از Jupyter استفاده می‌کنید، داخل Notebook نیز اجرا کنید:

import sys
print(sys.executable)

اگر مسیرها متفاوت‌اند، مشکل از انتخاب Environment یا Kernel است.

محیط روی سیستم همکار ساخته نمی‌شود

احتمالاً فایل Export شامل وابستگی‌های مخصوص سیستم‌عامل، Buildهای دقیق یا مسیر prefix است.

یک فایل ساده و دستی بسازید که فقط شامل موارد زیر باشد:

• نام Environment
• Channel اصلی
• نسخه Python
• وابستگی‌های مستقیم
• پکیج‌های ضروری pip

از انتقال کل پوشه Environment بین دو سیستم خودداری کنید. فایل environment.yml را منتقل و محیط را دوباره بسازید.

خطای SSL هنگام نصب پکیج

برای رفع سریع خطا، SSL verification را غیرفعال نکنید. این کار بررسی اعتبار ارتباط را از بین می‌برد.

به‌جای آن موارد زیر را بررسی کنید:

• ساعت و تاریخ سیستم
• اتصال اینترنت
• Proxy سازمانی
• Certificateهای سازمان
• تنظیمات Firewall
• مسیر CA Bundle
• وضعیت Repository
• به‌روز بودن Conda

در شبکه سازمانی، تنظیم Certificate و Proxy باید طبق سیاست همان سازمان انجام شود.

VS Code محیط اشتباه را اجرا می‌کند

Interpreter را دوباره انتخاب کنید:

Ctrl + Shift + P
Python: Select Interpreter

سپس Terminal قدیمی را ببندید و Terminal جدید بسازید.

برای Notebook، Kernel را نیز جداگانه انتخاب کنید.

بهترین روش‌های استفاده از Conda

برای هر پروژه یک Environment بسازید

از نام‌های روشن استفاده کنید:

darvareh-api
sales-analysis
image-processing
ml-experiment

نسخه Python را مشخص کنید

به‌جای:

conda create -n project

بنویسید:

conda create -n project python=3.12

فقط وابستگی‌های مستقیم را ثبت کنید

فایل environment.yml نباید بدون دلیل با صدها پکیج غیرضروری پر شود.

پکیج‌های پروژه را در base نصب نکنید

محیط base را تمیز و پایدار نگه دارید.

Conda و pip را بدون برنامه ترکیب نکنید

ابتدا پکیج‌های Conda و سپس موارد ضروری pip را نصب کنید.

مسیر محلی را در فایل Environment منتشر نکنید

خط prefix را پیش از انتشار بررسی کنید.

Environment را داخل Git ذخیره نکنید

فقط فایل مشخصات را Commit کنید:

environment.yml

پوشه واقعی Environment حجیم و وابسته به سیستم است.

قبل از ارتقای بزرگ Clone بسازید

conda create \
  -n project-upgrade-test \
  --clone project

اجرای پروژه را از محیط تازه آزمایش کنید

فقط کارکردن روی سیستم توسعه‌دهنده کافی نیست. Environment را از environment.yml دوباره بسازید و پروژه را آزمایش کنید.

چک‌لیست Environment قابل بازتولید

پیش از انتشار یا تحویل پروژه بررسی کنید:

• نسخه Python مشخص است.
• Environment مخصوص پروژه ساخته شده است.
• پروژه به base وابسته نیست.
• Channelها مشخص هستند.
• وابستگی‌های مستقیم ثبت شده‌اند.
• پکیج‌های pip در فایل Environment ثبت شده‌اند.
• خط prefix محلی منتشر نشده است.
• فایل .env در Git قرار نگرفته است.
• API Key داخل کد نوشته نشده است.
• محیط از روی فایل با موفقیت ساخته می‌شود.
• تست اجرای پروژه در Environment تازه انجام شده است.
• Jupyter Kernel به Environment صحیح متصل است.
• VS Code از Interpreter صحیح استفاده می‌کند.
• ارتقای وابستگی‌ها ابتدا در محیط آزمایشی بررسی می‌شود.

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

آیا Anaconda رایگان است؟

دسترسی به Installer و شرایط استفاده از Repositoryها به نوع کاربر و شرایط جاری ارائه‌دهنده بستگی دارد. کاربران شخصی و سازمان‌ها باید شرایط به‌روز نسخه و Repository مورد استفاده را در وب‌سایت رسمی بررسی کنند. اگر استفاده سازمانی دارید، بر اساس حدس یا اطلاعات قدیمی تصمیم نگیرید.

آیا برای برنامه‌نویسی پایتون به Anaconda نیاز داریم؟

خیر. برای بسیاری از پروژه‌ها، نصب Python همراه با venv و pip کافی است. Conda زمانی مفیدتر می‌شود که چند نسخه Python، کتابخانه‌های علمی یا Environmentهای متعدد داشته باشید.

Miniconda بهتر است یا Anaconda؟

برای شروع سریع و محیط آماده، Anaconda ساده‌تر است. برای کنترل بیشتر، نصب سبک‌تر و انتخاب دقیق پکیج‌ها، Miniconda معمولاً گزینه مناسب‌تری است.

آیا می‌توان Anaconda و Python معمولی را هم‌زمان نصب کرد؟

بله، اما باید همیشه بررسی کنید Terminal، VS Code و Jupyter از کدام Python استفاده می‌کنند. دستور where python در Windows و which python در Linux و macOS مسیر فعال را نشان می‌دهد.

آیا Conda فقط برای Python است؟

خیر. Conda می‌تواند بعضی پکیج‌ها و وابستگی‌های خارج از اکوسیستم Python را نیز مدیریت کند و از زبان‌ها و ابزارهای دیگری پشتیبانی می‌کند. بااین‌حال، بیشترین استفاده آن در Python، Data Science و محاسبات علمی دیده می‌شود.

آیا داخل Conda می‌توان از pip استفاده کرد؟

بله. ابتدا pip را داخل همان Environment نصب و سپس از python -m pip استفاده کنید. بهتر است نصب‌های Conda پیش از نصب‌های pip انجام شوند.

چرا Jupyter پکیج نصب‌شده را پیدا نمی‌کند؟

احتمالاً Jupyter Kernel با Environment محل نصب پکیج متفاوت است. مسیر sys.executable را داخل Notebook بررسی و Kernel صحیح را انتخاب کنید.

آیا می‌توان برای هر پروژه نسخه متفاوت Python داشت؟

بله. برای مثال:

conda create -n project-a python=3.11
conda create -n project-b python=3.12

هر Environment نسخه Python و پکیج‌های مستقل خود را خواهد داشت.

آیا Conda برای پروژه‌های هوش مصنوعی مناسب است؟

بله. جداسازی نسخه Python، کتابخانه‌های Data Science، ابزارهای Notebook و وابستگی‌های Machine Learning از مهم‌ترین دلایل استفاده از Conda در پروژه‌های هوش مصنوعی است.

چگونه از داخل Conda به API درواره متصل شویم؟

یک Environment بسازید، requests و python-dotenv را نصب کنید، API Key را در .env قرار دهید و درخواست را به آدرس زیر ارسال کنید:

https://api.darvareh.ir/v1/chat/completions

جمع‌بندی

Anaconda، Miniconda و Conda سه مفهوم مرتبط اما متفاوت هستند. Conda ابزار مدیریت پکیج و Environment است، Miniconda یک نصب حداقلی از آن ارائه می‌دهد و Anaconda Distribution مجموعه کامل‌تری از ابزارهای Data Science را در اختیار کاربر قرار می‌دهد.

برای یک Workflow حرفه‌ای:

1. Miniconda یا توزیع مناسب خود را نصب کنید.
2. محیط base را برای مدیریت Conda نگه دارید.
3. برای هر پروژه Environment جداگانه بسازید.
4. نسخه Python را مشخص کنید.
5. پکیج‌های Conda را پیش از pip نصب کنید.
6. Environment را با environment.yml مستند کنید.
7. Jupyter و VS Code را به Interpreter صحیح متصل کنید.
8. تغییرات بزرگ را در Clone محیط آزمایش کنید.
9. API Key و اطلاعات حساس را خارج از کد نگه دارید.
10. پروژه را در یک Environment تازه دوباره اجرا کنید.

با این ساختار، نصب پروژه روی سیستم جدید، همکاری تیمی، مدیریت وابستگی‌ها و عیب‌یابی خطاها بسیار قابل پیش‌بینی‌تر می‌شود.

برای افزودن قابلیت‌های مدل‌های زبانی، تولید محتوا، پردازش متن یا تحلیل هوشمند به پروژه Python خود می‌توانید در درواره ثبت‌نام کرده و API Key دریافت کنید. فهرست مدل‌های قابل استفاده و قیمت به‌روز آن‌ها در صفحه مدل‌ها و قیمت‌های درواره قرار دارد.

منابع رسمی

• راهنمای رسمی نصب Conda
• راهنمای نصب Anaconda و Miniconda
• صفحه دانلود Anaconda Distribution
• مستندات مدیریت Environmentهای Conda
• مستندات مدیریت پکیج‌ها با Conda

مقالات مرتبط

• آموزش Google Colab برای هوش مصنوعی و API درواره
• آموزش هوش مصنوعی با پایتون؛ ساخت پروژه واقعی با API
• آموزش Pandas با پایتون؛ تحلیل و پاک‌سازی داده از صفر
• Scikit-learn چیست؟ آموزش کامل Machine Learning با پایتون
• PyTorch چیست؟ آموزش کامل ساخت و آموزش شبکه عصبی
• TensorFlow چیست؟ آموزش Keras و ساخت شبکه عصبی

برای مطالعه شرایط استفاده و محدودیت‌های مسئولیت، صفحه «سلب مسئولیت» را مشاهده کنید.