[بسم‌الله الرحمن الرحیم]

[عنوان:راهنمای جامع Streamlit با یک مثال کاربردی ]

[دانشگاه فردوسی مشهد - دانشکده مهندسی - گروه کامپیوتر]

[رشته: کارشناسی ارشد هوش مصنوعی]

[استاد راهنما: دکتر هادی صدوقی یزدی]

[نام دانشجو: اسماعیل برزگری]

[تاریخ: زمستان - 1404]

[آدرس ایمیل:] smailbarzegari@gmail.com

راهنمای جامع Streamlit با یک مثال کاربردی

۱. Streamlit چیست و چرا ساخته شد؟

یک فریمورک قدرتمند و متن‌باز پایتون است که در سال ۲۰۱۹ معرفی شد. فلسفه اصلی آن تبدیل سریع اسکریپت‌های پایتون به اپلیکیشن‌های وب تعاملی با کمترین میزان کدنویسی اضافی است.

مشکل: قبل از Streamlit، اگر یک دانشمند داده می‌خواست مدل خود را به دیگران نشان دهد، باید با فریمورک‌های سنتی مانند Flask یا Django کار می‌کرد که نیاز به دانش مسیریابی (Routing)، قالب‌های HTML و مدیریت درخواست‌ها داشت. این کار سرعت توسعه را به شدت کاهش می‌داد.

راه‌حل: Streamlit این فاصله را کاملاً از بین برد. شما کد پایتون خود را می‌نویسید و Streamlit به طور خودکار آن را به یک برنامه وب تبدیل می‌کند.

رابط کاربری Streamlit

رابط کاربری Streamlit ساده، تمیز و کاربرپسند طراحی شده است و شامل اجزای زیر می‌شود:

صفحه اصلی (Main Area)

بخش اصلی صفحه که محتوای اصلی اپلیکیشن در آن نمایش داده می‌شود. این بخش می‌تواند شامل موارد زیر باشد:

متن و عنوان:

عنوان‌های اصلی با فونت درشت
زیرعنوان‌ها و متن‌های معمولی
متن‌های فرمت‌دار با مارک‌داون

جدول‌ها و دیتافریم‌ها:

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

نمودارها:

نمودارهای تعاملی از کتابخانه Plotly
نمودارهای ایستا از Matplotlib و Seaborn
قابلیت بزرگنمایی، ذخیره و اشتراک‌گذاری

تصاویر و ویدیوها:

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

ویجت‌های خروجی:

متریک‌ها برای نمایش شاخص‌های کلیدی
متن‌های موفقیت، خطا، هشدار و اطلاع‌رسانی
باکس‌های برجسته برای نتایج مهم

یک نوار عمودی در سمت راست یا چپ صفحه که با st.sidebar ایجاد می‌شود. کاربردهای آن:

تنظیمات و کنترل‌ها:

قرار دادن ویجت‌های ورودی مانند اسلایدر و سلکت‌باکس
دسترسی سریع به پارامترهای قابل تنظیم
کاهش شلوغی صفحه اصلی

فیلترها:

فیلتر کردن داده‌ها بر اساس پارامترهای مختلف
انتخاب محدوده تاریخ، محدوده عددی و دسته‌بندی‌ها
اعمال همزمان چند فیلتر

ناوبری:

دسترسی سریع به بخش‌های مختلف برنامه
منوی کشویی برای صفحات متعدد
دکمه‌های بازگشت و جلو

اطلاعات جانبی:

نمایش راهنما و توضیحات
آمار کلی و خلاصه داده‌ها
اطلاعات تماس و پشتیبانی

ویجت‌های تعاملی (Interactive Widgets)

مجموعه‌ای از عناصر کنترلی که کاربر می‌تواند با آنها تعامل کند:

ویجت‌های ورودی:

ویجت	کاربرد	ویژگی‌ها
دکمه (Button)	اجرای عملیات با کلیک	رنگ‌های مختلف، عرض کامل، افکت hover
اسلایدر (Slider)	انتخاب مقادیر عددی با کشیدن	محدوده دلخواه، گام قابل تنظیم، نمایش مقدار
انتخابگر (Selectbox)	انتخاب یک گزینه از لیست کشویی	جستجو در گزینه‌ها، placeholder
انتخاب چندگانه (Multiselect)	انتخاب چند گزینه	نمایش تعداد انتخاب‌ها، حذف تکی
ورودی عددی (Number Input)	وارد کردن عدد با کلیدهای بالا/پایین	محدوده مجاز، گام افزایش
چک‌باکس (Checkbox)	فعال/غیرفعال کردن گزینه‌ها	وضعیت پیش‌فرض، برچسب
رادیو باتن (Radio)	انتخاب یک گزینه از چند گزینه	چیدمان افقی/عمودی
آپلود فایل (File Uploader)	بارگذاری فایل از سیستم کاربر	محدودیت نوع فایل، حجم، چندتایی
ورودی متن (Text Input)	دریافت متن از کاربر	placeholder، حداکثر طول
ورودی تاریخ (Date Input)	انتخاب تاریخ	تقویم تعاملی، محدوده مجاز
ورودی زمان (Time Input)	انتخاب ساعت	دقت تا ثانیه

ویجت‌های خروجی:

ویجت	کاربرد	ویژگی‌ها
متریک (Metric)	نمایش شاخص‌های کلیدی	مقدار اصلی، تغییرات، رنگ
پیشرفت (Progress)	نمایش درصد پیشرفت عملیات	به‌روزرسانی دینامیک
پیام موفقیت (Success)	تأیید انجام عملیات	پس‌زمینه سبز، علامت ✅
پیام خطا (Error)	نمایش خطا	پس‌زمینه قرمز، علامت ❌
پیام هشدار (Warning)	هشدار به کاربر	پس‌زمینه زرد، علامت ⚠️
پیام اطلاعات (Info)	اطلاع‌رسانی عمومی	پس‌زمینه آبی، علامت ℹ️
اکسپندر (Expander)	محتوای بازشونده	پیش‌فرض بسته/باز
کد (Code)	نمایش کد با هایلایت	زبان برنامه‌نویسی، شماره خط

چیدمان و صفحه‌آرایی (Layout)

ابزارهای چیدمان برای سازماندهی محتوا:

ستون‌ها (Columns):

تقسیم صفحه به ستون‌های عمودی
نسبت‌های قابل تنظیم (مثلاً [1,2,1])
تطبیق خودکار با اندازه صفحه
امکان تو در تو کردن ستون‌ها

تب‌ها (Tabs):

دسته‌بندی محتوا در برگه‌های مجزا
برچسب‌های متنی و شکلکی
تغییر محتوا بدون بارگذاری مجدد صفحه
مناسب برای محتوای زیاد

کانتینر (Container):

گروه‌بندی المان‌ها در یک کادر
حاشیه و پس‌زمینه قابل تنظیم
کنترل روی نمایش/عدم نمایش گروهی

خط جداکننده (Divider):

جداسازی بخش‌ها با خط افقی
ضخامت و رنگ قابل تنظیم
فاصله‌گذاری بصری

فضای خالی (Empty Space):

ایجاد فاصله بین المان‌ها
تنظیم ارتفاع دقیق
بهبود تعادل بصری

عناصر وضعیت (Status Elements)

اسپینر (Spinner):

نمایش در حال اجرا بودن عملیات
متن دلخواه در کنار اسپینر
غیرفعال شدن خودکار پس از اتمام

نوار پیشرفت (Progress Bar):

نمایش درصد تکمیل فرآیند
به‌روزرسانی بلادرنگ
رنگ سبز برای تکمیل

وضعیت (Status):

نمایش مراحل انجام کار
وضعیت‌های pending, complete, error
جزئیات قابل توسعه

بالون (Balloons):

انیمیشن بادکنک‌های رنگی
جشن برای موفقیت
افزایش رضایت کاربر

برفک (Snow):

انیمیشن برف
جلوه ویژه برای مناسبت‌ها
ایجاد حس خوب

نوار بالایی (Top Bar)

منوی همبرگری (Hamburger Menu):

دسترسی به راهنما
گزارش خطا
درباره برنامه
تنظیمات پیشرفته

وضعیت اتصال:

نمایش اتصال به سرور
وضعیت آنلاین/آفلاین
زمان پاسخگویی

دکمه اجرای مجدد:

Re-run برنامه
به‌روزرسانی دستی
پاکسازی کش

ویژگی‌های کلیدی رابط کاربری Streamlit

واکنش‌گرا (Responsive):

تطبیق با اندازه صفحه نمایش
چیدمان مناسب در موبایل و تبلت
تغییر ستون‌بندی در صفحات کوچک

تعاملی (Interactive):

هر تغییر توسط کاربر بلافاصله اعمال می‌شود
بدون نیاز به دکمه ثبت یا تأیید
بازخورد فوری برای هر کنش

ساده و مینیمال:

بدون شلوغی و پیچیدگی غیرضروری
تمرکز بر محتوای اصلی
کاهش حواس‌پرتی کاربر

یکپارچه:

همه ویجت‌ها ظاهر هماهنگی دارند
طراحی یکسان در کل برنامه
تجربه کاربری منسجم

سفارشی‌پذیر:

امکان تغییر ظاهر با CSS
استایل‌دهی المان‌ها
برندینگ شخصی

سریع:

بارگذاری سریع صفحه
پاسخگویی آنی به تعاملات
بهینه‌سازی شده برای عملکرد

تجربه کاربری (User Experience)

بازخورد فوری:

هر کلیک نتیجه دارد
نمایش پیشرفت عملیات
پیام‌های تأیید و خطا

راهنمای شناور:

توضیحات روی ویجت‌ها
راهنمای استفاده
محدوده مجاز ورودی

اعتبارسنجی:

بررسی خودکار ورودی‌ها
هشدار قبل از خطا
غیرفعال کردن دکمه‌ها در شرایط نامناسب

دسترسی (Accessibility):

پشتیبانی از صفحه‌خوان‌ها
کنتراست مناسب رنگ‌ها
ناوبری با صفحه‌کلید

مزایای رابط کاربری Streamlit

سرعت توسعه: ایجاد رابط کاربری حرفه‌ای در چند دقیقه
سهولت استفاده: بدون نیاز به دانش HTML و CSS
تعامل غنی: ویجت‌های متنوع برای هر نیاز
زیبایی بصری: طراحی مدرن و جذاب
یکپارچگی با پایتون: استفاده مستقیم از متغیرها و توابع
جامعه بزرگ: منابع آموزشی و قالب‌های آماده
قابلیت گسترش: امکان اضافه کردن کامپوننت‌های سفارشی

این رابط کاربری ساده اما قدرتمند، دلیل اصلی محبوبیت Streamlit در بین دانشمندان داده و تحلیلگران است، زیرا بدون درگیر شدن با پیچیدگی‌های HTML و CSS، می‌توانند اپلیکیشن‌های کاربردی و زیبا بسازند.

۲. ویژگی‌ها و مزایای کلیدی

✅ توسعه مبتنی بر اسکریپت (پایتون خالص)
کل برنامه یک فایل .py است. هر بار که فایل را ذخیره می‌کنید، برنامه به طور خودکار در مرورگر به‌روزرسانی می‌شود (Hot-reloading).

✅ ویجت‌های تعاملی داخلی
انبوهی از ویجت‌های آماده مانند اسلایدر، دکمه، باکس انتخاب، آپلود فایل و… در اختیار دارید. بدون نوشتن جاوااسکریپت، این ویجت‌ها با برنامه شما تعامل دارند.

✅ معماری واکنش‌گرا (Reactive Execution)
قلب Streamlit در این ویژگی نهفته است. به محض اینکه کاربر با یک ویجت (مثلاً اسلایدر) تعامل کند، کل اسکریپت از بالا به پایین دوباره اجرا (Rerun) می‌شود. این مدل ساده‌سازی شده، کدنویسی را بسیار شهودی می‌کند.

✅ ذخیره‌سازی (Caching) هوشمند
آیا نگران کند شدن برنامه به خاطر اجرای مجدد هستید؟ با دکوراتورهای @st.cache_data و @st.cache_resource می‌توان عملیات سنگین (مثل لود دیتاست ۱۰۰ مگابایتی یا لود مدل یادگیری ماشین) را فقط یک بار انجام داد و درخواست‌های بعدی را سریع پاسخ داد.

✅ سازگاری کامل با اکوسیستم داده
شما همچنان از کتابخانه‌های همیشگی خود استفاده می‌کنید: pandas برای دیتافریم، matplotlib، plotly، seaborn و Altair برای رسم نمودار و scikit-learn یا PyTorch برای مدل.

✅ استقرار آسان
اپلیکیشن شما را می‌توان با یک کلیک روی Streamlit Community Cloud به صورت رایگان منتشر کرد یا در داکر و سرورهای اختصاصی مستقر نمود.

۳. محدودیت‌ها و نقاط ضعف

❌ سرعت در برنامه‌های بزرگ
مدل اجرای مجدد کامل اسکریپت، برای اپلیکیشن‌های بسیار بزرگ و پیچیده می‌تواند کند باشد.

❌ مدیریت حالت (State Management) پیچیده
برای انتقال متغیرها بین اجراهای مختلف باید از st.session_state استفاده کرد. این کار در پروژه‌های خیلی پیچیده نسبت به فریمورک‌هایی مثل Reflex یا Dash، دستی و نیازمند دقت بیشتری است.

❌ محدودیت در شخصی‌سازی ظاهر
تمامی اپلیکیشن‌های Streamlit تقریبا شبیه هم هستند. برای تغییر اساسی ظاهر (Custom UI) باید CSS بنویسید که برخلاف فلسفه اصلی آن است.

❌ عدم تعامل عمیق (True Interactivity)
در Streamlit نمی‌توان یک نمودار را به عنوان ورودی برای نمودار دیگر قرار داد. هر کلیک باعث رفرش کامل صفحه می‌شود، نه به‌روزرسانی جزئی.

۴. کاربردهای اصلی Streamlit

پروتوتایپ سریع (Proof of Concept): تبدیل یک ایده یا نوت‌بوک جیپینتر به یک دموی زنده در عرض ۳۰ دقیقه.
داشبوردهای سازمانی ساده: نمایش شاخص‌های کلیدی عملکرد (KPI) و مصورسازی داده.
اپلیکیشن‌های یادگیری ماشین: طبقه‌بندی، تشخیص چهره، پردازش متن (NLP) و…
ویرایشگر داده: اتصال به دیتابیس (مثل Snowflake) و ویرایش مستقیم رکوردها.
تحلیل فایل: آپلود اکسل یا CSV و دریافت گزارش آنی.

۵. مثال‌ عملی (کد اجرایی در پیوست می آید)

تشریح کامل بخش‌های مختلف برنامه (سیستم طبقه‌بندی گونه پنگوئن)

فهرست مطالب

کتابخانه‌ها و ماژول‌های استفاده شده
تنظیمات صفحه
استایل‌دهی با CSS سفارشی
توابع کمکی
مدیریت Session State
بارگذاری داده
عنوان و هدر
سایدبار - پنل تنظیمات
تب‌ها و نمایش داده
آموزش مدل
ارزیابی مدل
پیش‌بینی تعاملی
نمایش کد منبع
فوتر
مدیریت حافظه و Cache
مدیریت خطا
تعاملات و رویدادها
جریان کلی برنامه
مفاهیم کلیدی Streamlit
نکات حرفه‌ای و بهینه‌سازی

۱. کتابخانه‌ها و ماژول‌های استفاده شده

برنامه از چند دسته کتابخانه مختلف استفاده می‌کند که هر کدام نقش مشخصی دارند:

دسته اول - کتابخانه‌های اصلی:

Streamlit: فریمورک اصلی برای ساخت رابط کاربری وب. تمام ویجت‌ها، صفحات و تعاملات توسط این کتابخانه مدیریت می‌شود. این کتابخانه قلب تپنده برنامه است و امکان تبدیل کد پایتون به اپلیکیشن وب را فراهم می‌کند.
Pandas: برای کار با دیتافریم، انتخاب ستون‌ها، فیلتر کردن داده و نمایش جدولی اطلاعات. این کتابخانه ساختار اصلی داده‌ها را در قالب DataFrame نگهداری می‌کند و عملیات‌های مختلف مانند انتخاب ستون، حذف مقادیر گمشده و آمار توصیفی را ممکن می‌سازد.
NumPy: برای محاسبات عددی و عملیات ماتریسی در پشت صحنه. اگرچه مستقیماً در کد دیده نمی‌شود، اما بسیاری از کتابخانه‌های دیگر مانند pandas و scikit-learn بر پایه آن ساخته شده‌اند.

دسته دوم - کتابخانه‌های یادگیری ماشین:

Scikit-learn: کامل‌ترین کتابخانه یادگیری ماشین در پایتون که تقریباً تمام نیازهای این برنامه را پوشش می‌دهد. این کتابخانه شامل:
- مدل‌های طبقه‌بندی (Classification)
- پیش‌پردازش‌گرها (Preprocessing)
- تقسیم‌کننده‌های داده (Data Splitting)
- معیارهای ارزیابی (Evaluation Metrics)
- پایپلاین (Pipeline)
مدل‌های استفاده شده:
- رگرسیون لجستیک (LogisticRegression) : یک مدل خطی ساده و سریع که برای مسائل طبقه‌بندی دودویی و چندکلاسه مناسب است. در این برنامه به عنوان گزینه پیش‌فرض انتخاب شده است.
- جنگل تصادفی (RandomForestClassifier) : یک مدل ensemble مبتنی بر درخت تصمیم که با ترکیب چندین درخت، دقت بالاتر و مقاومت بیشتری در برابر overfitting دارد.
- SVM (Support Vector Machine) : مدلی که با یافتن ابرصفحه بهینه، کلاس‌ها را از هم جدا می‌کند. برای داده‌های با ابعاد بالا مؤثر است.
- گرادیان بوستینگ (GradientBoostingClassifier) : مدل ensemble پیشرفته‌ای که به صورت تدریجی مدل‌های ضعیف را ترکیب می‌کند و دقت بسیار بالایی دارد.
- KNN (K-Nearest Neighbors) : مدلی مبتنی بر فاصله که نمونه جدید را بر اساس نزدیک‌ترین همسایگانش طبقه‌بندی می‌کند.

دسته سوم - کتابخانه‌های مصورسازی:

Seaborn: برای بارگذاری دیتاست آماده پنگوئن. این کتابخانه چندین دیتاست کلاسیک برای یادگیری ماشین را در خود دارد که پنگوئن یکی از معروف‌ترین آنهاست.
Plotly: قدرتمندترین کتابخانه برای نمودارهای تعاملی. تفاوت اصلی آن با matplotlib در تعاملی بودن است. کاربر می‌تواند:
- روی نمودار زوم کند
- نقاط را انتخاب کند
- راهنمای متغیرها را ببیند
- نمودار را به فرمت PNG ذخیره کند
Plotly Express: رابط سطح بالای plotly برای رسم سریع نمودارها
Plotly Graph Objects: رابط سطح پایین برای تنظیمات پیشرفته

دسته چهارم - کتابخانه‌های کمکی:

datetime: برای ثبت زمان بارگذاری داده و زمان آموزش مدل. این زمان‌ها به کاربر نشان داده می‌شود و در متادیتای داده ذخیره می‌گردد.
hashlib: برای تولید شناسه یکتا برای هر سشن کاربر. این شناسه در فوتر نمایش داده می‌شود و به رهگیری خطاها کمک می‌کند.
time: برای اندازه‌گیری دقیق زمان آموزش مدل و نمایش آن به کاربر.
json: برای ذخیره و بازیابی تنظیمات و تاریخچه (در نسخه‌های پیشرفته‌تر).

۲. تنظیمات صفحه

این بخش در ابتدای برنامه قرار می‌گیرد و مشخصات کلی اپلیکیشن را تعیین می‌کند. این تنظیمات باید پیش از هر دستور Streamlit دیگر اجرا شوند.

تنظیمات اصلی:

عنوان صفحه (page_title) : “🐧 سیستم شناسایی پنگوئن Palmer Station”
- این عنوان در تب مرورگر نمایش داده می‌شود
- به کاربر کمک می‌کند برنامه را در بین چند تب باز شده تشخیص دهد
- وجود شکلک پنگوئن باعث جذابیت بصری می‌شود
آیکون صفحه (page_icon) : “🐧”
- در کنار عنوان در تب مرورگر نمایش داده می‌شود
- در بوکمارک‌ها و تاریخچه مرورگر نیز دیده می‌شود
- هویت بصری برنامه را تقویت می‌کند
نوع چیدمان (layout) : “wide”
- حالت پیش‌فرض Streamlit “center” است که محتوا را در یک ستون باریک وسط صفحه قرار می‌دهد
- حالت “wide” از تمام عرض صفحه استفاده می‌کند
- برای برنامه‌هایی که جدول و نمودار دارند، انتخاب بهتری است
- امکان چیدمان دو ستونی و سه ستونی را بهتر فراهم می‌کند
وضعیت سایدبار (initial_sidebar_state) : “expanded”
- “expanded”: سایدبار باز نمایش داده می‌شود
- “collapsed”: سایدبار بسته است و کاربر باید روی آیکون کلیک کند
- “auto”: بسته به اندازه صفحه نمایش تصمیم می‌گیرد
- انتخاب expanded به این دلیل است که کاربر بلافاصله تنظیمات را ببیند
منوی راهنما (menu_items) :
- Get Help: لینک به مستندات Streamlit یا مخزن گیت‌هاب پروژه
- Report a bug: لینک به صفحه ثبت خطا
- About: توضیح کوتاه درباره برنامه با قابلیت مارک‌داون
- این منو در گوشه سمت راست بالای صفحه و با آیکون ≡ قابل دسترسی است

چرا این تنظیمات مهم است؟ این تنظیمات اولین چیزی است که کاربر تجربه می‌کند و تأثیر زیادی در اولین برداشت دارد. همچنین بر نحوه نمایش محتوا و دسترسی به بخش‌های مختلف تأثیر می‌گذارد.

۳. استایل‌دهی با CSS سفارشی

Streamlit ظاهر ساده و یکنواختی دارد. برای متمایز کردن برنامه و بهبود تجربه کاربری، از CSS سفارشی استفاده می‌شود. این استایل‌ها از طریق تابع st.markdown با پارامتر unsafe_allow_html=True به صفحه تزریق می‌شوند.

المان‌های استایل‌دهی شده:

۳.۱ هدر اصلی (.main-header):

اندازه فونت: ۲.۵ رم (بزرگتر از عنوان معمولی)
رنگ متن: آبی (#1E88E5)
هم‌ترازی: وسط‌چین
حاشیه داخلی: ۱ رم در همه جهات
پس‌زمینه: گرادیانت خطی از آبی روشن (E3F2FD) به آبی کمی تیره‌تر (BBDEFB)
حاشیه گرد: ۱۰ پیکسل
حاشیه پایین: ۲ رم برای فاصله از محتوای بعدی

۳.۲ کارت متریک (.metric-card):

پس‌زمینه: خاکستری بسیار روشن (#f8f9fa)
حاشیه داخلی: ۱ رم
حاشیه گرد: ۱۰ پیکسل
سایه: ۲ پیکسل افقی، ۴ پیکسل عمودی، ۰.۱ کدورت
کاربرد: نمایش KPIها مانند دقت مدل، تعداد نمونه و…

۳.۳ باکس پیش‌بینی (.prediction-box):

پس‌زمینه: سبز بسیار روشن (#e8f5e9)
حاشیه داخلی: ۲ رم
حاشیه گرد: ۱۵ پیکسل
حاشیه چپ: ۵ پیکسل سبز تیره (#4CAF50)
حاشیه بالا/پایین/راست: ۱ رم
کاربرد: برجسته‌سازی نتیجه پیش‌بینی

۳.۴ دکمه (.stButton>button):

پس‌زمینه: آبی (#1E88E5)
رنگ متن: سفید
وزن قلم: bold
حاشیه گرد: ۱۰ پیکسل
حاشیه داخلی: ۰.۵ رم بالا/پایین، ۲ رم چپ/راست
بدون حاشیه (border: none)
افکت hover:
- پس‌زمینه تیره‌تر (#1565C0)
- سایه بزرگتر (۰ ۴px ۸px با ۰.۲ کدورت)
- انتقال نرم در ۰.۳ ثانیه

محدودیت‌ها و نکات:

استایل‌دهی در Streamlit محدودیت‌هایی دارد
برخی کلاس‌ها ممکن است در نسخه‌های بعدی تغییر کنند
توصیه می‌شود از انتخابگرهای ساده استفاده شود
استایل‌دهی بیش از حد می‌تواند سرعت بارگذاری را کاهش دهد

۴. توابع کمکی

برنامه شامل چندین تابع کمکی است که هر کدام وظیفه مشخص و مستقلی دارند. این توابع با دکوراتورهای @st.cache_data و @st.cache_resource مزین شده‌اند تا از اجرای مجدد غیرضروری جلوگیری شود.

۴.۱ تابع بارگذاری داده (load_penguin_data):

این تابع قلب بخش داده‌های برنامه است و مسئولیت بارگذاری و پیش‌پردازش دیتاست پنگوئن را بر عهده دارد.

مراحل اجرا:

بارگذاری: با استفاده از sns.load_dataset("penguins") داده از مخزن seaborn خوانده می‌شود.
پاکسازی: dropna() تمام رکوردهای دارای مقدار گمشده را حذف می‌کند. این کار ضروری است زیرا مدل‌های یادگیری ماشین نمی‌توانند با مقادیر NaN کار کنند.
تبدیل: ستون “species” که شامل نام گونه‌ها به صورت رشته است، به اعداد صحیح (0،1،2) تبدیل می‌شود. این فرآیند “Encoding” نام دارد.
ذخیره متادیتا: اطلاعات اضافی مانند زمان بارگذاری، منبع داده و تعداد رکوردهای حذف شده در df.attrs ذخیره می‌شود.
بازگشت: دیتافریم نهایی به برنامه برگردانده می‌شود.

ویژگی‌های مهم:

کشینگ: دکوراتور @st.cache_data باعث می‌شود این تابع فقط یک بار اجرا شود و نتیجه در حافظه کش ذخیره گردد.
مدیریت خطا: با try-except خطاهای احتمالی (مثل قطع اینترنت) مدیریت می‌شوند.
TTL: تنظیم ttl=3600 باعث می‌شود کش هر ساعت یک بار به‌روزرسانی شود.

۴.۲ تابع ایجاد پایپلاین (create_pipeline):

این تابع بر اساس الگوریتم انتخابی کاربر، یک پایپلاین یادگیری ماشین می‌سازد.

اجزای پایپلاین:

StandardScaler: مرحله پیش‌پردازش که ویژگی‌ها را استاندارد می‌کند:
- میانگین را به صفر می‌رساند
- واریانس را به یک می‌رساند
- برای مدل‌هایی مثل SVM و رگرسیون لجستیک ضروری است
Classifier: مرحله طبقه‌بندی که مدل اصلی است.

پارامترهای قابل بهینه‌سازی برای هر مدل:

رگرسیون لجستیک:
- C: پارامتر منظم‌سازی (0.01, 0.1, 1, 10)
- solver: الگوریتم بهینه‌سازی (lbfgs, liblinear)
جنگل تصادفی:
- n_estimators: تعداد درخت‌ها (50, 100, 200)
- max_depth: حداکثر عمق درخت (5, 10, None)
- min_samples_split: حداقل نمونه برای تقسیم (2, 5, 10)
SVM:
- C: پارامتر جریمه (0.1, 1, 10)
- kernel: نوع هسته (rbf, poly)
- gamma: ضریب هسته (scale, auto)
گرادیان بوستینگ:
- n_estimators: تعداد مرحله‌ها (50, 100)
- learning_rate: نرخ یادگیری (0.01, 0.1, 0.2)
- max_depth: عمق درخت (3, 5)
KNN:
- n_neighbors: تعداد همسایگان (3, 5, 7, 9)
- weights: وزن‌دهی (uniform, distance)

۴.۳ تابع آموزش و ارزیابی (train_and_evaluate):

این تابع عملیات اصلی آموزش مدل را انجام می‌دهد.

ورودی‌ها:

داده آموزش (X_train, y_train)
داده تست (X_test, y_test)
نام الگوریتم
وضعیت GridSearch

خروجی‌ها:

مدل آموزش دیده
دیکشنری معیارهای ارزیابی
پیش‌بینی‌ها
احتمالات (در صورت وجود)
بهترین پارامترها

فرآیند:

ایجاد پایپلاین با الگوریتم انتخاب شده
اگر GridSearch فعال باشد: جستجوی ترکیب پارامترها با Cross-Validation
آموزش مدل نهایی
پیش‌بینی روی داده تست
محاسبه معیارهای ارزیابی
بازگشت نتایج

۵. مدیریت Session State

Session State یکی از مهم‌ترین مفاهیم در Streamlit است. درک صحیح آن برای نوشتن اپلیکیشن‌های حرفه‌ای ضروری است.

چرا Session State ضروری است؟

Streamlit یک معماری واکنش‌گرا دارد. هر بار که کاربر با ویجتی تعامل می‌کند (مثل جابجا کردن اسلایدر یا کلیک روی دکمه)، کل اسکریپت از اول تا انتها دوباره اجرا می‌شود. این یعنی تمام متغیرهای محلی از بین می‌روند و دوباره ساخته می‌شوند.

بدون Session State:

مدل آموزش دیده پس از هر تعامل ناپدید می‌شود
تاریخچه پیش‌بینی‌ها حفظ نمی‌شود
تنظیمات کاربر ریست می‌شود
تجربه کاربری بسیار ضعیف می‌شود

مقادیر ذخیره شده در Session State:

۵.۱ شناسه سشن (session_id):

یک رشته هش شده از زمان جاری
برای هر کاربر منحصر‌به‌فرد است
در فوتر نمایش داده می‌شود
کاربرد: رهگیری خطاها، تحلیل رفتار کاربر

۵.۲ مدل آموزش دیده (model):

مهم‌ترین آیتم در Session State
پس از آموزش ذخیره می‌شود
در تب پیش‌بینی استفاده می‌شود
تا زمانی که کاربر برنامه را نبندد، حفظ می‌شود

۵.۳ اسکیلر (scaler):

شیء استانداردساز آموزش دیده
برای تبدیل داده‌های جدید ضروری است
همراه مدل ذخیره می‌شود

۵.۴ ویژگی‌های انتخاب شده (features):

لیست ستون‌هایی که کاربر انتخاب کرده
هم در آموزش و هم در پیش‌بینی استفاده می‌شود
باید بین مدل و پیش‌بینی یکسان باشد

۵.۵ معیارهای ارزیابی (metrics):

دیکشنری شامل accuracy, precision, recall, f1
در تب آموزش نمایش داده می‌شود
برای مقایسه مدل‌ها استفاده می‌شود

۵.۶ تاریخچه آموزش (training_history):

لیست تمام مدل‌های آموزش داده شده
هر آیتم شامل: زمان، الگوریتم، دقت، F1-score
امکان مقایسه مدل‌های مختلف

۵.۷ تاریخچه پیش‌بینی (predictions):

لیست ۱۰ پیش‌بینی آخر
شامل زمان، مقادیر ورودی، نتیجه
در انتهای تب پیش‌بینی نمایش داده می‌شود

۵.۸ تنظیمات کاربر:

الگوریتم انتخاب شده
درصد داده تست
وضعیت GridSearch
حالت تاریک/روشن

روش‌های مقداردهی:

روش اول - بررسی وجود کلید:

if 'model' not in st.session_state:
    st.session_state.model = None

روش دوم - استفاده از setdefault:

st.session_state.setdefault('predictions', [])

روش سوم - تابع مقداردهی اولیه:

def init_session_state():
    defaults = {'model': None, 'scaler': None, ...}
    for key, value in defaults.items():
        if key not in st.session_state:
            st.session_state[key] = value

۶. بارگذاری داده

بخش بارگذاری داده وظیفه خواندن، پاکسازی و آماده‌سازی دیتاست پنگوئن را بر عهده دارد.

مشخصات دیتاست:

۶.۱ منبع داده:

نام: Palmer Penguins Dataset
منتشرکننده: Dr. Kristen Gorman
سال: ۲۰۲۰
مکان: ایستگاه تحقیقاتی Palmer، قطب جنوب
لایسنس: CC0 (دامنه عمومی)
هدف: جایگزین برای دیتاست کلاسیک Iris

۶.۲ آمار کلی:

تعداد کل رکوردها: ۳۴۴ نمونه
تعداد ویژگی‌ها: ۷ ویژگی اصلی
تعداد کلاس‌ها: ۳ گونه
مقادیر گمشده: ۱۱ نمونه (حدود ۳٪)

۶.۳ گونه‌های پنگوئن:

کد	نام گونه	نام علمی	تعداد نمونه
۰	Adelie	Pygoscelis adeliae	۱۵۲
۱	Chinstrap	Pygoscelis antarcticus	۶۸
۲	Gentoo	Pygoscelis papua	۱۲۴

ویژگی‌های ظاهری:

Adelie: کوچکترین گونه، منقار کاملاً سیاه
Chinstrap: نوار سیاه زیر چانه
Gentoo: لکه سفید بالای چشم، منقار نارنجی-قرمز

۶.۴ ویژگی‌های فیزیکی:

ویژگی	محدوده	میانگین	واحد	توضیح
bill_length_mm	۳۲.۱ - ۵۹.۶	۴۳.۹	میلی‌متر	طول نوک از پایه تا نوک
bill_depth_mm	۱۳.۱ - ۲۱.۵	۱۷.۲	میلی‌متر	ضخامت نوک در پایه
flipper_length_mm	۱۷۲ - ۲۳۱	۲۰۰.۹	میلی‌متر	طول بالچه
body_mass_g	۲۷۰۰ - ۶۳۰۰	۴۲۰۲	گرم	وزن بدن

۶.۵ ویژگی‌های دسته‌بندی:

جزیره (island): ۳ مقدار (Biscoe, Dream, Torgersen)
جنسیت (sex): ۲ مقدار (Male, Female)
گونه (species): ۳ مقدار (هدف پیش‌بینی)

۶.۶ فرآیند بارگذاری:

مرحله ۱ - بارگذاری: داده از مخزن آنلاین seaborn دانلود می‌شود. این مخزن شامل چندین دیتاست کلاسیک است.

مرحله ۲ - پاکسازی:

شناسایی ردیف‌های حاوی NaN
حذف آنها با dropna()
ثبت تعداد ردیف‌های حذف شده

مرحله ۳ - تبدیل:

ستون species به کد عددی تبدیل می‌شود
ستون island و sex نیز برای استفاده‌های آینده کدگذاری می‌شوند

مرحله ۴ - ذخیره متادیتا: اطلاعات زیر در df.attrs ذخیره می‌شود:

loaded_at: زمان دقیق بارگذاری
source: منبع داده
dropped_rows: تعداد ردیف‌های حذف شده

مرحله ۵ - کشینگ: دکوراتور @st.cache_data با پارامترهای:

ttl=3600: اعتبار کش ۱ ساعت
show_spinner: نمایش پیام “در حال بارگذاری…”

۷. عنوان و هدر

بخش ابتدایی صفحه که کاربر بلافاصله پس از بارگذاری برنامه می‌بیند.

۷.۱ عنوان اصلی: عنوان با استایل CSS سفارشی و به صورت “سیستم هوشمند شناسایی گونه پنگوئن - ایستگاه پالمر” نمایش داده می‌شود.

عناصر بصری:

شکلک پنگوئن (🐧) در ابتدای عنوان
گرادیانت آبی در پس‌زمینه
حاشیه‌های گرد
سایه نرم

۷.۲ باکس توضیحات: یک کادر خاکستری رنگ که شامل:

معرفی اپلیکیشن:

توضیح کوتاه درباره کاربرد سیستم
اشاره به ایستگاه تحقیقاتی پالمر
ذکر قابلیت اصلی (پیش‌بینی گونه)

اطلاعات فنی:

شناسه سشن: یک کد یکتا برای هر کاربر
آخرین بروزرسانی: زمان بارگذاری دیتاست
تعداد مدل‌های قابل انتخاب: ۵ الگوریتم

هدف از این بخش:

ایجاد اعتماد در کاربر
نشان دادن حرفه‌ای بودن برنامه
ارائه اطلاعات زمینه‌ای درباره داده‌ها
شخصی‌سازی تجربه کاربری با شناسه سشن

۸. سایدبار - پنل تنظیمات

سایدبار مهم‌ترین بخش تعاملی برنامه است که در سمت راست صفحه (یا چپ در نسخه فارسی) قرار می‌گیرد.

۸.۱ تصویر هدر: یک تصویر از پنگوئن‌های سه گونه مختلف که از مستندات رسمی دیتاست پالمر گرفته شده است. این تصویر:

هویت بصری برنامه را تقویت می‌کند
فضای غیررسمی و دوستانه ایجاد می‌کند
به یادماندنی‌تر شدن برنامه کمک می‌کند

۸.۲ انتخاب ویژگی‌ها (Multiselect):

نوع ویجت: st.multiselect

گزینه‌ها:

bill_length_mm (طول نوک)
bill_depth_mm (عمق نوک)
flipper_length_mm (طول بالچه)
body_mass_g (وزن)

مقادیر پیش‌فرض: هر چهار ویژگی

اعتبارسنجی:

حداقل ۲ ویژگی باید انتخاب شود
در غیر این صورت دکمه آموزش غیرفعال می‌شود
پیام هشدار نمایش داده می‌شود

راهنمای شناور (Tooltip): “ویژگی‌های فیزیکی برای آموزش مدل - حداقل ۲ ویژگی انتخاب کنید”

۸.۳ تنظیمات مدل:

انتخاب الگوریتم (Selectbox):

گزینه‌ها: رگرسیون لجستیک، جنگل تصادفی، SVM، گرادیان بوستینگ، KNN
پیش‌فرض: رگرسیون لجستیک (سریع و قابل اعتماد)
راهنما: توضیح مختصر درباره هر الگوریتم

درصد داده تست (Slider):

محدوده: ۱۰٪ تا ۴۰٪
پیش‌فرض: ۲۰٪
گام: ۵٪
فرمت: درصد (بدون اعشار)
راهنما: “درصد داده‌ای که برای ارزیابی مدل کنار گذاشته می‌شود”

بهینه‌سازی خودکار (Checkbox):

برچسب: “🔍 بهینه‌سازی خودکار (Grid Search)”
پیش‌فرض: غیرفعال
توضیح: جستجوی خودکار بهترین پارامترها
هشدار: زمان اجرا را افزایش می‌دهد

۸.۴ تنظیمات ظاهری:

حالت تاریک (Checkbox):

برچسب: “🌙 حالت تاریک”
تأثیر: تغییر تم برنامه
پیاده‌سازی: نیاز به CSS اضافی

نمایش کد (Checkbox):

برچسب: “📝 نمایش کد”
تأثیر: نمایش کد منبع در انتهای صفحه
کاربرد: اهداف آموزشی

۸.۵ دکمه آموزش:

ویژگی‌های بصری:

نوع: primary (آبی)
عرض: کامل (use_container_width=True)
متن: “🚀 شروع آموزش مدل”
حالت: disabled در صورت عدم انتخاب ویژگی کافی

شرط فعال‌سازی:

disabled = len(selected_features) < 2

۸.۶ آمار کلی:

کارت‌های متریک:

تعداد نمونه: کل رکوردهای دیتاست
ویژگی‌ها: تعداد ستون‌های عددی
گونه‌ها: تعداد کلاس‌های هدف
جزایر: تعداد جزایر نمونه‌برداری

هشدار مقادیر گمشده:

اگر رکوردی حذف شده باشد
نمایش تعداد با آیکون ⚠️
متن کوچک (caption)

۸.۷ فوتر سایدبار:

نام پروژه: “🐧 Palmer Penguins”
نسخه: “v1.0.0”
کپی‌رایت: “© 2026 - Antarctic Research”
فاصله از محتوای اصلی با divider

۹. تب‌ها و نمایش داده

برنامه از چهار تب اصلی برای سازماندهی محتوای خود استفاده می‌کند. این تب‌ها با st.tabs ایجاد شده‌اند.

۹.۱ تب اول: داده‌ها و آمار

این تب به سه بخش اصلی تقسیم می‌شود:

بخش A - نمایش نمونه داده‌ها:

هدف: آشنایی سریع کاربر با ساختار داده
تعداد رکورد: ۱۰ نمونه اول
ستون‌ها: فقط ویژگی‌های انتخاب شده توسط کاربر
فرمت‌بندی:
- اعداد میلی‌متر: یک رقم اعشار
- وزن: عدد صحیح
- نام فارسی ستون‌ها

بخش B - اطلاعات دیتاست:

قالب: جدول کوچک دو ستونه
سطرها:
- منبع داده (Palmer Station)
- تاریخ بارگذاری
- تعداد رکوردها
- تعداد ویژگی‌ها

بخش C - آمار توصیفی:

ستون راست:
- میانگین، انحراف معیار، حداقل، حداکثر
- برای هر ویژگی عددی
- گرد شده تا ۲ رقم اعشار
ستون چپ:
- نمودار دایره‌ای توزیع گونه‌ها
- نوع: Donut Chart (دایره با سوراخ وسط)
- رنگ‌بندی: palette Set2
- نمایش درصد و برچسب روی هر بخش
- قابلیت تعاملی (هاورلایت)

۹.۲ تب دوم: مصورسازی تعاملی

این تب امکانات متنوعی برای رسم نمودارهای مختلف فراهم می‌کند:

نمودار پراکندگی (Scatter Plot):

کاربرد: نمایش رابطه بین دو ویژگی
محور X: انتخاب از لیست ویژگی‌ها
محور Y: انتخاب از لیست ویژگی‌ها
رنگ‌بندی: بر اساس گونه، جزیره یا جنسیت
اندازه: بر اساس وزن (اختیاری)
شفافیت: ۰.۷ برای نمایش نقاط هم‌پوشان

هیستوگرام:

کاربرد: نمایش توزیع یک ویژگی
ویژگی: انتخاب از لیست
تعداد دسته‌ها: ۱۰ تا ۵۰ (قابل تنظیم)
حاشیه: نمایش باکس‌پلات در کنار
حالت: overlay برای مقایسه گونه‌ها

نمودار جعبه‌ای (Box Plot):

کاربرد: نمایش پراکندگی و چولگی
ویژگی: متغیر عددی
دسته‌بندی: بر اساس گونه، جزیره یا جنسیت
نقاط: نمایش همه نقاط (all points)

نمودار جفتی (Scatter Matrix):

کاربرد: نمایش همبستگی همه ویژگی‌ها
ابعاد: ماتریس n×n برای n ویژگی
قطر اصلی: هیستوگرام (غیرفعال)
رنگ‌بندی: بر اساس گونه

۹.۳ تب سوم: آموزش و ارزیابی

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

بخش A - وضعیت آموزش:

اسپینر: نمایش در حین پردازش
مراحل:
1. آماده‌سازی داده‌ها
2. آموزش مدل
3. ارزیابی نتایج
زمان: نمایش مدت زمان سپری شده
اندازه مجموعه‌ها: تعداد نمونه‌های آموزش و تست

بخش B - نتایج ارزیابی:

۴ کارت متریک در بالا:
- دقت (Accuracy): درصد پیش‌بینی‌های صحیح
- دقت میانگین (Precision): میانگین دقت برای همه کلاس‌ها
- یادآوری (Recall): میانگین حساسیت
- F1-Score: میانگین هارمونیک دقت و یادآوری
۲ کارت متریک در پایین:
- زمان آموزش: به ثانیه
- بهترین پارامترها: در صورت فعال بودن GridSearch

بخش C - گزارش طبقه‌بندی:

جدول:
- سطرها: Adelie, Chinstrap, Gentoo
- ستون‌ها: Precision, Recall, F1-Score, Support
- هایلایت: بهترین مقدار در هر ستون با رنگ سبز
- فرمت: درصد با ۲ رقم اعشار

بخش D - ماتریس درهم‌ریختگی:

نوع: نمودار حرارتی
ابعاد: ۳×۳
محور افقی: مقدار پیش‌بینی شده
محور عمودی: مقدار واقعی
متن: نمایش تعداد روی هر خانه
رنگ‌بندی: Blue scale

بخش E - اعتبارسنجی متقابل:

تعداد فولد: ۵
روش: Stratified K-Fold
نتایج:
- میانگین دقت
- انحراف معیار
- بازه اطمینان (میانگین ± ۲×انحراف)
نمودار: خطی با نقاط برای هر فولد

بخش F - تاریخچه آموزش:

ذخیره خودکار هر مدل
ستون‌ها: زمان، الگوریتم، دقت، F1-score
امکان مقایسه مدل‌های مختلف

۹.۴ تب چهارم: پیش‌بینی تعاملی

بخش کاربردی برنامه که کاربر نهایی با آن کار می‌کند:

بخش A - ورود ویژگی‌ها:

ستون راست (ویژگی‌های نوک):
- طول نوک: ۳۰-۶۰ میلی‌متر
- عمق نوک: ۱۳-۲۲ میلی‌متر
- گام: ۰.۱
- فرمت: یک رقم اعشار
ستون چپ (ویژگی‌های بدن):
- طول بالچه: ۱۷۰-۲۴۰ میلی‌متر
- وزن: ۲۵۰۰-۶۵۰۰ گرم
- گام: ۱ و ۵۰
- فرمت: عدد صحیح

بخش B - انتخاب جنسیت:

گزینه‌ها: Male, Female
تأثیر: در صورتی که مدل با جنسیت آموزش دیده باشد
کدگذاری: Male → 0, Female → 1

بخش C - دکمه پیش‌بینی:

وضعیت: فعال فقط پس از آموزش مدل
رنگ: سبز (نشانه موفقیت)
متن: “🎯 پیش‌بینی گونه”

بخش D - نمایش نتیجه:

باکس سبز رنگ:
- نام گونه با فونت درشت
- شکلک متناسب با گونه
- پس‌زمینه سبز روشن
نمودار احتمال:
- میله‌ای سه‌تایی
- رنگ متفاوت برای هر گونه
- نمایش درصد روی میله‌ها
- عنوان: “احتمال تعلق به هر گونه”
انیمیشن: بادکنک‌های رنگی

بخش E - تاریخچه پیش‌بینی:

نمایش ۱۰ پیش‌بینی آخر
ستون‌ها: زمان، طول نوک، عمق نوک، طول بالچه، وزن، جنسیت، نتیجه
ذخیره در Session State

۱۰. آموزش مدل

فرآیند آموزش مدل یکی از پیچیده‌ترین بخش‌های برنامه است که در چند مرحله انجام می‌شود:

۱۰.۱ آماده‌سازی داده:

انتخاب ویژگی‌ها:

ویژگی‌های ورودی (X): ستون‌های انتخاب شده توسط کاربر
ویژگی هدف (y): ستون species_code (۰،۱،۲)
تبدیل به آرایه‌های numpy در پشت صحنه

تقسیم داده:

روش: train_test_split از کتابخانه sklearn
پارامترها:
- test_size: مقدار انتخاب شده توسط کاربر
- random_state: 42 (برای قابلیت تکرارپذیری)
- stratify: y (حفظ نسبت کلاس‌ها)

نسبت‌ها:

مجموعه آموزش: ۶۰-۹۰٪ از داده
مجموعه تست: ۱۰-۴۰٪ از داده
بسته به انتخاب کاربر

۱۰.۲ پیش‌پردازش:

استانداردسازی (StandardScaler):

هدف: تبدیل ویژگی‌ها به مقیاس یکسان
روش:
- میانگین → صفر
- واریانس → یک
اهمیت:
- برای SVM و رگرسیون لجستیک ضروری است
- برای جنگل تصادفی و KNN مفید است
- از تأثیر محدوده متفاوت ویژگی‌ها جلوگیری می‌کند

فرآیند:

fit: محاسبه میانگین و واریانس از داده آموزش
transform: اعمال تبدیل روی داده آموزش
transform: اعمال همان تبدیل روی داده تست

۱۰.۳ انتخاب الگوریتم:

رگرسیون لجستیک:

مزایا: سریع، ساده، قابل تفسیر
معایب: فقط روابط خطی را تشخیص می‌دهد
کاربرد: baseline مدل

جنگل تصادفی:

مزایا: مقاوم در برابر overfitting، اهمیت ویژگی
معایب: کندتر، حافظه بیشتر
کاربرد: زمانی که دقت اولویت است

SVM:

مزایا: مؤثر در فضاهای با ابعاد بالا
معایب: کند در داده‌های بزرگ، تنظیم پارامتر حساس
کاربرد: مرزهای غیرخطی پیچیده

گرادیان بوستینگ:

مزایا: دقت بسیار بالا
معایب: مستعد overfitting، زمان آموزش طولانی
کاربرد: مسابقات Kaggle

KNN:

مزایا: ساده، بدون نیاز به آموزش
معایب: کند در پیش‌بینی، حساس به مقیاس
کاربرد: داده‌های کوچک

۱۰.۴ بهینه‌سازی (GridSearchCV):

مفهوم:

جستجوی ترکیب‌های مختلف پارامترها
ارزیابی هر ترکیب با Cross-Validation
انتخاب بهترین ترکیب بر اساس دقت

پارامترها:

C در رگرسیون لجستیک: کنترل منظم‌سازی
n_estimators در جنگل تصادفی: تعداد درخت‌ها
max_depth: عمق درخت
kernel در SVM: نوع هسته

Cross-Validation:

تعداد فولد: ۵
روش: Stratified K-Fold
معیار: accuracy

۱۰.۵ آموزش نهایی:

مراحل:

دریافت بهترین پارامترها (در صورت GridSearch)
ایجاد مدل نهایی با این پارامترها
فیت مدل روی کل داده آموزش
ذخیره مدل در Session State
ذخیره اسکیلر در Session State

زمان‌سنجی:

ثبت زمان شروع
ثبت زمان پایان
محاسبه اختلاف
نمایش به کاربر

۱۱. ارزیابی مدل

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

۱۱.۱ معیارهای پایه:

دقت (Accuracy):

فرمول: (تعداد پیش‌بینی‌های صحیح) / (تعداد کل نمونه‌ها)
محدوده: ۰ تا ۱ (۰٪ تا ۱۰۰٪)
مزایا: ساده، قابل فهم
معایب: در داده‌های نامتوازن گمراه‌کننده است
مثال: اگر ۸۰ از ۱۰۰ نمونه درست پیش‌بینی شود، دقت ۸۰٪ است

دقت (Precision):

فرمول: (مثبت صحیح) / (مثبت صحیح + مثبت کاذب)
مفهوم: از بین نمونه‌هایی که مثبت پیش‌بینی شده، چند تایشان واقعاً مثبت هستند؟
محدوده: ۰ تا ۱
کاربرد: وقتی هزینه پیش‌بینی مثبت کاذب بالاست

یادآوری (Recall):

فرمول: (مثبت صحیح) / (مثبت صحیح + منفی کاذب)
مفهوم: از بین نمونه‌های مثبت واقعی، چند تا را درست تشخیص داده؟
محدوده: ۰ تا ۱
کاربرد: وقتی هزینه منفی کاذب بالاست

F1-Score:

فرمول: ۲ × (Precision × Recall) / (Precision + Recall)
مفهوم: میانگین هارمونیک Precision و Recall
محدوده: ۰ تا ۱
مزایا: متوازن‌کننده Precision و Recall

۱۱.۲ میانگین‌گیری:

Macro Average:

محاسبه معیار برای هر کلاس به صورت مجزا
میانگین ساده از همه کلاس‌ها
به کلاس‌های کم‌نمایش وزن برابر می‌دهد

Weighted Average:

محاسبه معیار برای هر کلاس
میانگین وزنی بر اساس تعداد نمونه‌های هر کلاس
به کلاس‌های پرنمایش وزن بیشتر می‌دهد

۱۱.۳ معیارهای پیشرفته:

Log Loss:

فرمول: منفی لگاریتم احتمال پیش‌بینی صحیح
محدوده: ۰ تا ∞
تفسیر: هرچه کمتر، بهتر
کاربرد: جریمه پیش‌بینی‌های اشتباه با اطمینان بالا

ROC-AUC:

فرمول: مساحت زیر منحنی ROC
محدوده: ۰.۵ تا ۱
تفسیر:
- ۰.۵ = حدس تصادفی
- ۰.۸ = خوب
- ۰.۹ = عالی
- ۱ = کامل
کاربرد: قدرت تفکیک‌پذیری مدل

۱۱.۴ ماتریس درهم‌ریختگی:

ساختار:

سطرها: کلاس واقعی
ستون‌ها: کلاس پیش‌بینی شده
قطر اصلی: پیش‌بینی‌های صحیح
خارج قطر: خطاها

اطلاعات استخراج شده:

TP (True Positive): قطر اصلی
FP (False Positive): مجموع ستون منهای قطر
FN (False Negative): مجموع سطر منهای قطر
TN (True Negative): مجموع کل منهای TP, FP, FN

۱۱.۵ اعتبارسنجی متقابل:

مفهوم:

ارزیابی پایدارتر از یک تقسیم واحد
کاهش وابستگی به یک تقسیم خاص
استفاده بهینه از داده

روش Stratified K-Fold:

K = ۵: داده به ۵ بخش مساوی تقسیم می‌شود
Stratified: نسبت کلاس‌ها در هر فولد حفظ می‌شود
تکرار: ۵ بار، هر بار یک فولد برای تست و بقیه برای آموزش

نتایج:

میانگین: عملکرد متوسط مدل
انحراف معیار: پایداری مدل
بازه اطمینان: حدود ۹۵٪ اطمینان

۱۲. پیش‌بینی تعاملی

فرآیند پیش‌بینی شامل مراحل زیر است:

۱۲.۱ دریافت ورودی:

ویجت‌های number_input:

هر ویجت دارای min_value, max_value, value, step
محدوده‌ها بر اساس دامنه واقعی داده‌ها
مقدار پیش‌فرض نزدیک به میانگین

اعتبارسنجی ضمنی:

کاربر نمی‌تواند خارج از محدوده وارد کند
نیازی به if/else جداگانه نیست

۱۲.۲ ساخت دیتافریم ورودی:

چالش:

ترتیب ستون‌ها باید دقیقاً مانند آموزش باشد
نام ستون‌ها باید یکسان باشد
تعداد ستون‌ها باید برابر باشد

راه‌حل:

ایجاد دیکشنری با کلیدهای feature names
تبدیل به DataFrame
مرتب‌سازی ستون‌ها بر اساس selected_features

۱۲.۳ پیش‌پردازش:

اعمال StandardScaler:

استفاده از همان اسکیلر آموزش دیده
فقط transform، نه fit
تبدیل داده ورودی به مقیاس استاندارد

۱۲.۴ پیش‌بینی:

predict():

ورودی: داده استاندارد شده
خروجی: کد کلاس (۰،۱،۲)
زمان: بسیار سریع (چند میلی‌ثانیه)

predict_proba():

ورودی: داده استاندارد شده
خروجی: آرایه ۳ عضوی از احتمالات
مجموع احتمالات = ۱
فقط برای مدل‌هایی که پشتیبانی می‌کنند

۱۲.۵ نگاشت به نام:

دیکشنری نگاشت:

species_map = {
    0: 'Adelie',
    1: 'Chinstrap', 
    2: 'Gentoo'
}

تبدیل:

کد عددی → نام گونه
نمایش نام کامل

۱۲.۶ نمایش نتیجه:

باکس نتیجه:

پس‌زمینه سبز
فونت درشت
شکلک مناسب

نمودار احتمال:

میله‌های افقی/عمودی
رنگ‌های متمایز
برچسب درصد

انیمیشن:

st.balloons() برای جشن
بازخورد مثبت

۱۲.۷ ذخیره در تاریخچه:

اطلاعات ذخیره شده:

timestamp: زمان پیش‌بینی
bill_length: طول نوک
bill_depth: عمق نوک
flipper_length: طول بالچه
body_mass: وزن
sex: جنسیت
prediction: نتیجه
probabilities: احتمالات

مدیریت حافظه:

نگهداری فقط ۱۰ پیش‌بینی آخر
حذف خودکار قدیمی‌ها

۱۳. نمایش کد منبع

یک ویژگی آموزشی و شفافیت‌بخش در برنامه:

۱۳.۱ هدف:

آموزشی: کاربران می‌توانند کد را ببینند و یاد بگیرند
شفافیت: نشان می‌دهد برنامه چگونه کار می‌کند
اشکال‌زدایی: کمک به رفع خطا
اعتماد: کاربر می‌بیند چه کدی اجرا می‌شود

۱۳.۲ شرط نمایش:

فقط اگر چک‌باکس “نمایش کد” فعال شده باشد
مقدار در Session State ذخیره می‌شود
پیش‌فرض: غیرفعال

۱۳.۳ نحوه نمایش:

اکسپندر: در حالت بسته برای کاهش شلوغی
هایلایت سینتکس: رنگ‌بندی کلمات کلیدی
زبان: python
اسکرول: عمودی برای کدهای طولانی

۱۳.۴ محتوای نمایشی:

فایل جاری با __file__ خوانده می‌شود
encoding=utf-8 برای پشتیبانی از فارسی
نمایش کامل کد

۱۴. فوتر

بخش پایانی صفحه که اطلاعات نهایی را نمایش می‌دهد:

۱۴.۱ اطلاعات نمایش داده شده:

اطلاعات پروژه:

نام پروژه: “Palmer Penguins Classifier”
فناوری: “Streamlit”
احساس: “❤️”

اطلاعات جلسه:

شناسه سشن: کد یکتا
تاریخ و ساعت: زمان جاری

کپی‌رایت:

سال: ۲۰۲۶
مالکیت: “Antarctic Research Program”
حقوق: “All Rights Reserved”

۱۴.۲ استایل:

هم‌ترازی: وسط‌چین
رنگ: خاکستری
حاشیه بالا: خط جداکننده
فونت: کوچک‌تر از متن اصلی
حاشیه داخلی: ۲۰ پیکسل

۱۴.۳ اهمیت:

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

۱۵. مدیریت حافظه و Cache

بخش پنهان اما حیاتی برنامه که تأثیر مستقیم بر عملکرد دارد:

۱۵.۱ @st.cache_data:

کاربرد: برای داده‌ها و دیتافریم‌ها

مکانیزم:

تابع فقط یک بار اجرا می‌شود
نتیجه در حافظه کش ذخیره می‌شود
درخواست‌های بعدی از کش خوانده می‌شود

پارامترها:

ttl=3600: انقضا بعد از ۱ ساعت
max_entries=10: حداکثر ۱۰ آیتم در کش
show_spinner: نمایش پیام در حین اجرا
persist: ذخیره روی دیسک (اختیاری)

۱۵.۲ @st.cache_resource:

کاربرد: برای مدل‌ها و اتصالات دیتابیس

تفاوت با cache_data:

بهینه برای منابع غیرسریالی‌شونده
مدل‌های یادگیری ماشین
اتصالات شبکه

۱۵.۳ پاکسازی دستی:

دکمه پاکسازی کش:

st.cache_data.clear(): پاک کردن کش داده‌ها
st.cache_resource.clear(): پاک کردن کش منابع
st.rerun(): اجرای مجدد برنامه

۱۵.۴ جمع‌آوری زباله (Garbage Collection):

gc.collect():

آزادسازی حافظه اشغال شده
کاهش مصرف RAM
جلوگیری از Memory Leak

۱۵.۵ استراتژی‌های بهینه‌سازی:

اجرای شرطی:

آموزش مدل فقط با کلیک دکمه
بارگذاری داده فقط یک بار
محاسبات سنگین در توابع جداگانه

انتخاب ویژگی:

فقط ویژگی‌های مورد نیاز بارگذاری شوند
حذف ستون‌های اضافی

۱۶. مدیریت خطا

برنامه برای شرایط مختلف خطا آماده است و به صورت گر‌آمیز با آنها برخورد می‌کند:

۱۶.۱ خطاهای بارگذاری داده:

سناریو:

قطع اینترنت در زمان بارگذاری
عدم دسترسی به مخزن seaborn
خرابی فایل

واکنش:

نمایش پیام خطا با st.error
پیشنهاد راه‌حل
توقف اجرا با st.stop()

۱۶.۲ خطاهای آموزش مدل:

سناریو:

انتخاب کمتر از ۲ ویژگی
داده با کیفیت پایین
عدم همگرایی مدل

واکنش:

غیرفعال کردن دکمه آموزش
نمایش هشدار با st.warning
راهنمایی برای رفع مشکل

۱۶.۳ خطاهای پیش‌بینی:

سناریو:

مدل آموزش ندیده
تعداد ویژگی‌ها نامتناسب
ورودی خارج از محدوده

واکنش:

غیرفعال کردن دکمه پیش‌بینی
نمایش پیام راهنما
پیشنهاد آموزش مدل

۱۶.۴ خطاهای پیش‌بینی‌نشده:

سناریو:

باگ‌های نرم‌افزاری
شرایط مرزی

واکنش:

نمایش خطای عمومی
ذخیره لاگ
پیشنهاد گزارش خطا

۱۷. تعاملات و رویدادها

نحوه پاسخگویی برنامه به کنش‌های کاربر:

۱۷.۱ مدل اجرای Streamlit:

چرخه حیات:

کاربر برنامه را اجرا می‌کند
اسکریپت از بالا به پایین اجرا می‌شود
صفحه در مرورگر رندر می‌شود
کاربر با ویجتی تعامل می‌کند
کل اسکریپت دوباره اجرا می‌شود
صفحه به‌روزرسانی می‌شود

نکته مهم: تمام متغیرهای محلی در هر اجرا از نو ساخته می‌شوند. برای حفظ داده باید از Session State استفاده کرد.

۱۷.۲ انواع تعامل:

تغییر در ویجت‌های پیوسته:

اسلایدر
اینپوت عددی
سلکت باکس
مولتی‌سلکت
→ اجرای مجدد فوری

کلیک روی دکمه:

دکمه ساده
دکمه فرم
→ اجرای مجدد با شرط

۱۷.۳ شرط‌های اجرا:

if st.button():

محتوای داخل if فقط پس از کلیک اجرا می‌شود
مناسب برای عملیات سنگین

if ‘model’ in st.session_state:

محتوا فقط وقتی مدل وجود دارد نمایش می‌یابد
مناسب برای تب پیش‌بینی

if len(features) >= 2:

اعتبارسنجی قبل از آموزش
غیرفعال کردن دکمه

۱۷.۴ بازخورد بصری:

st.success:

رنگ سبز
علامت ✅
برای موفقیت

st.warning:

رنگ زرد
علامت ⚠️
برای هشدار

st.error:

رنگ قرمز
علامت ❌
برای خطا

st.info:

رنگ آبی
علامت ℹ️
برای اطلاعات

۱۸. جریان کلی برنامه

مراحل کامل استفاده از برنامه از نگاه کاربر:

مرحله ۱ - راه‌اندازی:

کاربر دستور streamlit run penguin_classifier.py را اجرا می‌کند
Streamlit سرور محلی را روی پورت ۸۵۰۱ راه‌اندازی می‌کند
مرورگر به صورت خودکار باز می‌شود
صفحه کانفیگ تنظیم می‌شود
استایل CSS تزریق می‌شود
Session State مقداردهی می‌شود
دیتاست پنگوئن از کش بارگذاری می‌شود
عنوان و هدر نمایش می‌یابد

مرحله ۲ - پیکربندی:

کاربر در سایدبار ویژگی‌های مورد نظر را انتخاب می‌کند
الگوریتم یادگیری را انتخاب می‌کند
درصد داده تست را تنظیم می‌کند
(اختیاری) GridSearch را فعال می‌کند
دکمه آموزش فعال می‌شود

مرحله ۳ - آموزش:

کاربر دکمه “شروع آموزش مدل” را کلیک می‌کند
وضعیت “در حال آموزش…” نمایش می‌یابد
داده به آموزش و تست تقسیم می‌شود
ویژگی‌ها استاندارد می‌شوند
مدل آموزش می‌بیند
زمان آموزش محاسبه می‌شود
معیارهای ارزیابی محاسبه می‌شوند
ماتریس درهم‌ریختگی رسم می‌شود
گزارش طبقه‌بندی نمایش می‌یابد
مدل و اسکیلر در Session State ذخیره می‌شوند

مرحله ۴ - تحلیل:

کاربر به تب “داده‌ها و آمار” می‌رود
نمونه داده‌ها را مشاهده می‌کند
آمار توصیفی را بررسی می‌کند
توزیع گونه‌ها را در نمودار دایره‌ای می‌بیند
به تب “مصورسازی” می‌رود
انواع نمودارها را رسم می‌کند
روابط بین ویژگی‌ها را بررسی می‌کند

مرحله ۵ - پیش‌بینی:

کاربر به تب “پیش‌بینی تعاملی” می‌رود
مقادیر ویژگی‌های پنگوئن را وارد می‌کند
جنسیت را انتخاب می‌کند
دکمه “پیش‌بینی گونه” را کلیک می‌کند
مدل پیش‌بینی را انجام می‌دهد
نتیجه با باکس سبز رنگ نمایش می‌یابد
نمودار احتمال نمایش می‌یابد
بادکنک‌های جشن ظاهر می‌شوند
پیش‌بینی در تاریخچه ذخیره می‌شود

مرحله ۶ - تکرار و مقایسه:

کاربر به سایدبار برمی‌گردد
الگوریتم دیگری انتخاب می‌کند
مدل جدید آموزش می‌دهد
نتایج را با مدل قبلی مقایسه می‌کند
بهترین مدل را انتخاب می‌کند

مرحله ۷ - اتمام کار:

کاربر پنجره مرورگر را می‌بندد
در ترمینال Ctrl+C می‌زند
سرور Streamlit متوقف می‌شود
Session State پاک می‌شود

۱۹. مفاهیم کلیدی Streamlit

درک این مفاهیم برای نوشتن اپلیکیشن‌های حرفه‌ای Streamlit ضروری است:

۱۹.۱ معماری واکنش‌گرا (Reactive Architecture):

تعریف: در معماری سنتی، برنامه منتظر می‌ماند تا کاربر عملی انجام دهد و سپس پاسخ می‌دهد. در Streamlit، برنامه مدام در حال اجرای مجدد است.

مثال:

# کاربر اسلایدر را جابجا می‌کند
x = st.slider('x')  # ← این خط دوباره اجرا می‌شود
st.write(x)         # ← این خط هم دوباره اجرا می‌شود

پیامدها:

✅ کد ساده و خطی
✅ اشکال‌زدایی آسان
❌ نیاز به Session State برای حفظ داده
❌ ممکن است کند شود

۱۹.۲ کشینگ دو سطحی (Two-level Caching):

@st.cache_data:

برای داده‌های حجیم
دیتافریم‌ها
آرایه‌های numpy
نتایج API calls

@st.cache_resource:

برای مدل‌های ML
اتصالات دیتابیس
اشیاء سنگین

۱۹.۳ ویجت‌های هوشمند (Smart Widgets):

کلید (key):

هر ویجت می‌تواند یک کلید منحصر‌به‌فرد داشته باشد
مقدار ویجت در Session State با همان کلید ذخیره می‌شود
دسترسی به مقدار: st.session_state.key

مقدار پیش‌فرض (value):

مقداری که ویجت با آن شروع می‌کند
در اولین اجرا استفاده می‌شود

محدوده (min_value, max_value):

برای ویجت‌های عددی
کاربر نمی‌تواند خارج از محدوده وارد کند

۱۹.۴ چیدمان انعطاف‌پذیر (Flexible Layout):

st.sidebar:

نوار کناری جداگانه
محتوای متفاوت از صفحه اصلی
دسترسی آسان

st.columns:

تقسیم صفحه به ستون‌های عمودی
نسبت‌های قابل تنظیم
پاسخگو به اندازه صفحه

st.tabs:

تب‌بندی موضوعی
سازماندهی محتوای زیاد
کاهش شلوغی

st.expander:

محتوای بازشونده
جزئیات اضافی
پیش‌فرض بسته

st.container:

کادر محتوایی
گروه‌بندی المان‌ها
استایل‌دهی یکپارچه

۱۹.۵ وضعیت‌های نمایشی (Status Elements):

st.spinner:

در حین عملیات طولانی
متن دلخواه
غیرفعال شدن خودکار

st.progress:

درصد پیشرفت
به‌روزرسانی دینامیک
برای حلقه‌های طولانی

st.status:

مراحل انجام کار
وضعیت‌های pending, complete, error
جزئیات قابل توسعه

st.balloons/st.snow:

انیمیشن جشن
بازخورد مثبت
افزایش رضایت کاربر

۲۰. نکات حرفه‌ای و بهینه‌سازی

۲۰.۱ بهینه‌سازی عملکرد:

کشینگ هوشمند:

داده‌هایی که تغییر نمی‌کنند را کش کنید
از ttl مناسب استفاده کنید
مدل‌های سنگین را با cache_resource کش کنید

اجرای شرطی:

محاسبات سنگین را در if st.button() قرار دهید
از if برای نمایش/عدم نمایش استفاده کنید
ویجت‌های غیرضروری را غیرفعال کنید

انتخاب ویژگی:

فقط ویژگی‌های مورد نیاز را بارگذاری کنید
از دیتافریم‌های سبک استفاده کنید
ستون‌های اضافی را حذف کنید

۲۰.۲ بهبود تجربه کاربری:

بازخورد فوری:

برای هر کنش کاربر بازخورد نمایش دهید
از st.success, st.warning, st.error استفاده کنید
انیمیشن‌های تشویقی اضافه کنید

راهنمای شناور:

به همه ویجت‌ها help اضافه کنید
محدوده مجاز را مشخص کنید
واحد اندازه‌گیری را ذکر کنید

اعتبارسنجی:

ورودی‌ها را قبل از پردازش بررسی کنید
دکمه‌ها را در شرایط نامناسب غیرفعال کنید
پیام‌های خطای مفید نمایش دهید

۲۰.۳ نگهداری کد:

نام‌گذاری معنادار:

تابع: load_penguin_data (نه load_data)
متغیر: selected_features (نه feats)
کلید: training_history (نه hist)

توابع تک‌منظوره:

هر تابع یک کار انجام دهد
کمتر از ۵۰ خط
ورودی و خروجی مشخص

کامنت‌های توضیحی:

دلیل، نه چگونگی
docstring برای توابع
توضیح بخش‌های پیچیده

ساختار ماژولار:

بخش‌های مجزا با کامنت
ترتیب منطقی: ایمپورت، توابع، اجرا
ثابت‌ها در ابتدای فایل

۲۰.۴ امنیت:

عدم ذخیره اطلاعات حساس:

رمز عبور ذخیره نکنید
توکن‌های API در secrets.toml
از st.secrets استفاده کنید

پاکسازی حافظه:

Session State را مدیریت کنید
کش را در زمان مناسب پاک کنید
از atexit برای پاکسازی نهایی استفاده کنید

اعتبارسنجی ورودی:

محدوده اعداد را بررسی کنید
نوع فایل را بررسی کنید
حجم فایل را محدود کنید

۲۰.۵ تست و اشکال‌زدایی:

تست دستی:

همه ویجت‌ها را تست کنید
مقادیر مرزی را بررسی کنید
خطاهای احتمالی را شبیه‌سازی کنید

لاگ‌گیری:

زمان اجرا را ثبت کنید
خطاها را لاگ کنید
شناسه سشن برای رهگیری

پروفایلینگ:

زمان اجرای توابع را اندازه بگیرید
bottleneckها را پیدا کنید
بهینه‌سازی کنید

جمع‌بندی مثال

برنامه طبقه‌بندی گونه پنگوئن یک اپلیکیشن کامل و حرفه‌ای است که تمام مفاهیم کلیدی Streamlit را پوشش می‌دهد:

از نظر فنی:

معماری واکنش‌گرا
کشینگ دو سطحی
مدیریت state
چیدمان پیچیده
تعاملات شرطی

از نظر محتوایی:

بارگذاری و پیش‌پردازش داده
آموزش مدل‌های مختلف
ارزیابی جامع
پیش‌بینی تعاملی
مصورسازی داده

از نظر تجربه کاربری:

رابط کاربری زیبا
بازخورد فوری
راهنمای کامل
مدیریت خطا
انیمیشن‌های تشویقی

این برنامه می‌تواند به عنوان الگویی برای ساخت اپلیکیشن‌های یادگیری ماشین با Streamlit استفاده شود و با تغییر دیتاست و مدل، برای مسائل دیگر نیز قابل استفاده است.

پایان تشریح برنامه

۶. مقایسه Streamlit با سایر فریمورک‌ها

ویژگی	Streamlit	Dash (Plotly)	Taipy	Reflex	Flask
مخاطب اصلی	دانشمندان داده	تحلیلگران	توسعه‌دهندگان پایتون	توسعه‌دهندگان وب	توسعه‌دهندگان بک‌اند
منحنی یادگیری	خیلی کم	متوسط	متوسط	بالا	بالا
نیاز به اچ تی ام ال یا سی اس اس	خیر	خیر (تا حدی)	خیر	بله	مفاهیم	بله (کامل)
مدل اجرا	Rerun کامل اسکریپت	Reactive (Callback)	Reactive (State)	State Class	Request/Response
شخصی‌سازی ظاهر	ضعیف (نیاز به CSS)	عالی	خوب	عالی	کامل
مدیریت State	`session_state`	Callbacks	`State` متغیر	کلاس State	متغیرهای سراسری
کاربرد اصلی	MVP و پروتوتایپ	داشبورد Enterprise	اپ‌های صنعتی	اپ‌های Full-stack	هر نوع اپلیکیشن
سرعت در اپ‌های بزرگ	کند	سریع	سریع	متوسط	بسیار سریع

تحلیل مقایسه‌ای:

Streamlit vs. Dash: اگر نیاز به اپلیکیشنی دارید که فردا باید تحویل دهید و تیم شما فقط پایتون می‌داند، Streamlit انتخاب اول است. اما اگر اپلیکیشن شما باید در سطح سازمانی (Enterprise) با هزاران کاربر اجرا شود و ظاهر منحصربه‌فردی داشته باشد، Dash (با قابلیت Dash Enterprise) قدرتمندتر است.
Streamlit vs. Reflex (قدیمی‌تر: Pynecone): Reflex کنترل کامل تری روی State مدیریت وب به شما می‌دهد و اپلیکیشن‌های پیچیده‌تری می‌توان ساخت، اما به قیمت از دست دادن سادگی افسانه‌ای Streamlit.
Streamlit vs. Taipy: Taipy در زمینه سرعت اجرای ویجت‌ها و کنترل‌های پیشرفته (مثل اسلایدرهای پیچیده) عملکرد بهتری دارد، اما کدنویسی آن به اندازه Streamlit سریع و شهودی نیست.

۷. هر چیزی که باید بدانیم (نکات طلایی)

قانون طلایی Caching: همیشه برای لود دیتا و مدل‌های سنگین از @st.cache_data استفاده کنید. بدون آن، اپلیکیشن شما با هر کلیک کند خواهد بود.
Session State را بیاموزید: اگر می‌خواهید شمارنده داشته باشید یا نتیجه محاسبات قبلی را حفظ کنید، از st.session_state استفاده کنید. این کلید حرفه‌ای‌شدن در Streamlit است.
چیدمان (Layout): برای زیبایی اپلیکیشن از ترکیب st.sidebar (برای ورودی‌ها) و st.columns/st.tabs (برای خروجی‌ها) استفاده کنید.
محدودیت را بشناسید: اگر می‌خواهید یک وب‌سایت چندصفحه‌ای بسیار پیچیده با سطح دسترسی مختلف بسازید، Streamlit انتخاب درستی نیست.
قدرت Secrets: وقتی اپلیکیشن خود را در فضای ابری (Cloud) منتشر می‌کنید، برای ذخیره رمز دیتابیس و API Keyها از فایل .streamlit/secrets.toml استفاده کنید.

سخن آخر

Streamlit انقلابی در نحوه ارائه پروژه‌های داده محور ایجاد کرده است. این ابزار “فتوشاپ” دنیای علم داده نیست، بلکه “Paint” است؛ یعنی ابزاری برای سریع‌ترین حالت ممکن از ایده تا اجرا. اگر به دنبال ساخت داشبوردهای سریع، دموهای اثرگذار و MVP هستید، بهترین انتخاب است. اما اگر به دنبال مقیاس‌پذیری بالا، کنترل کامل بر ظاهر و تعاملات پیچیده هستید، باید به گزینه‌هایی مانند Dash یا Reflex فکر کنید.

شما می‌توانید از اینجا می‌توانید فایل penguin_classifier.py را دانلود کنید.

راهنمای جامع Streamlit با یک مثال کاربردی

Hadi Sadoghi Yazdi

راهنمای جامع Streamlit با یک مثال کاربردی

۱. Streamlit چیست و چرا ساخته شد؟

رابط کاربری Streamlit

صفحه اصلی (Main Area)

نوار کناری (Sidebar)

ویجت‌های تعاملی (Interactive Widgets)

ویجت‌های ورودی:

ویجت‌های خروجی:

چیدمان و صفحه‌آرایی (Layout)

عناصر وضعیت (Status Elements)

نوار بالایی (Top Bar)

ویژگی‌های کلیدی رابط کاربری Streamlit

تجربه کاربری (User Experience)

مزایای رابط کاربری Streamlit

۲. ویژگی‌ها و مزایای کلیدی

۳. محدودیت‌ها و نقاط ضعف

۴. کاربردهای اصلی Streamlit

۵. مثال‌ عملی (کد اجرایی در پیوست می آید)

تشریح کامل بخش‌های مختلف برنامه (سیستم طبقه‌بندی گونه پنگوئن)

۱. کتابخانه‌ها و ماژول‌های استفاده شده

۲. تنظیمات صفحه

۳. استایل‌دهی با CSS سفارشی

۴. توابع کمکی

۵. مدیریت Session State

۶. بارگذاری داده

۷. عنوان و هدر

۸. سایدبار - پنل تنظیمات

۹. تب‌ها و نمایش داده

۱۰. آموزش مدل

۱۱. ارزیابی مدل

۱۲. پیش‌بینی تعاملی

۱۳. نمایش کد منبع

۱۴. فوتر

۱۵. مدیریت حافظه و Cache

۱۶. مدیریت خطا

۱۷. تعاملات و رویدادها

۱۸. جریان کلی برنامه

۱۹. مفاهیم کلیدی Streamlit

۲۰. نکات حرفه‌ای و بهینه‌سازی

جمع‌بندی مثال

۶. مقایسه Streamlit با سایر فریمورک‌ها

۷. هر چیزی که باید بدانیم (نکات طلایی)

سخن آخر