🎮 چجوری معماری و ساختار نرم‌افزار رو مستند و نتقل کنیم؟
یادگیری C4 Model با مثال واقعی - بخش اول

💡سناریو:
فرض کن یه نرم‌افزار داریم که هر چند ساعت‌یک‌بار میره وب‌سایت‌هایی که بهش معرفی کردیم رو بازدید میکنه، خبرهای تازه‌شون رو می‌خونه و بعد متنشون رو از طریق ollama با یک مدل‌زبانی خلاصه و چکیده می‌کنه؛ بعد به صورت روزانه یه خبرنامه مختصر و کاربردی می‌سازه و برای کاربرهایی که عضو شدن میفرسته. کاربرها هم میتونن مشخص کنن که از کدوم سایت‌ها خبر بگیرن، ساعت ارسال خبرنامه کی باشه، و اینجور چیزها!
(توی این مثال سیستممون وابستگی خارجی مثل سایت‌ها و سرور ایمیل هم داره)

همون‌طور که توی مقدمه عرض کردم، ما در چهار سطح سیستم رو با C4 مدل‌سازی می‌کنیم (چهار کلمه که با حرف C شروع می‌شن) این چهار سطح رو مثل نقشه گوگل‌مپ تصور کنید، ابتدا نقشه کلی رو به همسایگی‌های کشور یا شهر مورد نظرمون می‌بینیم، و با زوم کردن جزئیات بیشتری برامون ظاهر می‌شه.
تعداد المان‌های مورد استفاده در مدل C4 خیلی ساده و معدود است. در نتیجه خیلی سریع می‌شه یادگرفت.

1️⃣سطح اول: دیاگرام Context
در سطح context ما یه نگاه کلان به سیستم می‌اندازیم، اینکه نمای کلی و سیستم‌هایی که با سیستم ما در ارتباطن چجوری هستن.

- سیستم اصلی: News Summarizer
- کاربر: User (Subscriber)
- کاربر: User (Admin)
- سیستم‌های بیرونی:
- وب‌سایت‌های خبری
- سرویس Ollama
- سرویس SMTP Server

📇 ارتباط‌ها:
- سیستم خبرها رو از سایت‌های خبری میگیره.
- خبرها رو برای خلاصه‌سازی به Ollama میفرسته و جواب خلاصه‌شده میگیره.
- خبرنامه رو از طریق SMTP برای کاربرها میفرسته.

2️⃣سطح دوم: دیاگرام Container
سطح context رو به مثابه کشور فرض کنید و سطح container رو استان‌های داخل مرزهای کشور اون داستان ارتباطات با سیستم‌های بیرونی هم مثل استان‌های مرزی که ارتباط فیزیکی با کشورهای همسایه دارن (سیستم‌های بیرونی). حالا بیاین استان‌های درون این کشور رو یعنی containerها رو نگاه کنیم:

- کانتینر Scheduler: مسئول زمانبندی و اجرا کردن وظایف به‌صورت منظم
- کانتینر News Collector: جمع‌آوری اخبار از وبسایت‌ها
-کانتینر Ollama Client: ارتباط با ollama برای خلاصه‌سازی اخبار
- کانتینر Newsletter Generator: تولید خبرنامه
- کانتینر SMTP Client: ارسال خبرنامه‌ها
- کانتینر Database: نگهداری اطلاعات کاربرها، منابع خبری، تنظیمات، اخبار خلاصه شده

⚙️ دیاگرام C4 رو می‌تونیم هم با کد بسازیم (سینتکس PlantUML یا سینتکس structurizr یا...) البته هم با ترسیم می‌شه به کد رسید هم با کد به ترسیم بصری.

قسمت بعدی همین دو بخش رو با دیاگرام و کد مرور می‌کنیم. بخش‌های بعدی هم همین مسیر و سناریو رو برای دو تا C بعدی یعنی component و code. بعدش هم احتمالا ویدیو مرور همین داستان.

💬 موافقید با این مسیر؟

📱 ویدیو مرور کلی C4
این هم ویدیو مرور کلی C4 که یه مقدار کامل‌تر از پست قبلی است و امیدوارم برای دوستانی که جدی دوست دارن ازش استفاده کنن، مفید باشه 😉

💡 یک قدم به سمت کاربرد عینی مدل زبانی با RAG, CAG, KAG یا Fine Tuning

سال ۱۴۰۳ هم تموم شد و مثل ۲ سال قبل‌ترش، روز و ساعتی نبود که هوش‌مصنوعی خصوصا از نوع مولدش از متن و تیتر اخبار بیوفته 😉 حالا اگر تا به امروز فقط باهاش چت کردین، یا همون چت رو با API انجام دادین، دیگه ۱۴۰۴ سالیه که خوبه از حاشیه به متن بیاریدش و «اگر و اگر ارزش افزوده‌ای به محصولتون اضافه می‌کنه»، به شکل جدی‌تری ازش استفاده کنین. حالا این یعنی چی؟ مگه چت کردن چشه؟

در حالت عادی، یه مدل زبانی از چند میلیارد تا چندصد میلیارد پارامتر آموزش می‌بینه، بلده به زبون‌های مختلف حرف بزنه و جملاتی عاقلانه تا ابلهانه سرهم کنه. بلده دستور پخت سوشی تا قرمه‌سبزی بده و برای دل‌دردتون چایی‌نبات تجویز کنه، ولی اینکه بالانس حساب آقای جمالی چقدره یا آیین‌نامه‌های داخلی شرکتی که ما توش کار می‌کنیم یعنی کامپیوتراندیشان عصر نوین پاسارگاد با مدیریت آقای موکت‌پور رو که بلد نیست!‍ پس باید راهی یاد بگیریم که مزخرفاتی که بلده رو با مزخرفات خودمون بیامیزیم و مزخرفات ترکیبی تولید کنیم. پس یه نگاه کلی به RAG، CAG, KAG و Fine Tuning بندازیم تا اگر مشتری داشت ادامه‌اش بدیم…


✅ مفهوم و کاربرد RAG یا Retrieval-Augmented Generation چیه؟

کار RAG اینه که داده‌های مدل رو با دیتای ما تکمیل کنه؛ یعنی موقع جواب دادن به سؤال، میره از یه دیتابیس یا منبع خارجی (که عموما به صورت Vector database ذخیره می‌کنیم) اطلاعات جدید رو می‌گیره و بعد جواب می‌ده. اینجوری دیگه همیشه اطلاعات سیستم خودمون رو در کنار قابلیت‌های مدل اصلی داریم. این اطلاعات رو می‌تونیم نهایتا به شکل ساختارمند و مشخص (مثلا یه آبجکت یا یه ساختار JSON مشخص) برگردونیم، یا باهاش جمله بسازیم و مثل یه محاوره انسانی برگردونیمش.

چرا لازمه ازش استفاده کنیم؟
- اطلاعات به‌روز و دقیق‌تر
- کاهش خطا و توهم در جواب‌های مدل
- جواب‌های دقیق و مبتنی بر داده واقعی


✅ مفهوم و کاربرد KAG یا Knowledge-Augmented Generation چیه؟

کاربرد و مفهموم KAG یه مرحله پیشرفته‌تر از RAG هست که از گراف‌های دانش ساختاریافته استفاده می‌کنه. یعنی علاوه بر داده‌های معمولی، داده‌ها رو به‌صورت ساختاریافته (مثل گراف دانش) به مدل می‌ده و مدل می‌تونه از طریق این ساختارها منطق و استدلال چندمرحله‌ای انجام بده. (توی RAG کوئری داریم ولی اینجا گراف دانش)

چرا لازمه ازش استفاده کنیم؟
- افزایش دقت در حوزه‌های تخصصی
- استدلال چندمرحله‌ای و منطقی
- رعایت قوانین و مقررات مشخص (مثل حوزه‌های پزشکی و حقوقی)


✅ مفهوم و کاربرد CAG یا Cache-Augmented Generation چیه؟

مفهوم CAG یه جورایی نسخه سریع‌تر و ساده‌تر از RAG هست. توی CAG، دانش ثابت (مثل دفترچه‌های راهنما) از قبل تو حافظه (Cache) بارگذاری می‌شه و موقع جواب دادن لازم نیست هر بار اطلاعات رو از بیرون بگیره.

چرا لازمه ازش استفاده کنیم؟
- جواب‌های سریع‌تر
- ساختار ساده‌تر و هزینه کمتر
- ثبات و یکپارچگی جواب‌ها


✅ مفهوم و کاربر Fine Tuning (تنظیم دقیق) دیگه؟

یه سری داده‌های محدود و مشخص رو به یه مدل زبانی که خیلی چیزا بلده، ولی دقیقاً کاری که میخوای رو درست انجام نمی‌ده. اینجا میای از Fine Tuning استفاده می‌کنی؛ یعنی یه سری داده خاص خودمون رو میدیم بهش که یاد بگیره دقیقاً طبق اون چیزی که می‌خوایم جواب بده. از RAG خیلی ساده‌تر و ابتدایی‌تره.

چرا لازمه ازش استفاده کنیم؟
- بهبود دقت مدل توی یه وظیفه خاص
- سفارشی کردن مدل برای کسب‌وکار یا حوزه خاص خودمون
- کاهش هزینه‌ها (چون نیازی به آموزش یه مدل عظیم از صفر نداریم)


📎 طی ماه‌های پیش رو، SQL Server 2025 قابلیت‌هایی ارائه خواهد کرد که کارهای RAG و CAG و KAG رو بتونیم انجام بدیم. یعنی به جای استفاده از Vector Databaseها که الان ازشون برای RAG کمک می‌گیریم، می‌تونیم مستقیم از خود SQL Server کمک بگیریم. البته چون هنوز قابلیت vector اش رونمایی عمومی نشده، نمی‌شه قضاوت کرد که در مقایسه با نمونه‌های پرشمار VectorDBها چه جایگاهی داره.

مثل همیشه: 💬⚙️😉

🚀 🤑 مثال عملی پیاده‌سازی RAG (قسمت ۱)
پاسخ به پرسش‌های ارزی! با دیتای لحظه‌ای... 😎🤑

گفتیم برای اینکه مدل‌های زبانی دیتای به‌روز یا دلخواه ما رو داشته باشن، باید با استفاده از روش‌هایی مثل RAG داده‌های دلخواهمون رو بهشون ارائه کنیم. برای ارائه دیتا از وکتور دیتابیس یا ساختارهای دیگه‌ی حافظه‌ای استفاده می‌کنیم. حالا برای اینکه دست‌به‌کد شیم، تصمیم گرفتم قبل از توضیح دقیق‌تر وکتور دیتابیس، یه مثال بنویسیم تا با ساختارهای ساده و فرایند کلی آشنا شیم. البته توی این مثال اول از memory store استفاده می‌کنم، و در ادامه می‌ریم سراغ وکتور دیتابیس.

سناریو:
هر مدل هوش‌مصنوعی هر چقدر کامل یا باهوش باشه، ۲ چیز در جهان رو نمی‌تونه پیش‌بینی کنه: اولیش قیمت ارز در ایرانه. دومیش هم فعلا بماند 😉؛ حالا می‌خواهیم توی این مثال بریم از یکی از سایت‌های اعلام نرخ ارز، قیمت ارزها رو بگیریم ولی با RAG به مدلمون دیتا بدیم. بعدش که از مدل سوال بپرسیم دیگه می‌دونه مثلا دلار چنده. دقت کنید که اینجا منظورم چپوندن «متن» در قالب پرامپت نیست. بلکه استفاده از ساختار RAG است.

روی کامپیوتر خودمون ollama نصب می‌کنیم و از مدل Phi استفاده می‌کنیم که کوچیک باشه و سخت‌افزار خاصی نیاز نداشته باشه.

موافقید با این مثال پیش بریم؟
اگر موافقید
اول: ollama رو نصب کنید
دوم: بعد از نصب، دستور زیر رو برای دریافت مدل phi3 mini که حدود ۲.۲ گیگابایت است توی ترمینالتون اجرا کنید

ollama pull phi3:mini

بعدش برگردید به همین پست یک عدد ⚙️ بکارید اینجا تا بریم سراغ قسمت بعدی یعنی کد #C که با استفاده از semantic kernel دیتا رو RAG می‌کنیم. البته قبلش هم با HtmlAgilityPack دیتا رو از bonbast.org کرال می‌کنیم.

* دلیل انتخاب سی‌شارپ این بود که حس کردم اعضا کانال عموما به سمت سی‌شارپ گرایش دارن (اگر هر کدوم از پایتون یا گو به حدنصاب برسه، با اون هم می‌نویسم)

* ادامه مثال، و اینکه تا چه حدی عمیق شیم بسته به بازخوردها داره.

💬 نظر؟ سوال؟

🚀 🤑 مثال عملی پیاده‌سازی RAG (قسمت ۲)
پاسخ به پرسش‌های ارزی! با دیتای لحظه‌ای... 😎🤑

توجه!
قرار بود از مدل Phi-3 mini استفاده کنیم که ۲ گیگ باشه و روی لپ‌تاپ راحت اجرا شه، اینقدر احمق بود که رفتم سراغ llama3.2 که اونم ۲ گیگ است، ولی بسی باشعورتر!

نکته: مدل‌ها نیاز به سنجش و انتخاب دارن (چه در مثال ساده چه در کارهای بزرگ که خودش بخشی از فرایند AIOps است. Phi3 برای این کار مناسب نبود. گرچه صرفا بر اساس سایز کوچک برای مثال انتخاب کرده بودم ولی خیلی بی‌شعور بود!

کد آماده است و قابل دسترس رو گیت‌هاب، ولی باید توضیحات رو به فایل read me اضافه کنم و «شاید، اگر فرصت شه» ویدیو ضبط کنم براش.
🤓 می‌بینید که برعکس چیزی که انتظار می‌رفت، RAG اصلا خوب نیست!!! چرا؟ چون بدون RAG، یورو ۶۹۰۰ تومنه، ولی بعد از RAG می‌شه ۱۰۶هزار تومن. نتیجه می‌گیریم عامل گرونی ارز RAG است، و شایسته است که سریع‌تر به دار آویخته شود ☠️☠️



*️⃣اپلیکیشن یک console app است که کل کد در program.cs قرار دارد.

*️⃣کتابخونه‌های مورد استفاده:

HtmlAgilityPack
برای استخراج نرخ ارز از دل html دریافت شده از سایت اعلام نرخ.
(توی یک تگ table قرار دارد). تمام فرایند دریافت صفحه و استخراج مقادیر، در متد GetExchangeRatesAsync است.


Microsoft.SemanticKernel
Microsoft.SemanticKernel.Connectors.Ollama
برای استفاده از قابلیت‌های Semantic Kernel و همچنین اتصال به ollama برای استفاده از مدل‌هایی که روی ollama داریم. کرنل در حقیقت قلب و رابط بین کد ما و مدل‌های هوش مصنوعی است، کانکتورهای مختلف داره که به مدل‌های لوکال یا ابری متصل شه و کار متن (مثل چت) یا کارهای تولید عکس، صدا، و... رو با مدل‌ها انجام بده. استفاده ازش هم ساده است و اول کرنل رو تعریف، بعد هم پلاگین‌های مورد نیازمون رو بهش متصل و شروع به کار می‌کنیم. مثلا اینجا با دو خط کد به راحتی به ollama متصل می‌شه و از مدل llama3.2 با ۳ میلیارد پارامتر استفاده می‌شه کرد (مثلا چت کرد باهاش).
هم‌زمان با سی‌شارپ، semantic kernel برای پایتون و جاوا هم به‌صورت رسمی توسعه و منتشر می‌شه.

var builder = Kernel.CreateBuilder();
builder.AddOllamaChatCompletion(
    modelId: "llama3.2:3b",
    endpoint: new Uri("http://127.0.0.1:11434"));

Microsoft.KernelMemory
Microsoft.SemanticKernel.Plugins.Memory
برای افزودن قابلیت «حافظه» به semantic kernel یعنی دیتای خودمون رو داخل حافظه قرار بدیم و کرنل از اون دیتا در کنار دیتای مدل استفاده کنه. اینجا memory رو استفاده کردیم. ولی می‌تونیم از وکتور دیتابیس هم استفاده کنیم. البته این ساختارها (مموری یا وکتور دیتابیس) اینقدر عادی شدند که نیازی ندارید تا جزئیات فنی داخلی‌شون رو الزاما یاد بگیرید و مهم نحوه استفاده ازشون است. به بیان خیلی ساده شده، دیتا توی یک ماتریس قرار می‌گیره که مشابهت/قرابت سطر و ستون که هر کدوم یک کلمه می‌تونیم در نظر بگیریم با یک عدد مشخص می‌شه.

ایجاد مموری:

var embeddingGenerator = kernel.Services.GetRequiredService<ITextEmbeddingGenerationService>();

var memory = new SemanticTextMemory(new VolatileMemoryStore(), embeddingGenerator);

حالا ذخیره داده‌ها داخل مموری:

const string MemoryCollectionName = "exchangeRates";

string url = "https://bonbast.org";
var exchangeRates = await GetExchangeRatesAsync(url);

foreach (var rate in exchangeRates)
{
    string memoryKey = $"{rate.Key} to Iranian Rial";
    await memory.SaveInformationAsync(MemoryCollectionName, id: memoryKey, text: $"1 {rate.Key} equals {rate.Value.AverageRate} Iranian Tomans...");
}

TextMemoryPlugin memoryPlugin = new(memory);

kernel.ImportPluginFromObject(memoryPlugin);

فایل راهنما و توضیحات بیشتر در پست بعدی... لطفا اجرا کنید و یه مقدار باهاش سر و کله بزنید که پست‌های بعدی مفید باشن 😉 اگر مفید بود و کاربردی، بگید تا بریم سراغ وکتور یا دریافت ورودی خروجی ساختار یافته به جای متن...

💬 سوال؟ پیشنهاد؟
البته Memory Store قابلیت‌های کمتری نسبت به Vector Store داره و خیلی ابتدایی‌تره. توی اولین مثال از مموری استفاده کردم فقط تا حداکثر سادگی رو داشته باشه.