اگر یک مدل هوش مصنوعی ساخته‌اید اما نمایش آن فقط در ترمینال یا نوت‌بوک باقی مانده، جای درستی آمده‌اید. Streamlit فریم‌ورکی پایتونی است که به شما اجازه می‌دهد بدون حتی یک خط HTML یا جاوااسکریپت، مدل‌تان را به یک اپلیکیشن تحت وب تعاملی، زیبا و قابل اشتراک‌گذاری تبدیل کنید؛ از داشبورد تحلیل داده تا چت‌بات متصل به LLM. در این آموزش، نصب، ساخت اولین اپ، مدیریت حالت، اتصال به هوش مصنوعی و انتشار نهایی را به‌صورت عملی یاد می‌گیرید.

آموزش Streamlit چیست و چرا سریع‌ترین راه ساخت اپ هوش مصنوعی است؟

Streamlit یک فریم‌ورک متن‌باز پایتون برای ساخت اپ‌های وب داده‌محور است که با اجرای یک فایل app.py، رابط کاربری را مستقیماً از کد پایتون می‌سازد. برخلاف Flask یا Django نیازی به فرانت‌اند ندارید؛ هر ویجت یک متغیر پایتون است و با هر تعامل، اسکریپت دوباره اجرا می‌شود. همین سادگی، آن را به انتخاب اول برای دموهای هوش مصنوعی، داشبوردها و ابزارهای داخلی تبدیل کرده است. در ادامه قدم‌به‌قدم پیاده‌سازی می‌کنیم.

فهرست مطالب

پیش‌نیازها و نصب Streamlit
نصب با pip و uv
ساختار پروژه پیشنهادی
اولین اپ Streamlit شما در ۵ دقیقه
اجزای کلیدی Streamlit که باید بشناسید
ویجت‌ها، Layout و Session State
اتصال هوش مصنوعی به Streamlit؛ نمونه چت‌بات ساده
مقایسه Streamlit با Gradio و Dash برای اپ‌های هوش مصنوعی
اشتباهات رایج و خطاهای پرتکرار در Streamlit
سوالات متداول
جمع‌بندی

پیش‌نیازها و نصب Streamlit

برای شروع فقط به پایتون ۳.۹ به بالا و یک محیط مجازی تمیز نیاز دارید. اگر با مفاهیم پایه پایتون، نصب پکیج و اجرای اسکریپت آشنا باشید کافی است. Streamlit روی ویندوز، مک و لینوکس بدون دردسر نصب می‌شود و حتی روی PythonAnywhere یا Streamlit Community Cloud رایگان اجرا می‌شود. پیشنهاد می‌کنیم همیشه از محیط مجازی استفاده کنید تا تداخل نسخه‌ها پیش نیاید.

نصب با pip و uv

سریع‌ترین روش با pip است، اما اگر سرعت برایتان مهم است، uv همان کار را چند برابر سریع‌تر انجام می‌دهد:

# با pip
python -m venv venv
source venv/bin/activate  # ویندوز: venv\Scripts\activate
pip install --upgrade pip
pip install streamlit

# با uv (پیشنهادی برای پروژه‌های جدید)
pip install uv
uv venv
uv pip install streamlit

# تست نصب
streamlit --version
streamlit hello

دستور streamlit hello یک اپ دمو را روی http://localhost:8501 باز می‌کند. اگر صفحه لود شد، نصب موفق بوده است. برای به‌روزرسانی، کافی است pip install --upgrade streamlit را اجرا کنید.

ساختار پروژه پیشنهادی

برای پروژه‌های هوش مصنوعی، ساختار تمیز جلوی سردرگمی را می‌گیرد:

my-ai-app/
├── app.py              # فایل اصلی Streamlit
├── requirements.txt    # یا pyproject.toml
├── .streamlit/
│   └── config.toml     # تنظیمات تم و سرور
├── src/
│   ├── model.py        # لود مدل / فراخوانی API
│   └── utils.py
└── data/
    └── sample.csv

در config.toml می‌توانید تم روشن/تیره، پورت و عنوان مرورگر را تنظیم کنید. این فایل اختیاری است اما برای ارائه حرفه‌ای مفید است.

[theme]
primaryColor = "#FF4B4B"
backgroundColor = "#FFFFFF"
[text]
[server]
headless = true
port = 8501

اولین اپ Streamlit شما در ۵ دقیقه

یک فایل app.py بسازید و این کد را قرار دهید. این اپ یک عنوان، اسلایدر، آپلود عکس و نمودار ساده دارد — همان الگوی ۸۰٪ اپ‌های هوش مصنوعی:

import streamlit as st
import pandas as pd
import numpy as np

st.set_page_config(page_title="اولین اپ Streamlit", page_icon="✨", layout="wide")

st.title("سلام Streamlit! اولین اپ تعاملی شما")
st.write("این اپ بدون HTML/JS فقط با پایتون ساخته شده است.")

name = st.text_input("نام شما چیست؟", placeholder="مثلاً سارا")
temp = st.slider("خلاقیت مدل (temperature)", 0.0, 1.5, 0.7, 0.1)

uploaded = st.file_uploader("یک تصویر آپلود کنید", type=["jpg", "png"])
if uploaded:
    st.image(uploaded, caption=f"سلام {name or 'دوست عزیز'}! تصویر دریافت شد.", use_column_width=True)

if st.button("نمایش نمودار نمونه"):
    chart_data = pd.DataFrame(np.random.randn(20, 3), columns=["مدل A", "مدل B", "مدل C"])
    st.line_chart(chart_data)

st.success(f"مقدار temperature انتخابی: {temp}")

برای اجرا:

streamlit run app.py

مرورگر به‌طور خودکار باز می‌شود. هر بار که فایل را ذخیره کنید، Streamlit به‌صورت خودکار ری‌لود می‌کند. نکته طلایی: Streamlit با هر تعامل کاربر، کل اسکریپت را از بالا تا پایین دوباره اجرا می‌کند؛ بنابراین برای کارهای سنگین (لود مدل، خواندن دیتاست) حتماً از کش استفاده کنید.

import streamlit as st

@st.cache_resource
def load_model():
    # لود مدل سنگین فقط یک بار انجام می‌شود
    return "model-object"

@st.cache_data
def load_data(path):
    return pd.read_csv(path)

اجزای کلیدی Streamlit که باید بشناسید

قدرت Streamlit در سه دسته خلاصه می‌شود: ویجت‌ها برای ورودی، Layout برای چیدمان، و State برای حافظه. اگر این سه را درست بشناسید، هر ایده‌ای را می‌توانید به اپ تبدیل کنید.

ویجت‌ها، Layout و Session State

۱. ویجت‌ها: تمام ورودی‌ها یک مقدار پایتون برمی‌گردانند. پرکاربردترین‌ها:

st.text_input ،st.number_input ،st.text_area برای متن
st.slider ،st.selectbox ،st.multiselect ،st.radio برای انتخاب
st.file_uploader ،st.camera_input برای فایل و دوربین
st.button ،st.form برای اکشن

۲. چیدمان (Layout): بدون CSS، صفحه را حرفه‌ای کنید:

col1, col2 = st.columns(2)
with col1:
    st.subheader("تنظیمات")
    st.slider("تعداد خروجی", 1, 10, 3)
with col2:
    st.subheader("نتیجه")
    st.info("خروجی مدل اینجا نمایش داده می‌شود")

tab1, tab2 = st.tabs(["پیش‌نمایش", "کد"])
with tab1:
    st.write("محتوا")
with tab2:
    st.code("print('hello')", language="python")

with st.sidebar:
    st.header("تنظیمات پیشرفته")
    model = st.selectbox("انتخاب مدل", ["gpt-4o-mini", "gemini-2.0"])

۳. حافظه با Session State: چون اسکریپت هر بار ری‌ران می‌شود، متغیرها از بین می‌روند. برای چت‌بات یا فرم چندمرحله‌ای از st.session_state استفاده کنید:

if "history" not in st.session_state:
    st.session_state.history = []

prompt = st.chat_input("پیامت را بنویس...")
if prompt:
    st.session_state.history.append({"role": "user", "content": prompt})
    # پاسخ مدل را هم اضافه کنید
    st.session_state.history.append({"role": "assistant", "content": f"پاسخ به: {prompt}"})

for msg in st.session_state.history:
    with st.chat_message(msg["role"]):
        st.write(msg["content"])

با همین الگو می‌توانید تاریخچه چت، توکن احراز هویت یا نتایج قبلی را نگه دارید.

اتصال هوش مصنوعی به Streamlit؛ نمونه چت‌بات ساده

حالا مدل را وصل می‌کنیم. دو سناریو رایج دارید: فراخوانی API ابری (OpenAI، Gemini) یا اجرای لوکال با Ollama. الگوی کد یکی است؛ فقط تابع فراخوانی عوض می‌شود. نمونه زیر با OpenAI سازگار است و به‌راحتی به Ollama هم تبدیل می‌شود:

import streamlit as st
from openai import OpenAI

st.title("چت‌بات هوش مصنوعی با Streamlit")

client = OpenAI(api_key=st.secrets["OPENAI_API_KEY"])  # کلید را در .streamlit/secrets.toml بگذارید

if "messages" not in st.session_state:
    st.session_state.messages = [{"role": "system", "content": "تو یک دستیار فارسی مفید هستی."}]

for m in st.session_state.messages[1:]:
    with st.chat_message(m["role"]):
        st.markdown(m["content"])

if prompt := st.chat_input("سوالت را بپرس..."):
    st.session_state.messages.append({"role": "user", "content": prompt})
    with st.chat_message("user"):
        st.markdown(prompt)

    with st.chat_message("assistant"):
        stream = client.chat.completions.create(
            model="gpt-4o-mini",
            messages=st.session_state.messages,
            stream=True,
        )
        response = st.write_stream(stream)
    st.session_state.messages.append({"role": "assistant", "content": response})

برای اجرای لوکال و حفظ حریم داده، می‌توانید به‌جای OpenAI از Ollama استفاده کنید که مدل‌ها را بدون اینترنت روی سیستم خودتان اجرا می‌کند. اگر می‌خواهید مدل را کاملاً آفلاین و رایگان اجرا کنید، آموزش Ollama برای اجرای لوکال مدل‌ها را ببینید؛ ترکیب Streamlit + Ollama یک چت‌بات خصوصی و سریع بدون هزینه API به شما می‌دهد.

نکات امنیتی مهم: هرگز کلید API را در کد هاردکد نکنید. از .streamlit/secrets.toml یا متغیر محیطی استفاده کنید و فایل را در .gitignore قرار دهید. برای استریم پاسخ، st.write_stream تجربه کاربری بسیار بهتری نسبت به انتظار تا پایان تولید می‌دهد.

مقایسه Streamlit با Gradio و Dash برای اپ‌های هوش مصنوعی

انتخاب ابزار به هدف شما بستگی دارد. Streamlit برای سرعت و سادگی، Gradio برای دموهای مدل‌محور، و Dash برای داشبوردهای سازمانی پیچیده بهتر است:

معیار	Streamlit	Gradio	Dash (Plotly)
سرعت ساخت MVP	بسیار بالا – فقط پایتون	بسیار بالا – مخصوص مدل	متوسط – نیاز به callback
بهترین کاربرد	اپ و داشبورد داده/AI عمومی	دمو سریع مدل‌های ML/HF	داشبورد سازمانی تعاملی
سفارشی‌سازی UI	متوسط – کامپوننت آماده	کم – قالب ثابت	بالا – کنترل کامل
اجرا و دیپلوی	Streamlit Cloud / Docker آسان	Hugging Face Spaces یک‌کلیکی	نیاز به سرور/ Gunicorn
منحنی یادگیری	ملایم	بسیار ملایم	تندتر

اگر هدفتان ارائه سریع یک مدل به کاربر غیرفنی یا مدیر محصول است، Streamlit یا Gradio انتخاب بهتری است. برای مثال، اگر می‌خواهید افکت‌های تصویری مثل ویرایش عکس بدون تغییر چهره را دمو کنید، Gradio هم گزینه خوبی است؛ اما برای اپ‌های چندصفحه‌ای با احراز هویت و چارت‌های پیشرفته، Streamlit انعطاف بیشتری نسبت به Gradio می‌دهد. برای الهام از قابلیت‌های ویرایش تصویر با مدل‌های جدید، معرفی Nano Banana Pro گوگل را ببینید و سپس رابط آن را با Streamlit پیاده کنید.

اشتباهات رایج و خطاهای پرتکرار در Streamlit

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

لود مدل در هر ری‌ران: بدون @st.cache_resource، مدل چندگیگابایتی هر بار لود می‌شود و اپ کند یا کرش می‌کند. همیشه لود مدل را کش کنید.
استفاده از متغیر سراسری به‌جای Session State: مقدار ورودی‌ها با رفرش از بین می‌رود. برای ذخیره تاریخچه چت، سبد خرید یا فرم چندمرحله‌ای حتماً st.session_state به کار ببرید.
قرار دادن کد سنگین خارج از کش یا فرم: پردازش تصویر یا فراخوانی API را داخل st.form یا دکمه قرار دهید تا با هر تغییر اسلایدر اجرا نشود.
فراموش کردن secrets.toml در دیپلوی: اپ لوکال کار می‌کند اما روی Streamlit Cloud خطای KeyError می‌دهد. کلیدها را در بخش Secrets پنل Cloud هم ست کنید.
استفاده از st.pyplot بدون بستن فیگور: در حلقه‌ها حافظه پر می‌شود. بعد از st.pyplot(fig) حتماً plt.close(fig) را صدا بزنید یا از st.line_chart / st.plotly_chart استفاده کنید.

سوالات متداول

آیا Streamlit برای محصول نهایی (Production) مناسب است؟

برای MVP، ابزار داخلی، دمو سرمایه‌گذار و داشبوردهای تیمی عالی است. برای محصول با میلیون‌ها کاربر همزمان، ترافیک بالا و نیاز به احراز هویت پیچیده، معمولاً آن را پشت Docker + Nginx یا به‌عنوان فرانت برای بک‌اند FastAPI استفاده می‌کنند، نه به‌تنهایی.

چطور اپ Streamlit را منتشر کنم؟

سه راه ساده: ۱) Streamlit Community Cloud رایگان – ریپو گیت‌هاب را وصل کنید. ۲) Docker – یک Dockerfile با streamlit run app.py --server.port=8501 بسازید و روی هر VPS دیپلوی کنید. ۳) Hugging Face Spaces با انتخاب SDK Streamlit.

تفاوت st.cache_data و st.cache_resource چیست؟

cache_data برای داده‌های قابل سریالایز مثل DataFrame یا JSON است و هر ورودی جدید را کپی می‌کند. cache_resource برای منابع غیرقابل کپی مثل مدل ML، اتصال دیتابیس یا کلاینت OpenAI است و شیء را به‌صورت مشترک نگه می‌دارد. استفاده اشتباه باعث خطای UnhashableParamError می‌شود.

آیا Streamlit از احراز هویت و چندصفحه‌ای بودن پشتیبانی می‌کند؟

بله. از نسخه ۱.۳۰ به بعد، با قراردادن فایل‌ها در پوشه pages/، اپ چندصفحه‌ای می‌شود. برای لاگین، از st.session_state به همراه پکیج‌هایی مثل streamlit-authenticator یا اتصال به Auth0/Supabase استفاده کنید.

چرا با هر تغییر ویجت، کل اپ دوباره اجرا می‌شود؟

این ذات Streamlit است (rerun-on-interaction). برای جلوگیری از اجرای بی‌مورد، کدهای سنگین را داخل with st.form یا شرط if st.button بگذارید و از کش استفاده کنید تا فقط بخش مورد نیاز دوباره محاسبه شود.

جمع‌بندی

با Streamlit می‌توانید ایده هوش مصنوعی‌تان را در یک عصر از نوت‌بوک به یک اپ قابل اشتراک‌گذاری تبدیل کنید. برای شروع حرفه‌ای، این چک‌لیست را دنبال کنید:

محیط مجازی + نصب Streamlit با pip یا uv را انجام دهید و streamlit hello را تست کنید.
ساختار پروژه با app.py و پوشه .streamlit بسازید و تم را تنظیم کنید.
اولین اپ با ویجت، ستون و نمودار را بسازید و منطق کش (cache_data/resource) را اضافه کنید.
حافظه را با st.session_state مدیریت کنید؛ به‌ویژه برای چت‌بات و فرم‌ها.
مدل را از طریق API یا Ollama لوکال وصل کنید و کلیدها را در secrets.toml نگه دارید.
اپ را روی Streamlit Cloud یا Docker دیپلوی کنید و لینک را با تیم به اشتراک بگذارید.

همین امروز یک اپ کوچک بسازید — حتی یک فرم ساده که پرامپت را به مدل می‌فرستد و جواب را نمایش می‌دهد — و مرحله‌به‌مرحله قابلیت‌های بیشتری اضافه کنید. Streamlit مسیر بین ایده و محصول را به کوتاه‌ترین شکل ممکن می‌کند.

آموزش Streamlit در پایتون؛ ساخت اپ هوش مصنوعی تعاملی