प्राकृतिक भाषा ऑर्डर: संरचित शॉपिंग कार्ट में बदलना
💡 एक वाक्य में सारांश: 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 Key सेट किए आधिकारिक सभी आंकड़े पुन:पेश किए जा सकते हैं (इस पृष्ठ पर परीक्षित)।
सीखने के बाद आप क्या कर सकते हैं
- लिखें
find_items(order): प्राकृतिक भाषा का एक ऑर्डर दें, चाहे उसने कितनी ही आइटम मंगाई हों, लूप हर आइटम ढूंढे, साथ में भरोसे का स्तर भी दे,nothing_elseसेंटिनल «ऑर्डर पूरा हुआ» को संभाले - लिखें
fill_fields(order, item): हर आइटम के लिए एक रिक्वेस्ट में सभी ज्ञात फ़ील्ड समानांतर में भरें, जो फ़ील्ड ग्राहक ने नहीं बताए उनका स्पष्ट उत्तरunspecifiedदें, किसी मान की कल्पना न करें - मेन्यू को शुद्ध डेटा के रूप में लिखें (विवरण + फ़ील्ड schema): आइटम जोड़ने, फ़ील्ड जोड़ने के लिए केवल डिक्शनरी बदलें, प्रश्न में एक शब्द भी न बदलना पड़े
- एक पैसा खर्च किए बिना आधिकारिक आंकड़े पुन:पेश करें: आधिकारिक
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 आइटम, पहले से पता नहीं
और आप नहीं चाहते:
- LLM के थूके JSON को पार्स करना, और फिर एक और परत लिखना «कहीं उसने फिर से कुछ गढ़ तो नहीं» सत्यापन की
- जनरेटिव मॉडल से गिनती करवाना — आधिकारिक गलतियों की रिपोर्ट स्पष्ट कहती है कि गिनती अविश्वसनीय है, त्रुटि पैमाने के साथ बढ़ती है
- मेन्यू के हर बदलाव पर prompt दोबारा ट्यून करना
🎒 शुरू करने से पहले की तैयारी
- पूरा किया Choice चुनाव प्रश्न:
criteriaविकल्प map लिखना आता हो,choiceऔरconfidenceपढ़ सकते हों, पता हो कि एक प्रश्न में अधिकतम 255 विकल्प - अनुशंसा करते हैं कि Confidence कॉन्फिडेंस पढ़ चुके हों: पता हो कि कम कॉन्फिडेंस वाले उत्तर को मानव समीक्षा में कैसे भेजा जाता है
- इंस्टॉल और पहला रिक्वेस्ट सफलतापूर्वक चला चुके हों:
.venvउपलब्ध है। इस पूरे पाठ में बिना Key के भी चलाया जा सकता है(आधिकारिक कैश रिप्ले); live चलाना चाहें तो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 डायरेक्ट लिंक; Key सेट किए बिना आधिकारिक आंकड़ों का पुनरुत्पादन पूरी तरह इसी पर निर्भर है):
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 के लिए, फ़ील्ड ही विकल्प हैं
क्यों: प्राकृतिक भाषा से संरचित डेटा में बदलने की संरचना कहाँ रहती है? आधिकारिक उत्तर एक डिक्शनरी है: हर उत्पाद का विवरण यह लिखता है कि ग्राहक इसे कैसे ऑर्डर करेगा (latte को flat white या milky coffee भी कहा जाता है), fields इसका अपना schema है——फ़ील्ड नाम वैध मानों की सूची से मैप होते हैं, और ये मान ही उस फ़ील्ड प्रश्न के 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", तो मैच latte के विवरण से होता है, इस शब्द के शाब्दिक अर्थ से नहीं। इसीलिए विवरण में "ग्राहक क्या कहेगा" लिखें, "यह क्या है" नहीं
- सिर्फ latte के फ़ील्ड हैं: size और milk अलग-अलग बंद सेट हैं; बाकी तीन के फ़ील्ड नहीं हैं, चरण 4 में उनके रिक्वेस्ट सीधे छोड़ दिए जाएंगे
python cart.py चलाएं।
आपको यह दिखना चाहिए: फिर भी सिर्फ setup ok——मेन्यू केवल डेटा परिभाषा है, एक भी रिक्वेस्ट नहीं भेजा गया।
- मैं बता सकता हूँ कि
MENUमें description और fields की अपनी-अपनी भूमिका क्या है, और विवरण में ऑर्डर के पर्यायवाची क्यों लिखने चाहिए
चरण 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 लूप नहीं——आधिकारिक बिल्डिंग गाइड स्पष्ट कहता है "जो सॉफ़्टवेयर वर्कफ़्लो से व्यक्त हो सके, उसे agent के while लूप से मत करो"। कंट्रोल फ़्लो, निकास शर्तें, डुप्लिकेशन हटाना सब आपके कोड में है; मॉडल हर राउंड में केवल एक बहुत संकरा काम करता है: उस राउंड के विकल्पों में से एक चुनना। गलत चुने तो कोड की हार्ड ऊपरी सीमा सहारा देती है; सही चुने तो confidence बताता है कि यह चुनाव कितना भरोसेमंद है।
- बिना Key के 3 item request और found 2 items चलाए; मैं लूप की तीन निकास शर्तें और सेंटिनल विकल्प की भूमिका बता सकता हूँ
चरण 4: हर उत्पाद के लिए एक बैच रिक्वेस्ट से फ़ील्ड भरें
क्यों: उत्पाद पूरे मिल जाने पर, हर उत्पाद के लिए कौन से फ़ील्ड पूछने हैं तय हो जाता है——latte में size और milk हैं, muffin में कोई फ़ील्ड नहीं। आधिकारिक तरीका है कि हर उत्पाद के लिए एक रिक्वेस्ट उसके सभी फ़ील्ड प्रश्नों के साथ (fan-out पैटर्न: एक ही state के लिए कई प्रश्न समानांतर मूल्यांकन), न कि एक फ़ील्ड के लिए एक रिक्वेस्ट। हर फ़ील्ड प्रश्न में 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}
)चलाएँ। Latte 1 बार अनुरोध भेजता है (size + milk दो प्रश्न समानांतर में), blueberry muffin का fields खाली है——अनुरोध सीधे छोड़ दिया जाता है। चरण 3 के 3 अनुरोधों को जोड़ने पर, पूरे केस में कुल 4 अनुरोध होते हैं।
आपको यह दिखना चाहिए:कोई नया आउटपुट नहीं——यह चरण केवल cart सूची को मेमोरी में जोड़ता है (latte दोनों फ़ील्ड के उत्तरों के साथ, muffin का fields खाली dict है), चरण 5 में ही प्रिंट होता है।
- मैं बता सकता हूँ कि muffin अनुरोध क्यों नहीं भेजता, और
unspecifiedविकल्प किस प्रकार की 'मनगढ़ंत डिफ़ॉल्ट मान' समस्या हल करता है
चरण 5:कोड से संरचित शॉपिंग कार्ट जोड़ना
क्यों:जोड़ना (assembly) शुद्ध कोड का काम है, एक भी 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)चरण 2 के मेनू schema से जाँचें:उत्पाद मेनू का वैध key है, 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 बार latte के फ़ील्ड भरना;muffin ने कोई अनुरोध नहीं भेजा
- मैं बता सकता हूँ कि लूप क्यों इस्तेमाल किया और 'कितने आइटम ऑर्डर किए' क्यों नहीं पूछा: गिनती अविश्वसनीय है, कोड इटरेशन + हर एक के लिए एक प्रश्न ही आधिकारिक विकल्प है
- मैं समझा सकता हूँ कि यह「वास्तविक निर्भरता」है:अगले राउंड के विकल्प पिछले राउंड के उत्तर का इंतज़ार करते हैं——यही वह स्थिति है जिसे आधिकारिक मानदंड दूसरे अनुरोध की अनुमति देता है
- मुझे
unspecifiedऔरnothing_elseका विभाजन पता है:पहला फ़ील्ड न बताया गया है, दूसरा उत्पाद खत्म हो गए
आम गलतियों की चेतावनी
❌ मॉडल से पूरा शॉपिंग कार्ट JSON आउटपुट करवाना
एक ही जनरेशन में गिनती, फ़ील्ड वैधता और फ़ॉर्मैट तीनों काम उलझ जाते हैं:गलत गिनती, venti जैसे मेनू से बाहर मान बना लेना, JSON पार्स विफलता——गलती हो तो पता ही नहीं चलता कि किस चरण में हुई। आधिकारिक तरीका हर काम को अलग-अलग टेस्ट करने योग्य बनाता है:आइटम संख्या लूप से, वैधता विकल्पों से, जोड़ना कोड से। जनरेटिव मॉडल यह गारंटी नहीं दे सकता, क्योंकि उसका हर अक्षर नए सिरे से टाइप होता है।
❌ सेंटिनल विकल्प या हार्ड अपर-लिमिट भूल जाना
nothing_else के बिना, Choice बचे हुए उत्पादों में से मजबूरन एक चुनता है——पूरा हुआ ऑर्डर「एक अतिरिक्त」आइटम ले लेगा। MAX_ITEM_REQUESTS के बिना, एक बुरा उत्तर लूप को हमेशा के लिए रुकने ही नहीं देगा। दोनों लिखें, तभी लूप सही भी है और अनिवार्य रूप से समाप्त भी होता है।
❌ जिन फ़ील्ड का ग्राहक ने उल्लेख नहीं किया, मॉडल ने उसकी ओर से चुन दिया
unspecified निकास के बिना, मॉडल केवल कोई ठोस मान चुन सकता है——「एक latte दीजिए」आत्मविश्वास से medium whole milk latte बन जाएगा। आधिकारिक समाधान यही है कि हर फ़ील्ड प्रश्न के साथ unspecified हो, डाउनस्ट्रीम आपके डिफ़ॉल्ट मान नियमों से भरे या स्टाफ़ से पुष्टि कराए। इसी परिदृश्य का दूसरा आधिकारिक तरीका देखें Agent निर्णय:फ़ंक्शन-कॉल cookbook「उपयोगकर्ता ने यह पैरामीटर बताया या नहीं」जानने के लिए एक अलग हाँ-ना प्रश्न लगाता है, और दोनों में से एक निकास चुनता है।
❌ सीधे चीनी ऑर्डर लाइव कर देना
आधिकारिक विवरण:Jev मुख्य रूप से अंग्रेज़ी पर ट्रेन किया गया है, अंग्रेज़ी में सटीकता सर्वोत्तम है;अन्य भाषाएँ (चीनी सहित) काम करती हैं पर सटीकता कम होती है——लाइव करने से पहले अपने चीनी ऑर्डरों का एक बैच चलाकर प्रायिकता वितरण देखें, confidence पर विशेष ध्यान दें, भाषा समर्थन विवरण देखेंमॉडल और कीमत। इसके अलावा मेनू या प्रश्न बदलने से कैश key बदल जाती है:cooksafe की कैश key फ़ंक्शन नाम और पैरामीटर से बनती है, MENU बदलकर दोबारा चलाने पर स्वतः वास्तविक अनुरोध होगा (Key सेट होने पर ही सफल होगा), ज़बरदस्ती दोबारा चलाना हो तो json_cache.json मिटा दें।
उन्नत तकनीकें (वैकल्पिक)
मात्रा: एक quantity फ़ील्ड जोड़ें। आधिकारिक रूप से इस उदाहरण की सीमा बताई गई है: शॉपिंग कार्ट में मात्रा फ़ील्ड नहीं है, 'two flat whites' भी केवल एक latte आइटम देता है। आधिकारिक समाधान: हर उत्पाद के schema में quantity फ़ील्ड जोड़ें, वैध मान जैसे 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 में पूरा state और प्रश्न होता है, संवेदनशील डेटा मत रखें। आधिकारिक वीडियो देखें:TypeSafe shopping cart demo।
अपने ऑर्डर फ़्लो में जोड़ें। ORDER को चैट संदेश, वॉइस ट्रांसक्रिप्ट, फ़ॉर्म नोट से बदलें, MENU को अपने उत्पाद कैटलॉग से;उत्तर की संरचना नहीं बदलती, डाउनस्ट्रीम ऑर्डर सिस्टम सब कुछ ज्यों का त्यों ले लेता है। फ़ील्ड बढ़ने से लागत बढ़ी? समानांतर प्रश्न और स्पेकुलेटिव फ़ैन-आउट ने बैच प्रश्नों का लाभ मापा है:13 प्रश्न एक ही अनुरोध में पूछना एक-एक प्रश्न से 12.2 गुना सस्ता और 10.0 गुना तेज़ है, उत्तर नहीं बदलते।
इस पाठ का सारांश
✅ प्राकृतिक भाषा से संरचित डेटा, आधिकारिक रूप से दो हिस्सों में बाँटा गया: संकुचित विकल्पों वाला लूप उत्पाद खोजता है (आइटम संख्या कोड गिनता है, nothing_else सेंटिनल ब्रेक), हर उत्पाद के लिए एक बैच अनुरोध फ़ील्ड भरता है (वैध मान ही विकल्प हैं, unspecified 'नहीं बताया' रिपोर्ट करता है)।
✅ हर निर्णय कैलिब्रेट किया जा सकता है:उत्पाद 0.99 / 1.00, फ़ील्ड 1.00 / 1.00——कम confidence वाले निर्णय स्टाफ़ के पास मानव-पुष्टि के लिए जाते हैं, सीधे ऑर्डर में नहीं।
✅ आधिकारिक संख्याओं के साथ बिना Key पुनरावृत्ति: 4 अनुरोध (3 उत्पाद खोजने के लिए + 1 फ़ील्ड भरने के लिए) सभी आधिकारिक कैश से मेल खाते हैं, इस पृष्ठ पर परीक्षण शब्दशः पुनरावृत्ति है।
✅ मेनू डेटा है, prompt नहीं: नया आइटम जोड़ने के लिए MENU डिक्शनरी बदलें, प्रश्न टेम्पलेट में एक शब्द भी न छेड़ें; बदलने पर कैश की स्वचालित रूप से बदल जाएगी और वास्तव में चलेगा।
मुख्य कॉन्फ़िगरेशन फ़ील्ड की समीक्षा:
| फ़ील्ड | इस पृष्ठ का मान | व्याख्या |
|---|---|---|
TYPESAFE_MODEL | "jev-1.14.0" | आधिकारिक संख्याओं का रिकॉर्ड किया गया संस्करण (2026-10-29); live चलाने के लिए लॉक संस्करण ID का उपयोग करें, बहते हुए 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 से फ़ंक्शन चुनें, प्रत्येक पैरामीटर के लिए एक प्रश्न से मान भरें; जिन पैरामीटर का उल्लेख न हो उनके लिए हाँ-ना प्रश्न से निकास
- मान निष्कर्षण: तारीख़, ईमेल, फ़ोन, राशि——「दस्तावेज़ और डेटा」मार्ग पर ही: मान केवल मूल पाठ से आ सकता है, रेगेक्स से उम्मीदवार खोजें, Jev सही वाला चुने
- समानांतर प्रश्न और स्पेकुलेटिव फैन-आउट——फ़ील्ड प्रश्न थोक में क्यों भेजे जाते हैं: 13 प्रश्न एक ही अनुरोध में 12.2 गुना सस्ते, 10.0 गुना तेज़
अगले पाठ की झलक
एक वाक्य का ऑर्डर शॉपिंग कार्ट बन गया, अगला प्रश्न है कि ढेर सारे उम्मीदवारों में से कौन से वास्तव में मेल खाते हैं। अगला पाठ: खोज और मिलान: रीरैंकिंग, पंक्ति-दर-पंक्ति खोज, एंटिटी अलाइनमेंट।
आप सीखेंगे:
- रीरैंकिंग से CLERC कानूनी क्वेरी की top-1 हिट दर 5% से 18%, top-10 38% से 62%
- GitHub ToS की 218 पंक्तियों की पंक्ति-दर-पंक्ति सिमेंटिक खोज: प्रत्येक पंक्ति को ID दें, एक Choice से मेल खाती पंक्ति की ओर इशारा——इस पृष्ठ के 「विकल्प ही उम्मीदवार」का बड़े पैमाने वाला संस्करण
- दो बियर कैटलॉग के 450 उम्मीदवार जोड़ों में से एक Score और तीन Noul से समान आइटम कैसे खोजें