Query Engine در LlamaIndex چیست و چه مشکلی را حل میکند؟
تفاوت این رابط با یک فراخوانی سادهٔ LLM در دو چیز است. اول، مدل فقط به دانش عمومی خودش تکیه نمیکند؛ مستندات شما در لحظه بازیابی و داخل پرامپت تزریق میشود — همان الگوی RAG [S6]. دوم، خروجی فقط متن نیست؛ آبجکت Response شامل source_nodes است تا بتوانید هر ادعا را به سند اصلی گره بزنید. همین دو ویژگی، Query Engine را برای کاربردهای حقوقی، مالی و پشتیبانی که پاسخِ قابلراستیآزمایی میخواهند، حیاتی میکند.
| مورد | ورودی | خروجی | حافظهٔ مکالمه | کاربرد اصلی |
|---|---|---|---|---|
| Retriever | متن پرسش | لیست گرههای خام با نمرهٔ شباهت | ندارد | بازیابی قطعات مرتبط بدون سنتز |
| Query Engine | یک سؤال مستقل | پاسخ سنتزشده + source_nodes | ندارد | پرسشوپاسخ مستندمحور |
| Chat Engine | پیام کاربر در مکالمه | پاسخ مکالمهای | دارد (تاریخ چت) | گفتوگوی چندمرحلهای |
Query Engine چطور از یک سؤال، یک پاسخ مستند میسازد؟
- 1
امبدینگ پرسش
پرسش کاربر با همان مدل امبدینگی که اسناد با آن ایندکس شدهاند، به بردار تبدیل میشود تا مقایسهٔ معنایی ممکن باشد.
- 2
جستوجوی برداری
در Vector Store، نزدیکترین گرهها به بردار پرسش بر اساس متریک شباهت (پیشفرض: کسینوسی) پیدا میشوند.
- 3
انتخاب Top-K
فقط K قطعهٔ دارای بالاترین نمرهٔ شباهت انتخاب میشوند؛ این K همان پارامتر similarity_top_k است که هم کیفیت و هم هزینه را کنترل میکند.
- 4
سنتز پاسخ
قطعات انتخابی در قالب پرامپت پیشفرض (متن Context information is below... بههمراه دستور پاسخ فقط بر اساس زمینه و بدون دانش قبلی) کنار پرسش قرار میگیرد و به LLM فرستاده میشود.
- 5
بازگشت Response
LLM پاسخ را برمیگرداند؛ LlamaIndex آن را همراه با source_nodes و نمرات شباهت در یک آبجکت Response میپیچد که هم متن و هم منابع را در اختیار شما میگذارد.
نکتهٔ مهم برای تیمهای فنی: توکنهای ورودی هر پرسوجو برابر است با پرامپت سیستمی + پرسش + K قطعهٔ بازیابیشده. یعنی هرچه similarity_top_k را بالاتر ببرید، هزینه و تأخیر خطی بالا میرود اما پوشش اطلاعات بهتر میشود. این همان پیچ تنظیمی است که باید بر اساس اندازهٔ chunk و ماهیت سؤالهای واقعی کاربران تنظیم کنید — در بخش هزینه دقیقاً همین عدد را حساب میکنیم.
برای شروع چه پیشنیازها و ابزارهایی لازم است؟
- Python 3.10 یا بالاتر همراه با pip
- کلید API از apx24.ir/account/api-keys با پیشوند sk-apx-
- اعتبار فعال در حساب APX24 (شارژ تومانی از apx24.ir/buy-credit)
- یک پوشهٔ data شامل چند فایل متنی، Markdown یا PDF فارسی برای ایندکس
چطور LlamaIndex را به API هوش مصنوعی APX24 متصل کنم؟
APX24 یک دروازهٔ API سازگار با فرمت OpenAI (OpenAI-compatible v1) است؛ یعنی هر ابزاری که بتواند به OpenAI وصل شود، با تغییر آدرس پایه (api_base) و کلید، به APX24 هم وصل میشود. در LlamaIndex این کار با کلاس OpenAILike انجام میشود — یک wrapper نازک روی کلاس OpenAI که مخصوص سرویسهای دارای API سازگار با OpenAI طراحی شده است. [S2] سرویس APX24 نیز همین قرارداد را رسماً اعلام کرده و بهازای هر مدل تعرفهٔ توکنی جداگانه دارد. [S7]
چطور در چهار گام اولین Query Engine را بسازم؟
چطور پاسخ را استریم کنم و منابع را ببینم؟
انواع Query Engine کداماند و چه زمانی از هر کدام استفاده کنم؟
| نوع | کلاس / سازنده | بهترین کاربرد |
|---|---|---|
| استاندارد برداری | index.as_query_engine() | پرسشوپاسخ روی اسناد با بازیابی معنایی |
| ارجاعدار | CitationQueryEngine | پاسخهایی که باید شمارهٔ منبع [n] داشته باشند |
| مسیریاب | RouterQueryEngine | انتخاب خودکار بین چند Query Engine یا منبع داده |
| چندبخشی | SubQuestionQueryEngine | سؤالات پیچیدهای که باید به چند زیرسؤال شکسته شوند |
| SQL | NLSQLTableQueryEngine | پرسش زبان طبیعی روی پایگاه دادهٔ رابطهای |
- پرسشهای مستقل روی اسناد: همان as_query_engine استاندارد — ساده و ارزان.
- پاسخهای قابلاستناد برای کاربر: CitationQueryEngine — ارجاع [n] اعتماد میسازد.
- چند منبع داده (اسناد + FAQ + دیتابیس): RouterQueryEngine — خودش انتخاب میکند کجا برود.
- سؤالهای ترکیبی مثل «مقایسهٔ سیاست مرخصی دو شعبه»: SubQuestionQueryEngine — به زیرسؤالها میشکند.
- اعداد و آمار در دیتابیس: NLSQLTableQueryEngine — سؤال فارسی به SQL و پاسخ طبیعی.
هزینهٔ هر پرسوجو در APX24 چقدر است؟
صورتحساب APX24 بهازای هر درخواست بر اساس توکن ورودی و خروجی محاسبه میشود؛ در Query Engine، ورودی شامل پرامپت سیستمی + پرسش + K قطعهٔ بازیابیشده و خروجی همان پاسخ مدل است. قیمتها به تومان و بهازای هر یک میلیون توکن است، بدون حداقل مصرف و بدون هزینهٔ اشتراک؛ درخواست ناموفق هم شارژ نمیشود. [S7]
خطاهای رایج اتصال LlamaIndex به APX24 و راهحلها
بهترین شیوهها و کاربردهای واقعی در کسبوکار
- نسخهٔ بستهها را پین کنید (llama-index-core در requirements.txt) تا ارتقاها کد را نشکنند.
- به هر Document متادیتا بدهید (واحد، تاریخ، سطح دسترسی) تا بازیابی قابلفیلتر و امن شود.
- مصرف توکن (فیلد usage) را لاگ کنید؛ بودجهٔ ماهانه را روی نرمال مصرف ببندید نه حدس.
- similarity_top_k و chunk_size را با ۲۰–۳۰ سؤال واقعی کاربران تیون کنید، نه با شهود.
- برای پاسخهای حساس، آستانهٔ نمرهٔ شباهت بگذارید: زیر حد مشخص، «مستند یافت نشد» بگویید.
- برای مقیاس، index را در vector store دائمی (Chroma، Qdrant، pgvector) ذخیره کنید نه حافظهٔ فرایند.




