Node Parser در LlamaIndex چیست و چرا کیفیت RAG شما به آن وابسته است؟
در LlamaIndex هر چیزی که وارد سیستم میشود — PDF، صفحهٔ وب، متن دیتابیس — ابتدا به یک Document تبدیل میشود. اما مدل زبانی و موتور جستوجوی برداری با «سند کامل» کار نمیکنند؛ به قطعههای کوچک و متمرکز نیاز دارند. تجزیهگر گره (Node Parser) همان کامپوننتی است که این تبدیل را انجام میدهد: فهرستی از Documentها را میگیرد و فهرستی از Node تحویل میدهد. به همین دلیل در ادبیات فنی، Node Parser و Text Splitter تقریباً هممعنا هستند.
- دقت بازیابی: قطعهٔ کوچک و متمرکز، بردار embedding دقیقتری دارد و جستوجوی معنایی نویز کمتری برمیگرداند.
- هزینهٔ توکن: هر Node بازیابیشده وارد prompt میشود؛ Nodeهای بزرگ یعنی پرداخت توکن اضافه برای هر سؤال.
- تأخیر پاسخ: زمینهٔ کوچکتر یعنی درخواستهای سبکتر و پاسخ سریعتر — بهویژه در حالت streaming.
- کنترل محدوده: با metadata هر Node میفهمید پاسخ از کدام فایل یا بخش آمده و نتایج را فیلتر میکنید.
نکتهٔ کلیدی این است که Node Parser فقط «برش» نیست؛ در همان مرحله، metadata سند به Nodeها ارث میرسد (include_metadata) و روابط قبلی/بعدی ساخته میشوند (include_prev_next_rel). یعنی تصمیمهایی که اینجا میگیرید، تا آخر زنجیره — از embedding تا پاسخ نهایی — همراه شما میمانند. برای همین در ادامه هر کلاس را با کاربرد واقعیاش مرور میکنیم.
پیشنیازها و نصب: محیط کار را در چند دقیقه آماده کنیم؟
از نسخهٔ ۰٫۱۰ به بعد، LlamaIndex به پکیجهای کوچک تقسیم شده است. هستهٔ کار ما llama-index-core است که با نصب بستهٔ llama-index بهصورت خودکار میآید؛ برای اتصال به سرویسهای سازگار با OpenAI هم دو یکپارچهساز llama-index-llms-openai-like و llama-index-embeddings-openai را نصب میکنیم. کد این مقاله با نسخهٔ stable مستندات (llama-index-core 0.12.x) و API نسخهٔ v1 نوشته شده است.
- Python 3.9 یا بالاتر و pip
- یک محیط مجازی جدا برای پروژه (توصیهشده)
- کلید API APX24 — فقط برای بخش اتصال به LLM
- ویرایشگر کد یا Jupyter Notebook
- 1
نصب بستهها
با دستور بالا هسته و یکپارچهسازها را نصب کنید و نسخهٔ چاپشده را یادداشت کنید.
- 2
ساخت کلید API
در پنل APX24 یک کلید جدید بسازید؛ فرمت کلیدها sk-apx-... است.
- 3
نگهداری امن کلید
کلید را در متغیر محیطی APX24_API_KEY بگذارید تا در همهٔ مثالهای مقاله با os.environ خوانده شود.
- 4
تست نهایی
import کلاسهای کلیدی را اجرا کنید؛ اگر خطا نداد، آمادهٔ ادامه هستید.
Document و Node چه تفاوتی دارند؟
قبل از انتخاب کلاس تقسیم، باید دقیقاً بدانید ورودی و خروجی چه هستند. مستندات رسمی LlamaIndex دو موجودیت را اینطور تعریف میکند: Document یک ظرف عمومی حول هر منبع داده است و Node یک «قطعه» از همان سند مبدأ. در کد، هر دو از خانوادهٔ TextNode هستند؛ یعنی Document هم در واقع یک Node خاص است که سند کامل را نگه میدارد.
یک اشتباه رایج این است که Node را «کپی سادهای از متن» ببینند. در واقع Node ساختار کاملتری است: id یکتا، hash محتوا، metadata و روابط. همین ساختار است که قابلیتهایی مثل حذف نتایج تکراری، پیمایش مجاورت و upsert سندهای تغییر یافته را ممکن میکند.
کدام Node Parser برای متن شما مناسب است؟ مقایسهٔ کامل کلاسها
LlamaIndex برای هر نوع محتوا یک کلاس تقسیم دارد؛ همه از یک interface مشترک پیروی میکنند و متد get_nodes_from_documents دارند، اما منطق تعیین مرز کاملاً متفاوت است. جدول زیر خانوادهٔ کامل را خلاصه میکند و بعد از آن، سه گزینهٔ پرکاربرد را عمیقتر مقایسه میکنیم.
| کلاس | منطق تقسیم | بهترین کاربرد | نکته / پیشنیاز |
|---|---|---|---|
| SentenceSplitter | سقف توکن با تلاش برای حفظ مرز جمله و پاراگراف | متن عمومی — پیشفرض پروژهها | برای فارسی sentence_splitter سفارشی نتیجهٔ بهتری میدهد |
| TokenTextSplitter | برش توکنمحور با جداکنندهٔ قابلتنظیم | متنهای حساس به مرز مثل کد و CSV | مرز جمله تضمین نمیشود |
| SemanticSplitterNodeParser | مرز در افت شباهت معنایی بین جملهها | متنهای پیوستهٔ موضوعمحور | به مدل embedding نیاز دارد؛ هزینهٔ بیشتر |
| SentenceWindowNodeParser | هر Node یک جمله + پنجرهٔ مجاور در metadata | بازیابی دقیق جملهمحور | همراه MetadataReplacementPostProcessor |
| HierarchicalNodeParser | چند سطح بزرگ/متوسط/کوچک | مستندات سازمانی و auto-merging | چند لایه Node تولید میکند |
| MarkdownNodeParser | هدرهای Markdown | مستندات فنی ساختارمند | هدرها به metadata تبدیل میشوند |
| HTMLNodeParser | ساختار DOM | صفحات وب و HTML پاکشده | بر پایهٔ BeautifulSoup |
| JSONNodeParser | اشیای تو در توی JSON | دادههای ساختارمند و پاسخهای API | خروجی خطی از اشیای تودرتو |
| CodeSplitter | ساختار نحوی کد با tree-sitter | مستندسازی و بازیابی کد | نیازمند وابستگی tree-sitter |
| مورد | کیفیت مرزها | سرعت و هزینهٔ اجرا | وابستگی خارجی | پیچیدگی راهاندازی |
|---|---|---|---|---|
| SentenceSplitter | خوب — مرز جمله حفظ میشود | بالا — بدون فراخوانی شبکه | هیچ | کم — دو پارامتر اصلی |
| TokenTextSplitter | متوسط — ممکن است جمله نصف شود | بالا | هیچ | کم |
| SemanticSplitterNodeParser | عالی — مرز در تغییر موضوع | کمتر — یک فراخوانی embedding برای هر مرز | مدل embedding لازم دارد | متوسط |
انتخاب استراتژی یک تصمیم یکباره نیست؛ با متن واقعی خودتان سه تنظیم اول را اجرا کنید و مرزهای تولیدشده را با چشم بازبینی کنید. در پروژههای واقعی ترکیب دو لایه — اول MarkdownNodeParser برای ساختار و بعد SentenceSplitter برای قطعههای بلند — نتیجهٔ قابلاعتمادی میدهد (تجربهٔ تحریریه).
SentenceSplitter چطور کار میکند و چه پارامترهایی دارد؟
SentenceSplitter پرکاربردترین کلاس LlamaIndex است و در کد منبع، الگوریتم آن چهار لایه دارد: اول متن با جداکنندهٔ پاراگراف میشکند، بعد با توکنایزر جمله (پیشفرض: nltk)، بعد در صورت نیاز با یک regex ثانویه روی ویرگول و نقطه و در نهایت با جداکنندهٔ سادهٔ فاصله. سپس قطعههای کوچک طوری merge میشوند که به سقف chunk_size برسند و همپوشانی در مرزها حفظ شود. نتیجه: Nodeهایی که تا حد ممکن روی مرز طبیعی جمله تمام میشوند.
| پارامتر | پیشفرض | کارکرد |
|---|---|---|
| chunk_size | ۱۰۲۴ | سقف اندازهٔ هر Node بر حسب توکن |
| chunk_overlap | ۲۰ (مثال مرجع مستندات) | تعداد توکن مشترک بین دو Node متوالی برای حفظ جملات مرزی |
| include_metadata | True | چسباندن metadata سند به هر Node تولیدشده |
| include_prev_next_rel | True | ساختن روابط PREVIOUS/NEXT بین Nodeهای متوالی |
| tokenizer | توکنایزر سراسری (tiktoken) | واحد شمارش اندازهٔ متن |
| secondary_chunking_regex | [^,.;]+[.;]? | برش ثانویه روی ویرگول و نقطه وقتی جمله هنوز بلند است |
Node Parserهای پیشرفته: Semantic، Sentence Window و Hierarchical
وقتی تقسیم ساده جواب نمیدهد، LlamaIndex سه الگوی حرفهای دارد. تقسیم معنایی مرز را جایی میگذارد که موضوع عوض میشود؛ پنجرهٔ جمله بازیابی دقیق را با زمینهٔ وسیع ترکیب میکند؛ و تقسیم سلسلهمراتبی چند سطح قطعه میسازد تا بازیابیهای ترکیبی ممکن شود. هر سه با همان interface آشنا کار میکنند.
چطور Node Parser را به APX24 وصل کنیم؟ یک RAG کامل از تقسیم تا پاسخ
APX24 یک API سازگار با OpenAI ارائه میدهد: همان endpointهای /v1/chat/completions و /v1/embeddings و همان قالب Bearer. نتیجهٔ عملی این استانداردسازی زیباست: بهجای تغییر در منطق LlamaIndex، فقط یک شیء LLM با OpenAILike میسازیم که api_base آن به APX24 اشاره میکند. از آن لحظه، همهٔ پرسوجوها و فراخوانیهای embedding خط تولید شما به APX24 میروند.
خطاهای رایج Node Parser و باورهای غلط — و رفع آنها
- کلید فقط در متغیر محیطی — هرگز در سورسکد.
- استفاده از IngestionPipeline با docstore برای جلوگیری از پردازش مجدد سندهای تغییریافته.
- رعایت هدر Retry-After و backoff نمایی در خطای ۴۲۹.
- لاگ فیلد usage هر پاسخ برای مانیتورینگ هزینه و هشدار آستانهٔ اعتبار.
- تست مرزهای Node روی متن واقعی فارسی قبل از استقرار.
- پینکردن نسخهٔ llama-index-core در requirements.txt.
جمعبندی: از Node Parser تا RAG آمادهٔ تولید
مسیر این مقاله یک زنجیرهٔ واحد بود: Document بهعنوان ورودی، Node Parser بهعنوان قلب تقسیم، پارامترهای chunk_size و chunk_overlap بهعنوان اهرم کیفیت و هزینه، و APX24 بهعنوان موتور LLM و embedding سازگار با OpenAI. اگر فقط یک نکته ببرید، این باشد: کیفیت بازیابی را قبل از تعویض مدل، در مرحلهٔ تقسیم بهینه کنید — ارزانترین و مؤثرترین اهرم RAG است.
- گام بعدی ۱: خط تولید خود را با IngestionPipeline و docstore cache استقرار دهید.
- گام بعدی ۲: الگوی پنجرهٔ جمله یا auto-merging را روی همان Nodeها تست کنید.
- گام بعدی ۳: مصرف توکن را با فیلد usage مانیتور کنید و مدل سنتز را بر اساس جدول قیمت بهینه کنید.
- گام بعدی ۴: برای پاسخهای زنده، پرسوجوی خود را با streaming ادامه دهید.




