Skip to content

طلب باللغة الطبيعية: التحويل إلى سلة تسوق مهيكلة ​

💡 الخلاصة في جملة: استخدم Jev لتحويل جملة طلب واحدة إلى سلة تسوق مهيكلة — حلقة Choice المتقلصة للخيارات تستخرج كل صنف، ثم يُرسل طلب دفعي لكل صنف لملء جميع الحقول، وأخيرًا يقوم الكود بالتجميع في نظام طلباتك.

سيقول العميل «Can I get a large oat milk latte and a blueberry muffin please» (لاتيه بحليب الشوفان بحجم كبير وكعكة توت أزرق واحدة، من فضلك)، لكن نظام الكاشير لديك يحتاج إلى سلة تسوق مهيكلة مفصولة صنفًا صنفًا مع كل حقل في مكانه. الحل في دليل Shopping cart cookbook الرسمي يستخدم نوع مسألة واحدًا فقط هو Choice، ويتم التحويل من اللغة الطبيعية إلى البيانات المهيكلة على مرحلتين:

  1. العثور على الأصناف: عدد الأصناف غير معروف مسبقًا، لذا نستخدم حلقة تقلص الخيارات — في كل دورة نسأل «ما أول صنف متبقٍ يُذكر في الطلب»، وعند اختيار صنف يُحذف من خيارات الدورة التالية، حتى يختار النموذج الخيار الحارس nothing_else.
  2. ملء الحقول: بمعرفة كل صنف، نعرف أيضًا حقوله (اللاتيه له 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 يولّد JSONJev حلقة تقلص الخيارات
عدد الأصناف❌ «كم صنفًا طلبت» يعتمد على عدّ النموذج، والخطأ في العد يعني نقصًا أو زيادة في العناصر✅ الحلقة تجد صنفًا واحدًا في كل مرة وتتوقف تلقائيًا عند الانتهاء، والعدّ يقوم به الكود
صلاحية قيم الحقول❌ قد يولّد 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 بشكل منفصل):

bash
pip install ipython 'cooksafe>=0.2.0,<0.3.0'

نزّل ذاكرة التخزين المؤقت الرسمية (رابط مباشر raw؛ إعادة إنتاج الأرقام الرسمية دون مفتاح تعتمد عليها بالكامل):

bash
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، والصق ترويسة الملف — العميل، ذاكرة التخزين المؤقت، الثوابت:

python
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، وعند إضافة منتج جديد يكفي تعديل القاموس.

الصق القائمة والطلب:

python
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 واحد «أي منتج متبقٍ هو أول ما ذُكر في الطلب»، وعند اختياره يُحفَظ ويُحذف من خيارات الجولة التالية، وتُرسَل الجملة كاملة مرة أخرى كما هي. وهذا أيضًا اعتماد حقيقي وفق معيار المسؤولين — بنصهم: لا يكون الطلب الثاني اعتمادًا حقيقيًا إلا عندما يستطيع الكود بناء الطلب التالي اعتمادًا على الإجابة السابقة (مثل تحديد خيارات السؤال التالي).

انظر أولًا إلى الحلقة كاملة، ثم الصق الكود:

text
الجولة 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)     ← اختير الحارس، فتوقفت الحلقة

الصق مُنشئ الأسئلة، ودالة الطلب الواحد، والحلقة الرئيسية:

python
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 الرسمية؛ وهذه الصفحة أعادت إنتاجها حرفيًا عند الاختبار):

text
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 — فالحقول التي لم يذكرها الزبون تُجاب صراحةً بـ «الطلب لم يذكر»، لا أن يُجبَر على اختيار قيمة محددة.

الصق بناء أسئلة الحقول وكود التعبئة:

python
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 خاصًا به، وكل حقل كذلك——يتضح فورًا أي حكم يجرّ الأداء للخلف.

الصق كود الطباعة:

python
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 الرسمية؛ وهذه الصفحة أعادت إنتاجها حرفيًا عند الاختبار):

text
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 المنكمشة) ​

الأثر المتوقع: كل احتياج من نوع «العثور على كل الإدخالات المعروفة المطابقة داخل جملة واحدة» — طلب الطعام، اختيار عناصر الإعداد، تحديد الخدمات — يُطبَّق عليه هذا النمط نفسه، ويوضَع في حلقة تُخرِج المطابقات واحدًا تلو الآخر.

python
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.

python
# 必填项: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 = 逼模型编一个值

🔧 هيكل الحلقة (نسخة الكود) ​

الأثر المتوقع: إيجاد عدد غير محدد من العناصر، ومنع الحلقات اللانهائية، والتوفير بالتخزين المؤقت——كود خالص قابل للاختبار المنفرد.

python
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) وغيّر صياغة الطلب، فتتغير الإجابة تبعًا. لتوليد رابطك الخاص:

python
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_REQUESTS6حد أقصى صارم: خط الدفاع الثالث إلى جانب الحارس وإفراغ القائمة
UNSPECIFIED"unspecified"المخرج عندما لا يُذكر الحقل، لمنع النموذج من اختلاق قيمة افتراضية
MENU4 منتجات، فقط latte يحتوي على size/milkالوصف يكتب كيف ينطق العميل طلبه؛ وfields هي الـ schema
عدد الطلبات لكل طلبيةللعثور على المنتجات N+1 مرة + 1 مرة لكل منتج ذي حقولفي هذا المثال 3+1=4 مرات؛ كلها تمر عبر التخزين المؤقت، ولا يحدث miss إلا عند تغيير القائمة أو الأسئلة

دروس ذات صلة:

استعراض الدرس التالي ​

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

ستتعلم:

  • إعادة الترتيب ترفع دقة استعلامات CLERC القانونية في top-1 من 5% إلى 18%، وtop-10 من 38% إلى 62%
  • بحث دلالي سطرًا بسطر عبر 218 سطرًا من شروط استخدام GitHub: أعطِ كل سطر معرّفًا، وسؤال Choice واحد يشير إلى السطر المطابق——نسخة واسعة النطاق من فكرة «الخيارات هي المرشحون» في هذه الصفحة
  • كيفية استخدام سؤال Score واحد وثلاثة أسئلة Noul للعثور على الأزواج المتطابقة من بين 450 زوجًا مرشحًا من دليلي جعة
gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.