نصب قدم‌به‌قدم ComfyUI

معرفی ComfyUI

ComfyUI یک محیط تصویری مبتنی بر Node است که با آن می‌توانید workflowهای تولید تصویر را بسازید و اجرا کنید. این راهنما شما را از انتخاب روش نصب تا باز شدن رابط، شناسایی مدل و یک اجرای آزمایشی کوتاه همراهی می‌کند.

برای نصب محلی چند راه رسمی وجود دارد. اگر تازه‌کار هستید لازم نیست از ابتدا Python، Git یا CUDA را دستی پیکربندی کنید؛ ابتدا روش مناسب خود را انتخاب کنید.

انتخاب روش نصب و دانلود امن

ComfyUI را فقط از صفحه دانلود رسمی ComfyUI، مستندات رسمی یا مخزن رسمی GitHub دریافت کنید. از دانلودکننده‌ها و mirrorهای ناشناس استفاده نکنید؛ آن‌ها ممکن است قدیمی باشند یا فایل ناامن ارائه کنند.

طبق راهنمای رسمی، Comfy Desktop ساده‌ترین نقطه شروع برای کاربران جدید Windows و macOS است. نسخه Portable نیز یک بسته مستقل Windows است که Python موردنیاز را در خود دارد؛ آن را فقط از راهنمای Portable رسمی دریافت کنید. نصب دستی را در ادامه آورده‌ایم تا کاربران فنی بتوانند محیط خود را مدیریت کنند.

پیش‌نیازها: چه چیزهایی واقعاً لازم است؟

لازم

• یک سیستم سازگار با روش انتخابی: برای Comfy Desktop در Windows، Windows 10 یا جدیدتر و معماری x64 یا ARM64 لازم است.
• فضای دیسک برای برنامه، مدل‌ها و خروجی‌ها. راهنمای Desktop برای هر نصب دست‌کم 4.85 گیگابایت فضا را پیشنهاد می‌کند؛ فایل مدل‌ها فضای جداگانه و قابل‌توجهی می‌گیرند.
• برای مسیر دستی: Python، Git و اتصال اینترنت برای دریافت وابستگی‌ها.

پیشنهادی

• GPU مجزا برای تولید تصویر با سرعت مناسب. داشتن GPU شرط باز شدن ComfyUI نیست، اما اجرای CPU معمولاً بسیار کندتر است.
• برای NVIDIA، درایور به‌روز NVIDIA. درایور و CUDA Toolkit یک چیز نیستند: PyTorch بسته سازگار با شتاب‌دهنده را فراهم می‌کند و نصب CUDA Toolkit به‌صورت جداگانه، پیش‌نیاز عمومی این آموزش نیست.
• RAM و VRAM بیشتر، تجربه بهتری می‌دهد؛ مقدار لازم به مدل، رزولوشن، workflow و batch size بستگی دارد. از یک عدد ثابت به‌عنوان حداقل همه‌کاره استفاده نکنید.

وابسته به روش

• Comfy Desktop و Portable نیاز ندارند شما Python یا Git را جداگانه نصب و فعال کنید.
• در نصب دستی، از محیط جداگانه Python استفاده کنید تا وابستگی‌های ComfyUI با پروژه‌های دیگر تداخل نداشته باشند. نسخه Python و وابستگی‌های GPU را مطابق راهنمای رسمی و نیازمندی‌های نسخه ComfyUI انتخاب کنید؛ بعضی custom nodeها ممکن است با نسخه‌های جدیدتر Python سازگار نباشند.

نصب پیشنهادی برای مبتدیان در Windows: Comfy Desktop

1. صفحه دانلود رسمی ComfyUI را باز کنید و installer مربوط به Windows را دانلود کنید.
2. فایل .exe دانلودشده را اجرا و مراحل installer را دنبال کنید.
3. بعد از نصب، Comfy Desktop را از Start Menu یا میان‌بر دسکتاپ باز کنید.
4. در صفحه Welcome، اولین installation را بسازید و منتظر بمانید تا برنامه آماده شود.

اگر مراحل درست انجام شده باشند، Desktop فهرست installationهای ComfyUI را نشان می‌دهد و می‌توانید instance خود را باز کنید. برای جزئیات به‌روزِ نصب و به‌روزرسانی، از راهنمای رسمی Comfy Desktop برای Windows استفاده کنید.

برای کاربران Windows: اگر نسخه‌ای مستقل و قابل استخراج می‌خواهید، Portable را از مستندات رسمی انتخاب کنید. بسته متناسب با GPU را بگیرید، archive را extract کنید و فایل اجرای متناسب—برای مثال run_nvidia_gpu.bat برای NVIDIA—را اجرا کنید. Portableهای جدید برای سخت‌افزارهای مختلف بسته‌های جدا دارند؛ قبل از دانلود، بخش سازگاری GPU در راهنمای رسمی را بخوانید.

نصب دستی ComfyUI برای کاربران فنی

این مسیر برای Windows، Linux و macOS است. قبل از شروع، راهنمای نصب دستی رسمی را برای سیستم‌عامل و GPU خود باز نگه دارید؛ دستور PyTorch با توجه به سیستم‌عامل، کارت گرافیک و نسخه‌های فعلی تغییر می‌کند.

۱. ساخت و فعال‌سازی محیط Python

پس از نصب Python مناسب، در پوشه‌ای که می‌خواهید پروژه در آن قرار بگیرد یک محیط مجازی بسازید:

python -m venv comfyenv

در Windows:

comfyenv\Scripts\activate

در Linux یا macOS:

source comfyenv/bin/activate

وقتی نام محیط در ابتدای خط فرمان ظاهر شد، فعال‌سازی موفق بوده است. اگر python در Windows پیدا نشد، نصب Python و گزینه افزودن آن به PATH را بررسی کنید؛ در صورت نیاز از Python Launcher (py) استفاده کنید.

۲. دریافت سورس رسمی

Git باید نصب باشد. سپس، در حالی که محیط مجازی فعال است، این دستورات را اجرا کنید:

git clone https://github.com/Comfy-Org/ComfyUI.git
cd ComfyUI

پس از موفقیت باید پوشه ComfyUI و فایل‌هایی مانند requirements.txt و main.py را ببینید. اگر پیام git is not recognized دریافت کردید، Git را از سایت رسمی Git نصب کنید و ترمینال را دوباره باز کنید.

۳. نصب PyTorch و وابستگی‌های ComfyUI

ابتدا دستور PyTorch سازگار با سیستم و GPU خود را از صفحه رسمی نصب PyTorch انتخاب و در همان محیط مجازی فعال اجرا کنید. یک دستور ثابت برای همه کارت‌ها و سیستم‌عامل‌ها وجود ندارد؛ به‌ویژه NVIDIA، AMD، Intel، macOS و CPU مسیرهای متفاوتی دارند.

سپس وابستگی‌های خود ComfyUI را نصب کنید:

pip install -r requirements.txt

اگر از NVIDIA استفاده می‌کنید، به‌جای نصب CUDA Toolkit صرفاً به‌خاطر این آموزش، ابتدا مطمئن شوید درایور NVIDIA به‌روز است و دستور فعلی PyTorch را از منبع رسمی انتخاب کرده‌اید.

افزودن مدل یا checkpoint

خود ComfyUI یک مدل تولید تصویر را به‌طور خودکار همراه با نصب شما دریافت نمی‌کند. برای تولید تصویر، حداقل به یک checkpoint سازگار نیاز دارید: فایلی که وزن‌های مدل را نگه می‌دارد و معمولاً پسوندهایی مانند .safetensors دارد.

مدل را از منبع معتبر و مطابق مجوز آن دریافت کنید؛ آن را با خود ComfyUI اشتباه نگیرید. برای نصب دستی و Portable، فایل checkpoint را در این مسیر قرار دهید:

ComfyUI/models/checkpoints/

مسیرهای رایج دیگر عبارت‌اند از:

• VAE: ComfyUI/models/vae/
• LoRA: ComfyUI/models/loras/
• ControlNet: ComfyUI/models/controlnet/

پس از کپی‌کردن مدل، ComfyUI را restart کنید. اگر checkpoint در فهرست انتخاب مدل ظاهر نشد، ابتدا نام و مسیر فایل را بررسی کنید. برای نگه‌داری مدل‌ها خارج از پوشه پیش‌فرض، از تنظیم رسمی extra_model_paths.yaml استفاده کنید؛ راهنمای Portable و مسیرهای مدل نمونه آن را توضیح می‌دهد.

اجرای ComfyUI و تشخیص موفقیت

در نصب دستی، از داخل پوشه ComfyUI و در حالی که محیط مجازی فعال است اجرا کنید:

python main.py

در Portable، فایل اجرای متناسب با سخت‌افزار را اجرا کنید. در هر دو روش، پس از راه‌اندازی سرور باید پیامی شبیه این ببینید:

To see the GUI go to: http://127.0.0.1:8188

مرورگر ممکن است خودکار باز شود. اگر باز نشد، مرورگر را دستی باز کنید و به آدرس زیر بروید:

http://127.0.0.1:8188

نمایش رابط گره‌ای ComfyUI و قابل‌انتخاب بودن checkpoint، نشانه‌های اصلی آماده‌بودن نصب هستند. پنجره Terminal یا Command Prompt را نبندید؛ با بستن آن، سرور محلی ComfyUI نیز متوقف می‌شود.

بررسی شتاب GPU و یک تست کوتاه

در مسیر دستی، پیش از تولید تصویر می‌توانید در همان محیط فعال، تشخیص PyTorch را بررسی کنید:

python -c "import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'CUDA unavailable')"

خروجی True و نام GPU یعنی PyTorch کارت NVIDIA را برای CUDA تشخیص داده است. خروجی False یا CUDA unavailable یعنی برنامه با شتاب CUDA اجرا نمی‌شود؛ این به معنی خراب‌بودن خود رابط نیست، اما تولید تصویر ممکن است روی CPU بسیار کند باشد. این بررسی مخصوص CUDA/NVIDIA است؛ برای AMD، Intel یا Apple Silicon باید مسیر رسمی همان پلتفرم را دنبال کنید.

برای یک تست حداقلی، checkpoint را در workflow پیش‌فرض انتخاب کنید، بدون دست‌کاری ساختار workflow آن را queue کنید و منتظر بمانید خروجی در رابط نمایش داده شود. هدف این مرحله فقط تأیید نصب، شناسایی مدل و اجرای یک job است، نه آموزش workflow. اگر این مرحله بدون خطا انجام شد، ادامه طبیعی مسیر یادگیری در ساخت اولین Workflow حرفه‌ای در ComfyUI است.

خطاهای رایج نصب و راه‌حل کوتاه

GPU یا CUDA شناسایی نمی‌شود

نشانه: دستور بررسی PyTorch مقدار False یا CUDA unavailable برمی‌گرداند، یا در اجرا پیام مربوط به CUDA می‌بینید.

راه‌حل: ابتدا درایور NVIDIA را به‌روزرسانی کنید، محیط مجازی فعال را بررسی کنید و نسخه ناسازگار PyTorch را با دستور مناسبِ صفحه رسمی PyTorch جایگزین کنید. برای این مشکل به نصب تصادفی CUDA Toolkit تکیه نکنید.

خطای نصب وابستگی‌ها یا ناسازگاری Python

نشانه: pip install -r requirements.txt با خطا پایان می‌یابد یا یک custom node بعداً خطای نسخه Python می‌دهد.

راه‌حل: مطمئن شوید دستور را در comfyenv اجرا کرده‌اید، Python را بررسی کنید و برای نصب پایه از راهنمای رسمی استفاده کنید. اگر مسئله فقط با custom node رخ داد، آن node را از مسیر نصب اولیه جدا کنید؛ Python 3.12 می‌تواند برای سازگاری بعضی nodeها گزینه مناسب‌تری باشد.

checkpoint در رابط دیده نمی‌شود

نشانه: فهرست مدل خالی است یا نام فایل جدید نمایش داده نمی‌شود.

راه‌حل: فایل checkpoint را مستقیماً در ComfyUI/models/checkpoints/ قرار دهید، نه در پوشه‌ای با نام مشابه یا یک سطح پایین‌تر. سپس ComfyUI را restart کنید. برای مسیر سفارشی از extra_model_paths.yaml استفاده کنید.

مرورگر باز نمی‌شود یا پورت 8188 اشغال است

نشانه: برنامه در Terminal اجرا شده ولی صفحه‌ای باز نمی‌شود، یا پیام اشغال‌بودن پورت می‌بینید.

راه‌حل: ابتدا http://127.0.0.1:8188 را دستی باز کنید. در صورت اشغال‌بودن پورت، برنامه دیگری را که از 8188 استفاده می‌کند ببندید یا فقط با مراجعه به راهنمای startup flags رسمی پورت را تغییر دهید.

در اولین تولید با کمبود VRAM روبه‌رو می‌شوید

نشانه: اجرای workflow شروع می‌شود اما با خطای out-of-memory متوقف می‌شود.

راه‌حل: ابتدا مدل سبک‌تر، رزولوشن پایین‌تر یا batch size برابر ۱ را امتحان کنید. نیاز VRAM به مدل و workflow بستگی دارد؛ برای روش‌های بهینه‌سازی بیشتر، راهنمای کاهش مصرف VRAM در Stable Diffusion را بخوانید.

درباره custom nodeها

برای نصب و اجرای اولیه به custom node یا ComfyUI Manager نیاز ندارید. ابتدا مطمئن شوید ComfyUI پایه با یک checkpoint اجرا می‌شود، سپس در صورت نیاز فقط از مخزن رسمی ComfyUI-Manager و دستورالعمل همان نسخه استفاده کنید. افزودن nodeها می‌تواند وابستگی‌های جداگانه و ناسازگاری نسخه ایجاد کند.