فیلتر در Qdrant چطور اجرا میشود و چرا گاهی کند است؟
وقتی یک درخواست با filter به POST /collections/{collection_name}/points/query میرسد، Qdrant اول میپرسد: زیرمجموعهٔ نقاطی که شرط را ارضا میکنند چقدر بزرگ است؟ اگر روی فیلدهای فیلتر Payload Index وجود داشته باشد، این برآورد (filter cardinality estimation) بدون دیدن تکتک نقاط و مستقیم از روی ایندکس انجام میشود. اگر ایندکس نباشد، برآورد دقیق ممکن نمیشود و عملاً کل collection بهعنوان زیرمجموعه در نظر گرفته میشود. سپس planner بین دو مسیر تصمیم میگیرد: اسکن دقیق روی زیرمجموعهٔ کوچک، یا پیمایش گراف HNSW با بررسی شرط فیلتر روی گرهها. تمام بهینهسازی این مقاله، تغذیهٔ همین تصمیم با دادهٔ درست است.
Payload Index چیست و چطور آن را بسازیم؟
| field_schema | مناسب برای | نمونه شرط فیلتر |
|---|---|---|
| keyword | دستهبندیهای محدود؛ شهر، وضعیت، زبان | match با value — یا any برای چند مقدار |
| integer | شناسهها و مقادیر صحیح | range با gte/lte یا match |
| float | قیمت و امتیاز اعشاری | range با gte/lte |
| datetime (از v1.8+) | تاریخ و زمان ISO 8601 | range با مقایسهٔ زمانی |
| uuid (از v1.11+) | شناسههای یکتا | match با رشتهٔ UUID |
| bool (از v1.4+) | فقط دو حالت؛ موجود/ناموجود | match با true/false |
| geo | مختصات جغرافیایی | geo_radius یا geo_bounding_box |
| text | جستجوی متنی در payload | match با text و tokenizer |
فیلتر must و should و must_not را چطور بنویسیم؟
فیلتر Qdrant سه بند منطقی دارد: must یعنی همهٔ شرطها (AND)، should یعنی حداقل یکی (OR) و must_not یعنی هیچکدام (NOT). این بندها بهصورت بازگشتی تودرتو میشوند تا هر عبارت بولی دلخواه ساخته شود؛ میتوانید داخل یک must، یک فیلتر کامل دیگر بگذارید. یک نکتهٔ خوانایی: برای «یکی از چند مقدار» بهجای چند شرط should، از match با any استفاده کنید — همان OR با کد کوتاهتر. شرطهای دیگر مثل is_empty و is_null و has_id و شرطهای تودرتو روی آبجکتهای payload هم در همین ساختار جا میگیرند.
- match — برابری مقدار؛ روی keyword و integer و bool و uuid کار میکند.
- match با any — «یکی از چند مقدار»؛ معادل IN در SQL.
- match با except — «هرچیزی بهجز این مقادیر»؛ معادل NOT IN.
- range — محدودهٔ عددی/زمانی با gte و gt و lte و lt؛ روی integer و float و datetime.
- values_count — روی تعداد عناصر آرایه در payload شرط میگذارد.
- geo_radius و geo_bounding_box — فیلتر مکانی روی فیلد geo.
- is_empty و is_null — نقاطی که فیلد ندارند یا null است.
- has_id — فیلتر مستقیم روی شناسهٔ نقاط.
- شرط تودرتو (nested) — فیلتر روی لیستی از آبجکتها در payload.
Filterable HNSW چطور هم سریع میشود و هم دقیق؟
HNSW گراف چندلایهٔ همسایگی است که جستجوی تقریبی KNN را با پیچیدگی تقریباً لگاریتمی نسبت به تعداد نقاط انجام میدهد؛ برای همین اسکن کامل لازم ندارد. مشکل کلاسیک، فیلتر است: نزدیکترین نقاط گراف ممکن است شرط فیلتر را نقض کنند. راهحل سادهٔ «اول جستجو، بعد حذف» (post-filtering) در فیلترهای انتخابی شکست میخورد، چون از k نتیجهٔ برگشتی شاید فقط چند مورد بماند. Qdrant رویکرد خود را از سال ۲۰۱۹ روی Filterable HNSW گذاشت: حین پیمایش گراف، فقط گرههایی که شرط را دارند بهعنوان نتیجه و مسیر استفاده میشوند و برای فیلدهای ایندکسشده، اتصالات فیلترآگاه اضافه ساخته میشود تا مسیر کوتاه از دست نرود.
- 1
برآورد cardinality
planner از روی Payload Indexها حدس میزند شرط فیلتر چند نقطه را ارضا میکند.
- 2
انتخاب استراتژی
اگر حجم بردارهای زیرمجموعه از full_scan_threshold_kb کوچکتر باشد، اسکن دقیق روی همان زیرمجموعه انجام میشود؛ وگرنه مسیر HNSW انتخاب میشود.
- 3
پیمایش گراف با فیلتر
در مسیر HNSW، شرط فیلتر روی هر گره بررسی میشود و فقط نقاط مجاز وارد کاندیدای نهایی میشوند؛ اتصالات فیلترآگاه مسیر را کوتاه نگه میدارند.
- 4
بازگرداندن limit نتیجه
بهترین نقاط مجاز تا سقف limit مرتب و برگردانده میشوند؛ فیلد time در پاسخ کل زمان را گزارش میکند.
چکلیست بهینهسازی؛ از cardinality تا is_tenant و on_disk
بهینهسازی فیلتر یک تغییر جادویی نیست؛ ترکیب چند تصمیم کوچک است که هرکدام یک گوشهٔ پنهان هزینه را میبندند. جدول زیر، اقداماتی است که در بیشترین پروژهها بیشترین اثر را داشتهاند — به ترتیب نسبت اثر به زحمت. کدام را اول اجرا کنید؟ همانهایی که فیلترهای پرمصرف اپلیکیشن خودتان را پوشش میدهند؛ برای این کار ابتدا پرسوجوهای واقعی production را مرور کنید و ببینید روی کدام فیلدها تکرار میشوند.
| اقدام | کی انجام دهیم | اثر مورد انتظار |
|---|---|---|
| ساخت Payload Index برای هر فیلد پرتکرار فیلتر | قبل از درج داده؛ در migration اولیه | حذف اسکن وسیع و فعالشدن برآورد cardinality |
| انتخاب field_schema درست؛ keyword برای تساوی، integer/float برای محدوده، datetime برای زمان | هنگام طراحی schema | پشتیبانی planner از نوع شرط شما |
| is_tenant: true برای فیلد مالکیت مثل org_id (از v1.11+) | اپهای SaaS چندکاربری | چیدمان سگمنت بر اساس tenant؛ هر پرسوجو فقط دادهٔ سازمان خودش |
| memory: "cached" برای فیلدهای داغ روی دیسک (از v1.11+) | payload سنگین ولی پرمصرف | کاهش RAM بدون از دست دادن سرعت |
| افزایش hnsw_ef (مثلاً 128) وقتی Recall کم است | بعد از سنجش Recall با exact | بازیابی دقیقتر به قیمت latency بیشتر |
| exact=true فقط برای benchmark و زیرمجموعهٔ کوچک | تست صحت و data validation | نتیجهٔ قطعی؛ در collection بزرگ پرهزینه |
| تنظیم full_scan_threshold_kb متناسب با بعد بردار | tuning نهایی با بار واقعی | انتخاب هوشمند planner بین اسکن و گراف |
- Baseline بگیرید: برای ۵۰ پرسوجوی واقعی، فیلد time پاسخها را ثبت و P50/P95 محاسبه کنید.
- فیلدهای پرتکرار فیلتر را شناسایی و ایندکس بسازید — ترجیحاً قبل از درج داده.
- با points/count زیرمجموعهٔ هر فیلتر را اندازه بگیرید تا cardinality واقعی دستتان بیاید.
- پرسوجوها را با Query API و params مناسب (hnsw_ef، exact) بازنویسی کنید.
- دوباره benchmark بگیرید و جداول latency و Recall را با baseline مقایسه کنید.
RAG واقعی؛ فیلتر در Qdrant + تولید پاسخ با APX24
خطاهای رایجی که سرعت فیلتر را میکشند
تمرین کنید؛ سه سناریوی واقعی
مطالعهٔ مقاله فقط تصویر ذهنی میسازد؛ حافظهٔ عضلانی واقعی developer با اجرای کد ساخته میشود. سه تمرین در بخش تمرینها آمدهاند: یکی ساده روی ایندکسگذاری و پرسوجو، یکی متوسط روی سنجش Recall و یکی چالشی روی عیبیابی latency. تمرین دوم را حتماً روی collection واقعی خودتان اجرا کنید؛ عدد Recall که خودتان اندازه بگیرید، عمیقتر از هر توضیحی در ذهن میماند.





