این مجموعه توسط Claude (دستیار هوش‌مصنوعی شرکت Anthropic) نوشته شده — بر اساس یک همکاری فنی طولانی و واقعی با حمیدرضا محمدی، نگهدارندهٔ گنجور، در ساخت این قابلیت. اعداد و نتیجه‌هایی که در این بخش می‌بینید، همه واقعی‌اند و مستقیماً از همان روند توسعه گرفته شده‌اند — نه نمونه‌های ساختگی برای توضیح.

یادآوری کوتاه، و سؤال این بخش

در سه بخش قبلی، همه‌چیز حول یک بردار برای کل هر شعر بود — ساخته‌شده از PoemSummary، خلاصه‌ای که کل شعر را در چند جمله جمع‌بندی می‌کند. این برای اکثر شعرها خوب کار می‌کند. اما غزل‌های فارسی یک ویژگی ساختاری خاص دارند: بیت‌های یک غزل، برخلاف یک داستان یا مثنوی، لزوماً دنبالهٔ منطقی و پیوسته‌ای ندارند — هر بیت می‌تواند مضمون نسبتاً مستقلی داشته باشد. وقتی همهٔ این بیت‌های گوناگون را در یک خلاصهٔ واحد برای کل شعر جمع می‌کنیم، ناخواسته جزئیات هر بیت رقیق می‌شود.

سؤال این بخش: اگر به‌جای یک بردار برای کل شعر، برای هر بیت جداگانه یک بردار بسازیم چه می‌شود؟

چرا اول یک آزمایش کوچک، نه کل مجموعه؟

قبل از هر تصمیمی، یک بررسی عددی انجام شد: آیا می‌شود فقط با محدودکردن به شعرهای کوتاه، حجم کار را به‌طور محسوس کم کرد؟ نتیجه نه بود — با اینکه شعرهای «خیلی بلند» (۱۶ بیت به بالا) فقط ۱۳ تا ۱۴٪ از کل شعرهاست، همین بخش کوچک، ۵۴.۸٪ از کل بیت‌های موجود را در خود دارد. یعنی محدودکردن بر اساس طول شعر، عملاً حجم کار را کم نمی‌کند.

پس به‌جای یک محدودیت عددی دلبخواه، یک محدودهٔ کوچک و معنادار انتخاب شد: غزل‌های حافظ — دقیقاً همان نمونه‌ای که از ابتدا انگیزهٔ این ایده بود.

یک کشف واقعی، پیش از نوشتن حتی یک خط کد

پیش از شروع، یک بررسی ساده انجام شد: آیا فیلد CoupletSummary (خلاصهٔ سطح بیت) اصلاً جزو داده‌ای هست که در ganjoor-data منتشر می‌شود؟ جواب، با بررسی مستقیم کد (نه حدس)، منفی بود — برخلاف PoemSummary، این فیلد اصلاً در خروجی عمومی گنجور وجود نداشت.

این کشف دو نتیجهٔ عملی داشت:

1. برای آزمایش اولیه، دادهٔ خام باید مستقیماً از پایگاه‌داده (نه از ganjoor-data) گرفته می‌شد.
2. یک تصمیم مهم‌تر: چون خلاصه‌های سطح بیت — به‌خصوص آن‌هایی که کاربران انسانی ویرایش کرده‌اند — کاری ارزشمند و احتمالاً غیرقابل‌بازسازی است (برخلاف خودِ متن شعر که یک اثر کلاسیک و در دسترس در منابع دیگر هم هست)، بهتر بود این فیلد هم به خروجی عمومی گنجور اضافه شود — تا اگر روزی سرویس زندهٔ گنجور از دسترس خارج شد، این کار انسانی از بین نرود. این تغییر (افزودن یک فیلد به یک DTO، و یک خط در نگاشت آن) کاملاً افزایشی و بی‌خطر بود — هیچ مصرف‌کنندهٔ فعلی این داده را خراب نمی‌کرد، فقط یک فیلد اختیاری جدید به آن اضافه می‌شد.

ساخت آزمایش اولیه — و چند نکتهٔ واقعی که در مسیر پیدا شدند

استخراج دادهٔ غزل‌های حافظ، با یک کوئری SQL که همان درسِ «پیمایش کامل زیردرخت دسته‌بندی» از بخش ۳ را این‌بار در سطح پایگاه‌داده تکرار می‌کرد (نه فقط یک لایه از دستهٔ «غزلیات»، بلکه کل زیرشاخه‌های آن).

چند اصلاح واقعی در همین مرحله لازم شد — نه چون برنامه‌ریزی بدی صورت گرفته بود، بلکه چون این‌جور جزئیات فقط با اجرای واقعی روی دادهٔ واقعی مشخص می‌شوند:

• نام واقعی جدول دسته‌بندی‌ها در پایگاه‌داده GanjoorCategories بود، نه فرضی که ابتدا نوشته شده بود — این را فقط با اجرای واقعی کوئری و مواجهه با خطا کشف کردیم.
• خروجی‌گرفتن با FOR JSON PATH در SQL Server Management Studio، در عمل با کپی‌کردن از یک سلول تکی در نتیجه‌ها مشکل‌ساز شد (هم یک ردیف اضافهٔ سرستون که کپی می‌شد، هم بریده‌شدن متن در کپی‌های طولانی). راه‌حل ساده‌تر بود: یک SELECT معمولی، و خروجی‌گرفتن با CSV — مسیری که SSMS به‌طور بومی و قابل‌اعتمادتر پشتیبانی می‌کند.
• یک نکتهٔ منطقه‌ای جالب: خروجی CSV گرفته‌شده از یک سیستم فارسی‌زبان، به‌جای کاما، از نویسهٔ «؛» (سمیکولن فارسی) به‌عنوان جداکننده استفاده کرده بود — و اصلاً سرستون هم نداشت. چون خودِ متن خلاصه‌ها هم به‌طور طبیعی از همین نویسه به‌عنوان علامت نگارشی استفاده می‌کنند، یک تجزیه‌کنندهٔ سادهٔ متنی می‌توانست به‌اشتباه وسط یک خلاصه را به‌عنوان مرز دو ستون تشخیص دهد. راه‌حل، استفاده از یک تجزیه‌کنندهٔ واقعی CSV بود (نه شکستن ساده بر اساس نویسه) — که نقل‌قول‌های داخل فایل را درست تشخیص می‌دهد؛ و کدِ خواندن فایل هم طوری نوشته شد که خودش تشخیص دهد کدام‌یک از این دو شکل را با آن روبه‌روست، به‌جای اینکه از قبل فرض ثابتی دربارهٔ قالب فایل داشته باشد.

سه تصمیم طراحی دیگر هم، پیش از تولید واقعی بردارها، آگاهانه گرفته شدند:

1. فقط از CoupletSummary استفاده شود، بدون ترکیب با PoemSummary — چون ترکیب‌کردن، دوباره همان اثر رقیق‌شدنی را ایجاد می‌کرد که کل این ایده قرار بود حلش کند (همهٔ بیت‌های یک شعر را به‌طور مصنوعی به هم نزدیک‌تر می‌کرد).
2. پیشوند «هوش مصنوعی:» پیش از ساخت بردار حذف شود — همان مشکلی که در خط لولهٔ سطح شعر هنوز حل نشده (و نیاز به بازسازی کامل دارد)، این‌بار از همان ابتدا درست انجام شد.
3. برای هر بیت، یک لینک مستقیم به همان بیت (نه فقط به کل شعر) ساخته شود — با بررسی مستقیم کد صفحهٔ واقعی گنجور، نه حدس.

دستورهای واقعی این مرحله

این اسکریپت‌ها الان در همان مخزن ganjoor-embeddings بخش ۱ منتشر شده‌اند — نیازی به دریافت جدا نیست، همان scripts/ که قبلاً clone کرده‌اید کافی است.

یک نکتهٔ مهم و صادقانه، پیش از دیدن دستورها: مرحلهٔ استخراج دادهٔ این آزمایش (فایل export_hafez_ghazal_couplets.sql) به دسترسی مستقیم به پایگاه‌دادهٔ زندهٔ گنجور نیاز دارد — چیزی که فقط نگهدارندگان پروژه در اختیار دارند. برخلاف بخش‌های ۱ تا ۳ که هر خواننده‌ای می‌توانست همهٔ دستورها را عیناً اجرا کند، این یک مرحله را نمی‌توان به همان شکل تکرار کرد؛ اما مرحلهٔ «آماده‌سازی کامل مجموعه» در ادامهٔ همین بخش، دوباره کاملاً برای همه قابل‌تکرار است — چون از ganjoor-data عمومی می‌خواند، نه از پایگاه‌داده.

با این توضیح، دستورهای واقعی که برای این آزمایش اجرا شدند:

# ابتدا export_hafez_ghazal_couplets.sql روی پایگاه‌داده اجرا و نتیجه به CSV ذخیره می‌شود
# (در SSMS: راست‌کلیک روی نتیجه‌ها -> Save Results As... -> CSV)

python3 scripts/generate_couplet_pilot_embeddings.py \
  --input /path/to/exported.csv \
  --model-dir /path/to/model \
  --output ./couplet-pilot-output \
  --inspect-only

python3 scripts/generate_couplet_pilot_embeddings.py \
  --input /path/to/exported.csv \
  --model-dir /path/to/model \
  --output ./couplet-pilot-output

و برای تأیید نتیجه — همان بررسی معنایی واقعی که در بخش ۱ هم دیدیم، این‌بار در سطح بیت:

python3 scripts/verify_couplet_pilot.py --embeddings-dir ./couplet-pilot-output \
  --query-poem-id 2130 --query-vorder 1 --top-k 8 \
  --source-csv /path/to/exported.csv

یک باگ واقعی: لینک‌ها یکی جابه‌جا بودند

فرض اولیه این بود که شمارهٔ استفاده‌شده در لینک هر بیت (مثلاً #bn2) دقیقاً همان مقدار فیلد CoupletIndex است. اما وقتی اولین خروجی واقعی تولید شد، لینک بیتِ اول غزل شمارهٔ یک حافظ #bn0 از آب درآمد — درحالی‌که صفحهٔ واقعی سایت از #bn1 استفاده می‌کند.

علت: CoupletIndex در پایگاه‌داده از صفر شمرده می‌شود، اما شمارهٔ داخل لینک از یک شروع می‌شود. راه‌حل یک +۱ ساده بود — اما نکتهٔ مهم‌تر این است که این اختلاف فقط با مقایسهٔ مستقیم خروجی واقعی با صفحهٔ واقعی سایت کشف شد، نه با فکرکردن دقیق‌تر دربارهٔ فرض اولیه. همان درسی که در بخش ۲ دربارهٔ باگ توکنایزر هم دیدیم: برای مطمئن‌شدن از تطابق دو پیاده‌سازی، باید واقعاً خروجی را مقایسه کرد.

نتیجهٔ آزمایش — و چرا واقعاً امیدوارکننده بود

آزمایش نهایی روی غزل‌های حافظ، ۴٬۱۹۲ بیت را از ۴۹۵ شعر مجزا استخراج کرد. این عدد دوم جالب توجه است: ۴۹۵ دقیقاً همان تعدادی است که در پژوهش‌های ادبی فارسی معمولاً به‌عنوان تعداد غزل‌های شناخته‌شدهٔ دیوان حافظ ذکر می‌شود — یک تأیید مستقل و غیرمنتظره از درستی استخراج داده.

اما آزمون واقعی، آزمون معنایی بود: بیت آغازین غزل اول («الا یا ایها الساقی…» — دربارهٔ اینکه عشق در ابتدا آسان می‌نماید اما در پایان دشوار می‌شود) با بردارهای بقیهٔ بیت‌ها مقایسه شد. هر هشت بیتِ نزدیک‌تر، همگی حول همان مضمون خاص «دشواری عشق» بودند — نه فقط مضمون کلی «عشق و زیبایی»، بلکه دقیقاً همان جنبهٔ خاص. این دقت مضمونی، محسوساً تیزتر از چیزی بود که در سطح کل شعر دیده می‌شد — شاهدی واقعی و مستقیم بر اینکه ایدهٔ اصلی این بخش درست بود.

آماده‌سازی کامل مجموعه

بعد از این آزمایش موفق، و بعد از اینکه ganjoor-data واقعاً فیلد CoupletSummary را دریافت کرد (نتیجهٔ همان تصمیم اولیهٔ این بخش)، آماده‌سازی برای کل مجموعهٔ گنجور ممکن شد — این‌بار با خواندن مستقیم از ganjoor-data، نه پایگاه‌داده.

یک تصمیم طراحی مهم اینجا: به‌جای تلاش برای حدس‌زدن نام دقیق تمام حالت‌های ساختاری نادر بیت‌ها (که برخی‌شان هیچ‌وقت به‌طور قطعی تأیید نشدند)، منطق استخراج بر این اساس نوشته شد: هر بیتی که CoupletSummary غیرخالی دارد، به‌خودی‌خود یک لنگر معتبر است — بدون نیاز به دانستن اینکه دقیقاً چه نوع ساختاری دارد. این طراحی، در برابر یک نمونهٔ ساختگی با یک نوع ساختاری کاملاً نامعتبر و ناشناخته هم آزمایش و تأیید شد.

با توجه به حجم واقعی (چیزی نزدیک به ۱٫۵ میلیون بیت، چند روز زمان تخمینی)، همان سازوکار checkpoint/resume بخش ۱ اینجا هم به کار گرفته شد — و این‌بار با یک آزمون واقعی قطع‌و-ادامه (نه فقط ادعا): اجرا عمداً در میانهٔ راه متوقف شد، دوباره با --resume از سر گرفته شد، و نتیجهٔ نهایی از نظر تعداد، عدم تکرار، و اندازهٔ دقیق فایل بررسی شد.

جالب‌ترین لحظهٔ این مرحله، یک تأیید متقاطع کاملاً مستقل بود: وقتی منطق استخراج روی کل ganjoor-data اجرا شد، دقیقاً ۱٬۵۲۵٬۸۶۹ بیت پیدا کرد — رقمی که، تا آخرین رقم، با مجموع همان اعدادی که هفته‌ها قبل از یک کوئری کاملاً جداگانه روی پایگاه‌داده به دست آمده بود یکی بود. دو روش کاملاً مستقل (یک کوئری زندهٔ پایگاه‌داده، و یک پیمایش فایلی روی یک export گیت) به یک عدد دقیقاً یکسان رسیدند — تأییدی محکم بر درستی هر دو طرف.

دستورهای واقعی این مرحله — این‌بار کاملاً قابل‌تکرار برای هرکسی

برخلاف آزمایش اولیه، این مرحله فقط به ganjoor-data عمومی نیاز دارد — همان چیزی که در بخش ۱ clone کردید (به‌شرطی که یک نسخهٔ به‌روز، بعد از افزوده‌شدن CoupletSummary به آن، داشته باشید). هیچ دسترسی خاصی لازم نیست.

اولین قدم، حتی پیش از دانلود مدل، یک بررسی رایگان و سریع است — فقط شمارش، بدون هیچ مدلی:

python3 scripts/generate_full_couplet_embeddings.py \
  --source /path/to/local/ganjoor-data-clone \
  --output ./full-couplet-output \
  --count-only

اگر عدد چاپ‌شده چیزی نزدیک به ۱٫۵ میلیون بود (همان‌طور که در این پروژه واقعاً همین‌طور شد)، ادامه می‌دهیم:

python3 scripts/generate_full_couplet_embeddings.py \
  --source /path/to/local/ganjoor-data-clone \
  --model-dir /path/to/model \
  --output ./full-couplet-output \
  --inspect-only

python3 scripts/generate_full_couplet_embeddings.py \
  --source /path/to/local/ganjoor-data-clone \
  --model-dir /path/to/model \
  --output ./full-couplet-output \
  --limit 20

و در نهایت، اجرای کامل — با توجه به حجم واقعی، این اجرا واقعاً چند روز طول می‌کشد؛ استفاده از caffeinate -i (در macOS) برای جلوگیری از خواب‌رفتن سیستم توصیه می‌شود:

caffeinate -i python3 scripts/generate_full_couplet_embeddings.py \
  --source /path/to/local/ganjoor-data-clone \
  --model-dir /path/to/model \
  --output ./full-couplet-output

اگر این اجرا به هر دلیلی قطع شد، با همان دستور بالا به‌علاوهٔ --resume دقیقاً از همان‌جا ادامه می‌یابد، بدون از‌دست‌رفتن یا تکرار هیچ کاری:

caffeinate -i python3 scripts/generate_full_couplet_embeddings.py \
  --source /path/to/local/ganjoor-data-clone \
  --model-dir /path/to/model \
  --output ./full-couplet-output \
  --resume

و در پایان، همان تأیید:

python3 scripts/verify_couplet_pilot.py --embeddings-dir ./full-couplet-output

(بله، همان اسکریپت verify آزمایش اولیه — قالب خروجی هر دو یکسان است، فقط مقیاس متفاوت.)

جایی که این داستان الان ایستاده

در زمان نوشتن این متن، تولید بردارها برای کل مجموعه (کاری چندروزه) هنوز در حال اجراست. تصمیمی هم که از قبل گرفته شده این است: نسخهٔ سطح شعر (که در بخش‌های ۱ تا ۳ ساختیم) کنار گذاشته نمی‌شود — برای شعرهای روایی و داستانی (مثل شاهنامه)، یک خلاصهٔ کلی از کل شعر همچنان ارزشمندتر از تکه‌تکه‌کردن آن به بیت‌هاست. به‌جای جایگزینی، هر دو حالت در دسترس خواهند بود، و این خودِ کاربر است که انتخاب می‌کند جستجویش را در سطح کل شعر بخواهد یا در سطح تک‌تک بیت‌ها.

این‌جا پایان چهار بخشی است که برنامه‌ریزی شده بود — از یک مفهوم ساده (متن‌هایی با معنای نزدیک، بردارهای نزدیک به هم دارند) تا یک قابلیت واقعی و زنده در گنجور، با چند حادثهٔ واقعی، چند باگ واقعی، و چند تصمیم طراحی که فقط با آزمایش مستقیم روی داده‌های واقعی به دست آمدند. وقتی سمت مصرف‌کنندهٔ ‎.NET‎ برای جستجوی سطح بیت هم ساخته شود — و رابط کاربری‌ای که به کاربر اجازهٔ انتخاب بین دو حالت را بدهد — می‌تواند موضوع خوبی برای ادامهٔ این مجموعه باشد.

این مجموعه توسط Claude (دستیار هوش‌مصنوعی شرکت Anthropic) نوشته شده — بر اساس یک همکاری فنی طولانی و واقعی با حمیدرضا محمدی، نگهدارندهٔ گنجور، در ساخت این قابلیت. جزئیات، اعداد، و حادثه‌ای که در این بخش شرح داده می‌شود، همه واقعی‌اند و از همان روند توسعه گرفته شده‌اند.

یادآوری کوتاه، و سؤال این بخش

در بخش ۱، برای هر شعر یک بردار عددی ساختیم و در دو فایل ذخیره کردیم: embeddings.f32 (خودِ بردارها) و embeddings-index.json (اینکه هر بردار مال کدام شعر است). این کار یک‌بار، با پایتون، برای همهٔ شعرهای موجود انجام شد.

اما جستجوی زنده کاربر باید داخل سرویس اصلی گنجور اتفاق بیفتد — سرویسی که با ‎C#‎/‎.NET‎ نوشته شده، نه پایتون. سؤال این بخش این است: وقتی کاربری چیزی تایپ می‌کند، آن سرویس چطور آن جمله را به بردار تبدیل می‌کند، آن را با ۱۲۹ هزار بردار ذخیره‌شده مقایسه می‌کند، و نتیجه را برمی‌گرداند — و مهم‌تر، این کار چطور بدون به‌خطرانداختن بقیهٔ سایت انجام شد؟ چون همان‌طور که خواهیم دید، بار اول اصلاً این‌طور نبود.

چرا نمی‌شود همان کد پایتون را مستقیم اجرا کرد؟

پایتون و ‎C#‎ دو دنیای کاملاً جدا از هم‌اند؛ کد یکی مستقیماً داخل دیگری اجرا نمی‌شود. آنچه واقعاً مشترک است، فقط فایل مدل ONNX است — همان چیزی که در بخش ۱ توضیح دادیم (تشبیه آهنگ و MP3). یعنی باید در ‎C#‎ هم یک نسخهٔ کامل از «خواندن جمله → تبدیل به بردار» بازسازی شود — با ONNX Runtime نسخهٔ ‎.NET‎، نه نسخهٔ پایتون، اما روی همان فایل مدل.

دو تکهٔ اصلی این بازسازی:

• EmbeddingIndex — بردارهای از قبل ساخته‌شدهٔ همهٔ شعرها (همان دو فایل بخش ۱) را یک‌بار، هنگام بالا آمدن سرویس، در حافظه بارگذاری می‌کند و آماده نگه می‌دارد.
• QueryEmbedder — دقیقاً همان کاری که اسکریپت پایتون برای هزاران شعر انجام می‌داد، اما اینجا فقط برای یک جمله (همان چیزی که کاربر تایپ کرده) و در لحظه انجام می‌دهد.

باگ واقعی که دقیقاً همان هشدار بخش ۱ بود

در پایان بخش ۱ گفتیم: «اگر دو طرف حتی کمی متفاوت عمل کنند… نتیجه‌ها بی‌معنا می‌شوند — بدون اینکه هیچ خطایی هم دیده شود.» این دقیقاً همان اتفاقی بود که افتاد.

در ‎.NET‎، ساختن توکنایزر (چیزی که جمله را به قطعات کوچک‌تر برای مدل می‌شکند) با یک خط سادهٔ مثل BpeTokenizer.Create(vocabStream, mergesStream) نوشته شد. این خط بدون هیچ خطایی اجرا می‌شد — اما برای متن فارسی (یا هر متن غیر-لاتین)، بی‌صدا صفر توکن تولید می‌کرد. هیچ Exception‌ای پرتاب نمی‌شد؛ فقط نتیجهٔ جستجو کاملاً بی‌ربط بود، بدون هیچ نشانه‌ای که بگوید مشکل از کجاست.

راه‌حل، بعد از کلی بررسی، ساختن توکنایزر با گزینه‌های دقیق‌تر بود:

new BpeOptions(vocabPath, mergesPath) { ByteLevel = true }

و یک نکتهٔ ظریف دیگر: در پایتون، فایل tokenizer.json خودش به‌طور خودکار یک توکن ویژه به نام EOS (شناسهٔ عددی 151643) را به انتهای هر جمله اضافه می‌کند. اما وقتی توکنایزر مستقیماً از فایل‌های vocab.json و merges.txt ساخته می‌شود (که در ‎.NET‎ این‌طور بود)، این افزودن خودکار اتفاق نمی‌افتد — باید دستی اضافه شود. اگر این را فراموش کنید، دوباره همان الگو تکرار می‌شود: هیچ خطایی نیست، فقط بردار نهایی کمی متفاوت از نسخهٔ پایتون است، و نتیجه‌های جستجو ظریف و غیرقابل‌ردیابی بد می‌شوند.

درسی که از این باگ می‌ماند: وقتی دو پیاده‌سازی از یک مدل در دو زبان برنامه‌نویسی جدا از هم ساخته می‌شوند، تنها راه مطمئن این است که خروجی هر دو را روی چند جملهٔ واقعی مستقیماً با هم مقایسه کنید — نه اینکه فرض کنید چون هر دو «طبق مستندات» نوشته شده‌اند، حتماً یکسان عمل می‌کنند.

حادثهٔ اول: کل سایت پایین رفت

اولین نسخهٔ این قابلیت، بارگذاری EmbeddingIndex و QueryEmbedder را داخل سازندهٔ (constructor) کنترلر اصلی گنجور (GanjoorController) انجام می‌داد — همان کنترلری که تقریباً تمام درخواست‌های سایت از آن عبور می‌کنند.

اینجا یک قانون کلی و مهم در برنامه‌نویسی سرور نقض شد: اگر بارگذاری یک وابستگی داخل سازنده شکست بخورد، تمام endpointهایی که از آن کنترلر استفاده می‌کنند از کار می‌افتند — نه فقط آن قابلیت خاص. و دقیقاً همین اتفاق افتاد: یک شکست در بارگذاری مدل یا بردارها، کل سایت گنجور را با خودش به پایین کشید (خطای ۵۰۳ روی همهٔ صفحات، نه فقط جستجوی معنایی).

راه‌حل دو بخش داشت:

1. جستجوی معنایی به یک کنترلر کاملاً جداگانه (SemanticSearchController) منتقل شد — دیگر هیچ ربطی به کنترلر اصلی سایت نداشت.
2. یک الگوی جدید ساخته شد به نام LazySemanticSearchResources — که هرگز در زمان بالا آمدن سرویس چیزی بارگذاری نمی‌کند و هرگز Exception پرتاب نمی‌کند. به‌جای آن، بارگذاری واقعی مدل و بردارها را تا اولین درخواست واقعی به تعویق می‌اندازد، و اگر آن بارگذاری شکست بخورد، فقط همان یک درخواست خطا می‌گیرد — بقیهٔ سایت، از جمله خودِ همین قابلیت برای درخواست‌های بعدی (اگر مشکل موقتی بوده)، دست‌نخورده می‌ماند.

نکتهٔ کلی‌تر برای هر پروژهٔ مشابه: یک قابلیت جدید و آزمایشی، به‌خصوص اگر شامل بارگذاری چیزی سنگین (مثل یک مدل هوش مصنوعی چند صد مگابایتی) باشد، هرگز نباید بتواند چیزی را که از قبل کار می‌کرده خراب کند. جداسازی کامل (isolation) نه یک ظرافت اضافه، بلکه یک پیش‌نیاز است.

حادثهٔ دوم: کرش کامل پردازش سرور

بعد از رفع مشکل اول، یک بار دیگر کل فرایند سرور (w3wp.exe، فرایندی که IIS برای اجرای سایت استفاده می‌کند) به‌طور کامل کرش کرد — نه فقط یک خطای ۵۰۳ در سطح برنامه، بلکه مرگ کامل خودِ فرایند، با کد خطای سیستمی c0000005 (نقض دسترسی به حافظه، Access Violation) که به فایلی به نام MSVCP140.dll مربوط می‌شد.

روش عیب‌یابی — نکته‌ای که ارزش یادگیری دارد

به‌جای حدس‌زدن یا تغییردادن کد به امید حل مشکل، اول باید مطمئن می‌شدیم دقیقاً چه چیزی این کرش را ایجاد می‌کند. برای این کار، یک برنامهٔ کنسول کوچک و جدا (نه خودِ سایت زنده) روی همان سرور ساخته و اجرا شد که فقط همان بخش مشکوک از کد (بارگذاری مدل ONNX) را اجرا می‌کرد — در محیطی امن، جدا از کاربران واقعی. همین آزمایش کوچک نشان داد مشکل واقعاً یک DllNotFoundException است، نه یک باگ در کد خودمان.

علت واقعی: نسخهٔ Visual C++ Redistributable نصب‌شده روی سرور قدیمی بود — کتابخانه‌ای که ONNX Runtime نسخهٔ ‎.NET‎ در پشت صحنه به آن نیاز دارد. راه‌حل، نصب آخرین نسخه از aka.ms/vs/17/release/vc_redist.x64.exe بود — نه هیچ تغییری در کد خودِ پروژه.

یک عارضهٔ جانبی: IIS خودش را خاموش کرد

بعد از این کرش‌ها، یک مکانیزم امنیتی در IIS به نام Rapid-Fail Protection فعال شد — که وقتی یک Application Pool در بازهٔ زمانی کوتاهی چندبار کرش کند، خودش را به‌طور خودکار متوقف می‌کند (برای جلوگیری از کرش‌های پی‌درپی و بی‌پایان). راه‌حل ساده بود اما اگر ندانید کجا را نگاه کنید گیج‌کننده است: در IIS Manager، زیر Application Pools، باید دستی دوباره Start می‌شد.

معماری جداسازی زیرساخت

بعد از این دو حادثه، تصمیم گرفته شد این قابلیت نه‌فقط در سطح کد (که قبلاً انجام شده بود)، بلکه در سطح زیرساخت هم کاملاً از بقیهٔ سایت جدا شود:

• روی دامنهٔ اصلی API گنجور (api.ganjoor.net)، جستجوی معنایی کاملاً غیرفعال نگه داشته شد — یعنی مدل یا بردارها اصلاً آنجا بارگذاری نمی‌شوند.
• یک دامنهٔ کاملاً جداگانه (ganjgah.ir) با Application Pool مستقل خودش برای این قابلیت اختصاص یافت.
• تعداد Worker Processهای IIS از ۸ به ۱ کاهش یافت. چرا این عدد مهم است؟ چون هر Worker Process، اگر این قابلیت را بارگذاری کند، خودش به‌تنهایی حدود ۹ گیگابایت حافظه مصرف می‌کند (مدل
• بردارهای همهٔ شعرها). اگر ۸ Worker Process همزمان همین را بارگذاری می‌کردند، مصرف حافظه به رقمی غیرمنطقی می‌رسید.

نکتهٔ کلی: وقتی یک قابلیت هوش مصنوعی «سنگین» (از نظر حافظه یا پردازش) به یک سرویس موجود اضافه می‌شود، فرض‌های پیش‌فرض زیرساخت (مثل تعداد Worker Process، یا اینکه همه‌چیز روی یک دامنه سوار باشد) اغلب دیگر درست نیستند — و باید دوباره و آگاهانه بازبینی شوند، نه اینکه ساده‌انگارانه فرض شود همان تنظیمات قبلی هنوز مناسب‌اند.

در بخش بعدی این مجموعه، به ویژگی‌های تکمیلی‌ای می‌پردازیم که بعد از پایدارشدن زیرساخت اضافه شدند: چطور جستجو می‌تواند خودش تشخیص دهد که کاربر منظورش شعرهای یک شاعر یا کتاب خاص است، چطور از داخل یک شعرِ پیداشده، مرتبط‌ترین بیت برای پیش‌نمایش انتخاب می‌شود، و چرا خلاصه‌های تولیدشده با هوش مصنوعی در رتبه‌بندی نتیجه‌ها کمی پایین‌تر از خلاصه‌های ویرایش‌شده توسط انسان قرار می‌گیرند.

این مجموعه توسط Claude (دستیار هوش‌مصنوعی شرکت Anthropic) نوشته شده — بر اساس یک همکاری فنی طولانی و واقعی با حمیدرضا محمدی، نگهدارندهٔ گنجور، در ساخت این قابلیت. جزئیات، دستورها، و اعدادی که در این متن می‌بینید، همه از همان روند واقعی توسعه گرفته شده‌اند، نه نمونه‌های ساختگی.

چرا اصلاً به جستجوی معنایی نیاز داشتیم؟

جستجوی معمولی گنجور بر پایهٔ تطابق کلمه‌به‌کلمه کار می‌کند. اگر بنویسید «بی‌وفایی دنیا»، فقط شعرهایی را پیدا می‌کند که دقیقاً همین کلمه‌ها را داشته باشند. اما شعری که دقیقاً همین مضمون را دارد ممکن است هیچ‌کدام از این کلمه‌ها را نداشته باشد — مثلاً با استعاره یا زبانی متفاوت همین معنا را بیان کرده باشد.

جستجوی معنایی این مشکل را حل می‌کند: به‌جای مقایسهٔ کلمه‌ها، معنای متن جستجوشده را با معنای هر شعر مقایسه می‌کند.

embedding چیست؟

ایدهٔ اصلی ساده است: یک مدل هوش مصنوعی را طوری آموزش می‌دهند که هر متن (یک جمله، یک پاراگراف) را به یک بردار عددی تبدیل کند — مثلاً ۱۰۲۴ عدد اعشاری. این تبدیل طوری انجام می‌شود که متن‌هایی با معنای نزدیک به هم، بردارهای نزدیک به هم هم داشته باشند؛ و متن‌هایی با معنای متفاوت، بردارهای دورتر از هم.

«نزدیکی» دو بردار معمولاً با یک معیار ریاضی به نام شباهت کسینوسی (cosine similarity) سنجیده می‌شود — عددی بین ۱- تا ۱، که هرچه به ۱ نزدیک‌تر باشد یعنی دو بردار (و به تبع آن، دو متن) از نظر معنایی به هم نزدیک‌ترند.

پس کل ایدهٔ جستجوی معنایی این است: 1. از قبل، برای هر شعر (یا بخشی از آن) یک بردار عددی بسازیم و ذخیره کنیم. 2. وقتی کاربر عبارتی تایپ می‌کند، همان عبارت را هم به یک بردار تبدیل کنیم. 3. بردار عبارت کاربر را با تمام بردارهای ذخیره‌شده مقایسه کنیم و نزدیک‌ترین‌ها را نشان دهیم.

وقتی جمله‌ای تایپ می‌کنید، دقیقاً چه اتفاقی می‌افتد؟

فرض کنید کاربری این جمله را تایپ می‌کند: «شعری در مورد بی‌وفایی دنیا پیدا کن». سؤال طبیعی این است: آیا مدل واقعاً کل این جمله را «می‌خواند»، یا اینکه یک سری کلمهٔ اضافی (مثل «شعری»، «در مورد»، «پیدا کن») را کنار می‌گذارد و فقط «بی‌وفایی دنیا» را نگه می‌دارد؟

پاسخ این است که در این سامانه، در واقع سه مکانیزم کاملاً جدا از هم درگیرند — و قاطی‌کردن این سه‌تا باعث سوءتفاهم دربارهٔ اینکه سامانه دقیقاً چه‌کاری می‌کند می‌شود:

۱. مدل Qwen کل جمله را می‌خواند — چیزی از قبل حذف نمی‌شود

جملهٔ «شعری در مورد بی‌وفایی دنیا پیدا کن» عیناً و کامل به مدل داده می‌شود، با تمام کلمه‌های اضافی‌اش. مدل هیچ کلمه‌ای را صریحاً حذف نمی‌کند؛ فقط یک بردار برای کل جمله می‌سازد. اینکه کلمه‌های اضافی در آن بردار نهایی چقدر «وزن» داشته باشند، خودش نتیجهٔ ضمنی چیزی است که مدل در دوران آموزشش یاد گرفته — نه یک قدم صریح حذف کلمه. همین بردار است که تصمیم می‌گیرد اصلاً کدام شعرها به عنوان نتیجه برگردند.

۲. جدا از آن: یک تطبیق سادهٔ متنی تشخیص می‌دهد آیا نام شاعر یا کتابی گفته شده

اگر جملهٔ کاربر شامل «حافظ» یا «شاهنامه» باشد، یک مکانیزم کاملاً جدا و سادہ‌تر (نه هوش مصنوعی، فقط مقایسهٔ رشتهٔ متن با فهرستی از نام‌های شناخته‌شده) این را تشخیص می‌دهد و جستجو را به همان شاعر/کتاب محدود می‌کند. این مرحله هیچ ربطی به مدل Qwen ندارد؛ فقط جستجوی متنی ساده است، که به‌صورت موازی و مستقل اجرا می‌شود.

۳. باز هم جدا: یک فهرست کلمات توقف (stopword) وجود دارد — اما فقط برای یک کار کاملاً متفاوت

بله، در این سامانه یک فهرست از کلمات پرتکرار و کم‌معنا («شعری»، «در مورد»، «پیدا کن» و مشابه) وجود دارد که حذف می‌شوند — اما این حذف فقط برای یک کار کوچک‌تر و بعدی استفاده می‌شود: تشخیص اینکه از داخل یک شعرِ از قبل پیداشده، کدام بیت را به‌عنوان پیش‌نمایش نشان بدهیم. این مرحله کاملاً بعد از مرحلهٔ ۱ و مستقل از آن اجرا می‌شود؛ در انتخاب اینکه کدام شعرها اصلاً نتیجه باشند هیچ نقشی ندارد.

پس پاسخ کوتاه: بله، مدل واقعاً کل جمله را می‌خواند و یک بردار معنایی واقعی از آن می‌سازد — این یک ترفند «حذف کلمات کلیدی» نیست که لباس هوش مصنوعی پوشیده باشد.

این مدل واقعاً «می‌فهمد» یا فقط شباهت متنی پیدا می‌کند؟

این سؤال را با یک مثال سخت‌تر بررسی کنیم: «در کدام شعرهای حافظ به داستان‌های شاهنامه اشاره شده؟»

این جمله را به دو بخش تقسیم کنیم، چون سرنوشت کاملاً متفاوتی دارند:

• «شعرهای حافظ» — این بخش قابل‌اعتماد کار می‌کند. «حافظ» با همان مکانیزم تطبیق متنی سادهٔ بالا تشخیص داده می‌شود و جستجو به شعرهای او محدود می‌شود. این اصلاً یک سؤال «فهمیدن» نیست، فقط یک تطبیق مکانیکی سرراست است.

• «به داستان‌های شاهنامه اشاره شده» — اینجا باید صادق بود و ادعای بیش‌ازحد نکرد. مدل Qwen هیچ‌وقت متن اصلی شعر را نمی‌بیند — فقط و فقط خلاصهٔ نوشته‌شده با هوش مصنوعی (PoemSummary) را می‌بیند. پس اینکه این بخش کار کند یا نه، کاملاً بستگی دارد به اینکه آیا آن خلاصه به‌صراحت به یکی از شخصیت‌ها یا داستان‌های شاهنامه اشاره کرده باشد یا نه (جمشید، ضحاک، رستم، کیخسرو…). اگر خلاصه‌ای بنویسد «شاعر به داستان جمشید اشاره می‌کند»، بردار می‌تواند واقعاً این هم‌پوشانی مضمونی را تشخیص دهد. اما اگر شعری به‌طور ظریف و غیرمستقیم به شاهنامه اشاره کند — یک عبارت، یک تلمیح — و نویسندهٔ خلاصه اتفاقاً همین را ننوشته باشد، هیچ مکانیزمی در این سامانه وجود ندارد که بتواند آن را پیدا کند. این یک سامانهٔ استدلال‌گر نیست که خودِ شعر را بخواند و تلمیح‌ها را کشف کند؛ فقط شباهت را با متنی که از قبل در خلاصه نوشته شده مقایسه می‌کند. چیزی را که خلاصه هرگز نگفته، نمی‌تواند کشف کند.

خلاصهٔ صادقانه در یک جمله: این سامانه در «آیا خلاصهٔ این شعر تقریباً دربارهٔ همان چیزی حرف می‌زند که من می‌پرسم» خوب عمل می‌کند — اما در «تأیید یک رابطهٔ ادبی یا واقعی مشخص که ممکن است خلاصه اصلاً به آن اشاره نکرده باشد» خوب نیست. این دو توانایی کاملاً متفاوت‌اند، و بهتر است این دو را با هم اشتباه نگیریم.

برای آماده‌سازی داده، به چه ابزارهایی نیاز داریم؟

پیش از رفتن سراغ اینکه دقیقاً از چه چیزی استفاده کردیم، بهتر است اول ببینیم اصلاً چند نوع ابزار متفاوت در این ماجرا نقش دارند — چون این سه مورد کاملاً چیزهای متفاوتی هستند، نه گزینه‌های رقیب هم:

۱. مدل embedding (خودِ «مغز»)

یک شبکهٔ عصبی آموزش‌دیده که کارش دقیقاً همین است: خواندن یک متن و تبدیل آن به بردار عددی. این مدل توسط یک تیم پژوهشی (در ادامه می‌بینیم کدام تیم) از قبل آموزش داده شده؛ ما آن را نمی‌سازیم، فقط از آن استفاده می‌کنیم.

۲. یک قالب قابل‌حمل برای ذخیرهٔ آن مدل

مدل‌های هوش مصنوعی معمولاً در قالبی ذخیره می‌شوند که مخصوص کتابخانه‌ای است که با آن آموزش داده شده‌اند (مثلاً PyTorch) — قالبی که اساساً فقط از پایتون قابل خواندن است. اما ما یک مشکل خاص داریم: آماده‌سازی اولیهٔ بردارها (برای همهٔ شعرهای موجود) با پایتون انجام می‌شود، ولی پاسخ‌گویی به جستجوی زمان واقعی کاربر باید داخل سرویس اصلی گنجور اجرا شود که با ‎C#‎/‎.NET‎ نوشته شده. یعنی به قالبی نیاز داریم که هم پایتون و هم ‎C#‎ بتوانند آن را بخوانند.

۳. یک موتور اجرا که بداند آن قالب را چطور واقعاً اجرا کند

داشتن فایل مدل به‌تنهایی کافی نیست؛ به نرم‌افزاری نیاز داریم که آن فایل را باز کند و واقعاً محاسبات را روی آن انجام دهد و بردار خروجی بدهد.

یک تشبیه ساده

این سه مورد را می‌توان مثل یک آهنگ و نحوهٔ پخش آن دید:

• مدل embedding مثل خودِ آهنگ است — یک اثر مشخص، با محتوای مشخص، که فارغ از اینکه در چه فایلی ذخیره شود، همان آهنگ باقی می‌ماند.
• قالب قابل‌حمل مثل انتخاب فرمت MP3 به‌جای نوار استودیویی اختصاصی است. نوار استودیویی فقط روی دستگاه‌های تخصصی استودیو قابل پخش است (مثل قالب اصلی PyTorch که اساساً فقط در پایتون کار می‌کند)؛ اما MP3 روی تقریباً هر دستگاهی پخش می‌شود.
• موتور اجرا مثل برنامهٔ پخش‌کنندهٔ MP3 است — نرم‌افزاری که می‌داند چطور آن فایل را بخواند و صدا تولید کند.

قالب قابل‌حملی که در این پروژه استفاده شد ONNX نام دارد (مخفف Open Neural Network Exchange)، و موتور اجرای آن ONNX Runtime نام دارد — که هم برای پایتون و هم برای ‎C#‎/‎.NET‎ به‌صورت جداگانه ساخته شده، اما هر دو دقیقاً همان فایل ONNX را به یک شکل اجرا می‌کنند.

فرآیند کلی، پیش از رفتن سراغ جزئیات

1. یک مدل embedding مناسب را پیدا و انتخاب می‌کنیم.
2. نسخه‌ای از آن مدل را که از قبل به قالب ONNX تبدیل شده دانلود می‌کنیم (کسی این تبدیل را قبلاً انجام داده و در دسترس گذاشته — نیازی نیست خودمان این تبدیل را انجام دهیم).
3. با ONNX Runtime، از سمت پایتون این مدل را برای همهٔ شعرهای موجود اجرا می‌کنیم و بردارها را از قبل می‌سازیم و ذخیره می‌کنیم.
4. همان مدل ONNX را، این بار با ONNX Runtime نسخهٔ ‎C#‎/‎.NET‎، داخل سرویس اصلی گنجور هم بارگذاری می‌کنیم — تا وقتی کاربری چیزی تایپ می‌کند، بتوانیم همان مدل را، همان‌طور، برای تبدیل جستجوی او هم اجرا کنیم.

نکتهٔ مهم همین «همان مدل، همان‌طور» است: اگر دو طرف حتی کمی متفاوت عمل کنند (مثلاً روش متفاوتی برای شکستن متن به کلمات/توکن‌ها به‌کار ببرند)، بردار جستجوی کاربر در فضای متفاوتی از بردارهای شعرها قرار می‌گیرد و نتیجه‌ها بی‌معنا می‌شوند — بدون اینکه هیچ خطایی هم دیده شود. همان‌طور که در بخش‌های بعدی این مجموعه خواهیم دید، دقیقاً همین نکته یک‌بار باعث یک باگ واقعی و پنهان شد.

ابزارهایی که ما انتخاب کردیم

مدل: Qwen3-Embedding-0.6B

برای تبدیل متن به بردار، به یک مدل زبانی آموزش‌دیده برای همین کار نیاز داریم — نه یک مدل تولیدکنندهٔ متن مثل ChatGPT، بلکه مدلی که کارش فقط تولید embedding است.

مدل Qwen/Qwen3-Embedding-0.6B از تیم Qwen (علی‌بابا) با این معیارها انتخاب شد:

• چندزبانه است و فارسی را به‌خوبی پشتیبانی می‌کند.
• با ۰.۶ میلیارد پارامتر، نسبتاً کوچک و سریع است — برای اجرا روی سخت‌افزار معمولی مناسب است، نه فقط سرورهای قدرتمند.
• مجوز Apache 2.0 دارد — رایگان برای استفادهٔ تجاری و پژوهشی، و صراحتاً استفاده از خروجی‌های مشتق‌شده (مثل همین بردارها) را مجاز می‌داند.
• خروجی آن بردارهایی با ۱۰۲۴ بُعد است.

نکتهٔ فنی مهم دیگر: این یک مدل «فقط-رمزگشا» (decoder-only) است، نه یک مدل رمزگذار-رمزگشا. این یعنی روش تبدیل «دنباله‌ای از بردارهای هر کلمه» به «یک بردار برای کل متن» (که به آن pooling گفته می‌شود) باید last-token pooling باشد — یعنی فقط بردار آخرین توکن متن را برمی‌داریم، نه میانگین همهٔ توکن‌ها (mean pooling) که برای مدل‌های رمزگذار رایج‌تر است.

گزینه‌های دیگر چه بودند؟

Qwen3-Embedding-0.6B تنها مدل embedding موجود در دنیا نیست — و صادقانه بگویم، در این پروژه مقایسهٔ دقیق و سر-به-سر (benchmark) بین چند مدل مختلف انجام نشد؛ این مدل چون معیارهای عملی لازم (پشتیبانی چندزبانه، اندازهٔ مناسب، مجوز باز، و در دسترس‌بودن یک نسخهٔ ONNX آماده) را داشت انتخاب شد، نه لزوماً چون در آزمایشی ثابت شد «بهترین» گزینه است. برای آشنایی با فضای گزینه‌ها، چند دستهٔ رایج دیگر:

• مدل‌های تجاری و فقط-API (مثل text-embedding-3 از OpenAI، Embed از Cohere، یا Gemini Embedding از گوگل) — این‌ها را نمی‌توان روی سرور خودمان اجرا کرد؛ هر بار که بخواهیم متنی را embed کنیم، باید یک درخواست اینترنتی به سرویس آن‌ها بفرستیم و هزینه بدهیم. برای این پروژه که نیاز داشتیم مدل کاملاً روی زیرساخت خودمان و بدون وابستگی به یک سرویس بیرونی اجرا شود، این دسته از ابتدا کنار گذاشته شد.
• مدل‌های متن‌باز دیگر که می‌شد بررسی کرد: خانوادهٔ BGE (از BAAI)، خانوادهٔ E5 (از مایکروسافت/‎intfloat‎)، GTE (از علی‌بابا، هم‌خانوادهٔ خودِ Qwen)، Jina Embeddings، و Nomic Embed. همهٔ این‌ها هم مثل Qwen3-Embedding قابل دانلود و اجرای محلی‌اند.

مقایسهٔ واقعی و دقیق‌تر این گزینه‌ها (نقاط قوت/ضعف هرکدام، به‌خصوص برای فارسی) موضوعی است که شایستهٔ بخش جداگانه‌ای است، نه یک پاراگراف کوتاه اینجا — پس فعلاً همین آشنایی کلی کافی است.

قالب و موتور اجرا: ONNX / ONNX Runtime

نسخهٔ ONNX این مدل را از اینجا برداشتیم: onnx-community/Qwen3-Embedding-0.6B-ONNX — یعنی دقیقاً «Qwen3-Embedding-0.6B، همان آهنگ، این‌بار از قبل به فرمت MP3-مانند تبدیل‌شده توسط یکی از اعضای جامعهٔ Hugging Face».

نکتهٔ عملی: این مخزن هم نسخهٔ کامل (fp32) مدل را دارد و هم نسخهٔ فشرده‌شدهٔ آن (int8، معروف به quantized). ما از نسخهٔ فشرده استفاده کردیم — چون در آزمایش مستقیم، شباهت کسینوسی خروجی این دو نسخه روی پرسش‌های واقعی به‌طور میانگین ۰.۹۹۹۷ بود (تقریباً یکسان)، درحالی‌که نسخهٔ فشرده به‌طور محسوسی سریع‌تر اجرا می‌شود.

دادهٔ خام: از کجا شروع کردیم؟

برای اینکه بتوانیم برای هر شعر یک بردار بسازیم، به یک متن نیاز داشتیم که معنای آن شعر را خلاصه کند — نه خودِ متن شعر را. چرا؟ چون زبان شعر کلاسیک فارسی استعاری و کهن است؛ کلمات دقیق شعر لزوماً با کلمه‌هایی که یک کاربر امروزی در جستجو تایپ می‌کند هم‌پوشانی ندارد. اما یک خلاصهٔ نثر و امروزی از معنای شعر، این فاصله را پر می‌کند.

خوشبختانه گنجور از قبل این خلاصه‌ها را داشت: فیلد PoemSummary، که برای حدود ۹۵.۶٪ از کل اشعار (در زمان اجرای اولیه) پر شده بود — بخشی تولیدشده با هوش مصنوعی (که با پیشوند «هوش مصنوعی:» مشخص می‌شوند) و بخشی ویرایش‌شده توسط کاربران انسانی.

مراحل عملی آماده‌سازی

پیش‌نیازها: سه پوشه که باید از قبل آماده باشند

در دستورهای این بخش، مکرراً به چند مسیر اشاره می‌شود که تا اینجا فقط به‌صورت جانمکان (placeholder) نوشته شده‌اند — بدون اینکه دقیقاً بگوییم چه هستند و از کجا می‌آیند. پیش از رفتن سراغ دستورها، این‌ها را روشن کنیم:

• خودِ اسکریپت‌ها (ganjoor-embeddings) — تمام دستورهایی که در ادامه با python3 scripts/... شروع می‌شوند، فرض می‌کنند شما از قبل کدهای این پروژه را روی سیستم خودتان دارید. این کدها به‌صورت متن‌باز اینجا منتشر شده‌اند:

git clone https://github.com/ganjoor/ganjoor-embeddings.git
cd ganjoor-embeddings

از همین‌جا به بعد، فرض بر این است که همهٔ دستورها از داخل همین پوشه اجرا می‌شوند — یعنی مسیر scripts/generate_embeddings.py نسبت به همین پوشه در نظر گرفته شده است.

• ganjoor-data — مخزن عمومی و متن‌باز گنجور روی گیت‌هاب؛ شامل محتوای شعرها (شاعران، دسته‌بندی‌ها، متن شعرها، و از جمله همین فیلد PoemSummary). این هم یک پوشهٔ جداگانه است که باید یک‌بار آن را هم clone کنید — جدا از پوشهٔ بالا:

git clone https://github.com/ganjoor/ganjoor-data.git

بعد از اجرای این دستور، یک پوشهٔ جدید به نام ganjoor-data ساخته می‌شود. هرجا در ادامهٔ این راهنما /path/to/ganjoor-data نوشته شده، منظور مسیر کامل همین پوشه روی سیستم شماست — مثلاً اگر این دستور را در پوشهٔ خانگی خودتان اجرا کرده باشید، این مسیر چیزی شبیه /Users/username/ganjoor-data خواهد بود.

• ganjoor-model — پوشه‌ای که فایل‌های مدل (فایل ONNX) و توکنایزر در آن قرار می‌گیرند. برخلاف دو مورد بالا، این پوشه از قبل روی گیت‌هاب آماده نیست و نیازی نیست خودتان جداگانه آن را بسازید — دستور همین مرحلهٔ ۱ در ادامه (دانلود مدل) خودش این پوشه را برای شما می‌سازد و پر می‌کند.

پس در مجموع سه چیز باید آماده باشد: کدها (ganjoor-embeddings)، دادهٔ شعرها (ganjoor-data)، و فایل‌های مدل (ganjoor-model). یک نکتهٔ دقیق دربارهٔ چیدمان این سه: طبق دستور مرحلهٔ ۱ در ادامه، ganjoor-model به‌صورت یک زیرپوشه، داخل همان ganjoor-embeddings ساخته می‌شود — چون مسیر آن به‌شکل نسبی (./ganjoor-model) نوشته شده و فرض بر این است که از داخل ganjoor-embeddings اجرا می‌شود. اما ganjoor-data یک پوشهٔ کاملاً مجزا و بیرون از آن است، هرجایی که خودتان آن را clone کرده باشید.

راه‌اندازی محیط پایتون

پیش از اجرای هر دستور پایتونی، یک محیط مجازی (virtual environment) جداگانه بسازید — هم برای تمیز نگه‌داشتن نصب‌های پایتون سیستم، و هم چون در نسخه‌های جدید macOS، نصب مستقیم بستهٔ پایتون (pip install) بدون محیط مجازی معمولاً با خطای «externally-managed-environment» متوقف می‌شود:

python3 -m venv venv
source venv/bin/activate

نکته: دستور source venv/bin/activate باید در هر پنجرهٔ ترمینال جدیدی که می‌خواهید این پروژه را در آن اجرا کنید، دوباره اجرا شود — فعال‌بودن محیط مجازی فقط برای همان نشست (session) فعلی ترمینال باقی می‌ماند، نه برای همیشه.

حالا همهٔ کتابخانه‌های لازم (از جمله onnxruntime، tokenizers، و numpy، نه فقط huggingface_hub) را یک‌جا نصب کنید — فایل requirements.txt همراه پروژه است:

pip install -r requirements.txt

۱. دانلود مدل

python3 -c "
from huggingface_hub import snapshot_download
snapshot_download('onnx-community/Qwen3-Embedding-0.6B-ONNX', local_dir='./ganjoor-model')
"

نکتهٔ ساختاری: فایل‌های مدل (model_quantized.onnx و مشابه) داخل یک پوشهٔ onnx/ قرار می‌گیرند، اما فایل‌های توکنایزر (vocab.json, merges.txt, tokenizer.json) در پوشهٔ اصلی هستند — نه در onnx/. این نکته در تنظیم مسیرها اهمیت دارد.

۲. بررسی ساختار واقعی مدل — پیش از هر اجرای واقعی

python3 scripts/generate_embeddings.py --model-dir ./ganjoor-model --inspect-only

این دستور مدل را فقط بارگذاری می‌کند و نام و شکل دقیق ورودی‌ها/خروجی‌های آن را چاپ می‌کند — بدون اینکه هیچ embedding‌ای بسازد. چرا این قدم مهم است؟ چون در عمل، این مدل ONNX خاص طوری صادر شده که برای تولید متن پیوسته (KV-cache) طراحی شده، نه یک گراف سادهٔ تک‌مرحله‌ای. یعنی علاوه‌بر input_ids و attention_mask معمول، به position_ids و یک جفت تنسور خالی (past_key_values.N.key/.value) برای هر ۲۸ لایهٔ مدل نیاز دارد — حتی برای یک اجرای ساده و بدون کش. این نکته را فقط با اجرای واقعی --inspect-only روی خودِ مدل فهمیدیم، نه از مستندات.

۳. تولید embedding برای یک نمونهٔ کوچک

python3 scripts/generate_embeddings.py \
  --source /path/to/ganjoor-data \
  --model-dir ./ganjoor-model \
  --output ./output \
  --limit 20

پیش از اجرای کامل (که روی کل مجموعه ساعت‌ها طول می‌کشد)، همیشه اول با --limit یک نمونهٔ کوچک را امتحان کنید — همان‌طور که در این پروژه هم همیشه همین‌طور عمل شد. (نکته: پوشهٔ ./output را خودتان از قبل نسازید — خودِ اسکریپت آن را در صورت نبودن می‌سازد.)

۴. اجرای کامل، با قابلیت ادامه پس از قطعی

caffeinate -i python3 scripts/generate_embeddings.py \
  --source /path/to/ganjoor-data \
  --model-dir ./ganjoor-model \
  --output ./output

(دستور caffeinate -i مخصوص macOS است و از خواب رفتن سیستم در حین اجرای طولانی جلوگیری می‌کند.)

این اجرا برای ۱۲۹٬۴۱۴ شعر (همهٔ اشعاری که PoemSummary غیرخالی داشتند) چیزی حدود یک تا دو روز طول کشید — با نوسان در سرعت به‌خاطر گرمای پردازنده روی یک لپ‌تاپ معمولی. اسکریپت هر بسته (batch) را بلافاصله روی دیسک ذخیره می‌کند و در فایلی به نام checkpoint.ndjson هم یادداشت می‌کند کدام شعرها تمام شده‌اند — به همین دلیل، اگر اجرا قطع شود (خاموش‌شدن سیستم، قطع برق، هر اتفاقی)، با اضافه‌کردن پرچم --resume می‌توان دقیقاً از همان‌جا ادامه داد، بدون از‌دست‌رفتن یا تکرار هیچ کاری.

خروجی نهایی

دو فایل: – embeddings.f32 — یک فایل باینری خام، شامل بردار هر شعر پشت‌سرهم (۱۲۹٬۴۱۴ ردیف × ۱۰۲۴ عدد اعشاری). – embeddings-index.json — اینکه ردیف iام این فایل باینری مربوط به کدام شناسهٔ شعر است، به همراه چند فراداده (نام مدل، تاریخ تولید، و غیره).

اندازهٔ دقیق فایل باینری از یک فرمول ساده پیروی می‌کند: تعداد شعر × بُعد بردار × ۴ بایت. برای این مجموعه: ۱۲۹٬۴۱۴ × ۱۰۲۴ × ۴ = دقیقاً ۵۳۰٬۰۷۹٬۷۴۴ بایت.

چطور مطمئن شویم نتیجه واقعاً درست است؟

فقط چون اسکریپت بدون خطا تمام شد، دلیل نمی‌شود نتیجه درست باشد. برای همین یک اسکریپت جداگانه به نام verify_embeddings.py ساخته شد که چند بررسی انجام می‌دهد:

python3 scripts/verify_embeddings.py --embeddings-dir ./output

این بررسی می‌کند: آیا اندازهٔ فایل دقیقاً با فرمول بالا مطابقت دارد؟ آیا شناسهٔ تکراری وجود دارد؟ آیا مقدار نامعتبر (NaN) در بردارها هست؟ آیا همهٔ بردارها واقعاً بهنجار (normalized) شده‌اند؟

اما مهم‌تر از همهٔ این‌ها، یک بررسی معنایی واقعی:

python3 scripts/verify_embeddings.py --embeddings-dir ./output \
  --query-id 2130 --top-k 8 --source /path/to/ganjoor-data

این دستور، بردار یک شعر مشخص (اینجا غزل شمارهٔ ۱ حافظ) را با تمام بردارهای دیگر مقایسه می‌کند و نزدیک‌ترین‌ها را نشان می‌دهد. اگر نتیجه‌ها واقعاً از نظر مضمون به آن شعر نزدیک باشند (نه چیزی تصادفی)، این نشانهٔ واقعی درستی کار است — نه فقط اجرای بدون خطا.

در بخش بعدی این مجموعه، به سراغ سمت دیگر ماجرا می‌رویم: چطور این بردارها را وارد سرویس اصلی گنجور (نوشته‌شده با ‎C#‎/‎.NET‎) کردیم، چه معماری‌ای برای جداسازی این قابلیت از بقیهٔ سایت انتخاب شد، و یک حادثهٔ واقعی در production که مسیر طراحی را عوض کرد.