الوحدة 6 — الأمثلة المعبّأة مسبقًا والتخزين المؤقّت

عرض بلا أمثلة مثل مطعم بلا قائمة طعام. الزائر يقف أمام حقل نصّ فارغ ولا يعرف ماذا يكتب ولا ما الذي يجيده النموذج. الأمثلة المعبّأة مسبقًا تحلّ هذه المشكلة في سطر واحد، والتخزين المؤقّت يجعل نقرها فوريّة. هذه الوحدة تشرح كلا الأداتين، ثمّ تُلحّ على السؤال الأهمّ: أيّ أمثلة تختار؟

examples: قوائم قابلة للنقر

gr.Interface وgr.ChatInterface يقبلان الوسيط examples كقائمة:

import gradio as gr

def resumer(texte):
    return " ".join(texte.split()[:20]) + "…"

gr.Interface(
    fn=resumer,
    inputs=gr.Textbox(lines=6, rtl=True, label="النصّ"),
    outputs=gr.Textbox(rtl=True, label="الملخّص"),
    examples=[
        ["كتب المؤرّخ حسن اللواتي كتابًا مفصّلًا عن قضيّة الجزيرة العربيّة في القرن الحادي عشر."],
        ["يواجه القطاع الصحّيّ ضغطًا متزايدًا بسبب ارتفاع أسعار الأدوية على المستوى العالميّ."],
        ["ناقش المجلس الوطنيّ قانونًا جديدًا يخصّ تنظيم استعمال البيانات الشخصيّة."],
    ],
    title="ملخّص نصّ",
).launch()

بمجرّد تحميل الواجهة، يرى المستخدم بطاقات تحت مكوّن الإدخال. النقر على أيّ منها يُعبّئ الحقل بقيمتها ويُشغّل الدالّة تلقائيًّا. هذا التصرّف بالضبط ما يُحوّل زائر مبتدئ إلى مستعمِل ينتج نتيجة في ثلاث ثوانٍ.

كلّ عنصر في examples قائمة داخليّة تحتوي قيمة لكلّ مكوّن مُدخَل بالترتيب. للتنقّل بين مكوّنَين: [["نصّ 1", 5], ["نصّ 2", 10]] حيث الرقم يمثّل قيمة Slider.

التخزين المؤقّت: cache_examples

عرض ملخّص بسيط يستغرق أقلّ من ثانية. لكن عرضًا يستدعي نموذجًا يستغرق خمس ثوانٍ لكلّ مثال يعني أنّ زائرًا ينقر ثلاثة أمثلة يتحمّل خمس عشرة ثانية من الانتظار. cache_examples="lazy" يحلّ هذا:

gr.Interface(
    fn=classer_image,
    inputs=gr.Image(type="pil"),
    outputs=gr.Label(num_top_classes=3),
    examples=[
        ["images/chat.jpg"],
        ["images/chien.jpg"],
        ["images/renard.jpg"],
    ],
    cache_examples="lazy",
).launch()

القيم الممكنة:

قيمة	متى تُنفَّذ الدالّة؟	متى تُعرض النتيجة؟
False (افتراضيّ)	عند كلّ نقرة	بعد الحساب
"lazy"	أوّل نقرة، ثمّ تُخزَّن	فوريّة في النقرات التالية
True	عند بدء تشغيل الخادم	فوريّة دائمًا

True يُضمن الاستجابة الفوريّة الكاملة لكن يُبطئ بدء الخادم بحاصل ضرب عدد الأمثلة في زمن كلّ مثال. على مساحة Hugging Face التي تنام وتستيقظ، هذا الوقت الإضافيّ يظهر عند كلّ استيقاظ. "lazy" توازن جيّدة: أوّل زائر يدفع الكلفة، والبقيّة تستفيد.

اختيار الأمثلة: القاعدة الذهبيّة

الخطأ الأكثر شيوعًا في اختيار الأمثلة: جميعها ناجحة. المستخدم يجرّبها فيُعجَب ثمّ يجرّب حالة حقيقيّة فيصدَم ويفقد الثقة. القاعدة الذهبيّة:

اجعل الأمثلة تُظهر الحدود بقدر ما تُظهر النجاحات.

مثال لعرض تصنيف صور مُدرَّب على ImageNet:

المثال	الغرض
قطّة منزليّة عاديّة	يظهر أنّ النموذج يعمل على الحالة الأكثر شيوعًا
كلب من سلالة نادرة	يظهر النجاح على حالة مفصّلة
رسم كاريكاتوريّ لقطّة	يُظهر أنّ النموذج يفشل خارج نطاق تدريبه
صورة داخل غرفة مظلمة	يُظهر أثر الإضاءة السيّئة على الاحتمالات
علم دولة	يُظهر أنّ النموذج يخترع تصنيفًا غير موجود بدل الاعتراف بجهله

هذا التنظيم يعلّم المستخدم متى يثق بالنموذج ومتى لا. عرض بلا هذا الصدق يخلق توقّعات مبالغة يحاسبك عليها المستخدم لاحقًا.

أمثلة ChatInterface

في المحادثة، examples قائمة سلاسل بسيطة تُملأ في حقل الرسالة عند النقر:

gr.ChatInterface(
    fn=repondre,
    examples=[
        "لخّص لي مبدأ عمل الشبكات العصبيّة الالتفافيّة.",
        "ما الفرق بين التعلّم المُوجَّه وغير المُوجَّه؟",
        "اقترح خطّة دراسة لعلوم البيانات في ثلاثة أشهر.",
    ],
    title="مساعد تعلّم الذكاء الاصطناعيّ",
).launch()

هنا أيضًا، الأمثلة العربيّة تشجّع المستخدم على الكتابة بالعربيّة وتُظهر أنّ المساعد يُتقنها. لو كانت الأمثلة بالإنكليزيّة فقط، فسيفترض كثير من المستخدمين أنّ العرض لا يدعم العربيّة أصلًا.

تخزين الأمثلة الديناميكيّ

في بعض الحالات، يجب أن تتغيّر الأمثلة حسب حالة المستخدم أو حسب تحديث لبيانات: لكلّ زائر جديد أمثلة مختلفة. Blocks يسمح بذلك عبر gr.Dataset:

import gradio as gr, random

echantillons = [
    ["مثال 1", 10],
    ["مثال 2", 20],
    ["مثال 3", 30],
    ["مثال 4", 40],
]

with gr.Blocks() as demo:
    entree = gr.Textbox(rtl=True)
    curseur = gr.Slider(1, 100, value=10)
    sortie = gr.Textbox(rtl=True)

    def calculer(t, n):
        return f"العدد {n} · {t}"

    entree.change(calculer, [entree, curseur], sortie)

    ex = gr.Dataset(components=[entree, curseur], samples=random.sample(echantillons, 3))
    ex.select(lambda t: t, ex, [entree, curseur])

demo.launch()

هذا مفيد لعرض يُبرِز في كلّ فتحة أمثلة مختلفة، فيُشجّع الزائر على العودة ويُحدّث الإحساس بأنّ العرض «حيّ».

ملفّات الأمثلة على مساحة Hugging Face

عند نشر عرض على مساحة، مسارات الأمثلة يجب أن تكون نسبيّة إلى جذر المستودع. ["images/chat.jpg"] يعمل إذا كان مجلّد images/ موجودًا في نفس مستودع المساحة، وليس مسارًا على جهازك المحلّيّ. هذا خطأ شائع يُنتج «صور مكسورة» في العرض المنشور.

قياس أثر الأمثلة على الاستعمال

لا تكفي الأمثلة أن تكون موجودة، بل يجب معرفة أيّها يُنقَر أكثر. gr.on() مع تسجيل بسيط يفعل ذلك:

import logging
logging.basicConfig(filename="clics.log", level=logging.INFO)

def journaliser_exemple(ex):
    logging.info(f"مثال منقور: {ex}")

بعد أسبوع من الاستعمال، ستعرف: هل الأمثلة المختارة تُغطّي ما يهمّ المستخدم، أم أنّه يبحث عن شيء آخر؟ هذه القراءة تُغذّي التصميم التالي للعرض.

الخلاصة

• examples قائمة قيم مسبقة، تُملأ الحقل بنقرة وتُشغّل الدالّة تلقائيًّا.
• cache_examples يخزّن النتائج مسبقًا؛ "lazy" توازن جيّدة، وTrue يُبطئ بدء التشغيل.
• اختيار الأمثلة أهمّ من وجودها: مزج بين نجاحات وحدود يعلّم المستخدم متى يثق ومتى لا.
• الأمثلة بلغة المستخدم إشارة مباشرة على أنّ العرض يعمل بها، فلا يفترض المستخدم العكس.

الوحدة التالية: قائمة الانتظار وحدود التزامن، كي لا ينهار العرض تحت خمسة مستخدمين متزامنين.