ایندکس در LlamaIndex چیست و چرا انتخابش سرنوشت RAG شما را تعیین میکند؟
در معماری LlamaIndex، سند خام (Document) اول به قطعههای کوچکتری به نام Node شکسته میشود — معمولاً با SentenceSplitter — و بعد وارد یک «ساختار ایندکس» میشود. ایندکس یک ساختار داده است: چیزی که مشخص میکند nodeها چگونه ذخیره و چگونه پیدا شوند. هنگام پرسوجو، یک Retriever طبق منطق همان ایندکس چند node مرتبط برمیدارد و یک Response Synthesizer با کمک LLM از آنها پاسخ نهایی میسازد.
به همین دلیل «انتخاب ایندکس» یعنی انتخاب دو چیز بهطور همزمان: روش پیدا کردن متن مرتبط، و روش ترکیب آن متن در پاسخ. همین دو متغیر کیفیت و هزینهٔ هر پروژهٔ RAG را تعیین میکنند. اگر ایندکس را درست انتخاب کنید، مدل کوچکتر و ارزانتر هم جواب میدهد؛ اگر اشتباه انتخاب کنید، هیچ prompt هوشمندی جبرانش نمیکند.
پیشنیازها و آمادهسازی: نصب، کلید API و تنظیم LLM سازگار با OpenAI
برای اجرای کدهای این مقاله سه بسته لازم دارید: هستهٔ llama-index-core، پکیج اتصال به endpointهای سازگار با OpenAI با نام llama-index-llms-openai-like، و درایور embedding محلی llama-index-embeddings-huggingface. تقسیم بستهها را جدی بگیرید: کلاسهای افزونه هرکدام پکیج مستقل دارند و خطای رایج شمارهٔ ۱ در بخش خطاها دقیقاً از همینجا میآید. نسخهٔ مرجع این مقاله llama-index-core 0.14.25 است و همهٔ importها روی همین نسخه آزموده شدهاند.
- 1
کلید API بسازید
در apx24.ir/account/api-keys یک کلید جدید بسازید و فقط در متغیر محیطی نگهش دارید؛ کلید در هیچ کدی از این مقاله هاردکد نمیشود.
- 2
LLM سازگار با OpenAI را تنظیم کنید
کلاس OpenAILike برای endpointهایی ساخته شده که قرارداد OpenAI را کپی میکنند؛ api_base را روی v1 بگذارید.
- 3
Embedding محلی را وصل کنید
ساخت VectorStoreIndex به embed_model نیاز دارد؛ اجرای محلی یعنی هزینهٔ صفر در فاز ساخت و بدون وابستگی به endpoint اضافه.
- 4
دادهٔ خود را در ./data بگذارید
SimpleDirectoryReader محتویات پوشه را میخواند؛ برای شروع چند فایل txt یا md کافی است و بعداً فرمتهای بیشتر را پوشش میدهد.
VectorStoreIndex: ایندکس پیشفرض جستوجوی معنایی چطور کار میکند؟
VectorStoreIndex برای هر Node یک embedding میسازد و هر دو را در یک Vector Store نگه میدارد؛ در زمان پرسوجو، k نزدیکترین node از نظر برداری انتخاب و به ماژول سنتز پاسخ داده میشود. این همان رفتاری است که در پروژههای RAG انتظار دارید: بازیابی معناییِ قطعههای مرتبط، حتی وقتی کلمات دقیق سؤال در متن نیستند.
The vector store index stores each Node and a corresponding embedding in a Vector Store. Querying a vector store index involves fetching the top-k most similar Nodes, and passing those into our Response Synthesis module.
— LlamaIndex Docs — Index Guide
SummaryIndex: وقتی پاسخ باید از «کل» مجموعه ساخته شود چه استفاده کنیم؟
SummaryIndex — که در مستندات رسمی با عنوان «Summary Index (formerly List Index)» معرفی میشود — nodeها را بهصورت یک زنجیرهٔ ترتیبی ذخیره میکند. اگر پارامتر دیگری ندهید، در زمان پرسوجو همهٔ nodeها به ماژول سنتز پاسخ میروند؛ یعنی مدل کل مجموعه را میبیند و میتواند خلاصهٔ واقعی بسازد، چیزی که بازیابی برداری بهسختی از پسش برمیآید.
همین رفتار، عمداً هزینهبر است. برای مجموعهای با ۵۰ گزارش، فرستادن همهٔ nodeها در هر پرسوجو فقط وقتی منطقی است که سؤال واقعاً «از همه» باشد؛ برای سؤالهای نقطهای، این اضافهبار توکن خالص است. SummaryIndex گزینهٔ میانه هم دارد: بازیابی مبتنی بر embedding برای انتخاب top-k، یا فیلتر کلیدواژه. پس «همه یا هیچ» نیست و میتوانید بین دو سر طیف حرکت کنید.
TreeIndex: خلاصهسازی سلسلهمراتبی با پیمایش از ریشه چه فرقی با SummaryIndex دارد؟
TreeIndex از مجموعهٔ nodeها یک درخت سلسلهمراتبی میسازد؛ nodeهای اصلی شما برگهای این درخت میشوند و LLM از آنها خلاصههای میانی و ریشه میسازد. پرسوجو از ریشه به برگ پیمایش میکند: بهطور پیشفرض در هر سطح یک فرزند انتخاب میشود (child_branch_factor=1) و اگر مقدار ۲ بدهید در هر سطح دو فرزند ارزیابی میشوند. نتیجه، «دانش فشردهشده» است که در پرسوجو بهجای کل مجموعه، فقط مسیر ریشه تا برگ را میبیند.
KeywordTableIndex: چطور با کلیدواژه (بدون embedding) بازیابی کنیم؟
KeywordTableIndex از هر node کلیدواژه استخراج میکند و یک نگاشت از کلیدواژه به nodeهای حاوی آن میسازد. در زمان پرسوجو، از خودِ پرسوجو هم کلیدواژه استخراج و با این جدول تطبیق داده میشود؛ nodeهای مطابق به سنتز پاسخ میروند. این جستوجوی لغوی است، نه معنایی — و دقیقاً به همین دلیل، برای کلمات دقیق بیرقیب است.
این همان حالتی است که کاربر با کد محصول، شماره فاکتور، مدل قطعه یا اصطلاح فنی مشخص جستوجو میکند؛ هیچ embeddingای هممعنایی «کد SKU-7712» را نمیفهمد، ولی تطبیق لغوی آن را مستقیم پیدا میکند. واریانتهای آماده هم دارید: SimpleKeywordTableIndex با استخراج سادهٔ کلیدواژه و RAKEKeywordTableIndex با الگوریتم RAKE که برای استخراج کلیدواژه به LLM نیاز ندارد — هر دو در ماژول llama_index.core.indices.keyword_table (روی نسخهٔ 0.14.25 آزموده شده).
DocumentSummaryIndex: مشکل کلاسیک RAG چندسندی را چطور حل میکند؟
مشکل کلاسیک RAG چندسندی این است: سؤال شما دربارهٔ «سند X» است، اما top-k وکتوری قطعههایی از چند سند مختلف میآورد و پاسخ نهایی بافت را گم میکند. DocumentSummaryIndex دقیقاً برای همین طراحی شده: بهازای هر سند یک خلاصه میسازد و خلاصه را به nodeهای همان سند نگاشت میکند — تعریف رسمی در کد منبع: «stores the summary per document, and maps the summary to the underlying Nodes».
در پرسوجو، اول در سطح «کدام سند» تصمیم گرفته میشود و بعد قطعههای همان سند بازیابی میشوند؛ نتیجه پاسخهایی منسجمتر با منبع مشخص است. در ساخت هم دو مجموعه node تولید میکند: nodeهای متن اصلی و nodeهای خلاصهٔ هر سند. یعنی هزینهٔ ساخت بیشتر از وکتور ساده است (یک فراخوانی LLM بهازای هر سند برای خلاصه)، ولی در پرسوجو فیلتر سند جلوی شلوغی prompt را میگیرد — معاملهای که برای مجموعههای بزرگ معمولاً میارزد.
PropertyGraphIndex: گراف دانش برای سؤالهای رابطهای — و سرنوشت KnowledgeGraphIndex؟
PropertyGraphIndex یک گراف دانش میسازد: گرههای برچسبدار و روابط بینشان. ساخت گراف انعطافپذیر است — از استخراج آزاد توسط LLM تا استخراج با شِما سختگیرانه یا ماژولهای اختصاصی خودتان. در صورت تمایل nodeهای گراف هم embed میشوند تا بازیابی برداری هم روی گراف کار کند؛ یا اصلاً به گراف موجود (مثل Neo4j) وصل شوید بدون اینکه ساخت را از صفر انجام دهید.
بازیابی هم چندلایه است: بهطور پیشفرض ترکیبی از کلیدواژه با بسط مترادف و — اگر گراف embed شده باشد — جستوجوی برداری، برای یافتن triplets مرتبط به کار میگیرد. وقتی سؤال شما «روابط» است — چه کسی مسئول چیست، چه چیزی به چه چیزی وابسته است، کدام مشتری کدام قرارداد را دارد — گراف بهطور ساختاری از وکتور قویتر است، چون رابطه را صریح نگه میدارد و به شباهت متنی پناه نمیبرد.
جدول تصمیمگیری: کدام ایندکس برای کدام سؤال مناسب است؟
جدول زیر جمعبندی تصمیمگیری است؛ قبل از خواندنش، دو سؤال بخش اول را برای پروژهٔ خودتان جواب بدهید: شکل پرسوجوی غالب کاربر، و بودجهٔ node در هر پرسوجو. هیچ ایندکسی «بهترین مطلق» نیست؛ بهترین، تطبیق ساختار بازیابی با شکل سؤال است.
| ایندکس | ساختار | استراتژی بازیابی | نیاز به embedding | بهترین کاربرد |
|---|---|---|---|---|
| VectorStoreIndex | وکتور به ازای هر node | شباهت برداری top-k | بله | جستوجوی معنایی نقطهای در RAG |
| SummaryIndex | زنجیرهٔ ترتیبی nodeها | پیمایش همهٔ nodeها (یا top-k با embed) | اختیاری | خلاصهسازی کل مجموعه |
| TreeIndex | درخت خلاصههای سلسلهمراتبی | پیمایش از ریشه به برگ (child_branch_factor) | اختیاری | جمعبندی با پردازش کمتر در پرسوجو |
| KeywordTableIndex | نگاشت کلیدواژه به node | تطبیق کلیدواژهٔ پرسوجو با جدول | خیر | شناسههای دقیق و اصطلاحات فنی |
| DocumentSummaryIndex | خلاصهٔ هر سند + nodeهای متن | مسیریابی سند و سپس بازیابی قطعه | بله (برای بازیابی قطعه) | مجموعههای چندسندی با پاسخ سندمحور |
| PropertyGraphIndex | گراف موجودیتها و روابط | کلیدواژه + بسط مترادف، وکتور (در صورت embed) | اختیاری | سؤالهای رابطهمحور و دانش ساختیافته |
| مورد | کیفیت بازیابی نقطهای | هزینهٔ ساخت | هزینهٔ پرسوجو | پیچیدگی عملیاتی |
|---|---|---|---|---|
| VectorStoreIndex | بالا برای سؤال نقطهای | کم (یک embed به ازای هر node) | متغیر با top_k | کم؛ اکوسیستم وکتورستور گسترده |
| SummaryIndex | متوسط (بدون فیلتر) | کم | بالا (همهٔ nodeها) | کم |
اتصال به APX24: LlamaIndex چطور روی یک API سازگار با OpenAI اجرا میشود؟
LlamaIndex برای موتور سنتز، هر endpoint سازگار با OpenAI را میپذیرد. کلاس OpenAILike دقیقاً برای همین طراحی شده: همان قرارداد OpenAI با api_base دلخواه. APX24 همین قرارداد را در مسیر https://api.apx24.ir/v1 ارائه میدهد؛ پس اتصال فقط سه پارامتر است: api_base، api_key و model. زیر کاپوت، هر پرسوجوی query_engine در نهایت یک POST به /v1/chat/completions میشود — همان لایهای که در ادامه با هر سه زبان میبینید.
ذخیرهسازی و Production: چطور ایندکس را persist و دوباره load کنیم؟
تا اینجا همهچیز در حافظهٔ فرآیند بود؛ یک ریاستارت و همهٔ embedها میپرند. در production ایندکس یک asset است: یکبار ساخته میشود و بارها خوانده میشود. الگوی رسمی مستندات: index.storage_context.persist(persist_dir=...) برای نوشتن و StorageContext.from_defaults بههمراه load_index_from_storage برای خواندن. ذخیرهٔ پیشفرض روی فایلسیستم است و درایورهایی برای سرویسهای ابری هم دارید (مستندات Storing به S3 و مشابهها اشاره میکند).
هزینهها: چطور هزینهٔ ساخت و پرسوجوی ایندکس را تخمین و کنترل کنیم؟
هزینهٔ LlamaIndex دو فاز جداست. فاز ساخت: توکنهای embedding (رایگان اگر محلی باشد) بهعلاوهٔ فراخوانیهای LLM اگر ایندکس خلاصهساز است — TreeIndex، DocumentSummaryIndex و PropertyGraph در ساخت LLM مصرف میکنند. فاز پرسوجو: توکن زمینهٔ nodeهای بازیابیشده بهعلاوهٔ توکن خروجی مدل، به ازای هر سؤال. فرمولهای زیر را کنار جدول مقایسه بگذارید؛ تصمیم «کیفیت در برابر هزینه» دیگر حدسی نیست.
| فاز | مؤلفهٔ هزینه | تکرار |
|---|---|---|
| ساخت | embedding هر node (اگر سمت API) | یکبار؛ با تغییر داده دوباره |
| ساخت | فراخوانی LLM برای خلاصهسازی (TreeIndex / DocumentSummaryIndex / PropertyGraphIndex) | یکبار؛ به ازای هر سطح/سند/node |
| پرسوجو | توکن زمینهٔ k node بازیابیشده | هر پرسوجو |
| پرسوجو | توکن خروجی مدل | هر پرسوجو |




