العودة إلى كل المقالات
برمجة وتطوير آخر تحديث: 3 نوفمبر 2026

أقواس JSON تكسر قالب البرومبت: افصل المتغيرات عن النص الحرفي

قالب ورقي كريمي ذو نافذة حول طائر أوريغامي أزرق وثلاث بطاقات إدخال فارغة وأدوات طباعة على طاولة
قالب ورقي كريمي ذو نافذة حول طائر أوريغامي أزرق وثلاث بطاقات إدخال فارغة وأدوات طباعة على طاولة.

يتوقف القالب قبل أن يصل إلى أي نموذج

يفشل المثال الأول عند استعمال str.format مع نص يجمع كائناً ظاهرياً بصيغة JSON وموضعاً اسمه subject بين أقواس. يمرر الاختبار subject بقيمة vase، لكنه يتوقع KeyError بدلاً من ناتج جاهز. السبب أن الأقواس الخارجية ليست محارف محايدة بالنسبة إلى format؛ فهي تدخل في تفسير حقول التنسيق أيضاً. لا توجد هنا استجابة API مرفوضة أو مشكلة في قدرة نموذج على فهم الموضوع. يتوقف تركيب النص محلياً قبل وجود أي طلب شبكة.

يتكرر هذا الالتباس عندما ينسخ صاحب مشروع قالباً من وصف نصي إلى سلسلة Python ثم يضيف له استبدالاً سريعاً. يبدأ بالتفكير في مظهر الناتج الذي يريد إرساله، بينما ينسى أن النص سيقرأ أولاً كلغة قالب. نحتاج إلى فصل قراءتين: قواعد مواضع الاستبدال التي يطبقها البرنامج، ومعنى النص الذي سيذهب إلى مستهلك لاحق. اختبار الفشل الأصلي يحفظ هذه الحالة الصغيرة حتى لا نعالجها بتغيير إعدادات نموذج لم تستدعِه الشيفرة أصلاً.

لا تعني النتيجة أن format عاجزة عن التعامل مع نص يحتوي JSON. يمكن تصميم قالب يهرب الأقواس الحرفية وفق قواعدها. الاختيار في هذا المشروع هو استعمال string.Template بعلامات دولار، كي تبقى أقواس JSON في المثال نصاً حرفياً ولا تتنافس مع أسماء المواضع. هذا تغيير في لغة القالب لا في صيغة الملف المطلوب من نموذج، ولا دليل على أن صورة ستصبح أفضل بسبب تبديل وسيلة الاستبدال.

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

اقرأ render_prompt كعقد صغير لا كمحرك قوالب كامل

تستعمل string.Template مواضع بعلامة دولار، ويكتب الدولار الحرفي بصيغة $$. تتيح is_valid وget_identifiers فحص القالب وأسماء مواضعه. Python 3.12 string.Template reference

تستقبل الدالة pattern وvalues، وتنشئ Template من النمط ثم تفحص is_valid. إذا كان في النمط موضع دولار غير صالح، تثير ValueError قبل فحص القيم. بعد ذلك تقارن مجموعة الأسماء التي تعيدها get_identifiers بمجموعة مفاتيح القيم المرسلة. لا يكفي أن تكون أسماء القالب موجودة بين مفاتيح كثيرة؛ اخترنا أن تتساوى المجموعتان تماماً. لذلك يرفض المثال المتغير الناقص والمتغير الزائد بدلاً من تجاهلهما دون إشارة.

بعد مطابقة الأسماء تتحقق الدالة من أن كل قيمة نصية، ثم تستعمل substitute لإنتاج النتيجة. هذا الترتيب يعطي خطأ القالب أولوية على محاولة إدخال قيم فيه، ويمنع تحويل رقم أو قاموس إلى نص بشكل ضمني. العقد المقصود نمط نصي وخريطة أسماء إلى نصوص. لا يحتوي المثال فحصاً شاملاً لكل نوع يمكن تمريره بدلاً من الخريطة، ولا نعرضه كمكتبة تتحمل كل كائن Python أو تستنتج طريقة عرضه.

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

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

prompt_slots.py

from string import Template

def render_prompt(pattern,values):
    template=Template(pattern)
    if not template.is_valid():raise ValueError('Invalid dollar placeholder')
    if set(template.get_identifiers()) != set(values):raise ValueError('Supply exactly the declared slots')
    if any(not isinstance(v,str) for v in values.values()):raise TypeError('Slot values must be strings')
    return template.substitute(values)

اجتازت المجموعة الأصلية 9 طرق والمجموعة الإضافية 7 طرق، بمجموع 16 طريقة مختلفة في Python 3.12.3 على Windows. حفظ ناتج نص عربي وحمولة JSON منفصلة. تشمل النتائج استبدالاً وتسلسلاً محليين، ولا تشمل طلب نموذج أو واجهة أو قياس أمان أو جودة صورة.

أقواس حرفية وموضع دولار في النتيجة نفسها

في test_dollar_slots_preserve_braces نستعمل نمطاً يحتوي output بقيمة png وsubject بقيمة الموضع $subject، ونمرر vase. يتوقع الاختبار نصاً ما زال يحتفظ بالأقواس وحقول المثال، مع استبدال قيمة الموضع فقط. هذا هو الإصلاح المحلي للالتباس الأول: لم تعد الأقواس الخارجية تطلب من محرك القالب تفسير اسم حقل منها. وقيمة png جزء من النص الذي اخترناه، وليست إعداداً أرسلناه بالفعل إلى أداة صور.

أضفنا test_literal_pattern_without_slots لنفحص نمطاً فيه أقواس وoutput لكن بلا مواضع دولار، مع خريطة قيم فارغة. يعود النص الحرفي كما هو. إذا قدم المستدعي مفاتيح إضافية لهذا القالب، فلن تتساوى مجموعة الأسماء الفارغة مع مفاتيحه، وسيرفضها العقد الحالي. لا نحتاج إلى جعل كل حقل في المثال قابلاً للاستبدال؛ اختر المواضع التي تريد فعلاً أن يملأها المستخدم واترك بقية البنية نصاً ثابتاً واضحاً.

يمكن أيضاً كتابة الموضع بصيغة ${subject}، وقد اختبرناها في test_braced_slot. هذه أقواس تخص تعريف موضع الدولار، ولا تعيد المشكلة الأصلية مع الأقواس الحرفية الأخرى. عند بناء أسماء متجاورة مع نص تالٍ، يفيد أن يعرف من يكتب القالب أين ينتهي اسم الموضع. لا تغير الاسم في واجهة المشروع ثم تبقِ خريطة القيم بالمفتاح القديم؛ المطابقة الصارمة ستكشف ذلك بوصفه اختلافاً في عقد القالب لا خطأ في النموذج.

لا تجعل شكل الناتج المقروء دليلاً على صلاحية كل بنية بيانات قد تشبهه. المثال الذي أدخل vase بلا اقتباسات داخلية أعطى النص المتوقع، لكن ذلك لا يثبت أن كل قيمة أخرى ستحافظ على JSON صالح. لهذا نعرض اختبار الاقتباس لاحقاً قبل أي تصميم لطلب API. نجاح حالة بسيطة ينبغي أن يظل حالة بسيطة يمكن توسيعها بأمثلة محددة، لا تصريحاً بأن وسيلة الاستبدال تتولى التهريب والتحقق وكل قواعد الصيغة المستهدفة.

الدولار الحرفي لا يساوي موضعاً جديداً

يفحص test_literal_dollar النمط budget $$12 مع خريطة فارغة، ويتوقع budget $12. في المقابل، يمرر test_invalid_dollar_sequence النمط $12 ويتوقع ValueError. الرقم المكتوب بعد الدولار ليس اسم موضع صالحاً في هذا المثال. لذلك ينبغي التمييز عند كتابة أسعار توضيحية أو رموز داخل النص بين الدولار الذي تريد ظهوره في النتيجة وبين العلامة التي تبدأ اسم متغير. لا تصلح إضافة مفتاح اسمه 12 إلى القيم لإلغاء قرار is_valid السابق.

يحفظ test_value_is_not_recursively_expanded الحد الآخر: إذا كانت قيمة subject هي $other، فإن الناتج هو $other نفسه. لا تعود الدالة لتقرأ القيمة التي أدخلتها كلغة قالب ثانية. هذا سلوك مفيد لفهم ترتيب التركيب؛ يفسر النمط مرة، ويضع فيه النصوص المقدمة. لكنه لا يحلل تعليمات تلك النصوص ولا يقرر كيف سيقرأها مستهلك لاحق. لا تستنتج منه دفاعاً ضد حقن البرومبت أو ضماناً بأن نموذجاً سيتجاهل عبارة كتبها مستخدم داخل القيمة.

وفي test_dot_is_literal_not_attribute_access يكون النمط $subject.name والقيمة vase، فتعود vase.name. النقطة واللاحقة نص بعد الموضع، لا طلب للوصول إلى خاصية name على كائن. إذا كنت تنقل قالباً من نظام آخر يدعم حقولاً متداخلة، فلا تفترض أن العلامة نفسها ستحمل المعنى نفسه هنا. عرّف المفاتيح البسيطة التي تدعمها الدالة، أو ابن القيم المركبة في خطوة صريحة قبل تسليمها لها.

أما test_repeated_slot فيكرر $x حول فاصل ويقدم قيمة a مرة واحدة، فتظهر في الموضعين. لا تحتاج إلى خريطة بأسماء x1 وx2 ما دام المطلوب استعمال القيمة نفسها. وإذا أردت موضوعين مختلفين في الوصف، فاختر اسمين فعليين يعبران عن دوريهما. يساعد هذا القرار عند تصميم محرر قالب لاحق، لأن أسماء المواضع تصبح حقولاً معروفة يمكن شرحها، بدلاً من الاعتماد على البحث والاستبدال العشوائي في كل كلمة متكررة من النص.

القيم العربية مدعومة واختيار اسم الموضع أمر آخر

يرسل test_arabic_value الاسم البرمجي subject مع قيمة إبريق إلى النمط scene: $subject، ويتوقع scene: إبريق. هذه مقارنة نصية محلية تؤكد مرور القيمة العربية في الحالة المسجلة. لا تتطلب ترجمة الكلمة إلى الإنجليزية، ولا تختبر جودة صورة إبريق أو قدرة نموذج على إخراج كتابة عربية. القيمة التي تتغير هي جزء من السلسلة في الذاكرة، وتبقى عملية التوليد خارج هذا المثال.

أضفنا test_default_arabic_slot_name_is_rejected للنمط $موضوع مع خريطة تحتوي المفتاح العربي نفسه. يتوقع الاختبار ValueError مع Template الافتراضية المستعملة في الكود. هذا لا يعني أن القيم العربية مرفوضة، بل يبين أن اسم الموضع في لغة القالب له قواعد تختلف عن محتوى القيمة. يمكن لمشروع عربي أن يعرض عنوان الحقل الموضوع في الواجهة، بينما يحتفظ باسم subject في العقد البرمجي الذي ترسله الواجهة إلى الدالة.

احفظ قيم إعدادات لا تستبدل الصفر أو False قبل بناء النص. وبعد تحديد المعنى المقصود، حول القيم المطلوبة إلى نص وفق عقد القالب؛ هذه الدالة ترفض القيم غير النصية ولا تختار صيغة عرضها نيابة عن التطبيق.

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

حفظنا ناتج الحالة العربية في outputs/arabic-prompt.txt، وهو نص فعلي تولد من render_prompt. لا نستعمل الملف دليلاً على إرسال الطلب أو الحصول على صورة؛ إنه مخرج تركيب نص فقط. يمكن للقارئ مقارنته بالقالب والقيمة لمعرفة ما تغير. ولو أضيفت خطوة توليد لاحقاً، فستحتاج سجلها وطلبها ومخرجها الخاص، بدلاً من إسناد صورة توضيحية أُنشئت بطلب آخر إلى هذا النص لمجرد أن كليهما يتحدث عن صورة.

قيمة نصية فارغة ليست قيمة مفقودة

تفحص الدالة أن القيم نصوص، لكنها لا تشترط أن تحتوي حروفاً. في test_empty_text_value_is_accepted يستعمل القالب Draw $subject قيمة فارغة، وتكون النتيجة Draw مع مسافة تالية. هذا نجاح وفق العقد الحالي لا خطأ مكتوم. فإذا كان موضوع الصورة مطلوباً في مشروعك، أضف قاعدة محتوى قبل تركيب البرومبت، وحدد هل النص المكون من مسافات يعد فارغاً أيضاً. لا تنسب هذا الفحص إلى isinstance الذي يجيب عن سؤال النوع فقط.

يقارن test_missing_or_extra_slot حالتين فرعيتين داخل طريقة واحدة: خريطة فارغة مع قالب يطلب x، وخريطة تحتوي x وy مع القالب نفسه. كلتاهما تثير ValueError لعدم تساوي الأسماء المطلوبة والمقدمة. يظل المفتاح الموجود بقيمة نصية فارغة مختلفاً عن مفتاح لم يقدم. هذه التفرقة تساعد الواجهة على عرض رسالة دقيقة؛ يمكنها أن تقول إن الحقل ناقص في الحالة الأولى أو إن محتواه غير كافٍ وفق قاعدة التطبيق في حالة أخرى.

وفي test_nonstring_value نمرر العدد 1 إلى x ونتوقع TypeError. لا تحول الدالة الرقم إلى سلسلة 1 نيابة عن المستدعي. إذا احتاج القالب بعداً أو عدداً، فصمم في خطوة الإعداد كيفية عرضه ووحدته ثم مرر النص الناتج. يمكن أن تعني قيمة رقمية عدد صور أو نسبة أو ميزانية توضيحية، ولا تستطيع الدالة استنتاج ذلك من النوع. قرار التحويل الصريح يمنع خلط واجهة الأعداد بوظيفة استبدال نص عامة.

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

اختبار الاقتباس يكشف ما لا تفعله substitute

يمرر test_quote_in_value_is_not_json_escaped القيمة a"b إلى موضع محاط باقتباسين داخل نص يشبه JSON. ينفذ الاستبدال النصي، لكن محاولة json.loads على الناتج تثير JSONDecodeError. هذه النتيجة مقصودة في الاختبار: نريد دليلاً واضحاً على أن render_prompt لا تهرب الاقتباس وفق قواعد JSON. لا نفشل الاختبار لأنه كشف هذا الحد، ولا نصف الناتج بأنه JSON صالح لمجرد أن القالب قبل الاستبدال كان يبدو كذلك.

يحل هذا المثال التباساً مهماً بين بقاء الأقواس وبين صلاحية البنية كلها. يترك Template الأقواس الحرفية، لكنه لا يعرف أن قيمة subject موضوعة داخل سلسلة JSON أو ما قواعد تهريبها. وقد يكون القالب في مشروع آخر نصاً عادياً لا يحتاج إلى JSON أصلاً. تحميل الدالة القاعدتين معاً سيجعل معنى الاستبدال غامضاً. الأفضل أن تحدد ما السلسلة التي تبنيها، وما المكون الذي سيتولى تسلسل البيانات إذا احتجت بنية منظمة.

لم نفتح الناتج في واجهة خدمة ولم نرسل JSON معيباً إلى API. يحدث الرفض في json.loads المحلي على قيمة محددة داخل الاختبار. لذلك لا توجد نتيجة عن كيفية تعامل موفر مع الحمولة أو رسالة خطأ من خدمة بعينها. إذا رأيت في مشروعك خطأ طلب شبكي، افحص أولاً الناتج المحلي والطبقة التي تسلسله، ولا تستعمل هذا الاختبار لتخمين تفاصيل موفر لم نفحصه. النتيجة التي نملكها أضيق وأوضح: الاقتباس المدخل لم يهربه الاستبدال النصي.

ابن حمولة البيانات منفصلة عن النص الذي بداخلها

يعرض test_separate_json_serialization_roundtrips مساراً مختلفاً: نبني قاموساً بقيمة subject الأصلية a"b، وبقيمة prompt الناتجة من Draw $subject، ثم نستعمل json.dumps على القاموس كله ونعيد قراءته بواسطة json.loads. يتوقع الاختبار مساواة القاموس المعاد بالأصلي. هذا دليل فعلي على الحالة المحلية المحددة، لا على قبول طلب عند موفر. يحتفظ ملف outputs/separate-payload.json بالمخرج المنظم الذي أنشأناه بهذه الطريقة كي يستطيع القارئ فحصه.

الفكرة أن يكون البرومبت قيمة نصية داخل بنية البيانات، لا وسيلة يدوية لبناء علامات الاقتباس المحيطة بكل حقل. حين يسلسل json.dumps القاموس، يعرف أنه يتعامل مع قيم نصية ضمن JSON. أما render_prompt فيظل مسؤولاً عن مواضع الدولار داخل النص نفسه. لا يحتاج صاحب القالب إلى إدخال محارف تهريب JSON في كل قيمة ليحافظ على حمولة النقل. وما يعود بعد القراءة هو النص المقصود، بما فيه الاقتباس الموجود في القيمة الأصلية.

يمكن أن يكون النص داخل prompt طبيعياً لا يحتوي أي مثال JSON، أو يحتوي مثالاً حرفياً يحتاج مراجعة مستقلة إذا كان مطلوباً تفسيره لاحقاً. تسلسل الحمولة الخارجية لا يحول كل مثال نصي داخلي إلى بيانات صحيحة. فإذا أراد التطبيق إرسال تعليمات تطلب مخرجاً منظماً، فطريقة تعريف ذلك المخرج سؤال تكامل آخر. لم نفحص هنا مواصفات استجابة نموذج أو تحقق مخطط لها. اختبرنا بناء القيم وتسلسل القاموس ثم قراءته فقط.

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

صمم محرر القالب حول أخطاء محددة

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

اجعل المعاينة المقترحة نصاً يمكن نسخه ومقارنته، مع توضيح أي القيم فارغة وأيها ناقص. لا تغير النص في الخلفية لكي يبدو الناتج أجمل ثم تسجل بصمة القالب القديم. وإذا عرضت نتيجة الاستبدال بجانب النمط، فاحتفظ بالفرق بين العلامة الموجودة في القالب والقيمة النهائية. اختبار القيمة $other يبين لماذا قد يظل دولار في الناتج دون أن يكون خطأً في اكتشاف المواضع: جاء من النص المدخل ولم يقرأ كقالب ثانٍ.

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

احتفظ بنسخة القالب دون كشف القيم الحساسة

يمكن لسجل مشروع مقترح أن يحفظ معرف القالب ونسخته وأسماء المواضع وطريقة التحقق، ثم يحفظ الناتج الذي يسمح عقد الخصوصية بتخزينه. لا يلزم إدخال أسرار اتصال داخل البرومبت أو طباعتها في تقرير الخطأ. وإذا كانت بعض القيم خاصة، فحدد ما الذي تحتفظ به لإعادة الإنتاج وما الذي تنقحه في السجل المشترك. render_prompt لا ينفذ سياسة تسجيل ولا يعرف الفرق بين قيمة وصف عادي ومعلومة خاصة؛ هذه مسؤولية المستهلك الذي يملك سياق استخدامها.

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

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

كرر الاختبارات الستة عشر واقرأ الحالات الفرعية

احفظ prompt_slots.py وtest_example.py وtest_contract.py في مجلد واحد. تعتمد التجربة على string وjson وunittest من المكتبة القياسية في البيئة المسجلة Python 3.12.3 على Windows. شغّل في نسختك python -m unittest discover -s . -p test_example.py -v ثم الأمر المقابل مع test_contract.py. هذه تعليمات إعادة تشغيل مختصرة؛ السجل يحتفظ بالمفسر ومسار الاكتشاف الفعليين وبصمات الشيفرة والاختبارات التي اجتازت الفحص المحلي.

تحتوي المجموعة الأصلية 9 طرق، وتحتوي المجموعة الإضافية 7 طرق، فيكون المجموع 16 طريقة مختلفة. تضم طريقة missing_or_extra حالتين فرعيتين داخل حلقة، فلا نزيد عدد الطرق بسبب وجود نتيجتي رفض فيها. كذلك لا نحسب ملف النص العربي أو ملف الحمولة كاختبارين إضافيين لمجرد حفظهما. هما مخرجان فعليان يمكن فحصهما، بينما الاختبارات لها أسماء وassertions ونتائج تشغيل مستقلة. يفيد هذا التمييز عندما تقارن سجلات أكثر من محاولة تحرير أو تنفيذ.

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

اختر الأداة وفق الشيء الذي تريد بناءه

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

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

تستطيع الآن تكرار الخلل المحلي وإصلاح لغة المواضع، وفحص حدود الدولار والقيم العربية والاقتباس، وحفظ حمولة منظمة على نحو منفصل. تظل خطوة التوليد الفعلية عملاً لاحقاً يحتاج أداة ومخرجاً، لا افتراضاً ملحقاً بنجاح الاختبارات. عند دمج الوحدة في مشروع، احتفظ بالقالب والقيم المسموح بها وبسجل النسخة، وراجع الناتج النصي قبل نقله إلى الطبقة التالية. بذلك يمكن تفسير خطأ التركيب من الشيفرة نفسها بدلاً من اتهام نموذج لم يتلق الطلب بعد.

test_example.py

import unittest
from prompt_slots import render_prompt
class TemplateTests(unittest.TestCase):
 def test_format_baseline_interprets_json_braces(self):
  with self.assertRaises(KeyError):'{"output":"png","subject":"{subject}"}'.format(subject='vase')
 def test_dollar_slots_preserve_braces(self):self.assertEqual(render_prompt('{"output":"png","subject":"$subject"}',{'subject':'vase'}),'{"output":"png","subject":"vase"}')
 def test_arabic_value(self):self.assertEqual(render_prompt('scene: $subject',{'subject':'إبريق'}),'scene: إبريق')
 def test_value_is_not_recursively_expanded(self):self.assertEqual(render_prompt('$subject',{'subject':'$other'}),'$other')
 def test_literal_dollar(self):self.assertEqual(render_prompt('budget $$12',{}),'budget $12')
 def test_repeated_slot(self):self.assertEqual(render_prompt('$x / $x',{'x':'a'}),'a / a')
 def test_missing_or_extra_slot(self):
  for values in [{},{'x':'a','y':'b'}]:
   with self.subTest(values=values),self.assertRaises(ValueError):render_prompt('$x',values)
 def test_nonstring_value(self):
  with self.assertRaises(TypeError):render_prompt('$x',{'x':1})
 def test_invalid_dollar_sequence(self):
  with self.assertRaises(ValueError):render_prompt('$12',{})

test_contract.py

import json,unittest
from prompt_slots import render_prompt

class PayloadContractTests(unittest.TestCase):
    def test_quote_in_value_is_not_json_escaped(self):
        rendered=render_prompt('{"subject":"$subject"}',{'subject':'a"b'})
        with self.assertRaises(json.JSONDecodeError):json.loads(rendered)

    def test_separate_json_serialization_roundtrips(self):
        value='a"b'
        payload={'subject':value,'prompt':render_prompt('Draw $subject',{'subject':value})}
        self.assertEqual(json.loads(json.dumps(payload,ensure_ascii=False)),payload)

    def test_literal_pattern_without_slots(self):
        self.assertEqual(render_prompt('{"output":"png"}',{}),'{"output":"png"}')

    def test_empty_text_value_is_accepted(self):
        self.assertEqual(render_prompt('Draw $subject',{'subject':''}),'Draw ')

    def test_braced_slot(self):
        self.assertEqual(render_prompt('Draw ${subject}',{'subject':'vase'}),'Draw vase')

    def test_dot_is_literal_not_attribute_access(self):
        self.assertEqual(render_prompt('$subject.name',{'subject':'vase'}),'vase.name')

    def test_default_arabic_slot_name_is_rejected(self):
        with self.assertRaises(ValueError):render_prompt('$موضوع',{'موضوع':'إبريق'})

أُعد المقال بمساعدة أدوات ذكاء اصطناعي ومراجعات آلية. شُغلت الشيفرة الأصلية محلياً ضمن نطاق الاختبارات المسجل. الصورة الرئيسية توضيحية، وليست تصويراً ميدانياً أو دليلاً على اختبار متصفح أو جدول بيانات أو فيديو.

التعليقات

كن أول من يعلّق على هذا المقال.

أضف تعليقاً

بريدك لن يُنشر. الحقول المطلوبة معلَّمة بنجمة.