راهنما
معماری
بک‌اند با الگوی پورت و آداپتور سازمان‌دهی شده است: هسته فقط رابط‌ها (interface) را می‌شناسد و یک ریشهٔ ترکیب (composition root) آن‌ها را به Qdrant، تجزیه‌گرها، OCR و کلاینت‌های مدل وصل می‌کند.
| لایه | چه چیزی در آن است |
|---|---|
| دامنه | اسناد، قسمت‌ها، شیوه‌های پرسش، سیاست بارگذاری، تنظیمات زمان اجرا، خطاها |
| اشیای انتقال داده (DTO) | درخواست‌های اعتبارسنجی‌شده و پاسخ‌های نوع‌دار |
| پورت‌ها | مخزن داده، تجزیه‌گر، بخش‌بند، خلاصه‌گر پرسش، دروازهٔ مدل، گزارش پیشرفت، رتبه‌بند، انبارهٔ تنظیمات زمان اجرا |
| یوزکیس‌ها | برای هر عملیات یک کلاس: دریافت و ایندکس سند، پاسخ، پیشنهاد پرسش، استفادهٔ دوباره، حذف، تنظیم مدل، فهرست مدل‌های Ollama، تغییر تنظیمات زمان اجرا، نمایش تصویر ارجاع‌شده و… |
| راهبردها | مسیرهای «فقط اسناد»، «ترکیبی» و «گفت‌وگوی آزاد»؛ ارجاع‌ها؛ بودجهٔ زمینه؛ یکسان‌سازی فارسی |
| آداپتورها | پایگاه برداری Qdrant و ایندکس BM25، کلاینت‌های مدل LlamaIndex، رتبه‌بند FlashRank، تجزیه‌گرهای PDF، Office و OCR |
| لایهٔ API | مسیرهای FastAPI، میان‌افزارها، نگاشت خطاها و رویدادهای جریانی (Server-Sent Events) |
در Compose سه کانتینر تعریف شده است: برنامه، Qdrant و Ollama که فقط با پروفایل local-model اجرا می‌شود. برنامه می‌تواند به‌جای کانتینر Ollama از Ollamaی نصب‌شده روی میزبان استفاده کند که از راه host.docker.internal در دسترس است؛ در این حالت مدل‌ها و GPU میزبان مستقیم به کار می‌روند. خطاها با کدهای ollama_url_not_allowed یا ollama_unreachable گزارش می‌شوند.
رابط HTTP
| مسیر | کاربرد |
|---|---|
| GET /health/live, /health/ready | بررسی زنده‌بودن سرویس، و آمادگی آن وقتی مدل‌ها و Qdrant در دسترس‌اند |
| GET /capabilities | محدودیت‌های بارگذاری و نوع فایل‌های پشتیبانی‌شده |
| GET, PUT /models/configuration | خواندن اتصال مدل، یا بررسی و اعمال آن |
| GET /models/ollama | مدل‌های نصب‌شدهٔ Ollama |
| GET, PUT, DELETE /settings/runtime | خواندن، تغییر یا بازگرداندن تنظیماتی که در برنامه تغییر کرده‌اند |
| POST /ingest | بارگذاری و ایندکس فایل‌ها |
| POST /query, /query/stream | پاسخ به پرسش، یکجا یا جریانی |
| POST /sessions/{id}/suggestions | سه پرسشی که اسناد جوابشان را دارند |
| POST /sessions/{id}/files/reuse | کپی سند ایندکس‌شده از گفت‌وگوی دیگر |
| GET /sessions/{id}/images/{n} | تصویری که بخش ارجاع‌شده از آن خوانده شده |
| GET, DELETE /sessions/{id}/files | فهرست یا حذف اسناد یک گفت‌وگو |
| DELETE /sessions/{id} | حذف ایندکس یک گفت‌وگو |
پاسخ جریانی
مسیر POST /query/stream رویدادها را به این ترتیب می‌فرستد: stage (درک، بازیابی، نگارش)، sources، یک token برای هر تکه از متن، و در پایان done همراه با پاسخ کامل، نتیجهٔ آن و شمارهٔ بخش‌های ارجاع‌شده. خطاها به شکل رویداد error با یک کد ثابت می‌رسند.
هر پاسخ خطا، کنار پیامش یک کد ثابت دارد تا رابط بتواند خطا را به زبان شما توضیح دهد.