درون معماری Chimerai برای خودکارسازی بازیابی اطلاعات با FastAPI

تصور کنید بخواهید یک سیستم پاسخ‌گویی هوشمند بر اساس اسناد شخصی خود بسازید، اما هفته‌ها وقتتان را صرف تنظیم متغیرهای محیطی و مسیرهای پروکسی کنید. حالا با یک دستور ساده، تمام این پیچیدگی‌ها حذف شده است. «یک دستور»؛ این تمام چیزی است که اکنون برای استقرار یک خط لوله کامل تولید بازیابی‌افزا (RAG) در یک پروژه Next.js لازم است.

به نقل از مستندات منتشر شده در ۲۹ سپتامبر ۲۰۲۶، chimerai ابزاری را معرفی کرد که فاصله میان آموزش‌های ساده‌ی ۳۰ خطی و فرآیندهای پیچیده خرید پایگاه‌داده‌های برداری سازمانی را از بین می‌برد. اکثر توسعه‌دهندگان با «منطقه میانی» RAG دست‌وپنجه نرم می‌کنند: ساخت سیستمی که فراتر از یک دموی ساده باشد اما در عین حال به یک پروژه زیرساختی عظیم تبدیل نشود. Chimerai این مشکل را با خودکارسازی اتصال یک سرویس هوش مصنوعی پایتونی مستقیماً به یک اپلیکیشن فرانت‌اند حل می‌کند.

این ابزار به توسعه‌دهندگان اجازه می‌دهد بدون درگیر شدن در زیرساخت‌های سنگین، یک خط لوله تولید بازیابی‌افزا (RAG) — شبیه دانش‌آموزی که قبل از جواب دادن، اول کتاب درسی را باز می‌کند و از آن نقل می‌آورد — را مستقیماً در پروژه‌های Next.js مستقر کنند. این رویکرد در مقایسه با سایر چارچوب‌های محبوب RAG، تمرکز ویژه‌ای بر سرعت استقرار در محیط‌های وب دارد. همان‌طور که در تحلیل‌های قبلی ما درباره‌ی بهینه‌سازی استنتاج در مدل‌های محلی اشاره کردیم، حذف لایه‌های زائد در ارتباط بین فرانت‌اند و بک‌اند، کلید افزایش سرعت توسعه است. Chimerai این کار را با اجرای دستور npx chimerai add rag انجام می‌دهد. این دستور یک سرویس پایتونی مستقل را در مسیر services/ai/ نصب می‌کند که از FastAPI برای لایه API و LiteLLM برای مسیریابی بین ارائه‌دهندگان مختلف مدل‌ها استفاده می‌کند. در این معماری، فرانت‌اند هرگز مستقیماً با پایتون ارتباط برقرار نمی‌کند، بلکه از مسیرهای پروکسی Next.js استفاده می‌کند که درخواست‌ها را به AI_SERVICE_URL (که به طور پیش‌فرض http://localhost:8002 است) هدایت می‌کنند.

معماری سرویس

ساختار پوشه‌ی services/ai/ برای تغییرپذیری بالا و ماژولار بودن طراحی شده است:

• config.py: مدیریت تنظیمات Pydantic و بارگذاری متغیرهای محیطی.
• provider_client.py: مدیریت مسیریابی چند-ارائه‌دهنده (multi-provider routing) از طریق LiteLLM.
• main.py: نقطه ورود FastAPI که بر اساس یک مانیفست تولید شده است.
• services/: شامل منطق اصلی سیستم؛ از جمله rag_service.py برای چرخه جذب-بازیابی-پاسخ (ingest-retrieve-answer)، vector_store.py برای مدیریت ایندکس FAISS و پایداری داده‌ها، و embedding_service.py برای تولید بردار معنایی (Embedding) از طریق LiteLLM — مثل کارت معرفی عددی برای هر واژه که می‌گوید این کلمه همسایه‌ی چه کلمات دیگری است.
• routes/rag_routes.py: تعریف نقاط اتصال (Endpoints) برای /api/rag/upload (آپلود)، /query (پرس‌وجو) و /stats (آمار).
• data/: دایرکتوری محلی که در آن ایندکس FAISS روی دیسک ذخیره می‌شود.

جزئیات فنی خط لوله

طبق گزارش فنی Chimerai، این سیستم از یک جریان سه‌مرحله‌ای سخت‌گیرانه پیروی می‌کند:

• جذب (Ingest): سیستم از یک RecursiveCharacterTextSplitter با اندازه تکه (chunk size) ۱۰۰۰ کاراکتر (تقریباً ۲۵۰ توکن انگلیسی) و هم‌پوشانی (overlap) ۲۰۰ کاراکتر استفاده می‌کند تا پیوستگی حقایق بین تکه‌ها حفظ شود. این تکه‌بند از یک سلسله‌مراتب خاص از جداکننده‌ها استفاده می‌کند: ["\n\n", "\n", ". ", " ", ""]. برای فعال کردن ارجاعات در رابط کاربری (مانند «منبع: صفحه ۳»)، به هر تکه متادیتایی شامل _chunk_index (ایندکس تکه)، _chunk_total (تعداد کل تکه‌ها) و _source_doc_index (ایندکس سند منبع) اختصاص می‌یابد.
• ذخیره (Store): بردارها توسط FAISS و با استفاده از IndexFlatL2 مدیریت می‌شوند تا جستجوی دقیق و Brute-force روی بردارهای ۱۵۳۶ بعدی انجام شود. این تنظیمات به‌طور خاص برای مدل text-embedding-ada-002 شرکت OpenAI بهینه شده است. چون از یک ایندکس تخت (Flat Index) استفاده می‌کند، نرخ بازیابی (Recall) کامل است زیرا تمام بردارها را اسکن می‌کند، هرچند در کد ذکر شده که برای مجموعه‌داده‌های بزرگتر می‌توان آن را به IndexIVFFlat تغییر داد. در این راستا، برخی راهکارهای جایگزین مانند NanoAgent حتی امکان پیاده‌سازی RAG را بدون نیاز به پایگاه‌داده‌های برداری فراهم کرده‌اند تا پیچیدگی‌های زیرساختی کاهش یابد.
• بازیابی (Retrieve): سیستم متون بازیابی شده را در پرامپت سیستمی «می‌چپاند» (Stuffing). سیستم تعداد k سند را بازیابی کرده و آن‌ها را به صورت [Document i] برچسب‌گذاری می‌کند تا مدل بتواند به آن‌ها ارجاع دهد. یک حفاظ (Guardrail) حیاتی در پیام سیستمی گنجانده شده است: «اگر متن حاوی اطلاعات لازم نیست، صراحتاً اعلام کن و یک پاسخ کلی ارائه بده». این کار مانع از تکیه مدل به حافظه پارامتریک خود می‌شود که در غیر این صورت، اعداد ارزیابی سیستم را به داستان‌های تخیلی تبدیل می‌کرد و باعث توهم (Hallucination) می‌شد.

تیم Chimerai برای پایداری سیستم، یک لایه محافظ برای وارد کردن (Import) FAISS پیاده کرده است. در پایتون ۳.۱۳ یا برخی نسخه‌های ویندوز، نصب faiss-cpu یا numpy ممکن است با خطا مواجه شود. به جای کرش کردن کل سرویس در زمان شروع، ماژول از یک بلوک try-except استفاده می‌کند تا متغیر FAISS_AVAILABLE = False را تنظیم کند. هر نقطه ورود RAG ابتدا تابع _check_availability() را فراخوانی می‌کند و به جای یک ImportError پیچیده در اعماق کد، یک خطای واضح با متن «FAISS vector store is not available» صادر می‌کند. این تضمین می‌کند که قابلیت‌های چت، حفاظ‌ها و ابزارهای دیگر حتی در صورت نبود بازیابی، به کار خود ادامه دهند.

پایداری داده‌ها از طریق یک ذخیره‌ساز دیسک محلی مدیریت می‌شود که ایندکس را در data/faiss_index و متادیتای مربوطه را در یک فایل .pkl ذخیره می‌کند. این ذخیره‌ساز تک-فرآیندی (single-process) در هنگام شروع بارگذاری شده و پس از هر عملیات جذب داده، روی دیسک نوشته می‌شود.

پیاده‌سازی و استفاده

توسعه‌دهندگان می‌توانند از طریق چندین نقطه اتصال API با خط لوله تعامل کنند:

• افزودن اسناد: یک درخواست POST به http://localhost:8002/api/rag/documents که لیستی از اسناد و متادیتای مربوطه (مثلاً {"source": "docs", "page": 1}) را می‌پذیرد.
• چت مبنی‌سازی شده (Grounded Chat): یک درخواست POST به http://localhost:8002/api/rag/chat که اجازه می‌دهد query (پرس‌وجو)، model (مثلاً gpt-3.5-turbo) و تعداد تکه‌های بازیابی شده k را مشخص کنید.
• مسیرهای کاربردی: سرویس همچنین مسیر /api/rag/search را برای بازیابی بدون تولید متن توسط LLM، مسیر /api/rag/stats برای بررسی سلامت ایندکس و /api/rag/clear برای پاکسازی کامل ذخیره‌ساز فراهم می‌کند.

پاسخ دریافتی از نقطه اتصال چت شامل یک بلوک rag_metadata است. این بلوک تعداد retrieved_documents و متن دقیق هر تکه به همراه امتیاز شباهت (مثلاً 0.123) را لیست می‌کند. این قابلیت به توسعه‌دهندگان اجازه می‌دهد دقیقاً عیب‌یابی کنند که چرا هوش مصنوعی پاسخ خاصی را ارائه داده است.

باید توجه داشت که این ساختار (Scaffold) به عنوان یک راهکار دائمی سازمانی در نظر گرفته نشده است، بلکه نقطه‌ای برای شروع با مرزهای مشخص است. استفاده از ایندکس تخت باعث می‌شود با عبور از ده‌ها هزار تکه، عملکرد سیستم افت کند. همچنین، ذخیره‌سازی تک-فرآیندی روی دیسک، فاقد مکانیسم‌های قفل‌گذاری (Locking) مورد نیاز برای مقیاس‌پذیری افقی در چندین نمونه (Instance) است؛ در واقع اجرای دو نمونه از سرویس منجر به ایجاد دو ایندکس متفاوت و واگرا می‌شود.

زمانی که پروژه رشد می‌کند و از این تنظیمات فراتر می‌رود، مسیر ارتقا کاملاً مشخص است. توسعه‌دهندگان باید ایندکس تخت را با IndexIVFFlat یا HNSW جایگزین کنند یا به یک پایگاه‌داده برداری تخصصی مانند pgvector، Qdrant یا Weaviate مهاجرت کنند. برای اپلیکیشن‌های چند-مستاجر (Multi-tenant)، ایندکس سراسری فعلی باید با فیلترهای متادیتایی جایگزین شود تا فضای نام کاربران از هم جدا گردد. علاوه بر این، اگر کیفیت بازیابی به بن‌بست رسید، کاربران ممکن است نیاز به پیاده‌سازی جستجوی ترکیبی برای پر کردن شکاف‌های دقت، باز-رتبه‌بندی (Re-ranking) یا تنوع‌بخشی MMR داشته باشند.

با مشخص کردن دقیق نقاط شکست، chimerai به توسعه‌دهندگان اجازه می‌دهد سریع بسازند بدون اینکه بترسند بدهی فنی (Technical Debt) نامرئی به ارث ببرند. شما می‌توانید با یک اسکلت‌بندی شروع کنید و هر جزء — چه ایندکس و چه ذخیره‌ساز — را تنها زمانی که کیفیت بازیابی متوقف شد، جایگزین کنید.

گام بعدی شما

• برای تست سریع پیاده‌سازی، دستور chimerai create my-rag-app --sqlite --yes را اجرا کرده و سپس chimerai add rag و در نهایت chimerai dev را بزنید. پرچم --sqlite باعث می‌شود داکر برای پایگاه‌داده اپلیکیشن نادیده گرفته شود، در حالی که سرویس AI همچنان به عنوان یک فرآیند پایتونی مستقل اجرا می‌شود.
• اگر حجم داده‌های شما از ۱۰ هزار رکورد گذشت، ایندکس FAISS را به IndexIVFFlat تغییر دهید.
• برای محیط عملیاتی، سرویس پایتون را از دیسک محلی به یک Volume مشترک در داکر منتقل کنید.

اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.