طلب باللغة الطبيعية: التحويل إلى سلة تسوق مهيكلة
💡 الخلاصة في جملة: استخدم Jev لتحويل جملة طلب واحدة إلى سلة تسوق مهيكلة — حلقة Choice المتقلصة للخيارات تستخرج كل صنف، ثم يُرسل طلب دفعي لكل صنف لملء جميع الحقول، وأخيرًا يقوم الكود بالتجميع في نظام طلباتك.
سيقول العميل «Can I get a large oat milk latte and a blueberry muffin please» (لاتيه بحليب الشوفان بحجم كبير وكعكة توت أزرق واحدة، من فضلك)، لكن نظام الكاشير لديك يحتاج إلى سلة تسوق مهيكلة مفصولة صنفًا صنفًا مع كل حقل في مكانه. الحل في دليل Shopping cart cookbook الرسمي يستخدم نوع مسألة واحدًا فقط هو Choice، ويتم التحويل من اللغة الطبيعية إلى البيانات المهيكلة على مرحلتين:
- العثور على الأصناف: عدد الأصناف غير معروف مسبقًا، لذا نستخدم حلقة تقلص الخيارات — في كل دورة نسأل «ما أول صنف متبقٍ يُذكر في الطلب»، وعند اختيار صنف يُحذف من خيارات الدورة التالية، حتى يختار النموذج الخيار الحارس
nothing_else. - ملء الحقول: بمعرفة كل صنف، نعرف أيضًا حقوله (اللاتيه له size و milk)، وطلب دفعي واحد لكل صنف يسأل جميع مسائل الحقول بالتوازي.
الاختبار الرسمي الفعلي (jev-1.14.0، 2026-10-29): 3 طلبات للعثور على 2 أصناف (اللاتيه 0.99، كعكة التوت الأزرق 1.00، الحارس 1.00)، بالإضافة إلى 1 طلب لملء حقلي اللاتيه (large 1.00، oat 1.00) — إجمالي 4 طلبات لبناء السلة بأكملها. يستغرق هذا الدرس حوالي 15 دقيقة للتنفيذ الكامل، وبعد تنزيل التخزين المؤقت الرسمي يمكن إعادة إنتاج جميع الأرقام الرسمية دون تعيين مفتاح API (تم التحقق فعليًا في هذه الصفحة).
ماذا ستستطيع أن تفعل بعد إتمام الدرس
- كتابة
find_items(order): عند إعطاء طلب بلغة طبيعية، مهما طلبت من أصناف، تستخرج الحلقة كل صنف مع درجة ثقة مدمجة، وnothing_elseالحارس يلتقط حالة «انتهى الطلب» - كتابة
fill_fields(order, item): طلب واحد لكل صنف يملأ بالتوازي جميع الحقول المعروفة، والحقول التي لم يذكرها العميل تُجاب صراحةً بـunspecifiedبدلًا من اختلاق قيمة - كتابة القائمة كبيانات خالصة (وصف + مخطط الحقول): لإضافة صنف أو حقل يكفي تعديل القاموس، دون تغيير حرف واحد من المسائل
- إعادة إنتاج الأرقام الرسمية دون إنفاق قرش واحد: إعادة تشغيل التخزين المؤقت الرسمي
json_cache.json، وإعادة التشغيل بصفر طلبات
لماذا نستخدم Jev بدلًا من ترك LLM يولّد JSON للسلة مباشرة؟
«دع LLM يحلل هذه الجملة إلى JSON لسلة تسوق» هو رد الفعل الأول لدى الكثيرين — يعمل، لكن ما تحصل عليه هو نص يتطلب الدعاء لنجاحه.
| القدرة | LLM يولّد JSON | Jev حلقة تقلص الخيارات |
|---|---|---|
| عدد الأصناف | ❌ «كم صنفًا طلبت» يعتمد على عدّ النموذج، والخطأ في العد يعني نقصًا أو زيادة في العناصر | ✅ الحلقة تجد صنفًا واحدًا في كل مرة وتتوقف تلقائيًا عند الانتهاء، والعدّ يقوم به الكود |
| صلاحية قيم الحقول | ❌ قد يولّد venti و燕麦奶 — وهما ليسا في قائمتك | ✅ الخيارات هي القيم الصالحة (size ∈ small/medium/large)، والإجابة تقع دائمًا ضمن الخيارات |
| الحقول التي لم تُذكر | ❌ يميل إلى اختلاق «حجم متوسط افتراضي» نيابة عن العميل | ✅ خيار unspecified يفصح بوضوح أن «الطلب لم يذكر»، ويترك لك المعالجة وفق قواعدك الافتراضية |
| التحليل في المراحل اللاحقة | ❌ فشل تحليل JSON، وحقول مُهلوسة، وتحقق طبقة فوق طبقة | ✅ إجابات مُنمَّطة + توزيع احتمالي، يستخدمها الكود مباشرة |
| درجة الثقة | ❌ عليك أن تسأل «هل أنت متأكد» | ✅ كل حكم يحمل confidence خاصًا به، والثقة المنخفضة تُحوَّل لموظف المتجر للتحقق البشري |
باختصار: LLM سيقوم بإعادة كتابة الطلب نيابة عنك، أما Jev فيقوم فقط** بقراءة** الطلب نيابة عنك — كل صنف وكل حقل هو مسألة اختيار قابلة للمعايرة.
معضلتك الحالية
- «أجعل LLM يُخرج JSON لسلة التسوق، فيصيب تسع مرات من عشر، والمرة الفاشلة هي عندما طلب العميل ثلاثة أصناف فيُخرج صنفين فقط — وحتى الشكوى لا تجد سطر الكود المخطئ»
- «يقول العميل «لاتيه من فضلك» دون تحديد الحجم، فيختلق النموذج في كل مرة قيمة medium بثقة ويكتبها في الطلب»
- «كلما أُضيف صنف جديد إلى القائمة، يجب تعديل prompt التحليل تبعًا لذلك، ثم إعادة اختبار الانحدار الكامل بعد التعديل»
متى تستخدم هذه الحيلة
عندما تحتاج إلى:
- تحويل جملة بلغة طبيعية إلى بيانات مهيكلة: الطلبات، عناصر الإعداد، تعبئة النماذج، اختيار خصائص المنتجات
- مجموعة المرشحين هي مجموعة مغلقة معروفة — القائمة أنت من يحددها، والقيم الصالحة للحقول أنت من يحددها
- عدد غير محدد: قد يطلب 1 صنفًا أو 5 أصناف، ولا يمكن معرفة ذلك مسبقًا
ولا تريد:
- تحليل JSON الذي يُخرجه LLM ثم كتابة طبقة تحقق إضافية من نوع «هل اختلق شيئًا مرة أخرى»
- جعل نموذج التوليد يقوم بالعدّ — دليل المخاطر الرسمي ينص صراحةً على أن العد غير موثوق وأن الخطأ يزداد مع الحجم
- إعادة ضبط prompt مع كل تغيير في القائمة
🎒 الاستعدادات قبل البدء
- أتممت مسألة Choice: تعرف كتابة خريط خيارات
criteria، وتفهم قراءةchoiceوconfidence، وتعلم أن المسألة الواحدة تحوي 255 خيارًا كحد أقصى - يُنصح بقراءة Confidence درجة الثقة: معرفة كيف تُحوَّل الإجابات منخفضة الثقة إلى مراجعة بشرية
- أن تكون قد نجحت في تشغيل التثبيت وأول طلب:
.venvيعمل. يمكنك إتمام هذا الدرس بالكامل دون مفتاح (إعادة تشغيل ذاكرة التخزين المؤقت الرسمية)؛ وإذا أردت التشغيل الحي فاضبطTYPESAFE_API_KEY - كوب من الماء ☕——هذا الدرس مشروع صغير متكامل: حلقة واحدة ومجموعة أسئلة، تحوّل «جملة واحدة» إلى «سلة تسوق»
نفّذ معي
لنبدأ بتوضيح طريقة التشغيل: أنشئ cart.py، والصق كتل الكود لكل خطوة أدناه بالترتيب في الملف نفسه، وبعد إتمام كل خطوة شغّل python cart.py مرة واحدة. جميع استدعاءات API تمر عبر ذاكرة التخزين المؤقت json_cache.json، فالتشغيل المتكرر بلا تكلفة.
الخطوة 1: تثبيت البيئة، تنزيل ذاكرة التخزين المؤقت الرسمية، وتجهيز القائمة والطلب
لماذا: سجّل المسؤولون لهذه الحالة ذاكرة تخزين مؤقت لإجابات جميع 4 طلبات json_cache.json، وإذا وضعتها في المكان الصحيح يمكنك إعادة إنتاج جميع الأرقام الرسمية دون استدعاء API؛ وإلا فاضبط TYPESAFE_API_KEY للتشغيل الحقيقي.
ثبّت التبعيات (الأمر الأصلي من cookbook الرسمي؛ cooksafe هي مكتبة الأدوات المرافقة الرسمية، وصفها الذاتي على PyPI هو «Shared helpers for the TypeSafe cookbooks»، وبيان تبعياتها يتضمن typesafe-sdk<0.8.0,>=0.7.0، لذا لا حاجة لكتابة SDK بشكل منفصل):
pip install ipython 'cooksafe>=0.2.0,<0.3.0'نزّل ذاكرة التخزين المؤقت الرسمية (رابط مباشر raw؛ إعادة إنتاج الأرقام الرسمية دون مفتاح تعتمد عليها بالكامل):
curl -sL -o json_cache.json https://raw.githubusercontent.com/typesafe-ai/typesafe-public-examples/main/cookbooks/cart_from_primitives/json_cache.jsonأنشئ cart.py، والصق ترويسة الملف — العميل، ذاكرة التخزين المؤقت، الثوابت:
import os
from pathlib import Path
from cooksafe import JsonCache, make_playground_link
from IPython.display import Markdown, display
from typesafe_sdk import Choice, TypeSafeClient
TYPESAFE_MODEL = "jev-1.14.0" # 官方数字的录制版本
NOTHING_ELSE = "nothing_else" # the sentinel option that ends the item loop
MAX_ITEM_REQUESTS = 6 # a hard stop, so a bad answer can never loop forever
client = TypeSafeClient(
api_key=os.environ.get("TYPESAFE_API_KEY", "cache-only"), # cached re-renders need no key
model=TYPESAFE_MODEL,
timeout=30.0,
)
json_cache = JsonCache(Path("json_cache.json"))
def fmt_confidence(confidence: float | None) -> str:
"""A confidence for printing. The API can return None, so never format it blind."""
return f"{confidence:.2f}" if confidence is not None else "n/a"
print("setup ok")شغّل python cart.py.
ينبغي أن ترى: setup ok — لم يُرسَل أي طلب بعد.
احفظ ثلاثة أسماء أولًا: NOTHING_ELSE هو خيار الحارس الذي يُنهي الحلقة؛ MAX_ITEM_REQUESTS = 6 هو الحد الأقصى الصارم — تعليق المسؤولين واضح جدًا: الغاية منعه إجابة سيئة تجعل الحلقة لا تتوقف أبدًا؛ وfmt_confidence يذكّرك بأن confidence قد تكون None، فلا تُنسِّق بشكل أعمى.
- تمت طباعة
setup ok، وjson_cache.jsonموجود في مجلد التشغيل
الخطوة 2: كتابة القائمة كبيانات — الأوصاف موجهة إلى Jev، والحقول هي الخيارات
لماذا: أين تسكن «البنية» في تحويل اللغة الطبيعية إلى بيانات مهيكلة؟ إجابة المسؤولين هي قاموس: لكل منتج وصف يذكر كيف سيطلبه الزبون (اللاتيه يُسمى أيضًا flat white أو milky coffee)، وfields هو مخططه الخاص — أسماء الحقول تُربط بقوائم القيم المسموحة، وهذه القيم هي خيارات criteria لسؤال ذلك الحقل. القائمة بيانات لا prompt، وعند إضافة منتج جديد يكفي تعديل القاموس.
الصق القائمة والطلب:
MENU = {
"latte": {
"description": "Espresso with steamed milk. Also ordered as a flat white or a milky coffee.",
"fields": {
"size": ["small", "medium", "large"],
"milk": ["whole", "oat", "almond"],
},
},
"filter_coffee": {
"description": "Plain brewed drip coffee, sometimes ordered as a black coffee.",
"fields": {},
},
"blueberry_muffin": {
"description": "A blueberry muffin.",
"fields": {},
},
"almond_croissant": {
"description": "An almond croissant, sometimes ordered as a pastry.",
"fields": {},
},
}
ORDER = "Can I get a large oat milk latte and a blueberry muffin please"نقطتان تصميميتان:
- الوصف يحمل لغة الطلب: Jev يطابق الطلب مع هذه الأوصاف — عندما يقول الزبون «a milky coffee»، ما يُطابَق هو وصف اللاتيه، لا المعنى الحرفي لهذه الكلمة. لهذا يجب أن يكتب الوصف «كيف سيقول الزبون» لا «ما هذا الشيء»
- اللاتيه وحده له حقول: كلٌّ من size و milk مجموعة مغلقة؛ والمنتجات الثلاثة الأخرى بلا حقول، وسيتخطى الطلب الخاص بها مباشرة في الخطوة 4
شغّل python cart.py.
ينبغي أن ترى: ما يزال setup ok فقط — القائمة مجرد تعريف بيانات، ولم يُرسَل أي طلب.
- أستطيع أن أشرح دور كل من description و fields في
MENU، ولماذا يجب أن يتضمن الوصف مرادفات صياغة الطلب
الخطوة 3: حلقة تقليص الخيارات — الجزء الأول من تحويل اللغة الطبيعية إلى بيانات مهيكلة، والعثور على كل منتج
لماذا: عدد الأصناف التي يطلبها الزبون غير معروف مسبقًا. أن تسأل مباشرة «كم صنفًا طلبت؟» فهذا يجعل النموذج يَعُدّ — ودليل المزالق الرسمي (Jev 1.13 إصدار، 9 أنماط فشل، انظر Jev 1.13 دليل المزالق) يقول صراحةً: Jev يَعُدّ بشكل غير موثوق، ويزداد الخطأ مع كبر حجم الأشياء المعدودة؛ والبديل هو أن يُكرِّر الكود المرشحين، بسؤال واحد لكل مرشح. حلقة تقليص الخيارات هي هذا النهج بالضبط: في كل جولة سؤال Choice واحد «أي منتج متبقٍ هو أول ما ذُكر في الطلب»، وعند اختياره يُحفَظ ويُحذف من خيارات الجولة التالية، وتُرسَل الجملة كاملة مرة أخرى كما هي. وهذا أيضًا اعتماد حقيقي وفق معيار المسؤولين — بنصهم: لا يكون الطلب الثاني اعتمادًا حقيقيًا إلا عندما يستطيع الكود بناء الطلب التالي اعتمادًا على الإجابة السابقة (مثل تحديد خيارات السؤال التالي).
انظر أولًا إلى الحلقة كاملة، ثم الصق الكود:
الجولة 1 الخيارات = latte / filter_coffee / blueberry_muffin / almond_croissant + nothing_else
→ latte (0.99) يُحفَظ، ويُحذف من خيارات الجولة التالية
الجولة 2 الخيارات = filter_coffee / blueberry_muffin / almond_croissant + nothing_else
→ blueberry_muffin (1.00) يُحفَظ، ويُحذف من خيارات الجولة التالية
الجولة 3 الخيارات = filter_coffee / almond_croissant + nothing_else
→ nothing_else (1.00) ← اختير الحارس، فتوقفت الحلقةالصق مُنشئ الأسئلة، ودالة الطلب الواحد، والحلقة الرئيسية:
def item_question(remaining: dict[str, dict], found: list[str]) -> Choice:
"""Build one request's question from the items not found yet."""
already = ", ".join(found) if found else "nothing yet"
criteria = {name: item["description"] for name, item in remaining.items()}
criteria[NOTHING_ELSE] = (
"The order mentions no menu item other than the ones already accounted for."
)
return Choice(
instructions=(
f"This is a cafe order. Items already accounted for: {already}. "
"Which remaining menu item does the order mention? If the order mentions more "
"than one remaining item, choose the one mentioned first."
),
criteria=criteria,
)
@json_cache
def ask_item(order: str, question: dict) -> dict:
"""One item request. The question arrives as its API JSON, which also keys the cache."""
answer = client.system_one(state=order, questions={"item": question}).choices["item"]
return {"choice": answer.choice, "confidence": answer.confidence}
def find_items(order: str) -> list[dict]:
remaining = list(MENU)
found: list[dict] = []
item_requests = 0
for _ in range(MAX_ITEM_REQUESTS):
if not remaining:
break
question = item_question(
{name: MENU[name] for name in remaining},
[item["name"] for item in found],
)
result = ask_item(order, question.model_dump(mode="json", exclude_none=True))
item_requests += 1
print(
f"item request {item_requests}: {len(remaining)} items + sentinel "
f"-> {result['choice']} (confidence {fmt_confidence(result['confidence'])})"
)
if result["choice"] == NOTHING_ELSE:
break
remaining.remove(result["choice"])
found.append({"name": result["choice"], "confidence": result["confidence"]})
return found
items = find_items(ORDER)
print(f"\nfound {len(items)} items: {[item['name'] for item in items]}")شغّل python cart.py — كلها تصيب ذاكرة التخزين المؤقت الرسمية، فلا يُرسَل أي طلب.
ينبغي أن ترى (سجّلتها jev-1.14.0 الرسمية؛ وهذه الصفحة أعادت إنتاجها حرفيًا عند الاختبار):
item request 1: 4 items + sentinel -> latte (confidence 0.99)
item request 2: 3 items + sentinel -> blueberry_muffin (confidence 1.00)
item request 3: 2 items + sentinel -> nothing_else (confidence 1.00)
found 2 items: ['latte', 'blueberry_muffin']أربع نقاط تصميمية تستحق التوقف عندها:
- الحارس هو فرامل الحلقة: يجب على Choice اختيار خيار، ولا يوجد «لا اختيار» — لذا تُدرَج
nothing_elseفي كل جولة، ووصفها ينص صراحةً «لم يُذكَر في الطلب أي منتج غير ما حُسِب بالفعل». وعند اختيارها تتوقف الحلقة - instructions تُبلّغ بالتقدم: «Items already accounted for: nothing yet → latte → latte, blueberry_muffin» — في كل جولة تُخبِر النموذج بما وُجد سابقًا، لتجنّب إعادة ذكر منتجات وُجدت بالفعل
- «اختر أول ما ذُكر» لإزالة الالتباس: عندما يذكر الطلب أكثر من منتج متبقٍ، يُختار أول ما ذُكر فقط — قاعدة محددة، لا مجال لاجتهاد النموذج الحر
- خروج بثلاثة ضمانات: اختيار الحارس، إفراغ القائمة، حد
MAX_ITEM_REQUESTS— الحلقة ستتوقف حتمًا
💡 هذه هي القيمة الفريدة لـ Jev
هذه حلقة برمجية، وليست حلقة agent — دليل البناء الرسمي يقول صراحةً «ما يمكن التعبير عنه بسير عمل برمجي، فلا تستخدم له حلقة while الخاصة بالـ agent». تدفق التحكم وشروط الخروج وإزالة التكرار كلها في كودك، والنموذج في كل جولة يفعل شيئًا واحدًا ضيقًا للغاية: يختار واحدًا من خيارات الجولة الحالية. إن أخطأ الاختيار، فالحد الأقصى الصارم في الكود هو شبكة الأمان؛ وإن أصاب، فـ confidence تخبرك كم كان هذا الاختيار موثوقًا.
- شغّلت دون مفتاح 3 أسطرًا من item request و found 2 items؛ وأستطيع ذكر شروط الخروج الثلاثة للحلقة ودور خيار الحارس
الخطوة 4: طلب دفعي واحد لكل منتج لتعبئة الحقول
لماذا: بعد العثور على جميع المنتجات، تتحدد حقول كل منتج التي ينبغي سؤالها — اللاتيه له size و milk، والمافلن بلا حقول. نهج المسؤولين في التعبئة هو طلب واحد لكل منتج يضم جميع أسئلة حقوله (نمط fan-out: تقييم أسئلة متعددة بالتوازي على نفس الحالة)، لا طلب لكل حقل. وكل سؤال حقل يتضمن أيضًا خيار unspecified — فالحقول التي لم يذكرها الزبون تُجاب صراحةً بـ «الطلب لم يذكر»، لا أن يُجبَر على اختيار قيمة محددة.
الصق بناء أسئلة الحقول وكود التعبئة:
UNSPECIFIED = "unspecified"
def field_questions(item_name: str) -> dict[str, Choice]:
questions = {}
for field, values in MENU[item_name]["fields"].items():
criteria = {value: None for value in values}
criteria[UNSPECIFIED] = (
f"The order does not say which {field} for the {item_name}."
)
questions[field] = Choice(
instructions=f"Which {field} did the order ask for, for the {item_name}?",
criteria=criteria,
)
return questions
@json_cache
def ask_fields(order: str, questions: dict[str, dict]) -> dict:
"""One field request. The questions arrive as their API JSON, which also keys the cache."""
response = client.system_one(state=order, questions=questions)
return {
field: {"choice": answer.choice, "confidence": answer.confidence}
for field, answer in response.choices.items()
}
def fill_fields(order: str, item_name: str) -> dict:
if not MENU[item_name]["fields"]:
return {}
questions = {
field: question.model_dump(mode="json", exclude_none=True)
for field, question in field_questions(item_name).items()
}
return ask_fields(order, questions)
cart = []
for item in items:
fields = fill_fields(ORDER, item["name"])
cart.append(
{"name": item["name"], "confidence": item["confidence"], "fields": fields}
)شغّل البرنامج. يرسل اللاتيه 1 طلب (سؤالان size و milk بالتوازي)، وحقول fields للمافين بالتوت فارغة——يتخطى الطلب مباشرة. مع 3 طلبات من الخطوة 3، يصبح إجمالي الطلبات في الحالة الكاملة 4 طلب.
يجب أن ترى: لا مخرجات جديدة——هذه الخطوة تجمع قائمة cart في الذاكرة فقط (اللاتيه مع إجابتي الحقلين، والمافين fields قاموس فارغ)، والطباعة تحدث في الخطوة 5.
- أستطيع أن أشرح لماذا لا يرسل المافين طلبًا، وأي نوع من مشاكل «القيم الافتراضية المتخيلة» يحلّه خيار
unspecified
الخطوة 5: يجمّع الكود سلة تسوق مهيكلة
لماذا: التجميع عمل كود خالص، لا يُرسل أي استدعاء API. كل منتج يحمل confidence خاصًا به، وكل حقل كذلك——يتضح فورًا أي حكم يجرّ الأداء للخلف.
الصق كود الطباعة:
print(f'order: "{ORDER}"\n')
for line in cart:
print(f"{line['name']} (item confidence {fmt_confidence(line['confidence'])})")
for field, answer in line["fields"].items():
conf = fmt_confidence(answer["confidence"])
print(f" {field:<6} {answer['choice']:<12} confidence {conf}")شغّل البرنامج.
ينبغي أن ترى (سجّلتها jev-1.14.0 الرسمية؛ وهذه الصفحة أعادت إنتاجها حرفيًا عند الاختبار):
order: "Can I get a large oat milk latte and a blueberry muffin please"
latte (item confidence 0.99)
size large confidence 1.00
milk oat confidence 1.00
blueberry_muffin (item confidence 1.00)قارن مع مخطط (schema) القائمة في الخطوة 2: المنتج مفتاح صالح في القائمة، و size هي large (إحدى القيم الصالحة)، و milk هي oat (إحدى القيم الصالحة)——من المستحيل ظهور منتج أو قيمة حقل خارج القائمة، لأن الإجابة لا يمكن اختيارها إلا من الخيارات. هذا هو مصدر الثقة في «التهيكل»: نظام الطلبات في اتجاه المصب يحصل دائمًا على بيانات داخل الـ schema.
- مخرجاتي مطابقة حرفيًا للأرقام الرسمية: latte 0.99 / large 1.00 / oat 1.00 / blueberry_muffin 1.00
📋 الـ Prompt السحري
«الـ Prompt» في هذه الصفحة هو قالب السؤال الموجه إلى API——انسخه واستبدل العناصر النائبة 【】 (التي تحمل ? اختيارية) لتوصيله بقائمتك أو دليل منتجاتك. ثلاث قطع: سؤال إيجاد المنتجات، سؤال ملء الحقول، وهيكل الحلقة.
📝 سؤال إيجاد المنتجات (نسخة Choice المنكمشة)
الأثر المتوقع: كل احتياج من نوع «العثور على كل الإدخالات المعروفة المطابقة داخل جملة واحدة» — طلب الطعام، اختيار عناصر الإعداد، تحديد الخدمات — يُطبَّق عليه هذا النمط نفسه، ويوضَع في حلقة تُخرِج المطابقات واحدًا تلو الآخر.
from typesafe_sdk import Choice
# 必填项:remaining 传还没找到的商品(名字 -> 顾客会怎么点它的描述)
criteria = {【name】: 【商品描述,写顾客的同义叫法】 for name in 【remaining】}
criteria[【哨兵名】] = "【订单里没有提到已算过之外的商品】"
item_q = Choice(
instructions=(
f"【这是什么场景的一句话。已算过的:{【found 或 'nothing yet'】}。】"
"【订单里最先提到的剩余商品是哪样?提到多件时选最先说的】"
),
criteria=criteria,
)
# 选填项:场景词换掉 cafe order——配置单、服务预约、商品咨询?
# 输出规范:answer.choice 是商品名或哨兵名;answer.confidence 接复核线
# 约束条件:
# ✅ 描述写「顾客会怎么点它」,同义词写进去(flat white 也是 latte)
# ✅ 每轮把已找到的报进 instructions,防止重复报
# ❌ 别问「她点了几样」——计数交给循环,模型只做挑选✅ سؤال ملء الحقول (نسخة schema للحقول)
الأثر المتوقع: تحويل القيم الصالحة لحقول كل منتج إلى أسئلة Choice واحدًا تلو الآخر، تُسأل بالتوازي في طلب واحد؛ الحقول التي لم يذكرها الزبون تُبلَّغ صراحةً بـ unspecified.
# 必填项:fields 是该商品的 schema:字段名 -> 合法值列表
questions = {}
for field, values in 【商品["fields"]】.items():
criteria = {value: None for value in values}
criteria[【"unspecified"】] = f"The order does not say which {field} for the {【商品名】}."
questions[field] = Choice(
instructions=f"【订单为这个商品点了哪个 {field}?】",
criteria=criteria,
)
# 选填项:unspecified 的下游处理——按你的默认值规则补,或转人工确认?
# 输出规范:每字段 answer.choice ∈ 合法值 ∪ {unspecified},各带 confidence
# 约束条件:
# ✅ 选项就是函数/系统接受的合法值——答案不可能越界
# ✅ 没有字段的商品跳过请求,别发空请求
# ❌ 不给 unspecified = 逼模型编一个值🔧 هيكل الحلقة (نسخة الكود)
الأثر المتوقع: إيجاد عدد غير محدد من العناصر، ومنع الحلقات اللانهائية، والتوفير بالتخزين المؤقت——كود خالص قابل للاختبار المنفرد.
MAX_REQUESTS = 【6:硬上限,防坏答案死循环】
remaining, found = list(【MENU】), []
for _ in range(MAX_REQUESTS):
if not remaining:
break
result = ask(【order】, build_question(remaining, found))
if result["choice"] == 【哨兵名】:
break
remaining.remove(result["choice"])
found.append(result)
# 输出规范:found 是 [{name, confidence}, ...];件数 = len(found),由代码数
# 约束条件:
# ✅ 三个出口缺一不可:哨兵、候选清空、硬上限
# ✅ 请求函数挂 @json_cache——改菜单/改问题会换缓存键自动真跑,重跑零花费
# ❌ 别把循环交给模型自己「决定何时结束」——退出条件是代码的事نقاط التحقق ✅
- بدون ضبط
TYPESAFE_API_KEY، ووضعjson_cache.jsonالرسمي، أعدت إنتاج جميع الأرقام الرسمية حرفيًا: latte 0.99 / blueberry_muffin 1.00 / nothing_else 1.00 / size large 1.00 / milk oat 1.00 - إجمالي الطلبات في الحالة الكاملة 4 طلب: 3 لإيجاد المنتجات (منها 1 للخيار الحارس) + 1 لملء حقول اللاتيه؛ المافين لم يرسل طلبًا
- أستطيع أن أشرح لماذا نستخدم حلقة بدلًا من سؤال «كم عدد العناصر المطلوبة؟»: العد غير موثوق، والتكرار بالكود + سؤال واحد لكل عنصر هو البديل الرسمي
- أستطيع أن أشرح أن هذه «تبعية حقيقية»: خيارات الجولة التالية لا تُبنى إلا بعد إجابة الجولة السابقة——وهذا بالضبط الموقف الذي يعترف به معيار الجهة الرسمية كمسوّغ للطلب الثاني
- أعرف تقسيم الأدوار بين
unspecifiedوnothing_else: الأول يعني أن الحقل لم يُذكر، والثاني يعني أن المنتجات انتهت
تنبيهات للمزالق
❌ جعل النموذج يُخرج JSON لسلة التسوق كاملة
توليد واحد يخلط ثلاثة أمور: العد، وصلاحية الحقول، والصيغة: عدد قطع خاطئ، اختلاق قيم خارج القائمة مثل venti، فشل تحليل JSON——إن حدث خطأ لا تعرف في أي حلقة وقع. طريقة الجهة الرسمية في التقسيم تجعل كل أمر قابلًا للاختبار منفردًا: عدد القطع من عدد دورات الحلقة، والصلاحية مضمونة بالخيارات، والتجميع يقوم به الكود. النماذج التوليدية لا تستطيع تقديم هذا الضمان، لأن كل حرف عندها يُكتب من جديد.
❌ نسيان الخيار الحارس أو الحد الأقصى الصارم
بدون nothing_else، تُجبر Choice على انتقاء منتج من المنتجات المتبقية——فطلب مكتمل سيظهر له منتج «زائد». وبدون MAX_ITEM_REQUESTS، إجابة سيئة واحدة قد تجعل الحلقة لا تتوقف أبدًا. اكتب كليهما لتكون الحلقة صحيحة ومتوقفة حتمًا.
❌ حقل لم يذكره الزبون، فيختاره النموذج نيابةً عنها
بدون مخرج unspecified، لا يملك النموذج إلا انتقاء قيمة محددة——«لاتيه من فضلك» سيتحول بثقة إلى medium whole milk latte. حل الجهة الرسمية هو أن كل سؤال حقل يحمل unspecified، وفي اتجاه المصب تُستكمل القيمة وفق قواعدك الافتراضية أو يُحوَّل الأمر إلى موظف للتأكيد. لممارسة رسمية أخرى في نفس السيناريو انظر قرارات الـ Agent: يستخدم دليل function calling سؤال نعم/لا منفصلًا للحكم على «هل ذكر المستخدم هذا المعامل أم لا»، فيختار أحد المخرجين.
❌ تشغيل طلبات باللغة الصينية مباشرةً في الإنتاج
التوضيح الرسمي: Jev مدرَّب أساسًا بالإنجليزية ودقته أفضل ما تكون بالإنجليزية؛ اللغات الأخرى (بما فيها الصينية) قابلة للاستخدام لكن بدقة أقل——قبل الإنتاج شغّل دفعة من طلباتك الصينية الخاصة وراقب توزيع الاحتمالات، مع تركيز على confidence، وشرح دعم اللغات فيالنماذج والأسعار. كذلك، تعديل القائمة أو تعديل الأسئلة يغيّر مفتاح التخزين المؤقت: مفتاح cooksafe يتكون من اسم الدالة والمعاملات، وبعد تعديل MENU ستعيد التشغيل طلبًا حقيقيًا تلقائيًا (ينجح فقط إذا ضبطت Key)، وإن أردت فرض إعادة التشغيل فاحذف json_cache.json.
تقنيات متقدمة (اختيارية)
الكمية: أضف حقل quantity. تقول الجهة الرسمية صراحةً عن قيد هذا المثال: سلة التسوق لا تملك حقل كمية، و«two flat whites» تنتج latte واحدًا فقط. الحل الرسمي: أضف حقل quantity إلى schema كل منتج، بقيم صالحة مثل one / two / three——الطلب الدفعي في الخطوة 4 سيسأل عنه تلقائيًا مع الباقي.
القوائم الكبيرة: قسّم أولًا ثم انتقِ. سؤال Choice واحد يحتوي حتى 255 خيارًا (الشرح الكامل في سؤال الاختيار Choice). عندما تكون القائمة أكبر، انتقِ أولًا الكتلة (أي فئة)، ثم المنتج داخل الكتلة——كل مقطع يبقى ضمن 255. البحث سطرًا بسطر في البحث والمطابقة هو تطبيق عملي لنفس الفكرة: أعطِ كل سطر من 218 سطرًا معرّفًا ID، ووجّه Choice إلى السطر المطابق.
جرّب بلا كود أولًا. في أسفل صفحة الـ cookbook الرسمية توجد روابط مشاركة Playground جاهزة——طلب كامل + سؤال إيجاد المنتجات للجولة الأولى (أربعة منتجات مع الحارس)، افتح (https://console.typesafe.ai/playground) وغيّر صياغة الطلب، فتتغير الإجابة تبعًا. لتوليد رابطك الخاص:
playground_link = make_playground_link(ORDER, {"item": item_question(MENU, [])})
# Print a usable URL in a script; render a clickable link in a notebook.
if __name__ == "__main__" and "__file__" in globals():
print(f"Open in the TypeSafe playground:\n{playground_link}")
else:
display(Markdown(f"🔗 [Open the first item-finding request in the TypeSafe playground]({playground_link})"))يتم توليد الرابط دون اتصال ولا يحتاج إلى API Key؛ يحمل الـ URL الحالة الكاملة والأسئلة، لا تضع بيانات حساسة. شاهد التسجيل الرسمي: TypeSafe shopping cart demo.
أدخِله في مسار الطلب لديك. استبدل ORDER برسائل الدردشة أو تحويل الصوت إلى نص أو ملاحظات النماذج، واستبدل MENU بدليل منتجاتك؛ بنية الإجابة لا تتغير، ونظام الطلبات في اتجاه المصب يستقبلها كما هي. الحقول كثرت فارتفعت التكلفة؟ الأسئلة المتوازية والانتشار التخميني قاس فعليًا مكاسب الأسئلة الدفعية: 13 سؤالًا في طلب واحد أرخص بـ 12.2 مرة وأسرع بـ 10.0 مرة من السؤال واحدًا تلو الآخر، والإجابة لا تتغير.
خلاصة هذا الدرس
✅ تحويل اللغة الطبيعية إلى بنية مهيكلة، تقسمه الجهة الرسمية إلى مرحلتين: حلقة خيارات منكمشة لإيجاد المنتجات (العدد يحسبه الكود، وفرامل nothing_else الحارس)، ولكل منتج طلب دفعي لملء الحقول (القيم الصالحة هي الخيارات، و unspecified يبلّغ «لم يُذكر»).
✅ كل حكم قابل للمعايرة: المنتج 0.99 / 1.00، الحقل 1.00 / 1.00——الأحكام منخفضة الثقة تُرسل إلى موظف للتأكيد اليدوي بدلًا من دخولها الطلب قسرًا.
✅ الأرقام الرسمية المعاد إنتاجها بدون مفتاح: 4 طلبات (3 للعثور على المنتجات + 1 لتعبئة الحقول) أصابت جميعها ذاكرة التخزين المؤقت الرسمية، وأعيد تشغيلها حرفيًا في هذه الصفحة عمليًا.
✅ القائمة هي بيانات وليست prompt: لإضافة منتج جديد عدّل قاموس MENU دون تغيير حرف واحد من قوالب الأسئلة؛ وإذا غيّرته فسيتم تغيير مفتاح التخزين المؤقت تلقائيًا وتشغيله فعليًا.
مراجعة حقول الإعدادات الرئيسية:
| الحقل | قيمة هذه الصفحة | الشرح |
|---|---|---|
TYPESAFE_MODEL | "jev-1.14.0" | نسخة تسجيل الأرقام الرسمية (2026-10-29)؛ عند التشغيل الحي قفل معرّف النسخة، ولا تستخدم jev-latest الذي يتغير باستمرار |
NOTHING_ELSE | "nothing_else" | خيار الحارس: يُختار عندما لا تتبقى منتجات في الطلب، فيتوقف التكرار |
MAX_ITEM_REQUESTS | 6 | حد أقصى صارم: خط الدفاع الثالث إلى جانب الحارس وإفراغ القائمة |
UNSPECIFIED | "unspecified" | المخرج عندما لا يُذكر الحقل، لمنع النموذج من اختلاق قيمة افتراضية |
MENU | 4 منتجات، فقط latte يحتوي على size/milk | الوصف يكتب كيف ينطق العميل طلبه؛ وfields هي الـ schema |
| عدد الطلبات لكل طلبية | للعثور على المنتجات N+1 مرة + 1 مرة لكل منتج ذي حقول | في هذا المثال 3+1=4 مرات؛ كلها تمر عبر التخزين المؤقت، ولا يحدث miss إلا عند تغيير القائمة أو الأسئلة |
دروس ذات صلة:
- قرارات الـ Agent: اختيار المهارات والتحويل إلى استدعاء دوال——نفس فكرة «جملة واحدة تصبح استدعاءً منظمًا» مطبقة على الدوال: سؤال Choice واحد لاختيار الدالة، وسؤال لكل معلمة لتعبئة قيمتها؛ والمعلمات غير المذكورة لها مخرج بسؤال نعم/لا
- استخراج القيم: التواريخ والبريد الإلكتروني والهاتف والمبالغ——في نفس مسار «المستندات والبيانات»: القيم لا تأتي إلا من النص الأصلي، والـ regex يجد المرشحين، وJev يختار الصحيح منها
- الأسئلة المتوازية والتوسع التخميني——لماذا تُرسل أسئلة الحقول دفعة واحدة: 13 سؤالًا في طلب واحد أرخص بـ 12.2 مرة وأسرع بـ 10.0 مرة
استعراض الدرس التالي
تحوّل الطلب بجملة واحدة إلى سلة تسوق، والمشكلة التالية هي أي العناصر من بين كومة كبيرة من المرشحين تطابق حقًا. الدرس التالي: البحث والمطابقة: إعادة الترتيب، البحث سطرًا بسطر، محاذاة الكيانات.
ستتعلم:
- إعادة الترتيب ترفع دقة استعلامات CLERC القانونية في top-1 من 5% إلى 18%، وtop-10 من 38% إلى 62%
- بحث دلالي سطرًا بسطر عبر 218 سطرًا من شروط استخدام GitHub: أعطِ كل سطر معرّفًا، وسؤال Choice واحد يشير إلى السطر المطابق——نسخة واسعة النطاق من فكرة «الخيارات هي المرشحون» في هذه الصفحة
- كيفية استخدام سؤال Score واحد وثلاثة أسئلة Noul للعثور على الأزواج المتطابقة من بين 450 زوجًا مرشحًا من دليلي جعة