الانتقال إلى المحتوى الرئيسي
احفظ رسائلك مع {{variables}} في إعداد مسبق، فلا يرسل تطبيقك سوى مرجع الإعداد المسبق وقيم المتغيرات. يتحقق Phaseo من القيم، ويملأ الرسائل، ويرسل الطلب إلى نموذج الإعداد المسبق. لا يحتاج تغيير الموجّه في لوحة التحكم إلى نشر جديد، ويحصل كل مستدعٍ على الصياغة والأدوات وصيغة الاستجابة نفسها. تعمل القوالب على POST /v1/chat/completions وPOST /v1/responses وPOST /v1/messages.

أنشئ قالبًا واستدعِه

1

اكتب القالب

افتح الإعدادات ← الإعدادات المسبقة، وأنشئ إعدادًا مسبقًا أو افتح واحدًا، واختر نموذجه، وافتح علامة التبويب قالب الموجّه. أضف الرسائل واكتب المتغيرات بين قوسين معقوفين مزدوجين:
يسرد المحرر كل متغير يعثر عليه. اضبط نوعه، وما إذا كان مطلوبًا، وقيمته الافتراضية، ووصفه. املأ لوحة جرّبه لترى الرسائل الدقيقة التي سيرسلها الـ Gateway، ثم احفظ.بعد حفظ الإعداد المسبق، يرسل تشغيل الإعداد المسبق المحفوظ طلبًا حقيقيًا بقيم الاختبار الخاصة بك ويعرض الرد والنموذج وأعداد الـ tokens. ويستهلك أرصدة مساحة عملك. تحتوي اللوحة نفسها على شيفرة cURL وTypeScript وPython للطلب، معبأة بقيم الاختبار الخاصة بك.
2

أرسل المتغيرات

أشر إلى الإعداد المسبق في prompt.id وضع القيم في prompt.variables. احذف model، أو اضبطه على المرجع نفسه.
3

تحقّق من الطلب

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

استخدم القوالب من كل نقطة نهاية

يعمل كائن prompt نفسه على نقاط النهاية الثلاث. تصبح رسائل النظام والمطوّر في القالب تعليمات النظام لنقطة النهاية، وتأتي رسائله الأخرى قبل أي محادثة يرسلها طلبك. يمكنك إرسال محادثة مع القالب. على سبيل المثال، يمكن لطلب دردشة أن يضيف أدوار المتابعة من المستخدم بعد رسائل القالب:

صيغة القوالب

تستخدم القوالب مجموعة فرعية صغيرة من Mustache خالية من المنطق. لا يُنفَّذ أي شيء في القالب كشيفرة أبدًا. تُدرج القيم كنص عادي، دون تهريب HTML. يمكن للقيمة أن تغيّر نص رسالة لكنها لا تغيّر بنية الطلب أبدًا. إذا لم ينتج عن عرض رسالة سوى مسافات بيضاء، فإنها تُحذف. استخدم هذا لجعل رسالة كاملة اختيارية:
لتكرار نص لكل عنصر في قائمة، افتح قسمًا على القائمة واستخدم {{.}} للعنصر الحالي:
لا تُدعم القوالب الجزئية ({{> name}})، والوسوم غير المهرّبة ({{{name}}} و{{& name}})، وتغيير المحددات، ودوال lambda، ويرفض المحرر وواجهة API القوالب التي تستخدمها.

المتغيرات

لكل متغير نوع. لا تحتاج إلى التصريح عن متغير إلا لتغيير قيمه الافتراضية؛ المتغيرات المستخدمة في الرسائل دون تصريح هي نص مطلوب. يمكن أن يحتوي كل متغير أيضًا على:
  • required: يفشل الطلب عندما تكون القيمة مفقودة. لا يمكن أن يكون للمتغير المطلوب قيمة افتراضية.
  • default: تُستخدم عندما يترك الطلب القيمة. يجب أن تطابق النوع.
  • description: يُعرض في المحرر وفي رسائل الخطأ، حتى 500 حرف.
الاسم المستخدم فقط لفتح الأقسام، مثل notes وexamples أعلاه، اختياري ويقبل أي قيمة. تُفحص الطلبات بصرامة. تعيد القيمة المطلوبة المفقودة، أو القيمة من نوع خاطئ، أو الاسم غير الموجود في القالب الخطأ 400 الذي يسرد كل المشكلات دفعة واحدة، حتى لا يُسقط خطأ إملائي جزءًا من الموجّه بصمت.

متغيرات الصور

يملأ متغير الصورة جزء محتوى كاملًا من رسالة مستخدم، لذا يحدد القالب موضع الصورة. في المحرر، اختر إضافة صورة داخل رسالة مستخدم. في واجهة API، استخدم جزءًا من نوع variable:
يمكن للطلب إرسال كل صورة كعنوان URL بصيغة https، أو عنوان URL بصيغة data:image/...، أو جزء صورة بشكل chat completions أو Responses أو Messages. يحوّلها Phaseo إلى صيغة نقطة النهاية التي استدعيتها. يجب أن يقبل النموذج المختار إدخال الصور.

الأدوات وصيغة الاستجابة

يمكن أن يتضمن القالب tools وtool_choice وresponse_format، مكتوبة بشكل chat completions (راجع استدعاء الأدوات والمخرجات المنظَّمة). يحوّلها Phaseo لنقطتي النهاية Responses وMessages. يفوز الطلب دائمًا عندما يضبط الاثنان الشيء نفسه:
  • تُدمج الأدوات حسب اسم الدالة. إذا عرّف الطلب أداة بالاسم نفسه، يُستخدم تعريف الطلب.
  • تستبدل قيمة tool_choice وصيغة الاستجابة في الطلب (response_format أو text.format أو output_config.format) قيم القالب.
تعمل معاملات الطلب مثل temperature وmax_tokens كالمعتاد. لا تملأ القيم الافتراضية للإعداد المسبق إلا الحقول التي يتركها الطلب.

أنشئ قالبًا عبر API

تُخزَّن القوالب في config.prompt الخاص بالإعداد المسبق. أنشئ الإعداد المسبق أو حدّثه باستخدام مفتاح API للإدارة يملك صلاحية presets:write:
يتحقق Phaseo من القالب عند حفظه. يُرفض القالب الذي يحتوي على خطأ في الصيغة، أو نوع غير معروف، أو قيمة افتراضية لا تطابق نوعها، بالخطأ 400 invalid_prompt_template مع موضع كل مشكلة، هنا وفي المحرر على حد سواء. تصل التغييرات المحفوظة إلى الطلبات خلال دقيقتين تقريبًا.

الإصدارات والتسميات

في كل مرة تنشر فيها إعدادًا مسبقًا، يحفظ Phaseo إصدارًا غير قابل للتغيير (راجع الإعدادات المسبقة). تشغّل الطلبات أحدث إصدار منشور ما لم تثبّت إصدارًا. يستخدم الطلب المثبّت نماذج ذلك الإصدار ومعاملاته وقالبه معًا. ثبّت إصدارًا باستخدام prompt.version:
يقبل prompt.version تسمية إصدار مثل v3 أو 1.2.0 أو 2026.10.27، أو تسمية مثل production. يمكنك أيضًا وضع الإصدار في معرّف النموذج، مع قالب أو بدونه:
تستخدم الإعدادات المسبقة العامة @publisher/support-triage@production. إذا ثبّت كل من model وprompt.version إصدارًا، فيجب أن يسمّيا الإصدار نفسه.

التسميات

التسمية اسم، مثل production أو staging، يشير إلى إصدار منشور واحد. تتكون التسميات من 1 إلى 32 حرفًا لاتينيًا صغيرًا أو رقمًا أو شرطة أو شرطة سفلية، وتبدأ بحرف، ولا يمكن أن تشبه تسمية إصدار (v1، v2). في الإعدادات ← الإعدادات المسبقة، افتح الإعداد المسبق. يحفظ نشر، بجانب حفظ المسودة، تغييراتك وينشرها كالإصدار التالي. افتح الإصدارات والتسميات لإدارة التسميات: لكل تسمية منتقي إصدار، فاختيار إصدار آخر ينقل التسمية، واختيار إصدار سابق يتراجع إليه. استخدم إضافة تسمية لتسمية جديدة. افتح إصدارًا لترى نماذجه ورسائل قالبه وكيف تختلف عن الإصدار الافتراضي (الذي تشغّله الطلبات عندما لا تثبّت إصدارًا)، واستخدم تشغيل لتجربة ذلك الإصدار بقيم الاختبار من قالب الموجّه. يمكن لمنشئ الإعداد المسبق تغيير تسمياته، وكذلك مالكو مساحة العمل ومسؤولوها عندما يكون الإعداد المسبق مشتركًا. باستخدام مفتاح API للإدارة يملك صلاحية presets:write:
يقبل الجسم version (تسمية إصدار، أو تسمية أخرى لنسخ ما تشير إليه) أو version_id. يسرد GET /v1/presets/{id}/labels التسميات، ويزيل DELETE /v1/presets/{id}/labels/{label} واحدة منها. تفشل الطلبات التي تثبّت تسمية مُزالة حتى تُضاف مجددًا.

التراجع

للتراجع، انقل التسمية إلى الإصدار السابق: اختر ذلك الإصدار في منتقي إصدار التسمية في الإصدارات والتسميات، أو أرسل الطلب نفسه مع "version": "v2". تشغّل الطلبات التي تثبّت production الإصدار v2 مجددًا دون أي تغيير في تطبيقك. تصل تنقلات التسميات إلى الطلبات خلال دقيقتين تقريبًا، مثل تغييرات الإعداد المسبق الأخرى.

الأخطاء

تعيد مشكلات القالب في الطلب 400 بالرمز validation_error. يحمل reason رمز المشكلة الأولى، ويسرد details جميعها مع مساراتها:
تعيد قيمة prompt.id التي لا تسمّي أي إعداد مسبق في مساحة عملك 404. يعيد الإصدار أو التسمية المثبّتة غير الموجودة، أو التي لا يستطيع المفتاح استخدامها، 404 بالسبب preset_version_not_found.

الحدود

ضوابط الحماية والسجلات

تفحص ضوابط الحماية قيم المتغيرات كمحتوى مستخدم، حتى عندما يضعها القالب في رسالة نظام. يحجب ضابط الحماية الذي ينقّح قيمة تلك القيمة في كل موضع أدرجها فيه القالب، ويحظر الضابط الذي يحظر قيمة الطلب كله. تسجّل البيانات الوصفية للطلب الإعداد المسبق وأسماء المتغيرات وعدد الرسائل المعروضة. أما القيم نفسها فلا تُحفظ إلا حيث يُحفظ جسم الطلب، وفق إعدادات التسجيل المعتادة لمساحة عملك.
آخر تعديل في ٥ نوفمبر ٢٠٢٦