ایندکس برداری در Pinecone چیست و کدام تصمیمها را کنترل میکند؟
ایندکس برداری جایی است که بردارهای embedding شما بههمراه متادیتا (metadata) ذخیره میشوند و جستجوی شباهت روی آنها اجرا میشود. برخلاف یک لیست ساده در حافظه که باید همهٔ بردارها را یکییکی مقایسه کنید، ایندکس برداری با الگوریتمهای ANN (جستجوی تقریبی نزدیکترین همسایه) در کسری از ثانیه، نزدیکترین بردارها به بردار پرسوجو را پیدا میکند. در Pinecone این ایندکس سرویسِ مدیریتشده است: شما فقط پارامترهای ساخت را انتخاب میکنید و مقیاسدهی، توزیع و نگهداشت با خود Pinecone است [S1].
واژهٔ کلیدی این بخش «ANN» یا Approximate Nearest Neighbor است. الگوریتمهای ANN بهجای مقایسهٔ قطعی با همهٔ بردارها، ساختارهایی میسازند که فقط بخشی از کاندیدها را بررسی میکنند؛ نتیجه در عمل برای جستجوی معنایی کاملاً قابلاعتماد است، اما این پذیرشِ تقریب همان چیزی است که تأخیر (latency) چند صد میلیثانیهای را روی میلیونها بردار ممکن میکند. Pinecone جزئیات الگوریتم را از شما پنهان میکند و بهجای آن، همان چهار تصمیم سطحبالا را از شما میخواهد [S1].
- نوع ایندکس و شکل داده: بردار dense خارجی، بردار sparse، یا ایندکس سند (document index) با فیلدهای متنی و برداری
- معیار فاصله (metric): cosine، dotproduct یا euclidean — برای dense پیشفرض cosine است [S2]
- ابعاد (dimension): باید دقیقاً برابر ابعاد خروجی مدل embedding شما باشد
- استقرار (deployment): cloud و region برای ایندکس serverless — مثل aws و us-east-1 [S1]
- ساختار منطقی: تقسیم داده بین namespaceها و انتخاب فیلدهای متادیتا برای فیلتر کردن
در معماری امروزی Pinecone چه انتخابهایی برای استقرار ایندکس داریم؟
اولین تصمیم استراتژی، لایهٔ استقرار است. Pinecone معماری serverless را پیشفرض خود کرده است: ایندکس روی زیرساخت ابریِ مدیریتشده بالا میآید، cloud و region را شما انتخاب میکنید (مثلاً aws و us-east-1) و ظرفیت بهصورت خودکار مدیریت میشود. در مقابل، ایندکسهای pod-based قدیمی — که با انواعی مثل s1 و p2 و واحدهای محاسباتی ثابت کار میکردند — در مستندات فعلی «legacy» نامیده میشوند و به کاربران جدید ارائه نمیشوند [S3]. برای پروژهٔ جدید، این تصمیم عملاً یک تصمیم است: serverless.
Pod indexes are legacy and unavailable to new customers, and serverless is recommended.
— مستندات رسمی Pinecone — Understanding pod-based indexes
| مورد | وضعیت در مستندات ۲۰۲۶ | دریافت برای کاربران جدید | مقیاسدهی | انتخاب ظرفیت | مناسب برای |
|---|---|---|---|---|---|
| Serverless | معماری پیشفرض و توصیهشده | بله | خودکار توسط Pinecone | فقط انتخاب cloud و region | پروژههای جدید، RAG، جستجوی معنایی، multi-tenant |
| Pod-based | legacy | خیر — برای کاربران جدید غیرفعال | دستی با افزودن replica و pod | انتخاب نوع pod (مثل s1، p2) و تعداد | ایندکسهای قدیمی موجود که هنوز کار میکنند |
| تصمیم | گزینهها | لحظهٔ تعیین | قابل تغییر پس از ساخت؟ |
|---|---|---|---|
| نوع ایندکس و شکل داده | document / dense / sparse | ساخت ایندکس | خیر — ایندکس جدید لازم است [S1] |
| معیار فاصله (metric) | cosine / dotproduct / euclidean | ساخت ایندکس | خیر — ایندکس جدید لازم است [S2] |
| ابعاد (dimension) | برابر خروجی مدل embedding (مثلاً ۱۵۳۶) | ساخت ایندکس | خیر — ایندکس جدید لازم است |
| استقرار | cloud و region (مثل aws / us-east-1) | ساخت ایندکس | خیر — برای جابهجایی، ایندکس جدید در region مقصد میسازید |
| محتوای namespaceها | هر تعداد namespace داخل همان ایندکس | زمان upsert | بله — namespace جدید با اولین upsert ساخته میشود |
| متادیتای بردارها | کلید-مقدار دلخواه روی هر بردار | زمان upsert/update | بله — با update قابل تغییر است |
یک نکتهٔ عملیاتی دربارهٔ region: انتخاب region نزدیک به کاربران یا سرویسهای شما تأخیر شبکه را کم میکند، اما این انتخاب هم در لحظهٔ ساخت قفل میشود. اگر کاربران شما در ایراناند، عملاً بین چند region معروف اختلاف تأخیر را با یک تست ساده اندازه بگیرید و بعد تصمیم بگیرید؛ بعداً جابهجایی یعنی re-index. تجربهٔ تحریریه: برای پروژههای فارسیزبان، تفاوت تأخیر بین regionهای رایج معمولاً از هزینهٔ re-index کمتر اهمیت دارد — ساده شروع کنید.
کدام معیار فاصله (Distance Metric) برای دادهٔ شما درست است؟
معیار فاصله (metric) تابعی است که Pinecone با آن امتیاز شباهت بردار پرسوجو با بردارهای ذخیرهشده را حساب میکند و بر اساس آن رتبهبندی میکند [S2]. این تابع را باید در لحظهٔ ساخت ایندکس انتخاب کنید — سه گزینه دارید: cosine، dotproduct و euclidean — و برای بردارهای dense پیشفرض همان cosine است [S2]. انتخاب درست این پارامتر رتبهبندی نتایج را مستقیم تغییر میدهد؛ پس بیایید هر سه را با تعریف دقیق ببینیم.
| معیار | چه چیزی را میسنجد؟ | کی انتخابش کنیم؟ |
|---|---|---|
| cosine | همجهتی دو بردار؛ مستقل از طول بردار | متن و embeddingهای زبانی؛ پیشفرض ایندکس dense در پاینکان [S2] |
| dotproduct | حاصلضرب داخلی؛ همجهتی و بزرگی را با هم ترکیب میکند | بردارهای sparse (اجباری) و سیستمهای توصیه که بزرگیِ سیگنال مهم است |
| euclidean | فاصلهٔ هندسی مستقیم بین دو نقطه | بردارهایی که فاصلهٔ مطلق معنا دارد؛ مثل فضاهای feature پیوسته و مقایسهٔ مشابهت هندسی |
ابعاد ایندکس (dimension) را چطور با مدل embedding همخوان کنیم؟
ابعاد (dimension) تعداد مولفههای بردار شماست و عددی است که مدل embedding تعیین میکند — نه شما. اگر با APX24 مدل text-embedding-3-small را صدا بزنید، خروجی یک آرایهٔ ۱۵۳۶ عنصری است؛ پس ایندکس شما باید دقیقاً با dimension=1536 ساخته شود. هر اختلافی بین این دو عدد، اولین upsert را با خطا میشکند. برای همین قاعدهٔ طلایی این بخش را حفظ کنید: «اول مدل، بعد ایندکس» — مدل embedding را انتخاب کنید، ابعاد خروجیاش را از response بخوانید و بعد ایندکس را بسازید.
| مدل | ابعاد خروجی | نحوهٔ استفاده در استراتژی ما |
|---|---|---|
| text-embedding-3-small (سازگار با OpenAI) | ۱۵۳۶ | از طریق POST https://api.apx24.ir/v1/embeddings — مدل مثالهای این مقاله [S8][S7] |
| text-embedding-3-large (اکوسیستم OpenAI) | ۳۰۷۲ | در صورت دسترسی در کاتالوگ؛ برای کیفیت بالاتر با هزینهٔ بیشتر [S7] |
| llama-text-embed-v2 (مدل میزبان پاینکان) | مدیریت خودکار | در مسیر integrated embedding ابعاد را شما تعیین نمیکنید [S1] |
| pinecone-sparse-english-v0 (sparse میزبان پاینکان) | بردار sparse — بدون dimension ثابت | ایندکس sparse با metric=dotproduct [S1] |
- 1
مدل embedding را انتخاب کنید
بر اساس کیفیت، هزینه و زبان دادهتان. برای متن فارسی در این مقاله، text-embedding-3-small از طریق اپکس۲۴ نقطهٔ شروع اقتصادی است.
- 2
ابعاد واقعی خروجی را از response بخوانید
یک درخواست تستی به /v1/embeddings بزنید و طول آرایهٔ embedding را چاپ کنید؛ این عدد مرجع شماست.
- 3
ایندکس را با همان عدد بسازید
dimension را برابر عدد مرحلهٔ قبل بگذارید و metric را بر اساس بخش قبل انتخاب کنید. این دو عدد از این لحظه قفل میشوند.
- 4
همخوانی را در کد قفل کنید
قبل از هر upsert، طول بردار را با dimension ایندکس مقایسه کنید تا خطای 400 در production رخ ندهد؛ این چک را در CI هم داشته باشید.
چطور با API اپکس۲۴ بردار بسازیم و در Pinecone ایندکس کنیم؟ (پیادهسازی کامل)
این بخش قلب عملی مقاله است: چهار درخواست واقعی که کل چرخه را میسازند. نقشها را اول روشن کنیم: اپکس۲۴ «مدل embedding» را تأمین میکند (تولید بردار از متن فارسی، با API سازگار با OpenAI روی نسخهٔ v1 [S8]) و Pinecone «ذخیره و جستجوی بردار» را. کلیدهای هر دو سرویس جدا هستند: کلید اپکس۲۴ با پیشوند sk-apx- در هدر Authorization مینشیند و کلید Pinecone در هدر Api-Key. همهٔ کدها با placeholder کار میکنند — کلید واقعی هرگز در کد نمیآید.
- 1
کلید API اپکس۲۴ و Pinecone را آماده کنید
کلید اپکس۲۴ را از پنل کاربری بسازید و هر دو کلید را در متغیرهای محیطی بگذارید — نه در کد.
- 2
بردار متن فارسی را از اپکس۲۴ بگیرید
درخواست POST به /v1/embeddings با model=text-embedding-3-small؛ خروجی آرایهای ۱۵۳۶ عنصری است.
- 3
ایندکس serverless را با dimension درست بسازید
ایندکسی با dimension=1536 و metric=cosine روی aws/us-east-1 بسازید و تا status.ready=true صبر کنید [S1].
- 4
upsert کنید و اولین query را اجرا کنید
بردارها را با id و metadata در namespace دلخواه ذخیره کنید و بعد بردار پرسوجو را با topK و فیلتر جستجو کنید.
namespace یا metadata filter؟ مرز multi-tenancy کجاست؟
وقتی دادهها «مالکهای» مختلف دارند — شرکتهای مشتری در یک SaaS، زبانهای جدا، یا محیطهای تست و تولید — این سؤال پیش میآید که مرز را کجا بکشیم. namespace پارتیشنی منطقی داخل همان ایندکس است: هر بردار در زمان upsert یک namespace میگیرد و هر query هم صریحاً روی یک namespace اجرا میشود؛ دادهٔ دو namespace هیچوقت در جستجو با هم ترکیب نمیشوند. metadata filter برعکس، روی دادهٔ مشترک یک namespace کار میکند و کاندیدها را بر اساس فیلدهایی مثل lang یا category قبل از رتبهبندی حذف میکند [S5].
- namespace را انتخاب کنید وقتی: ایزولهسازی کامل دادهٔ هر مشتری (tenant) لازم است — چتبات هر شرکت فقط باید تیکتهای همان شرکت را ببیند.
- namespace را انتخاب کنید وقتی: مجموعههای بزرگ با الگوی جستجوی کاملاً جدا دارید (مثلاً محیط dev و prod) و نمیخواهید فیلتر فراموششدنی بر رفتار جستجو اثر بگذارد.
- metadata filter را انتخاب کنید وقتی: داده مشترک است اما نماها متفاوتاند — کاربر فروشگاه «فقط کالاهای موجود زیر ۵ میلیون تومان» را میبیند.
- metadata filter را انتخاب کنید وقتی: فیلترها داینامیک و رودررو با کاربرند و ساختن namespace برای هر ترکیب، منفجر میشود.
- ترکیب هر دو: tenant در namespace + فیلترهای تحلیلی روی metadata — الگوی رایج SaaSهای فارسی.
خطاهای رایج ایندکسگذاری و جستجو را چطور رفع کنیم؟
خطاهای این حوزه الگوی مشخصی دارند: یا «قرارداد» ایندکس شکسته شده (ابعاد، نام)، یا «احراز هویت» اشتباه است، یا «سقف مصرف» لمس شده. سه خطای زیر تقریباً همهٔ تیکتهای اولیه را میسازند؛ برای هرکدام علت، راهحل با کد و پیشگیری را میبینید. نکتهٔ مهم: پیامهای خطای نمونه در این بخش نمایشیاند؛ متن دقیق ممکن است بین نسخههای API فرق کند اما status code و معنا ثابت است.
استراتژی را چطور بر اساس سناریوی کسبوکار انتخاب و هزینهاش را محاسبه کنیم؟
تا اینجا ابزارها را دیدیم؛ حالا دو سناریوی واقعی را با همین ابزار حل میکنیم و بعد سراغ عددی میرویم که CTOها بیشتر از همه دربارهاش میپرسند: هزینه. هر worked example، همان چهار تصمیم استراتژی (نوع ایندکس، metric، dimension، namespace) را برای یک کسبوکار مشخص پر میکند تا ببینید «استراتژی» در عمل یعنی پرکردن یک جدول تصمیم، نه حدسزدن.
و اما عددی که CTOها بیشتر از همه میپرسند: هزینه. سناریوی مرجع ما یک چتبات RAG با ۵۰۰ پرسوجو در روز است که هر پرسوجو حدود ۲۰۰۰ توکن ورودی (سؤال + متن chunkهای بازیابیشده) و ۵۰۰ توکن خروجی مصرف میکند و با مدل اقتصادی gpt-6-luna پاسخ میگیرد. جدول زیر محاسبهٔ کامل را با تعرفهٔ ثبتشده در ۲۰۲۶-۱۱-۰۱ نشان میدهد؛ سه اهرم اصلی کاهش هزینه هم مشخصاند: chunkهای کوتاهتر و رتبهبندی دقیقتر (توکن ورودی کمتر)، مدل اقتصادی برای پاسخهای کوتاه و مدل قوی فقط برای سؤالهای سخت، و کش پاسخ/کش embedding برای متنهای تکراری.
| مؤلفه | محاسبهٔ روزانه | تعرفه (تومان بهازای ۱M توکن) | هزینهٔ روزانه (تومان) |
|---|---|---|---|
| توکن ورودی | ۵۰۰ پرسوجو × ۲۰۰۰ توکن = ۱,۰۰۰,۰۰۰ توکن | ۵,۴۰۰ | ۵,۴۰۰ |
| توکن خروجی | ۵۰۰ پرسوجو × ۵۰۰ توکن = ۲۵۰,۰۰۰ توکن | ۲۷,۰۰۰ | ۶,۷۵۰ |
| جمع روزانه | ۵,۴۰۰ + ۶,۷۵۰ | — | ۱۲,۱۵۰ |
| جمع ماهانه (۳۰ روز) | ۱۲,۱۵۰ × ۳۰ | — | ۳۶۴,۵۰۰ |





