Namespace در Pinecone چیست و چه مشکلی را حل میکند؟
این جداسازی در معماری serverless حتی از نظر فیزیکی هم برقرار است: طبق مستندات رسمی Pinecone هر namespace جداگانه ذخیره میشود و همین موضوع هم ایزولهسازی داده را محکم میکند و هم پایهٔ محاسبهٔ هزینهٔ کوئری بر اساس حجم همان namespace است. به همین دلیل namespace ستون فقرات الگوی رسمی multitenancy در Pinecone است: یک namespace برای هر مستأجر روی یک ایندکس serverless.
- جداسازی دادهٔ هر مشتری (tenant isolation) در سرویسهای SaaS بدون ساخت ایندکس اضافه.
- تفکیک محیطها (dev / staging / prod) روی یک ایندکس با namespaceهای «env-dev» و «env-prod».
- پارتیشنبندی بر اساس زبان، برند یا نوع سند (مثلاً «lang-fa» و «lang-en»).
- حذف تقریباً آنی و کامل دادهٔ یک مجموعه هنگام offboarding مشتری یا expiry داده.
چه زمانی Namespace بزنیم و چه زمانی Metadata Filtering؟
راه دیگری هم برای جداسازی منطقی وجود دارد: فیلتر metadata. اگر به هر بردار تگ «tenant: acme» بدهید، میتوانید در زمان کوئری با فیلتر {"tenant": {"$eq": "acme"}} همان نتایج مشابهی بگیرید. اما انتخاب بین این دو فقط سلیقه نیست؛ مستندات رسمی Pinecone دلیل هزینهای صریحی برای ترجیح namespace در سناریوهای چندمستأجری میدهد: هزینهٔ هر کوئری بر اساس اندازهٔ namespace محاسبه میشود و فیلتر metadata از دادهٔ فیلترنشده عبور میکند، پس با رشد داده گرانتر میشود.
| مورد | ایزولهسازی داده | هزینهٔ کوئری با رشد داده | حذف سریع یک مجموعه | جستجوی بینمجموعهای | محاسبهٔ RU |
|---|---|---|---|---|---|
| Namespace | فیزیکی/منطقی در سطح پارتیشن | مستقل از حجم کل ایندکس؛ فقط حجم همان namespace | بله؛ delete_all روی همان namespace | خیر؛ هر کوئری فقط یک namespace | ۱ RU به ازای هر ۱ گیگابایت دادهٔ همان namespace |
| Metadata Filtering | منطقی در سطح رکورد | با رشد کل ایندکس بالا میرود؛ اسکن کل داده | خیر؛ باید رکورد به رکورد حذف کنید | بله؛ با تغییر filter روی کل namespace | RU بر اساس کل دادهٔ اسکنشده، مستقل از مقدار فیلتر |
- «من یک SaaS چندمستأجری دارم و دادهٔ هر مشتری نباید دیده شود» → namespace به ازای هر مستأجر.
- «فقط میخواهم محصولات موجود و ارزان را فیلتر کنم» → فیلتر metadata داخل همان namespace.
- «هر دو را میخواهم» → کوئری داخل namespace مستأجر با فیلتر metadata روی ویژگیهای رکورد.
- «گزارش ترکیبی از دادهٔ همهٔ مستأجرها لازم دارم» → کوئریهای موازی per-namespace و ادغام در لایهٔ اپلیکیشن.
کدام قواعد و محدودیتهای Namespace را باید بدانید؟
| قاعده | جزئیات | منبع |
|---|---|---|
| namespace پیشفرض | اگر namespace مشخص نکنید، عملیات روی namespace پیشفرض با نام "__default__" انجام میشود. | S1، S3 |
| ساخت خودکار | در هنگام upsert اگر namespace وجود نداشته باشد، ساخته میشود؛ میتوانید قبل از داده، با create_namespace بسازید. | S1، S3 |
| نامگذاری | نام namespace باید ASCII باشد، بدون کاراکتر NUL و تا ۵۱۲ کاراکتر. | S6 |
| Rename و انتقال | rename مستقیم و انتقال رکورد بین namespaceها پشتیبانی نمیشود؛ باید بردارها را بازخوانی و در namespace جدید upsert و سپس حذف کنید. | S1 |
| کوئری بین namespaceها | ممکن نیست؛ هر درخواست فقط یک namespace را هدف میگیرد. | S2، S6 |
| سقف تعداد | در ایندکس serverless به پلن بستگی دارد: از ۱۰۰ در Starter تا ۱٬۰۰۰٬۰۰۰ در Enterprise. | S2 |
چطور با curl اولین namespace را بسازیم و در آن داده بریزیم؟
برای نوشتن اولین namespace فقط سه چیز لازم دارید: کلید API از کنسول Pinecone، هاست یکتای ایندکس (که در بخش Target an index مستندات توضیح داده شده) و یک درخواست POST به endpoint /vectors/upsert با فیلد namespace. لازم نیست namespace را «از قبل بسازید»؛ طبق مستندات رسمی اگر وجود نداشته باشد، در همان لحظهٔ upsert ساخته میشود. بردارهای نمونهٔ این مقاله عمداً ۸بعدی و سادهاند تا تمرکز روی خودِ namespace بماند.
- 1
کلید و هاست ایندکس را آماده کنید
از کنسول Pinecone کلید API و هاست ایندکس serverless خود را بردارید و در دو متغیر محیطی نگه دارید. هرگز کلید واقعی را در کد یا گیت هاردکد نکنید.
- 2
با upsert و فیلد namespace داده بریزید
درخواست POST به /vectors/upsert بزنید و نام namespace را صریح بدهید؛ اگر وجود نداشته باشد همانجا ساخته میشود.
- 3
با کوئری داخل همان namespace جستجو کنید
همان نام namespace را در /query بدهید تا فقط بردارهای همان مستأجر جستجو شوند.
- 4
نتیجه را با describe_index_stats تأیید کنید
آمار ایندکس را بگیرید و ببینید namespace شما با تعداد بردار درست ظاهر شده است.
چطور با Python و JavaScript داخل یک namespace کوئری بزنیم؟
اگر با REST گامها را جلو بردید، حالا همان کار را در SDKها ببینید؛ منطق یکسان است و فقط syntax عوض میشود: در پایتون namespace یک آرگومان کلمهکلیدی در upsert و query است، در جاوااسکریپت یک آبجکت namespace روی index با متدهای زنجیرهای. هر دو نمونه زیر با اسنپشات ۲۰۲۶-۰۷ مستندات رسمی تطبیق داده شدهاند و قابل copy-paste با مقادیر خودتان هستند.
الگوی واقعی: multitenancy در یک سرویس RAG با namespace و APX24
در چنین پایپلاینی، هزینهٔ توکن فقط بعدِ هزینه است؛ چانکهای بازیابیشده ورودی مدل چت میشوند و هر چه topK بزرگتر و چانکها طولانیتر باشند، prompt_tokens و در نتیجه هزینهٔ ورودی بالا میرود. برای شروع، مدل اقتصادی را با temperature پایین امتحان کنید و کیفیت پاسخ را با پرسشهای واقعی مشتری بسنجید؛ مهاجرت بین مدلهای APX24 فقط تغییر یک فیلد در همان درخواست سازگار با OpenAI است.
چطور namespaceها را مدیریت، ممیزی و حذف کنیم؟
مدیریت چرخهٔ حیات namespace سه عملیات اصلی دارد: دیدن آمار (چه namespaceهایی دارم و چند بردار)، فهرستکردن (برای ممیزی و داشبورد ادمین) و حذف (برای offboarding یا پاکسازی محیط تست). describe_index_stats ارزانترین ابزار روزمرهٔ شماست و فهرستکردن در ایندکس serverless با صفحهبندی ۱۰۰تایی کار میکند.
خطاهای رایج namespace و راهحلهای قطعی؟
سه خطا بیشترین زمان توسعهدهندگان را در کار با namespace میگیرد: خطای احراز هویت ۴۰۱، کوئریهای خالی بهخاطر namespace اشتباه و خطای ۴۰۹ مخصوص aliasها. هر سه را با علت، راهحل و راه پیشگیری مرور میکنیم تا موقع وقوع، حدس نزنید بلکه بدانید.





