متادیتا در ChromaDB چیست و چرا فیلترکردن آن همهچیز را تغییر میدهد؟
در Chroma هر رکورد (Record) فقط یک بردار و یک متن نیست؛ میتواند یک دیکشنری کامل از اطلاعات جانبی هم با خود حمل کند: وضعیت تیکت، اولویت، زبان کاربر، نوع مشتری و حتی فهرستی از تگها. به این دادههای ساختاریافته، متادیتا (Metadata) میگویند. متادیتا درون بردار ذخیره نمیشود و در محاسبهٔ شباهت معنایی دخالتی ندارد؛ در عوض بهعنوان شرط ساختاری روی نتایج اعمال میشود. همین تفاوت ساده، مرز میان «جستجوی شبیه» و «جستجوی قابلاعتماد» است.
پس این دو ابزار جای یکدیگر را نمیگیرند، مکملاند: بردار «معنا» را میفهمد و متادیتا «شرط ساختاری» را اعمال میکند. اگر چتبات پشتیبانی شما با جستجوی برداری خالص، تیکتهای بسته و رفعشده را هم به مدل تحویل دهد، پاسخ تولیدشده بر اساس راهحلهای قدیمی و منسوخ خواهد بود. با یک where ساده میتوانید پیش از رسیدن به مدل، این آلودگی را حذف کنید؛ بدون آنکه حتی یک توکن اضافه بپردازید.
| عملگر | کار | مثال | نوع مقدار |
|---|---|---|---|
| $eq (یا کوتاهنویسی مستقیم) | تساوی | {"status": "open"} | str / int / float / bool |
| $ne | نابرابری | {"status": {"$ne": "closed"}} | همنوع فیلد |
| $gt و $gte | بزرگتر (یا مساوی) | {"priority": {"$gte": 2}} | int / float |
| $lt و $lte | کوچکتر (یا مساوی) | {"priority": {"$lt": 3}} | int / float |
| $in | عضویت در فهرست | {"language": {"$in": ["fa", "en"]}} | فهرست همنوع |
| $nin | عدم عضویت در فهرست | {"language": {"$nin": ["en"]}} | فهرست همنوع |
| $and و $or | ترکیب شرطها | {"$and": [{...}, {...}]} | فهرستِ حداقل ۲ عبارت |
| $contains / $not_contains | عضویت در آرایهٔ متادیتا (تگها) | {"tags": {"$contains": "billing"}} | مقدار اسکالر همنوع عناصر آرایه |
پیشنیازها: قبل از اولین فیلتر چه چیزی لازم دارید؟
- Python 3.9 یا بالاتر (تست مقاله با Python 3.12 انجام شده است)
- مدیر بستهٔ pip برای نصب chromadb
- بستهٔ chromadb — نسخهٔ توصیهشده: 1.5 یا بالاتر (مقاله با 1.5.9 تست شده)
- کلید API اپکس۲۴ — فقط برای بخش پروژهٔ واقعی (بخش ۹)؛ بقیهٔ مقاله کاملاً آفلاین اجرا میشود
چطور متادیتا را هنگام ذخیرهسازی به رکورد اضافه کنیم؟
برای اینکه همهٔ مثالها قابلتکرار باشند، در سراسر مقاله از یک دیتاست کوچک اما واقعنما استفاده میکنیم: هشت تیکت پشتیبانی یک سرویس API با شش فیلد متادیتا. متادیتا هنگام متد add و در آرگومان metadatas داده میشود؛ هر عنصر یک دیکشنری کامل و مستقل است و به ids همان اندیس پاسخ میدهد. این کد را یکبار اجرا کنید — همهٔ خروجیهای بعدی مقاله از همین دیتاست آمدهاند.
| فیلد | نوع | مقادیر نمونه | کاربرد اصلی در فیلتر |
|---|---|---|---|
| topic | str | billing، api_key، streaming | شرط تساوی و $in |
| status | str | open، pending، closed | شرط تساوی، $ne |
| priority | int | 1 تا 3 | عملگرهای عددی $gte، $lt |
| language | str | fa، en | $in و $nin |
| customer | str | free، enterprise | شرط تساوی، $or |
| tags | آرایهٔ str | [billing, payment] | $contains و $not_contains |
فیلترهای تساوی و فهرست: $eq، $ne، $in و $nin
سادهترین فیلتر، یک جفت کلید-مقدار مستقیم است: {"status": "open"}. Chroma این را میانبُرِ تساوی میداند و معادل {"status": {"$eq": "open"}} است. برای مقادیر چندگانه از $in استفاده میشود و برای «هر چیز جز این» از $ne و $nin. در ادامه هر چهار حالت را روی دیتاست تیکت اجرا کردهایم و خروجیها عیناً از اجرای واقعی روی chromadb 1.5.9 آمده است.
فیلترهای عددی و بازهای: $gt، $gte، $lt و $lte
چهار عملگر مقایسهای فقط روی فیلدهای int و float معنا دارند و در آستانهگذاریهای واقعی بینقصاند: اولویت بالای یک حد، قیمت زیر سقف، امتیاز بین دو مرز. دو نکته تجربی: اول، بازهٔ نیمهباز (مثل ۲≤priority<۳) در Chroma مستقیم نوشته نمیشود و باید با $and ترکیب شود — همینجا در این بخش. دوم، اگر نوع فیلد رشته باشد حتی یک مقدار رشتهای معتبر هم جواب نمیدهد؛ Chroma اصلاً وارد مقایسه نمیشود.
ترکیب شرطها با $and و $or — و قانون تککلیدی که همه را غافلگیر میکند
قانون طلایی where این است: در سطح بالا همیشه دقیقاً یک کلید مجاز است — یا نام یک فیلد، یا یکی از $and/$or. برای «این و آن»، هر شرط را داخل آکولاد جدا بنویسید و در فهرست $and بگذارید؛ برای «این یا آن» فهرست را به $or بدهید. عناصر داخل $or لازم نیست همنوع باشند: یک شرط رشتهای و یک شرط عددی میتوانند کنار هم بنشینند و این دقیقاً چیزی است که در سناریوهای SLA به آن نیاز دارید.
متادیتای آرایهای: فیلتر روی تگها با $contains و $not_contains
تگها، دستهبندیهای چندگانه و شناسهٔ اجزا از پرکاربردترین ساختارهای دنیای واقعیاند که در یک مقدار اسکالر جا نمیشوند. Chroma به نسخههای خانوادهٔ 1.x اجازه میدهد مقدار متادیتا خودش یک آرایهٔ همنوع باشد و با $contains و $not_contains رویش فیلتر نوشت. در دیتاست ما فیلد tags همین نقش را دارد: ticket-1 با تگهای billing و payment.
| قاعده | توضیح | مثال مجاز / غیرمجاز |
|---|---|---|
| همنوعی عناصر | همهٔ عناصر آرایه باید از یک نوع باشند | مجاز: ["a", "b"] — غیرمجاز: ["a", 1] |
| ممنوعیت آرایهٔ خالی | آرایهٔ بدون عنصر ذخیره نمیشود | غیرمجاز: [] — کلید را حذف کنید |
| ممنوعیت تو در تو | آرایهٔ داخل آرایه پشتیبانی نمیشود | غیرمجاز: [["a"], ["b"]] |
| مقدار $contains | باید اسکالرِ همنوع با عناصر باشد | روی آرایهٔ str فقط str بدهید |
ترکیب فیلتر متادیتا با جستجوی برداری و جستجوی متنی
اینجا سه لایهٔ جستجوی Chroma در یک فراخوانی جمع میشوند: لایهٔ معنایی با query_texts (یا query_embeddings)، لایهٔ ساختاری با where و لایهٔ متنی با where_document. Chroma هر سه را مثل AND منطقی روی هم سوار میکند: ابتدا کاندیدهای واجد شرطِ متادیتا و متن مشخص میشوند، بعد در میان آنها جستجوی برداری انجام و n_results نتیجهٔ برتر برگردانده میشود. نتیجهٔ عملی: خروجی query هم معنایی دقیق دارد، هم از نظر شرطهای کسبوکاری مطمئن است.
پروژهٔ واقعی: چتبات RAG با فیلتر متادیتا و مدلهای اپکس۲۴
تا اینجا همهچیز محلی بود؛ حالا حلقه را کامل کنیم. سناریو: کاربر فارسیزبان دربارهٔ شارژ اعتبار میپرسد، Chroma فقط تیکتهای بازِ billing به زبان فارسی را برمیگرداند و مدل زبانی اپکس۲۴ بر اساس همین قطعات فیلترشده پاسخ میدهد. اپکس۲۴ از فرمت سازگار با OpenAI استفاده میکند؛ پس با همان OpenAI SDK رسمی و تغییر base_url کار میکند و کد شما بین پلتفرمها قابلحمل میماند.
| مدل | هزینهٔ هر درخواست | هزینهٔ روزانه | هزینهٔ ماهانه (۳۰ روز) |
|---|---|---|---|
| gpt-6-luna (ورودی ۵٬۴۰۰ / خروجی ۲۷٬۰۰۰ تومان) | ۱۸٫۹ تومان | ۱۸٬۹۰۰ تومان | ۵۶۷٬۰۰۰ تومان |
| claude-sonnet-5 (ورودی ۱۶۲٬۰۰۰ / خروجی ۸۱۰٬۰۰۰ تومان) | ۵۶۷ تومان | ۵۶۷٬۰۰۰ تومان | ۱۷٬۰۱۰٬۰۰۰ تومان |
| gpt-6-astra (ورودی ۵۴۰٬۰۰۰ / خروجی ۲٬۷۰۰٬۰۰۰ تومان) | ۱٬۸۹۰ تومان | ۱٬۸۹۰٬۰۰۰ تومان | ۵۶٬۷۰۰٬۰۰۰ تومان |
بهروزرسانی متادیتا و چکلیست production
متادیتا نوشتهشده و تمام نیست؛ وضعیت تیکتها در زندگی واقعی دائماً عوض میشود. متد update تنها فیلدهای دادهشده را بازنویسی میکند و بقیهٔ کلیدها دستنخورده میمانند — برخلاف تغییر document که بردار را دوباره میسازد، آپدیت متادیتا سبک و فوری است. یک تابع کمکی هم برای ساخت where چندفیلدی میبینید که همان قانون تککلیدی را برای همیشه از کدتان حذف میکند.
- اسکیمای متادیتا را نسخهگذاری کنید (مثلاً schema_version در خود رکورد) تا مهاجرتهای بعدی قابلتشخیص باشند.
- مقدار None هرگز به متادیتا ندهید؛ فیلد غایب را کلاً حذف کنید و رفتار $ne/$nin با کلید غایب را در تصمیمها لحاظ کنید.
- فیلدهای عددی را واقعاً عدد ذخیره کنید؛ رشتهٔ "2" در فیلترهای $gt/$gte شکست میخورد.
- برای هر فیلتر پرتکرار، یک تست خودکار با دیتاست ثابت بنویسید و خروجی انتظار را assert کنید.
- در query همیشه include را صریح بدهید و embeddings را فقط وقتی واقعاً لازم است بیاورید.
- کلید API اپکس۲۴ را از متغیر محیطی بخوانید و برای هر محیط (توسعه/تولید) کلید جدا بسازید.





