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

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

Gradio یک کتابخانه متن‌باز پایتون است که با یک دستور نصب می‌شود و به شما اجازه می‌دهد برای هر تابع پایتونی ــ از یک مدل یادگیری ماشین تا یک API ساده ــ یک رابط وب تعاملی بسازید. کافی است ورودی و خروجی تابع را تعریف کنید؛ Gradio خودش فرم، دکمه، اسلایدر و نمایش نتیجه را می‌سازد و با share=True لینک موقت عمومی می‌دهد. در ادامه، نصب، اولین دمو، Blocks پیشرفته و انتشار روی Hugging Face را قدم‌به‌قدم می‌بینیم.

فهرست مطالب

پیش‌نیازها؛ قبل از نصب Gradio چه چیزهایی لازم دارید؟
نصب Gradio در پایتون؛ یک دستور و تمام
اولین دمو با Gradio؛ رابط ساده در کمتر از ۱۰ خط کد
ساخت رابط پیشرفته با Gradio Blocks؛ چیدمان حرفه‌ای
اتصال مدل واقعی هوش مصنوعی به Gradio؛ نمونه تشخیص متن و تصویر
اشتراک‌گذاری و انتشار دمو؛ از لینک موقت تا Hugging Face Spaces
Gradio در برابر Streamlit و FastAPI؛ کدام را انتخاب کنیم؟
اشتباهات رایج در کار با Gradio
سوالات متداول
جمع‌بندی

پیش‌نیازها؛ قبل از نصب Gradio چه چیزهایی لازم دارید؟

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

پایتون ۱۰ به بالا: نسخه 3.10 تا 3.12 بهترین سازگاری را دارد. با python --version چک کنید.
محیط مجازی: حتماً از venv یا conda استفاده کنید تا تداخل پکیج‌ها پیش نیاید. مخصوصاً اگر قبلاً Streamlit یا FastAPI نصب کرده‌اید.
pip به‌روز: با pip install --upgrade pip مطمئن شوید آخرین pip را دارید.
مرورگر مدرن و اینترنت: برای اجرای لوکال پورت 7860 و برای share نیاز به اینترنت دارید.
مدل آزمایشی: در ابتدا نیازی به مدل سنگین نیست؛ یک تابع ساده def greet(name): کافی است تا رابط را تست کنید.

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

نصب Gradio در پایتون؛ یک دستور و تمام

نصب Gradio به اندازه یک خط است، اما برای جلوگیری از خطاهای رایج، این ترتیب را رعایت کنید:

python -m venv venv
# ویندوز:
venv\Scripts\activate
# مک/لینوکس:
source venv/bin/activate

pip install --upgrade pip
pip install gradio

برای اطمینان از نصب درست، نسخه را چک کنید:

python -c "import gradio as gr; print(gr.__version__)"

نکات مهم:

اگر پشت پروکسی یا اینترنت محدود هستید، از pip install gradio --trusted-host pypi.org --trusted-host files.pythonhosted.org استفاده کنید.
برای کار با مدل‌های Hugging Face، پیشنهاد می‌شود هم‌زمان transformers و torch را هم نصب کنید، اما برای شروع الزامی نیست.
نسخه Gradio 4 به بعد API کمی تغییر کرده؛ اگر کدی از Gradio 3 دارید، پارامترهای inputs و outputs به Interface همچنان کار می‌کنند اما در Blocks نام‌ها کمی متفاوت است.

اولین دمو با Gradio؛ رابط ساده در کمتر از ۱۰ خط کد

ساده‌ترین حالت Gradio، کلاس Interface است. یک تابع تعریف می‌کنید، نوع ورودی و خروجی را می‌گویید و تمام.

import gradio as gr

def greet(name, age):
    return f"سلام {name} عزیز! تو {age} سال داری و آماده‌ای دمو بسازی."

demo = gr.Interface(
    fn=greet,
    inputs=[gr.Textbox(label="نام شما"), gr.Slider(1, 100, value=25, label="سن")],
    outputs=gr.Textbox(label="پیام"),
    title="دمو سلام با Gradio",
    description="اولین رابط تعاملی شما در کمتر از یک دقیقه"
)

demo.launch()

با اجرای این فایل (python app.py) یک لینک لوکال مثل http://127.0.0.1:7860 می‌بینید. روی آن کلیک کنید، نام و سن را تغییر دهید و نتیجه را لحظه‌ای ببینید. برای اشتراک موقت:

demo.launch(share=True)

این حالت یک لینک عمومی https://xxxx.gradio.live می‌سازد که تا 72 ساعت فعال است و برای ارائه سریع به کارفرما یا تیم عالی است. برای اجرای مدل‌های لوکال بزرگ مثل LLM روی سیستم خودتان، بد نیست نگاهی هم به آموزش Ollama؛ اجرای لوکال مدل‌های هوش مصنوعی بدون اینترنت بیندازید و سپس خروجی آن را با Gradio نمایش دهید.

پارامترهای کلیدی Interface

inputs: می‌تواند Textbox، Image، Audio، Slider، Checkbox، Dropdown باشد.
outputs: مشابه ورودی‌ها، مثلاً Label برای کلاس‌بندی، Gallery برای تصاویر.
examples: با examples=[["علی", 23], ["سارا", 30]] نمونه‌های آماده به رابط اضافه کنید تا تست سریع‌تر شود.
allow_flagging: برای جمع‌آوری بازخورد کاربران، روی auto بگذارید.

ساخت رابط پیشرفته با Gradio Blocks؛ چیدمان حرفه‌ای

وقتی بخواهید چند ورودی، چند خروجی، دکمه‌های سفارشی و چیدمان ستونی داشته باشید، باید سراغ Blocks بروید. Blocks مثل یک صفحه‌ساز منعطف است.

import gradio as gr

def summarize(text, max_len):
    # یک خلاصه‌سازی ساده برای دمو
    return text[:int(max_len)] + " ..."

with gr.Blocks(title="دمو خلاصه‌ساز") as demo:
    gr.Markdown("# 📝 دمو خلاصه‌سازی متن با Gradio Blocks")
    gr.Markdown("متن را وارد کنید، طول خلاصه را انتخاب کنید و نتیجه را ببینید.")
    
    with gr.Row():
        with gr.Column():
            inp_text = gr.Textbox(lines=6, label="متن ورودی", placeholder="متن طولانی خود را اینجا بگذارید...")
            inp_len = gr.Slider(50, 500, value=150, step=10, label="حداکثر طول خلاصه")
            btn = gr.Button("خلاصه کن", variant="primary")
        with gr.Column():
            out = gr.Textbox(lines=6, label="خلاصه")
            gr.Examples(["هوش مصنوعی در سال ۱۴۰۵ تحول بزرگی در ابزارهای برنامه‌نویسی ایجاد کرده است...", "Gradio به توسعه‌دهندگان اجازه می‌دهد..."], inputs=inp_text)

    btn.click(fn=summarize, inputs=[inp_text, inp_len], outputs=out)
    gr.ClearButton([inp_text, out])

demo.launch()

مزیت Blocks این است که هر کامپوننت را با .click یا .change به تابع وصل می‌کنید و می‌توانید چند رویداد مختلف برای یک دکمه تعریف کنید. همچنین می‌توانید تم تیره/روشن، لوگو و استایل CSS سفارشی اضافه کنید:

demo.launch(theme=gr.themes.Soft(), css="footer {display:none !important}")

برای دموهای حرفه‌ای، استفاده از gr.Tab برای دسته‌بندی بخش‌ها و gr.Accordion برای تنظیمات پیشرفته بسیار کاربردی است.

اتصال مدل واقعی هوش مصنوعی به Gradio؛ نمونه تشخیص متن و تصویر

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

مثال ۱: تحلیل احساسات با Hugging Face Transformers

import gradio as gr
from transformers import pipeline

# بار اول مدل دانلود می‌شود
sentiment = pipeline("sentiment-analysis", model="distilbert-base-uncased-finetuned-sst-2-english")

def analyze(text):
    result = sentiment(text)[0]
    return f"{result['label']} ({result['score']:.2f})"

gr.Interface(
    fn=analyze,
    inputs=gr.Textbox(label="جمله انگلیسی وارد کنید"),
    outputs=gr.Label(label="نتیجه"),
    title="تحلیل احساسات با Gradio + Transformers",
    examples=["I love Gradio!", "This is terrible."]
).launch()

مثال ۲: ورودی تصویر و خروجی برچسب

import gradio as gr
from transformers import pipeline

classifier = pipeline("image-classification", model="google/vit-base-patch16-224")

def classify_image(img):
    preds = classifier(img)
    return {p['label']: float(p['score']) for p in preds[:3]}

gr.Interface(
    fn=classify_image,
    inputs=gr.Image(type="pil", label="عکس را آپلود کنید"),
    outputs=gr.Label(num_top_classes=3, label="پیش‌بینی"),
    title="تشخیص محتوای تصویر"
).launch()

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

اشتراک‌گذاری و انتشار دمو؛ از لینک موقت تا Hugging Face Spaces

بعد از اینکه دمو لوکال کار کرد، سه سطح اشتراک دارید:

لینک موقت gradio.live: با share=True برای ارائه فوری. محدودیت: نیاز به اینترنت پایدار و زمان انقضای 72 ساعته.
سرور شخصی/VPS: با demo.launch(server_name="0.0.0.0", server_port=7860) و سپس reverse proxy با Nginx. مناسب دمو داخلی سازمان.
Hugging Face Spaces (پیشنهادی): بهترین گزینه رایگان و دائمی. کافی است یک Space از نوع Gradio بسازید، فایل app.py و requirements.txt را پوش کنید.

# requirements.txt
gradio==4.36.0
transformers
torch

در Spaces، فایل app.py باید در روت باشد و آخرین خط demo.launch() بدون share=True باشد؛ خود Spaces پورت را مدیریت می‌کند. مزیت Spaces این است که لینک دائمی https://huggingface.co/spaces/username/demo می‌گیرید و می‌توانید آن را در رزومه یا مقاله قرار دهید.

برای امنیت، هرگز کلید API را هاردکد نکنید؛ از os.environ یا Secrets در Spaces استفاده کنید:

import os
API_KEY = os.getenv("HF_TOKEN")

Gradio در برابر Streamlit و FastAPI؛ کدام را انتخاب کنیم؟

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

معیار	Gradio	Streamlit	FastAPI + فرانت
سرعت ساخت دمو مدل	بسیار سریع (۱-۱۰ خط)	سریع (۲۰-۴۰ خط)	کند (نیاز به API + UI جدا)
مناسب برای	دمو ML/AI، تست ورودی/خروجی مدل	داشبورد داده، تحلیل و نمودار	محصول نهایی مقیاس‌پذیر
کامپوننت‌های آماده ML	Image, Audio, Chatbot, Gallery	Chart, Dataframe, Metric	باید خودتان بسازید
اشتراک‌گذاری	gradio.live + Spaces یک‌کلیکی	Streamlit Cloud	دیپلوی دستی روی سرور
قابلیت سفارشی‌سازی	متوسط (Blocks انعطاف خوب)	متوسط	بسیار بالا
مناسب تولید (Production)	خیر (برای دمو)	خیر (برای نمونه اولیه)	بله

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

اشتباهات رایج در کار با Gradio

اجرای بدون محیط مجازی: نصب Gradio کنار ده‌ها پکیج دیگر باعث تداخل نسخه gradio-client می‌شود. همیشه venv بسازید.
استفاده از share=True روی سرور دائمی: این لینک موقتی است و برای پروداکشن پایدار نیست. برای انتشار دائم از Spaces یا سرور اختصاصی استفاده کنید.
بارگذاری مدل در داخل تابع: اگر pipeline() را داخل def بگذارید، هر درخواست مدل را از نو لود می‌کند و حافظه پر می‌شود. مدل را یک‌بار بیرون تابع لود کنید.
نادیده گرفتن queue: برای مدل‌های کند، حتماً demo.queue() را قبل از launch فعال کنید تا درخواست‌ها صف‌بندی شوند و سرور کرش نکند.
فراموشی اعتبارسنجی ورودی: ورودی خالی، تصویر با فرمت اشتباه یا متن بسیار طولانی را هندل نکنید، اپ خطای 500 می‌دهد. یک if ساده با پیام فارسی اضافه کنید.

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

آیا Gradio رایگان است؟

بله، Gradio کاملاً متن‌باز و رایگان است. اجرای لوکال هیچ هزینه‌ای ندارد. لینک share موقت هم رایگان است و انتشار روی Hugging Face Spaces تا سقف منابع رایگان (CPU basic) بدون پرداخت ممکن است. برای GPU یا منابع بیشتر، پلن پولی Spaces وجود دارد.

تفاوت Interface و Blocks چیست؟

Interface برای دموهای تک‌تابعه و سریع است؛ ورودی و خروجی را لیست می‌کنید و تمام. Blocks برای رابط‌های چندبخشی با چیدمان سفارشی، چند دکمه و منطق پیچیده‌تر است. برای هر پروژه‌ای که بیش از یک ورودی/خروجی دارد، Blocks را پیشنهاد می‌کنیم.

چطور ورودی صوتی یا چت‌بات بسازم؟

از کامپوننت‌های آماده استفاده کنید: gr.Audio(type="filepath") برای صدا و gr.Chatbot() همراه با gr.ChatInterface برای چت‌بات. Gradio به‌صورت پیش‌فرض استریم متن را هم پشتیبانی می‌کند و برای مدل‌های LLM کافی است تابع شما یک generator باشد.

آیا Gradio برای محصول نهایی مناسب است؟

خیر، Gradio برای دمو، نمونه اولیه و ارائه تحقیقاتی عالی است اما برای پروداکشن با ترافیک بالا، احراز هویت و منطق تجاری پیچیده بهتر است خروجی مدل را با FastAPI به API تبدیل کنید و فرانت جدا بسازید. Gradio را به‌عنوان پلی برای تست سریع ببینید نه مقصد نهایی.

Gradio با Streamlit چه فرقی دارد؟

Gradio برای ورودی/خروجی مدل (عکس، صدا، متن، ویدیو) و اشتراک سریع مدل بهینه است؛ Streamlit برای داشبورد داده و نمودار. اگر مدل شما ورودی چندرسانه‌ای دارد، Gradio انتخاب طبیعی‌تر است. جزئیات بیشتر را در مقاله Streamlit که بالاتر لینک شد ببینید.

چرا بعد از launch صفحه سفید می‌آید؟

معمولاً به‌دلیل تداخل پورت 7860 یا کش مرورگر است. پورت را عوض کنید: demo.launch(server_port=7861)، کش را پاک کنید و مطمئن شوید فایروال پورت را نبسته است. همچنین نسخه gradio و gradio-client را همگام نگه دارید.

جمع‌بندی

با Gradio می‌توانید فاصله بین یک مدل آزمایشگاهی و یک دمو قابل لمس را از چند هفته به چند دقیقه کاهش دهید. مسیر پیشنهادی شما:

پایتون 3.10+ و محیط مجازی بسازید و با یک دستور Gradio را نصب کنید.
اولین Interface ساده را با یک تابع دو ورودی اجرا کنید و share موقت را تست کنید.
برای نیاز واقعی، به Blocks مهاجرت کنید و چیدمان ستونی، تب و Example اضافه کنید.
مدل Hugging Face را بیرون تابع لود کنید، queue را فعال کنید و ورودی‌ها را اعتبارسنجی کنید.
دمو را روی Hugging Face Spaces منتشر کنید و لینک دائمی را به اشتراک بگذارید.
برای داشبورد تحلیلی Streamlit و برای محصول نهایی FastAPI را در نظر بگیرید.

همین امروز یک فایل app.py با مثال سلام بسازید، اجرا کنید و نتیجه را با تیم به اشتراک بگذارید؛ Gradio دقیقاً برای همین لحظه سریع ساخته شده است.

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