أسئلة Choice: اختر عنصرًا واحدًا من خيارات ثابتة
جهّزتَ المواد في الدرس السابق، وفي هذا الدرس تبدأ تعلّم طرح الأسئلة. Jev Choice هو أول أساليب طرح الأسئلة الخمسة وأكثرها مباشرة: تسرد الخيارات بوضوح، ويختار Jev واحدًا منها، ويعيده مع احتمال كل خيار ودرجة الثقة الإجمالية — الإجابة تكون دائمًا أحد خياراتك، ولن تحتاج في الكود إلى كتابة سطر واحد لتحليل النصوص بـ if.
في الواقع لقد استخدمته بالفعل في أول طلب: سؤال department في route_ticket.py كان سؤال Choice، واختار technical. هذا الدرس يشرحه بالكامل، ومدته 10 دقيقة.
ماذا ستستطيع أن تفعل بعد إتمام الدرس
- كتابة سؤال Jev Choice كامل باستخدام خريطة الخيارات
criteria(اسم الخيار ← وصف من سطر واحد)، مع معرفة أن أسماء الخيارات وأوصافها تُرسل جميعها إلى النموذج - قراءة حقول الإرجاع الثلاثة
choiceوprobabilitiesوconfidence، وتحويل الخيار ذي الاحتمال الأعلى مباشرة إلى تفرع كود - طرح عدة أسئلة Choice بالتوازي في طلب واحد (بحد أقصى 255 خيارًا لكل سؤال)، وتجاهل إجابات الأسئلة الاستباقية إذا لم تُستخدم
- إضافة خيار
otherعندما قد تكون القائمة غير كاملة، أو — بحسب التوصية الرسمية — تهيئة سؤال Noul مرافق كاحتياطي - استخدام طريقة «أعد ترتيب الخيارات وشغّل مرة أخرى» للتحقق من استقرار الإجابة — قد يؤثر ترتيب الخيارات في الإجابة
معضلتك الحالية
- عندما تجعل GPT يصنّف التذاكر، يعيد في كل مرة أسماء فئات مختلفة — «استرداد» و«استرداد وإرجاع» و«طلب استرداد المال» — و
ifفي المراحل التالية لا يلحق أبدًا بالمفردات التي يخترعها - لمعرفة مدى تأكده، لا يوجد سوى سؤاله «ما مدى تأكدك؟»، فتحصل على مقالة نثرية من نوع «أعتقد أنه مرجّح إلى حد كبير» لا يمكن كتابتها في الكود
- تذكرة واحدة تتطلب الحكم على عدة أمور (أي فريق تتبع، وما السبب، وماذا يريد العميل)، وثلاثة طلبات متسلسلة بطيئة ومكلفة؛ وحشركا في prompt واحد يجعل الإجابات تتشابك
متى تستخدم هذه الطريقة
عندما تحتاج إلى:
- إجابة هي مجموعة خيارات تحددها بنفسك: التوجيه إلى أي فريق، وأي فئة ينتمي إليها المنتج، وبأي لغة كُتب الكود
- إجابة تتحول مباشرة إلى تفرع كود — مسار واحد لكل خيار، دون تحليل من نص مُولَّد
- طرح عدة أسئلة اختيار من متعدد على نفس المادة متتالية، مع رغبتك في إرسال طلب واحد فقط
ولا تريد:
- أن يخترع النموذج إجابة جديدة خارج قائمتك في اللحظة الأخيرة
- كتابة prompt طويل لأجل حكم يستغرق ثانية واحدة مثل «إلى من تُوجَّه هذه التذكرة»
- أن تتركه ينفذ تلقائيًا حتى عندما لا يكون النموذج واثقًا
🎒 التحضير قبل البدء
- State الحالة: تعرف أن المواد توضع في
state(نص، أو كائن JSON، أو مصفوفة نصوص — كلها ممكنة)، وأن الأسئلة تُكتب في questions - نجح في تشغيلأول طلب: تم تجهيز
typesafe-sdkفي.venv، وتم تعيين متغير البيئةTYPESAFE_API_KEY - تتذكر الشكل التقريبي لسؤال
departmentفيroute_ticket.py— إن نسيت فارجع وألقِ نظرة سريعة
الفكرة الجوهرية
التعريف الرسمي في جملة واحدة: عندما تكون الإجابة أحد مجموعة خيارات ثابتة، استخدم Choice. الأسئلة النموذجية في الوثائق: أي فريق يعالج هذه التذكرة، وأي فئة ينتمي إليها هذا المنتج، وبأي لغة كُتب هذا الكود.
سبب فعالية Choice هو ضمان صارم واحد — الإجابة مقيَّدة بالخيارات التي تقدمها:
كل إجابة مقيَّدة بالخيارات التي تقدمها. يعيد النموذج توزيع احتمالات على خياراتك، ولن يكون أبدًا قيمة خارجها. لن يحتاج كودك أبدًا إلى انتشال الإجابة من نص مُولَّد.
سؤال Choice يبدو هكذا:
| الحقل | ماذا تُكتب | الشرح |
|---|---|---|
| المعرّف (مفتاح السؤال) | تختاره بنفسك، مثل department | يُستخدم في كودك فقط، لا يُرسل إلى النموذج؛ وتُسترجع الإجابة بواسطته |
type | ثابت "choice" | — |
instructions | السؤال الكامل | يُكتب المحتوى الكامل للسؤال هنا، ولا تعتمد على المعرّف لينقل عنك |
criteria | خريطة الخيارات: اسم الخيار ← الوصف | اسم الخيار والوصف يُرسلان إلى النموذج؛ بحد أقصى 255 خيارًا لكل سؤال |
كيف تختار بين أنواع الأسئلة الثلاثة (المعيار الرسمي):
| نوع السؤال | بماذا يجيب | الاستخدام في الكود |
|---|---|---|
| Choice (هذا الدرس) | أي خيار ثابت يُختار، دون ترتيب بين الخيارات | مسار كود واحد لكل خيار |
| Score | إلى أي مدى على الطيف، وعند كل مستوى هل تستطيع وصف | عبور العتبة والترتيب |
| Noul | نعم/لا واضحة، والاحتمال نفسه مفيد | واحد if |
الإجابة: إذا كان طيفًا (ما مدى الخطورة، ما مدى الغضب) ← Score؛ وإذا كانت نعم/لا واضحة (هل ذُكر استرداد المال أم لا) ← Noul. وعندما يتشابه الاثنان، توصي الجهة الرسمية باختيار الإجابة التي يمكن للكود التصرف بناءً عليها مباشرة: الخيارات الثلاثة refund / rebook / information ترتبط مباشرة بثلاثة مسارات كود، وهذا هو شكل الـ Choice.
اتبع خطواتي
الخطوة 1: عرّف خريطة الخيارات واكتب أول سؤال Jev Choice لك
لماذا: سؤال Choice لا يحتوي إلا على ثلاثة حقول: type وinstructions وcriteria — يُرسل اسم الخيار ووصفه كلاهما إلى النموذج، لذا يجب كتابة الوصف بحيث يميّز الخيارات عن بعضها.
باستخدام مثال الوثائق الرسمية: تذكرة دعم لعميل متجر أحذية عبر الإنترنت، تسأل أي فريق يجب أن يتولاها. أنشئ choice_first.py:
# 运行前:export TYPESAFE_API_KEY="<你的API Key>"
from typesafe_sdk import Choice, TypeSafeClient
with TypeSafeClient() as client:
response = client.system_one(
state="My running shoes arrived in the wrong size. Can I swap them for a size 10?",
questions={
"department": Choice(
instructions="Which team should handle this?",
criteria={
"returns": "Exchanges, wrong or damaged items",
"shipping": "Delivery status, delays, lost packages",
"billing": "Charges, invoices, payment problems",
},
),
},
)
print(response.answers["department"].choice)شغّله:
.venv/bin/python choice_first.pyيجب أن ترى:
returnsمقاس خاطئ ويريد استبدال الزوج — من اختصاص فريق returns، وفي التسجيل الرسمي للمثال راهن النموذج بالكامل على returns.
ثلاث نقاط أساسية لكتابة criteria:
اسم الخيار هو قيمة الإجابة. ما يحصل عليه الكود في
choiceهو سلسلة نصية لاسم الخيار، فاستخدم معرّفات إنجليزية ثابتة (returns) ولا تستخدم نصوصًا عرضية قابلة للتغييروظيفة الوصف هي الفصل. بالنص الحرفي الرسمي: يُرسل اسم الخيار ووصفه كلاهما إلى النموذج، «لذا اكتب الأوصاف بحيث تُبعد الخيارات عن بعضها». عندما يكون الاسم نفسه واضحًا بما يكفي، يمكن إعطاء الوصف قيمة
null(يوجد مثال جاهز في الخطوة 3)أعطِ القائمة الكاملة، لا قائمة مختصرة. سؤال Choice واحد يقبل حتى 255 خيارًا، وإضافة الخيارات لا تكلّف سوى بضعة token — أعطِ النموذج كل الفئات والتصنيفات والمنتجات بدلًا من فرزها مسبقًا
حصلت على
returns، وأعرف أن هذه القيمة تأتي من اسم خيار داخلcriteria
الخطوة 2: اقرأ الـ choice وprobabilities وconfidence في النتيجة المرجعة
لماذا: choice ليس سوى ذروة التوزيع؛ في المشاريع الحقيقية ستحتاج على الأرجح إلى استخدام probabilities وconfidence لكتابة الفروع، لا الاكتفاء بأخذ اسم واحد.
النتيجة الكاملة لطلب الخطوة 1 (المثال الرسمي):
{
"model": "jev-1.13.0",
"answers": {
"department": {
"type": "choice",
"choice": "returns",
"confidence": 1.0,
"probabilities": {
"shipping": 0.0,
"returns": 1.0,
"billing": 0.0
}
}
},
"usage": {
"input_tokens": 328,
"output_tokens": 34
}
}يجب أن ترى: في كائن الإجابة، إلى جانب type هناك ثلاث قيم، نفككها واحدة واحدة:
| الحقل | قيمته في هذا المثال | كيف تقرؤه |
|---|---|---|
choice | returns | الخيار ذو الاحتمال الأعلى |
probabilities | returns 1.0 والبقية 0.0 | توزيع جميع الخيارات، مجموعها يقارب 1؛ والمفاتيح هي أسماء الخيارات |
confidence | 1.0 | يضغط شكل التوزيع في رقم واحد بين 0–1: كله على خيار واحد = 1، موزّع بالتساوي = 0 |
ثلاث حقائق تستحق التذكر:
- الإجابة دائمًا ضمن الخيارات. في سؤال من ثلاثة خيارات،
probabilitiesلا يحتوي إلا على هذه المفاتيح الثلاثة — لا يوجد شيء اسمه «النموذج أضاف رابعًا من عنده» - confidence ينظر إلى الاحتمال الأعلى فقط. صيغة الخيارات الثلاثة هي
(3 × 最大概率 − 1) / 2، لذا فإن الـ confidence لكل من(0.6, 0.3, 0.1)و(0.6, 0.2, 0.2)هو 0.4. كيف يُحسب شكل التوزيع في هذا الرقم وكيف تُستخدم الدرجات الثلاث، تُشرح بالتفصيل في درس Confidence الثقة - confidence وصف للتوزيع، وليس ضمانًا لصحة الإجابة. هذه التذكرة بسيطة، والاحتمال كله على
returns، فمن الطبيعي أن يكون الـ confidence 1.0؛ أما تذكرة تذكر مقاسًا خاطئًا وخصمًا مزدوجًا معًا فستقسم الاحتمال بينreturnsوbilling، وسيهبط الـ confidence — توجد تذكرة كهذه في الخطوة 3
الـ "model": "jev-1.13.0" في المثال هو الإصدار الذي استُخدم عند تسجيل المثال الرسمي؛ وإذا شغّلته الآن بـ jev-latest، فسيُظهر هذا الحقل إصدار النموذج الحالي.
- أستطيع أن أشير إلى النتيجة المرجعة وأقول:
choiceهو الذروة، وprobabilitiesهو التوزيع (المجموع يقارب 1)، وconfidenceهو شكل التوزيع
الخطوة 3: خمسة أسئلة Choice في طلب واحد (تقييم متوازٍ)
لماذا: توصي الجهة الرسمية بطرح جميع أسئلة Choice التي قد تحتاجها في طلب واحد: تُقيَّم جميع الأسئلة على نفس الـ state بشكل متوازٍ ومستقل — إضافة الأسئلة لا تزيد زمن الاستجابة تقريبًا، ويكفي أن يتجاهل الكود الإجابات غير المستخدمة.
هذه المرة نستبدلها بتذكرة أكثر غموضًا: تأخرت أسبوعين، والمقاس خاطئ، وخُصمت منها رسوم مرتين — الفرق الثلاثة كلها معنية، والعميل لم يقل ما يريده. الجهة الرسمية طرحت على هذه التذكرة خمسة أسئلة Choice في طلب واحد:
# 运行前:export TYPESAFE_API_KEY="<你的API Key>"
from typesafe_sdk import Choice, TypeSafeClient
TRIAGE_QUESTIONS = {
"department": Choice(
instructions="Which team should handle this?",
criteria={
"returns": "Exchanges, wrong or damaged items",
"shipping": "Delivery status, delays, lost packages",
"billing": "Charges, invoices, payment problems",
},
),
"return_reason": Choice(
instructions="If the customer wants to return something, why?",
criteria={
"wrong_size": "The item doesn't fit",
"wrong_item": "A different product was delivered",
"damaged": "The item arrived broken or faulty",
"changed_mind": "The item is fine, the customer no longer wants it",
"other": "A return reason that fits none of the above",
},
),
"shipping_issue": Choice(
instructions="If this is a shipping problem, which kind is it?",
criteria={
"not_delivered": "The package never arrived",
"delayed": "The package is late but still on the way",
"wrong_address": "The package went to the wrong place",
"damaged_in_transit": "The package arrived damaged",
"other": "A shipping problem that fits none of the above",
},
),
"requested_resolution": Choice(
instructions="What does the customer want to happen?",
criteria={
"exchange": "Swap the item for a different one",
"refund": "Money back",
"replacement": "The same item sent again",
"information": "Just an answer, no action needed",
},
),
"tone": Choice(
instructions="What is the customer's tone?",
criteria={"calm": None, "frustrated": None, "angry": None},
),
}
ticket = "Shoes arrived two weeks late and in the wrong size. Also I see two charges of $120 on my card. What are you going to do about this?"
with TypeSafeClient() as client:
response = client.system_one(state=ticket, questions=TRIAGE_QUESTIONS)يجب أن ترى (نتيجة المثال الرسمي، الإجابات الخمس تصل دفعة واحدة؛ هذا الطلب بلغ إجمالًا 589 token إدخال / 212 token إخراج):
| السؤال | choice | confidence | أهم نقاط الاحتمال |
|---|---|---|---|
department | returns | 0.42 | returns 0.61، وbilling 0.35، وshipping 0.04 |
return_reason | wrong_size | 1.0 | wrong_size 1.0 والبقية 0.0 |
shipping_issue | delayed | 0.67 | delayed 0.74، وother 0.26 |
requested_resolution | refund | 0.2 | refund 0.40، replacement 0.34، exchange 0.24 |
tone | frustrated | 0.76 | frustrated 0.84، angry 0.16 |
تفسير المسؤولين لكل إجابة يستحق أن تقرأه سطراً بسطر:
departmentمنقسمة: returns 0.61، billing 0.35 — الخصم المتكرر أعطى billing أكثر من ثلاثين بالمئة من الاحتمال. هذه التذكرة تمتد عبر مجموعتين، وconfidence الخاص بـ 0.42 يتحدث عن هذا بالضبطreturn_reasonنظيفة: «المقاس غير مناسب» مكتوبة بوضوح تام، كل الرهان علىwrong_size، وconfidence 1.0shipping_issueسؤال تخميني: الإجابة منقسمة بين delayed وother، لكنdepartmentليس shipping من الأساس — الكود يتجاهله فحسب (الخطوة 4 تفعل ذلك)requested_resolutionثقة منخفضة: استرداد المال 0.40، استبدال 0.34، مقايضة 0.24 — الخصم المتكرر يوحي بطلب استرداد المال، والمقاس غير المناسب يوحي بطلب مقايضة، والعميل لم يحدد أيهما من البداية إلى النهايةtoneوصفهnullبالكامل: أسماء calm / frustrated / angry واضحة بذاتها ولا تحتاج إلى وصف — وهذا بالضبط موقف «إذا لم تستطع كتابة تمييز فأعطِ null» المذكور في الخطوة 1
لاحظ أن من بين هذه الأسئلة الخمسة يوجد سؤالان تخمينيان (speculative): return_reason مفيد فقط عند التصنيف في مجموعة returns، وshipping_issue مفيد فقط عند التصنيف في shipping. اسأل أولاً ثم خُذ ما تحتاجه عند الحاجة — هذه هي الممارسة القياسية في Jev — الاختبار الفعلي لأسئلة 13 الرسمية مقابل 13 طلباً يظهر أنها أرخص بـ 12.2 مرة وأسرع بـ 10.0 مرة، والإجابة لا تتغير (التوسعة في درس الأسئلة المتوازية). عرض المنزل الذكي الرسمي أكثر تطرفاً: كل طلب يقيّم دفعة واحدة قائمة طويلة من أسئلة Choice (الفئة، الغرفة، الجهاز، الإجراء)، ومعظم الإجابات غير مفيدة، والكود يأخذ منها فقط ما يحتاجه.
الخطوة 4: اكتب فروع التوجيه باستخدام choice وprobabilities وconfidence
لماذا: الإجابات كلها قيم مُنمّطة — choice تُربط مباشرة بمسارات الكود، والثقة المنخفضة تُحوَّل إلى الإنسان، واحتمال الخيار الثاني يتجاوز العتبة فيُرسل نسخة. طلب واحد، خمس إجابات، وما تبقى هو if عادي بالكامل.
كود التوجيه الكامل الذي يقدمه المسؤولون بعد الخطوة 3:
def triage(ticket: str) -> None:
with TypeSafeClient() as client:
response = client.system_one(
state=ticket,
questions=TRIAGE_QUESTIONS,
)
answers = response.answers
department = answers["department"]
if department.confidence < 0.3:
# Not clear which team to send to. Let a person decide.
send_to_manual_triage(ticket)
return
if department.choice == "returns":
# return_reason answer is only used here
assign(ticket, team="returns", issue=answers["return_reason"].choice)
elif department.choice == "shipping":
# shipping_issue answer is only used here
assign(ticket, team="shipping", issue=answers["shipping_issue"].choice)
else:
assign(ticket, team="billing")
# A second team with a real share of the probability gets a copy
for team, probability in department.probabilities.items():
if team != department.choice and probability > 0.25:
notify(ticket, team=team)
resolution = answers["requested_resolution"]
if resolution.confidence < 0.5:
# The customer hasn't said what they want. Ask, don't guess.
ask_customer_what_they_want(ticket)
elif resolution.choice == "refund":
flag_for_refund_approval(ticket)
if answers["tone"].choice == "angry":
flag_for_senior_agent(ticket)(assign / notify / send_to_manual_triage وغيرها دوال توضيحية، استبدلها بمنطق التوجيه الخاص بك.)
يجب أن ترى — بالنسبة لتذكرة الخطوة 3، السلوك الذي قدمه المسؤولون هو:
assigned to returns team with issue wrong_size
billing team notified (0.35 > 0.25)
customer asked what they want (confidence 0.20 < 0.5)قيم البوابات الثلاث كلها مأخوذة من المثال الرسمي: 0.3 (تحتها لا يمكن حتى تحديد المجموعة، فتُحوَّل إلى الإنسان)، 0.25 (حصة احتمال الخيار الثاني، تجاوزتها فيُرسل نسخة)، 0.5 (مدى التأكد من طلب العميل، تحتها نَسأل بدلاً من التخمين). إجابة shipping_issue لم تُقرأ طوال الوقت — وهنا تكمن فائدة السؤال التخميني.
«تصنيف النية + بوابات الثقة» كنظام توجيه كامل (منطق حتمي / LLM خبير / تفريع ثلاثي إلى الإنسان)، يتوسع في درس التوجيه الذكي.
- أستطيع أن أشرح بوضوح بالنسبة لهذه التذكرة: لماذا أُرسلت نسخة إلى billing، ولماذا نَسأل العميل، ولماذا لم يُستخدم shipping_issue
الخطوة 5: خيارَا احتياط عندما تكون القائمة غير كاملة: خيار other وNoul المصاحب
لماذا: قد لا تغطي قائمة الخيارات كل المدخلات — يطرح العميل طلباً لم تتوقعه، فلا يملك النموذج إلا أن يختار قسراً واحداً من الخيارات التي أعطيته. قدّم المسؤولون خيارين احتياطيين.
**الاحتياط الأول: خيار other. ** توصية المسؤولين: عندما قد لا تغطي القائمة كل المدخلات، أضف خيار other أو none of the above ليتيح للنموذج أن يقول «لا ينطبق أي منها». في return_reason وshipping_issue الخاصتين بالخطوة 3 يوجد خيار other، ويُذكر في الوصف أنه «مخرج عند عدم انطباق أي منها».
الاحتياط الثاني: Noul المصاحب (يفضّله المسؤولون أكثر). ** يشير المسؤولون إلى أن none of the above في كثير من السيناريوهاتليس بالضرورة عملياً**؛ والبديل هو إضافة سؤال Noul في نفس الطلب يحكم على «هل ينطبق أي من الخيارات»، مثلاً:
Choice: إلى أي فئة ينتمي هذا الطلب؟
Noul : هل يذكر `message` أيًّا من `our_products`؟لا يقرأ الكود إجابة Choice إلا عندما تكون Noul بـ yes — إذا لم ينطبق أي شيء تُتخطى المجموعة كلها. وهذه بالضبط طريقة لعب تصفية الدردشة المباشرة: لكل رسالة طلب واحد وثلاثة أسئلة، وما لا ينطبق يُمرَّر مباشرة. أما Noul نفسه فيُشرح في الدرس التالي.
يجب أن ترى: كلا الاحتياطين لا يحتاج إلى طلب جديد — other هو خيار إضافي في criteria، وNoul المصاحب هو سؤال إضافي في نفس questions، والمجموع يبقى ضمن إطار «طلب واحد».
- أستطيع أن أقول متى يُستخدم كل من الاحتياطين: إذا كانت القائمة تنقصها عناصر أحياناً أضِف
other؛ وإذا أردت «إيقاف ما لا ينطبق إطلاقاً» فاقرن Noul مصاحباً
نقطة تحقق ✅
- أعلم أن
criteriaلديّ هو map للخيارات (الاسم → الوصف)، وأعلم أن كليهما يُرسل إلى النموذج بينما معرّف السؤال لا يُرسل - أعلم أن الإجابة لا بد أن تكون ضمن الخيارات المعطاة، وأن
probabilitiesيغطي كل الخيارات ويبلغ مجموعها تقريباً 1 - أعلم أن الطلب الواحد يضم أسئلة متعددة متوازية تُقيَّم باستقلال؛ وإجابة السؤال التخميني يكفي ألا يستخدمها الكود
- أعلم أن confidence ينظر فقط إلى أعلى احتمال (
(3×最大概率−1)/2لثلاثة خيارات)، وهو وصف للتوزيع لا ضمان للصحة - أتذكر الفحصين الذاتيين: أعد ترتيب الخيارات للتحقق من الاتساق؛ وإذا اخترت الأفضل فقط فخذ أعلى احتمال مباشرة
تنبيه من المخاطر
❌ وصفا خيارين لا يمكن الفصل بينهما
الظاهرة: خيارات متقاربة المعنى مثل return_policy / return_status، التذكرة تذكر return وrefund معاً، والنموذج يتأرجح دائماً بينهما، وconfidence لا يرتفع أبداً.
لماذا هو خطأ: اسم الخيار ووصفه كلاهما يُرسل إلى النموذج. عندما يشير الوصفان إلى النوع نفسه من المدخلات، لا يملك النموذج أساس مقارنة، فلا يملك الاحتمالات إلا أن تُوزَّع بينهما.
الطريقة الصحيحة: اكتب الحدود بشكل قاطع في الوصف — ما الذي يغطيه هذا الخيار، وما الذي لا يغطيه (شأن الخيار المجاور). هكذا تكتب الوثائق الرسمية عن return_policy / return_status: كل وصف يحدد بوضوح حدود «whether and how an item can be returned»، وبعد إضافة الأمثلة المقارنة حصل المثال الرسمي على return_status و confidence بقيمة 1.0. عندما تحتاج إلى الكتابة أكثر، استخدم كائنًا كقيمة للخيار مباشرة (انظر البند الأول في نصائح متقدمة).
❌ غيّر الترتيب، فيتغير الجواب
الظاهرة: عند تغيير ترتيب الخيارات الثلاثة داخل criteria، يتغير الجواب معها.
سبب الخطأ: هذا نمط فشل معروف مذكور في دليل الأخطاء الرسمي (ينطبق على jev-1.13) — ترتيب خيارات Choice يؤثر على الجواب، ويميل النموذج إلى الخيارات المدرجة في المقدمة.
الطريقة الصحيحة: الوثائق الرسمية تقولها بجملة واحدة — «أعد ترتيب الخيارات، وشغّل مرة أخرى، وتحقق من اتساق الجواب». اجعلها فحصًا ذاتيًا ثابتًا قبل الإطلاق، خاصة للأسئلة ذات الخيارات القليلة والأوصاف القصيرة. القائمة الكاملة لأنماط الفشل في Jev 1.13 دليل الأخطاء.
❌ استخدام Choice لجعل النموذج «يكتب الجواب بنفسه»
الظاهرة: تُكتب في instructions عبارة «ما التاريخ المذكور في هذه الرسالة»، متوقعًا أن يملأ النموذج التاريخ.
سبب الخطأ: Jev ليس نموذج توليد؛ التوليد النصي مهمة LLM مدرّب عليها. صياغة السؤال بقيمة مفتوحة لا ترضي أيًا من الطرفين: النموذج لا يستطيع الارتجال (الجواب مقيّد بالخيارات)، وأنت لم تعطه خيارات للاختيار من بينها.
الطريقة الصحيحة: إذا كانت مساحة الأجوبة محدودة، فعدّدها كخيارات. التاريخ مثال نموذجي: سؤال Choice لكل من السنة والشهر واليوم — الشهر اثنا عشر فقط، واليوم واحد وثلاثون كحد أقصى — ثم أضف لكل منها خيار «لم يُذكر»، فتُبلَّغ الأجزاء الناقصة بصدق بدلًا من تخمينها. الكود هو من يجمع الأجزاء في تاريخ حقيقي ويتولى جميع المقارنات والعمليات. الطريقة الكاملة لاستخراج القيم (regex لإيجاد المرشحين، Jev لاختيار الصحيح منهم) في استخراج القيم.
❌ وضع عتبات confidence في كل مكان
الظاهرة: وضع عتبة confidence لكل جواب وكل فرع، تتزايد باستمرار حتى يتعذر ضبطها.
سبب الخطأ: قائمة الأسئلة الشائعة في Agent Skill الرسمي تسمّي هذه العادة بالاسم — عندما يهمك فقط اختيار أفضل خيار، يكفي أخذ الأعلى احتمالًا مباشرة دون حاجة لعتبات confidence في كل مكان؛ وعند وجود حاجة حقيقية لخوارزمية إحصائية، فالصحيح استخدام probabilities.
الطريقة الصحيحة: استخدم choice لفروع التوجيه؛ وprobabilities لتحليل التوزيعات؛ وضع عتبات confidence فقط على البوابات الحاسمة من نوع «غير متأكد هل أنفّذ تلقائيًا» (مثل 0.3 / 0.5 في الخطوة 4)، واجعلها تتدرج مع حجم المخاطرة — الطريقة الكاملة في درس Confidence الثقة.
نصائح متقدمة (اختيارية)
🔧 عندما لا يتسع الخيار في سطر واحد، استخدم كائنًا. عندما تتكرر إرباك خيارين أو ثلاثة، ولا يكفي سطر وصف واحد لتوضيح الحدود، استبدل الوصف بكائن: حقل يوضح ما يغطيه هذا الخيار، وحقل يوضح ما لا يخصه، وحقل يعطي أمثلة. كتابة الوثائق الرسمية لـ return_policy / return_status (طلب خام مباشر من Playground، الاستجابة return_status و confidence 1.0):
مثال الوثائق الرسمي للمعايير المهيكلة (JSON خام)
{
"state": "I sent the shoes back a week ago. When do I get my money?",
"questions": {
"return_topic": {
"type": "choice",
"instructions": {
"question": "Which returns topic is the customer asking about?",
"focus": "Classify the information the customer wants."
},
"criteria": {
"return_policy": {
"what": "Whether and how an item can be returned",
"not_for": "Progress of a return already sent",
"examples": [
"Can I return shoes I've worn once?",
"How long do I have to return an order?"
]
},
"return_status": {
"what": "Progress of a return already sent",
"not_for": "Whether and how an item can be returned",
"examples": [
"Has my return arrived yet?",
"When will my refund be paid?"
]
}
}
}
}
}نقطتان مهمتان: instructions يمكن هيكلتها بالطريقة نفسها (question + focus)؛ وأسماء الحقول what / not_for / examples كلها ليست كلمات محجوزة في API، أنت من يسمّيها — النموذج يرى أسماء الحقول وقيمها، فيكفي أن تسمّي الحقل بكلمة قصيرة «توضّح ما هو المكتوب أدناه».
🔧 أشجار التصنيف العميقة: اسأل طبقة بطبقة. عندما تكون التصنيفات عميقة (تصنيف براءات الاختراع، فهارس التجزئة، شجرة مجلدات مستودع الشيفرة)، صِف Choice في سلسلة: جواب كل طبقة يحدد الخيارات التي تُعطى لطلب الطبقة التالية. كتاب الطبخ الرسمي للتصنيف الهرمي يشغّل فوق ذلك beam search — باستخدام probabilities الخاصة بـ Choice للاحتفاظ بأفضل K مسارات مرشحة في كل طبقة، بدلًا من المراهنة على مسار واحد فقط في كل طبقة. الطريقة الكاملة في التصنيف العميق.
🔧 الاتصال المباشر بـ API متجاوزًا SDK. أرسل POST إلى https://api.typesafe.ai/v1/systemone، بثلاثة حقول في الطبقة العليا من جسم الطلب state / model / questions، وهكذا يبدو JSON الخام لسؤال department:
{
"model": "jev-latest",
"state": "My running shoes arrived in the wrong size. Can I swap them for a size 10?",
"questions": {
"department": {
"type": "choice",
"instructions": "Which team should handle this?",
"criteria": {
"returns": "Exchanges, wrong or damaged items",
"shipping": "Delivery status, delays, lost packages",
"billing": "Charges, invoices, payment problems"
}
}
}
}التعريف الكامل لقيود الحقول (criteria بحد أدنى 1 خيار وبحد أقصى 255 خيار، والجواب بأربعة حقول) في مرجع API السريع.
خلاصة الدرس
✅ طريقة كتابة Choice لدى Jev: خريطة خيارات criteria (الاسم → وصف بسطر واحد؛ بحد أقصى 255 خيارًا)، والجواب يقع دائمًا ضمن خياراتك، ولا يحتاج الكود إلى تحليل نص.
✅ اقرأ حقول الإرجاع الثلاثة معًا: choice هو الخيار الأعلى احتمالًا، وprobabilities هو توزيع جميع الخيارات، وconfidence هو رقم واحد يلخص شكل التوزيع.
✅ أسئلة متعددة في طلب واحد تعمل بالتوازي وتُقيَّم باستقلال؛ الأسئلة التخمينية اسألها أولًا ثم استخدمها في الكود حسب الحاجة — 13 سؤالًا في طلب واحد قيست عمليًا أرخص بـ 12.2 مرة وأسرع بـ 10.0 مرة.
✅ القائمة قد لا تكون كاملة: أضف مخرج other، أو اقرنها بـ Noul مرافق للحكم على «هل يوجد شيء ذو صلة».
مراجعة حقول الإعداد الأساسية:
| الحقل | الكتابة الموصى بها | الشرح |
|---|---|---|
type | "choice" | قيمة ثابتة |
instructions | السؤال كاملًا | لا يُرسل معرّف السؤال إلى النموذج، فاكتب السؤال كاملًا |
criteria | خريطة الخيارات: الاسم → وصف مميّز بسطر واحد | إذا كان الاسم واضحًا بذاته اجعل الوصف null؛ أعطِ القائمة الكاملة لا قائمة قصيرة |
| الوصول إلى الجواب | response.answers["id"].choice | اقرأه مع .probabilities و.confidence معًا |
لمشاهدة كيفية استخدام Choice في سيناريوهات واقعية: التصنيف العميق (تشغيل beam search عبر شجرة التصنيف باحتمالات Choice)، وتصفية محادثات البث المباشر (رسالة واحدة بطلب واحد وثلاثة أسئلة)، والتوجيه الذكي (Choice لتصنيف النية و confidence كبوابة).
استعراض الدرس التالي
على الطرف الآخر من الخيارات الثابتة يأتي «إلى أي درجة»: سؤال Score للتقييم: التقييم على مقياس تحدده أنت.
ستتعلم:
- استبدال
criteriaمن خريطة خيارات بقائمة مراتب مرتبة، ورقم المرتبة هو فهرس المصفوفة - يمكن لـ
scoreأن يقع بين مرتبتين (مثل 1.43)، ويجب قراءته مع توزيع الاحتمالات - تقسيم الحكم متعدد الأبعاد إلى أسئلة Score متعددة، ودمجها في الكود بالتطبيع والترجيح
- متى ينبغي استبدال Choice بـ Score