راهنما

نصب و نخستین اجرا

روش پیشنهادی برای اجرای پارس‌رگ، Docker Compose همراه با Ollamaی است که از قبل روی رایانه‌تان نصب است: یک کانتینر برنامه رابط کاربری و API را ارائه می‌کند، Qdrant بردارها را نگه می‌دارد و پاسخ‌ها را Ollamaی خودتان می‌نویسد. اجرای Ollama داخل Docker و استفاده از مدل‌های API، راه‌های دیگر اجرا هستند.

پیش‌نیازها

برنامهٔ Docker Desktop در ویندوز یا مک، یا Docker Engine همراه با Compose در لینوکس، و ۸ تا ۱۶ گیگابایت RAM.
برنامهٔ Ollama نصب‌شده روی رایانه، برای راه‌اندازی پیشنهادی. اگر آن را ندارید، Ollama را داخل Docker اجرا کنید یا از یک مدل API استفاده کنید.
فضای دیسک کافی برای imageها و وزن مدل‌ها.

راه‌اندازی کامل

در راه‌اندازی پیشنهادی، پاسخ‌ها را همان Ollamaی می‌نویسد که روی رایانه‌تان نصب است، با مدل‌هایی که از قبل دارید و روی GPU خودش. برنامه از راه نشانی host.docker.internal به آن وصل می‌شود؛ پس نه پروفایل Compose لازم است و نه فایل override، و کانتینر برنامه هم به GPU نیازی ندارد. روی مک تنها راه تولید پاسخ با GPU همین است، چون Docker نمی‌تواند GPU مک را در اختیار کانتینر بگذارد.

برنامهٔ Ollama را نصب کنید و یک مدل بگیرید. روی GPU حدود ۶ گیگابایتی، مدل ۳ تا ۴ میلیارد پارامتری کاملاً روی GPU اجرا می‌شود.
فایل .env.example را با نام .env کپی کنید و در LLM_MODEL_NAME نام مدلی را بنویسید که گرفته‌اید. پیش‌فرض‌های این فایل از قبل برنامه را به Ollamaی همین رایانه وصل می‌کنند: OLLAMA_DOCKER_BASE_URL=http://host.docker.internal:11434.
فقط در لینوکس: Ollama به‌طور پیش‌فرض فقط روی 127.0.0.1 گوش می‌دهد و کانتینرها به آن نمی‌رسند. سرویس Ollama را روی نشانی پل Docker تنظیم کنید، مثلاً OLLAMA_HOST=172.17.0.1:11434. ویندوز و مک کاری لازم ندارند.
پارس‌رگ را اجرا کنید، نشانی http://127.0.0.1:8000 (یا پورتی که در PARSRAG_PORT گذاشته‌اید) را باز کنید، سند بارگذاری کنید و بپرسید.

ollama pull qwen2.5:7b
Copy-Item .env.example .env
docker compose up -d --build
ollama ps

در مک یا لینوکس، فایل تنظیمات را با cp .env.example .env کپی کنید. وقتی پاسخ در حال نوشته‌شدن است، دستور ollama ps نشان می‌دهد مدل کجا اجرا می‌شود؛ عبارت 100% GPU یعنی کل مدل روی GPU است. پورت فقط روی نشانی 127.0.0.1 در دسترس است، مگر اینکه PARSRAG_BIND_HOST را تغییر دهید.

برنامهٔ Ollama احراز هویت ندارد. در لینوکس نشانی پل را ترجیح دهید: مقدار OLLAMA_HOST=0.0.0.0 درگاه Ollama را روی همهٔ شبکه‌هایی که رایانه به آن‌ها وصل است باز می‌کند. اگر از آن استفاده می‌کنید، درگاه 11434 را فقط برای شبکه‌های Docker باز بگذارید.

روش‌های دیگر اجرا

نوع نصب	مناسب برای	روش
اجرای Ollama داخل Docker روی CPU	وقتی Ollama روی رایانه نصب نیست؛ روی هر سیستمی اجرا می‌شود	پروفایل local-model، همراه با OLLAMA_DOCKER_BASE_URL=http://ollama:11434 و OLLAMA_MODEL در فایل .env
کارت NVIDIA	اجرای Ollama داخل Docker با ساخت embedding و تولید پاسخ سریع‌تر در ویندوز یا لینوکس	افزودن فایل compose.gpu.yaml
کارت NVIDIA با VRAM کم	کارت‌های حدود ۶ گیگابایتی که جای هر دو مدل را ندارند	افزودن فایل compose.gpu-low-vram.yaml: embedding روی CPU و پنجرهٔ زمینهٔ Ollama برابر ۲۰۴۸
کارت AMD	میزبان‌های لینوکسی پشتیبانی‌شده با ROCm	افزودن فایل compose.amd.yaml (با PyTorch 2.6 و wheelهای ROCm)
مدل از راه API	وقتی سخت‌افزار محلی مناسبی ندارید	تنظیم LLM_PROVIDER=api و نشانی سرویس در فایل .env، یا انتخاب آن در تنظیمات برنامه

docker compose --profile local-model up -d qdrant ollama
docker compose --profile local-model run --rm ollama-init
docker compose --profile local-model up -d --build app

نخستین اجرا

مدل تبدیل متن به بردار (intfloat/multilingual-e5-base) و رتبه‌بند حالت ترکیبی (حدود ۱۰۰ مگابایت) در کش مدل‌ها دانلود می‌شوند.
با Ollamaی خود رایانه، پارس‌رگ هیچ مدلی دانلود نمی‌کند. با Ollama داخل Docker، سرویس ollama-init مدل تنظیم‌شده را فقط یک بار، در volume مخصوص خودش، دانلود می‌کند.
تا وقتی همه‌چیز آماده نشده، نشانی /health/ready با کد 503 و وضعیت preparing پاسخ می‌دهد و رابط هم نشان می‌دهد که مدل و پایگاه اسناد در حال آماده‌شدن‌اند.
اگر هنگام شروع برنامه Ollama خاموش باشد، برنامه باز هم آماده می‌شود. تا Ollama روشن نشود، پرسش‌ها پیام می‌گیرند که سرویس مدل در دسترس نیست و بعد بدون راه‌اندازی دوباره کار می‌کنند.
پس از نخستین دانلودها، نصبی که با Ollama محلی کار می‌کند می‌تواند آفلاین اجرا شود.

اجرا بدون Docker

برای اجرای مستقیم به Python 3.12، Node.js 22، یک Qdrant در حال اجرا، Ollama یا یک سرویس سازگار با OpenAI، و برای OCR به Tesseract با داده‌های فارسی و انگلیسی نیاز دارید. فایل .env.example را با نام .env کپی کنید و علامت # را از سطرهای بخش «Running without Docker» در انتهای آن بردارید: نشانی Qdrant، نشانی Ollama، فایل تنظیمات و OCR_ENABLED=1.

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-runtime.txt -c requirements.lock
Set-Location frontend
npm ci
npm run build
Set-Location ..
.\.venv\Scripts\python.exe -m uvicorn backend.main:app --host 127.0.0.1 --port 8000

در اجرای مستقیم، تا وقتی OCR_ENABLED=1 را تنظیم نکنید OCR خاموش می‌ماند. در نصب با Docker، OCR روشن است.

دستورهای روزمره

docker compose ps
docker compose logs -f app
docker compose down

دستور docker compose down داده‌ها را نگه می‌دارد. اما docker compose down -v بردارها، تنظیماتی که در برنامه ذخیره کرده‌اید، کش‌ها و وزن مدل‌های Ollama داخل Docker را برای همیشه پاک می‌کند.