این مجموعه توسط 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، یا اینکه همه‌چیز روی یک دامنه سوار باشد) اغلب دیگر درست نیستند — و باید دوباره و آگاهانه بازبینی شوند، نه اینکه ساده‌انگارانه فرض شود همان تنظیمات قبلی هنوز مناسب‌اند.

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