Box और इमेज: Jev को फोटो में चीज़ें ढूंढने दें
पिछले पाँच पाठों का state केवल टेक्स्ट रखता था। लेकिन असली निर्णय की ज़रूरतें अक्सर फोटो में होती हैं: डोरबेल की फोटो में कोई है या नहीं, स्कैन की गई तालिका पर हस्ताक्षर कहाँ है, बर्ड-फीडर कैमरे के इस फ्रेम में पक्षी कहाँ खड़ा है। ऐसी इमेज GPT को दें, तो वह एक विवरण थूक देगा—जबकि आपको चाहिए ऐसे निर्देशांक जिन्हें सीधे क्रॉप किया जा सके, सीधे if में डाला जा सके।
यह पाठ Jev Box के बारे में है: इसे एक फोटो और एक वाक्य दें, यह लक्ष्य को घेरने वाले सबसे छोटे आयत के चार किनारे लौटाता है। कुल 10 मिनट।
पहले साफ कर दें: Images और Box प्रयोगात्मक फीचर हैं। आधिकारिक शब्दों में dreamer-ready—अभी वे उस प्रोडक्शन मानक तक नहीं पहुंचे जिसकी वे गारंटी देने की स्थिति में हों, रिक्वेस्ट फॉर्मेट और सटीकता वर्शन के साथ बदल सकते हैं। प्रोटोटाइप बनाने, विचार सत्यापित करने के लिए बढ़िया; प्रोडक्शन पर ले जाने से पहले खुद आंकलन करें।
सीखने के बाद आप क्या कर सकेंगे
- Python SDK के
Imageसे एक फोटो state में डालें, और Danger Zone रिक्वेस्ट हेडर वाला पहला Box रिक्वेस्ट भेजें - Box उत्तर पढ़ें:
top/bottom/left/rightचारों किनारे फोटो की चौड़ाई-ऊंचाई के कितने भाग हैं, और उन्हें पिक्सेल निर्देशांक में बदलकर लक्ष्य क्रॉप करें - Box उत्तर में मिलने वाले
confidenceसे तय करें कि बॉक्स सीधे इस्तेमाल करें, किनारे बढ़ाकर क्रॉप करें, या बेहतर इमेज लेकर दोबारा पूछें - एक Noul से गेटकीपिंग करके «Box के पास 'नहीं मिला' उत्तर नहीं होता» समस्या हल करें
- इमेज रिक्वेस्ट की सीमाएँ बताएं: फॉर्मेट, आकार, साइज़, और सीमा पार होने पर कौन-सा एरर कोड मिलेगा
आपकी मौजूदा दुविधा
- GPT से फोटो में चीज़ ढूंढवाएं, तो वह «तस्वीर में बाईं ओर एक मग है» जैसा गद्य लौटाता है—दिशा मिल गई, निर्देशांक नहीं, क्रॉप कोड नहीं लिखा जा सकता
- 专用 डिटेक्शन मॉडल के लिए डेटा लेबल करना, ट्रेन करना, ट्यून करना पड़ता है—सिर्फ एक कप की जगह ढूंढनी हो तो इसके लायक नहीं
- मल्टीमॉडल मॉडल हर बार निर्देशांक अलग फॉर्मेट में लौटाते हैं, और «साफ नहीं दिखा»«नहीं मिला» जैसे तरह-तरह के जवाबों के लिए पार्सर लिखना पड़ता है
यह तरीका कब इस्तेमाल करें
जब आपको चाहिए:
- फोटो में लक्ष्य की स्थिति: स्कैन किए दस्तावेज़ पर हस्ताक्षर, डोरबेल फोटो में इंसान, शेल्फ की फोटो में कोई उत्पाद
- स्थिति सीधे कोड में जा सके: लक्ष्य क्षेत्र क्रॉप करके OCR को भेजना, बॉक्स बनाकर चिह्नित करना,
topकिनारे के अनुसार क्रमबद्ध करना - निर्णय और लोकेशन एक साथ पूछना: इंसान के हाथ में पार्सल है या थैला, लक्ष्य फोटो में है या नहीं
और आप नहीं करना चाहते:
- 专用 विज़न मॉडल ट्रेन या डिप्लॉय करना
- मॉडल के स्वतंत्र रूप से लिखे प्राकृतिक भाषा के निर्देशांक विवरण को पार्स करना
- प्रोटोटाइप चरण में ही विज़न क्षमता के लिए पूरा इंफ्रास्ट्रक्चर खड़ा करना
🎒 शुरू करने से पहले की तैयारी
- State स्थिति पूरा किया है: पता है state क्या है, प्रश्न बैकटिक पाथ से इसके फ़ील्ड को कैसे संदर्भित करता है
- पहला रिक्वेस्ट चला चुके हैं:
.venvमेंtypesafe-sdkइंस्टॉल है,TYPESAFE_API_KEYपर्यावरण वेरिएबल में है - चीज़ ढूंढने के लिए एक फोटो तैयार रखें (आधिकारिक उदाहरण रसोई की फोटो में मग ढूंढता है; न हो तो कोई भी PNG/JPEG चलेगा—पहले चरण 1 की आकार सीमाएँ देखें)
- पता हो कि Box को Jev 1.14 चाहिए (
jev-latestपहले से उसी की ओर इशारा करता है, संभवतः बदलने की ज़रूरत नहीं); पुष्टि करनी हो तोमॉडल और मूल्य देखें
मुख्य विचार
Box बताता है «कहाँ»। आधिकारिक पोज़िशनिंग: Box चौथी प्रश्न-प्रकार है (Choice विकल्प चुनता है, Score स्तर देता है, Noul हाँ-नहीं तय करता है), और पहला स्थिति-प्रकार है जो पूरी तरह «आउटपुट ही डेटा है» के लिए बना है। इसे एक फोटो और एक वाक्य «फोटो में कॉफी का कप» दें, यह कॉफी कप को घेरने वाला सबसे छोटा आयत लौटाता है।
उत्तर बस चार किनारे हैं, और वे अनुपात में।
| फ़ील्ड | अर्थ | रेंज |
|---|---|---|
left / right | फोटो के बाएं किनारे से दूरी, चौड़ाई का अनुपात | 0–1, left < right |
top / bottom | छवि के शीर्ष किनारे से दूरी, ऊँचाई के अनुपात में | 0–1, top < bottom |
मूल बिंदु ऊपरी बाएँ कोने में है: top: 0 छवि का ऊपरी किनारा है, bottom: 1 निचला किनारा। सब 0–1 के अनुपात में हैं, जिसका मतलब है कि कोई भी उत्तर किसी भी छवि आकार पर लागू होता है — फोन से ली गई 4000×3000 और थंबनेल 400×300, दोनों में बॉक्स घेरी गई सापेक्ष स्थिति एक जैसी होती है। बॉक्स खींचने या क्रॉप करने के लिए हर किनारे को छवि के पिक्सेल चौड़ाई-ऊँचाई से गुणा कर दें (चरण 3)।
छवि अनुरोध में कैसे जाती है: रेफरेंस + assets। हर छवि को अनुरोध के शीर्ष स्तर के assets में एक बार रजिस्टर करें, एक रेफरेंस स्ट्रिंग मिलती है; इस रेफरेंस को state, instructions या criteria में कहीं भी लिखें जहाँ कोई स्ट्रिंग आ सकती है, मॉडल को वहीं छवि मिल जाती है। सीधे HTTP से जुड़ते समय multipart फ़ाइल या base64 उपयोग करें; Python SDK आपके लिए रेफरेंस बनाकर अपलोड भी कर देता है, Image(路径) को सीधे state में डाल दें, बस (चरण 2)।
एक स्विच: Danger Zone अनुरोध हेडर। छवि और Box डिफ़ॉल्ट रूप से बंद हैं। छवि या Box वाले हर अनुरोध में यह जोड़ना होगा:
TypeSafe-Danger-Zone-Images: trueSDK में बस extra_headers पास करें (चरण 2)। जोड़ना भूल गए, तो अनुरोध सीधे 400।
Box को अन्य प्रश्नों के साथ मिलाकर पूछा जा सकता है। पिछले पाठों की तरह: सभी प्रश्न एक ही state पर समानांतर में मूल्यांकित होते हैं, प्रश्न जोड़ने से रिस्पॉन्स समय लगभग नहीं बढ़ता।
एक महत्वपूर्ण स्वभाव: Box हमेशा एक बॉक्स लौटाता है। 「नहीं मिला」 जैसा कोई उत्तर नहीं है — छवि में कॉफ़ी का मग न हो, फिर भी यह चार किनारे दे देगा। इसे नियंत्रित करने का तरीका: उसी अनुरोध में एक Noul प्रश्न जोड़ें 「क्या छवि में कॉफ़ी का मग है」, यदि Noul कहे नहीं है तो उस बॉक्स को नज़रअंदाज़ कर दें (चरण 5)।
मेरे साथ करें
चरण 1: सीमाओं के अनुरूप एक छवि तैयार करें और Pillow इंस्टॉल करें
क्यों: छवि अनुरोधों की सीमाएँ टेक्स्ट से अलग हैं — आकार, फ़ॉर्मैट, साइज़ सब कड़ाई से तय हैं, पहले सूची के अनुसार छवि तैयार करें, तभी चरण 2 का अनुरोध 413 / 400 नहीं होगा।
आधिकारिक सीमाएँ (images.md):
| विषय | सीमा |
|---|---|
| फ़ॉर्मैट | PNG या JPEG, स्थिर छवि (एनिमेटेड PNG अस्वीकार कर दी जाती है) |
| प्रति किनारा पिक्सेल | 280–1568, कोई भी किनारा 280 से कम होने पर अस्वीकृत |
| कुल पिक्सेल | 78,400–2,458,624 (यानी 280×280 से 1568×1568 का क्षेत्रफल) |
| प्रति फ़ाइल | ≤ 16 MiB |
| अनुरोध बॉडी | ≤ 32 MiB (सभी छवियाँ, JSON, multipart ढाँचा शामिल) |
छवि तैयार करने के तीन काम (आधिकारिक 「Preparing images」 दिशानिर्देश):
- स्केल करें: सबसे लंबे किनारे को 1568 पिक्सेल से नीचे लाएँ। 1200 लाख पिक्सेल (12 मेगापिक्सेल) वाली एक फोन फ़ोटो आमतौर पर 1568×1176 बन जाती है
- सीधा करें: API सारा मेटाडेटा (EXIF आदि) हटा देती है और EXIF ओरिएंटेशन लागू नहीं करती — फ़ोटो व्यूअर में खड़ी दिखने वाली छवि मॉडल तक पहुँचते-पहुँचते आड़ी हो सकती है। पिक्सेल को ही घुमाएँ, EXIF पर भरोसा न करें
- फ़ॉर्मैट बदलें: GIF, WebP, HEIC को पहले PNG या JPEG में बदलें; स्टैंडर्ड 8-bit baseline JPEG सबसे भरोसेमंद है
एक छवि को तैयार करना हो तो Pillow से तीन लाइनों में हो जाता है (सीधा करना + स्केल करना + स्टैंडर्ड JPEG में बदलना):
from PIL import Image, ImageOps
with Image.open("photo.jpg") as original:
img = ImageOps.exif_transpose(original) # rotate the pixels upright
img.thumbnail((1568, 1568)) # longest side at most 1568, same aspect ratio
img.convert("RGB").save("photo-ready.jpg", "JPEG", quality=90)Pillow इंस्टॉल नहीं है तो इंस्टॉल कर लें (आगे Image.from_pil और क्रॉपिंग में भी लगेगा):
.venv/bin/pip install pillowआपको यह दिखना चाहिए: photo-ready.jpg सफलतापूर्वक बनी; इमेज व्यूअर में खोलें, ओरिएंटेशन सही है, स्पष्टता कम नहीं हुई।
- मेरी छवि PNG/JPEG है, हर किनारा 280–1568 पिक्सेल है, ओरिएंटेशन पहले से सीधा है
चरण 2: Python SDK के Image से पहला Jev Box अनुरोध भेजें
क्यों: सीधे HTTP से जुड़ने पर multipart खुद जोड़ना होता है, रेफरेंस संभालने होते हैं, base64 में बदलना होता है; Python SDK (v0.7.5 से Image और Box समर्थित) यह सब संभाल लेता है — Image ऑब्जेक्ट को कंटेंट में डालें, रेफरेंस अपने आप बनता है, फ़ाइल अपने आप अपलोड होती है।
Image चार तरीकों से दे सकते हैं:
| तरीका | लिखने का ढंग | परिदृश्य |
|---|---|---|
| फ़ाइल पथ | Image(Path("kitchen.jpg")) | सबसे आम |
| रॉ बाइट्स | Image(data) | नेटवर्क स्ट्रीम, डेटाबेस से मिली बाइट्स |
| base64 टेक्स्ट | Image.from_base64(data_base64) | किसी और का अपलोड पाना |
| PIL ऑब्जेक्ट | Image.from_pil(pil_image) | क्रॉप/स्केल के बाद सीधे भेजें, डिस्क पर सहेजने की एक बार बचत; typesafe-sdk[pil] चाहिए |
box_kitchen.py नई फ़ाइल बनाएँ। अपनी photo-ready.jpg ही उपयोग करें, छवि में कोई लक्ष्य चुनें (आधिकारिक उदाहरण कॉफ़ी का मग है, अपनी छवि में जो वास्तव में है उसे रखें):
from pathlib import Path
from typesafe_sdk import Box, Image, TypeSafeClient
with TypeSafeClient() as client:
response = client.system_one(
state={"photo": Image(Path("photo-ready.jpg"))},
questions={
"target": Box(instructions="the coffee mug in `photo`"),
},
extra_headers={"TypeSafe-Danger-Zone-Images": "true"},
)
print(response.answers["target"].box)
print(response.answers["target"].confidence)चलाएँ:
.venv/bin/python box_kitchen.pyआपको यह दिखना चाहिए (मान आपकी छवि और लक्ष्य पर निर्भर करते हैं):
top=0.25 bottom=0.82 left=0.44 right=0.84
0.92तीन बातें:
Box प्रश्न में केवल दो फ़ील्ड होते हैं:
type(निश्चित"box") औरinstructions(क्या खोजना है, किस छवि में)। कोईcriteriaनहीं — विकल्प, स्तर, हाँ-नहीं की परिभाषाएँ यहाँ काम नहीं आतींinstructionsप्रश्न होना ज़रूरी नहीं, एक वाक्य काफ़ी है:"the coffee mug in`photo`"— बैकटिक वाला पथ बताता है कि किस छवि में खोजना है (आधिकारिक मूल शब्द: It doesn't have to be a question)Image(Path(...))को state में रखें, SDK अपने आप एक UUID जैसा रेफरेंस बनाता है — कई छवियाँ, नेस्टेड स्ट्रक्चर, कुछ भी आपस में नहीं उलझतामुझे 0–1 के बीच चार संख्याएँ और एक confidence मिली, कोई 400 एरर नहीं
⚠️ Danger Zone हेडर भूल गए तो सीधे 400
जब तक रिक्वेस्ट में इमेज हो या Box क्वेश्चन हो, TypeSafe-Danger-Zone-Images: true में से एक भी कम नहीं चलेगा। एरर बिना किसी रियायत के आता है: 400, और कारण बिल्कुल साफ लिखा होता है। सीधे HTTP कनेक्ट करने वालों के लिए, API क्विक रेफरेंस में curl का multipart का पूरा उदाहरण है।
💡 Box के लिए Jev 1.14 चाहिए
Jev 1.13 और 1.14 दोनों इमेज स्वीकार करते हैं, लेकिन Box क्वेश्चन 1.14 से ही उपलब्ध हैं। jev-latest पहले से jev-1.14.0 की ओर पॉइंट करता है, सामान्य रूप से उसी के साथ चलते रहें; जिन प्रोजेक्ट्स ने 1.13 को लॉक किया है और Box चाहते हैं, उन्हें पहले मॉडल अपग्रेड करना होगा।
चरण 3: Box उत्तर के चार किनारों को समझें और पिक्सेल निर्देशांकों में बदलें
क्यों: 0–1 के अनुपात को सीधे बॉक्स नहीं खींच सकते और न ही सीधे क्रॉप कर सकते——इसे आपकी इस इमेज के पिक्सेल साइज़ से गुणा करना होगा। ऑफिशियल "Reading a Box" का कोड यही करता है।
पहले रॉ रिस्पॉन्स देखें (curl से सीधे जुड़ने वालों को यह JSON सीधे मिलेगा; SDK को भी यही स्ट्रक्चर मिलता है):
{
"model": "jev-1.14.0",
"answers": {
"mug": {
"type": "box",
"box": {
"top": 0.25,
"bottom": 0.82,
"left": 0.44,
"right": 0.84
},
"confidence": 0.92
}
},
"usage": {"input_tokens": 290, "output_tokens": 21}
}पढ़ने की तुलना (मान लें आपकी इमेज 1568×1176 है):
| फ़ील्ड | मान | बदलाव | पिक्सेल स्थिति |
|---|---|---|---|
left | 0.44 | 0.44 × 1568 | बाएँ से 690px |
right | 0.84 | 0.84 × 1568 | बाएँ से 1317px |
top | 0.25 | 0.25 × 1176 | ऊपर से 294px |
bottom | 0.82 | 0.82 × 1176 | ऊपर से 964px |
ऑफिशियल क्रॉपिंग कोड (Pillow का crop पिक्सेल निर्देशांक लेता है, क्रम है left, top, right, bottom):
from PIL import Image
image = Image.open("photo-ready.jpg")
width, height = image.size
mug = response["answers"]["mug"]
edges = mug["box"]
box = (
round(edges["left"] * width),
round(edges["top"] * height),
round(edges["right"] * width),
round(edges["bottom"] * height),
)
image.crop(box).save("mug.jpg")SDK वाले इसे जस का तस कॉपी कर सकते हैं, बस mug = response["answers"]["mug"] की जगह mug = response.answers["mug"] और edges = mug["box"] की जगह edges = mug.box रखें——उत्तर फ़ील्ड का स्ट्रक्चर एक ही है।
आपको यह दिखना चाहिए: mug.jpg खोलने पर बिल्कुल वही टारगेट है जिसके बारे में आपने पूछा था——कॉफ़ी का मग बिल्कुल साफ़ घिरा हुआ है, ऊपर-नीचे-बाएँ-दाएँ लगभग कोई अतिरिक्त बैकग्राउंड नहीं।
- मेरा क्रॉप परिणाम टारगेट को घेरता है, चारों किनारों का बदलाव उल्टा नहीं हुआ (left/right को चौड़ाई से, top/bottom को ऊँचाई से गुणा किया)
चरण 4: confidence से तय करें कि क्रॉप करें या दोबारा जाँचें
क्यों: Box उत्तर के साथ confidence (0–1, जितना अधिक, उतना ज़्यादा भरोसा) आता है। पिछले पाठ के विचार जैसा ही: हाई कॉन्फिडेंस को सीधे इस्तेमाल करें, लो कॉन्फिडेंस पर ज़्यादा ध्यान दें——एक बॉक्स टेढ़ा क्रॉप हो गया, तो आगे की पूरी पाइपलाइन गलत डेटा प्रोसेस कर रही होगी।
ऑफिशियल कहना: कोई रेकमेंडेड थ्रेशोल्ड नहीं है, अपनी ही इमेज पर ट्यून करें। थ्रेशोल्ड से नीचे होने पर, ऑफिशियल दो रास्ते देता है:
| तरीका | कैसे करें | कब इस्तेमाल करें |
|---|---|---|
| बेहतर इमेज लेकर दोबारा पूछें | बड़ा वर्ज़न भेजें, या बॉक्स के पास का हिस्सा काटकर बड़ा करके उसी Box को दोबारा पूछें | जब ओरिजिनल इमेज का रेज़ोल्यूशन कम हो, टारगेट बहुत छोटा हो |
| पहले किनारे बढ़ाएँ, फिर क्रॉप करें | चारों किनारों को थोड़ा बाहर की ओर सरकाकर crop करें, और इमेज की सीमा के भीतर रखें | जब क्रॉपिंग किसी भी हालत में टारगेट का कोई हिस्सा न काटे |
किनारे बढ़ाने का ऑफिशियल कोड (PAD हर किनारे को बाहर बढ़ाने का अनुपात है, जस का तस कॉपी करके अपनी इमेज के हिसाब से एडजस्ट करें):
PAD = 0.05 # Fraction of the image to add on each side. Tune for your images.
MIN_CONFIDENCE = 0.6 # Example threshold. Tune it on your own images.
if mug["confidence"] < MIN_CONFIDENCE:
edges = {
"left": max(0.0, edges["left"] - PAD),
"top": max(0.0, edges["top"] - PAD),
"right": min(1.0, edges["right"] + PAD),
"bottom": min(1.0, edges["bottom"] + PAD),
}इसके बाद इस नए edges सेट से चरण 3 के तरीके से क्रॉप करें——टारगेट के साथ एक रिंग का मार्जिन भी mug.jpg में जाए, थोड़ा ज़्यादा बैकग्राउंड चल जाए तो चलेगा, लेकिन आधा हैंडल कटना नहीं चाहिए।
आपको यह दिखना चाहिए: हाई कॉन्फिडेंस वाले उत्तर जस के तस इस्तेमाल हों; थ्रेशोल्ड से नीचे वाले उत्तर या तो बॉक्स एक रिंग बड़ा हो जाए, या "बड़ा करके दोबारा पूछने" वाला रास्ता ले।
- मैंने अपने Box उत्तरों के लिए confidence थ्रेशोल्ड तय किया है, उससे नीचे वालों का साफ़ प्रोसेसिंग पाथ है (किनारे बढ़ाना या दोबारा पूछना)
चरण 5: Noul से गेटकीपिंग करें, मिक्स क्वेश्चन बैच में पूछें
क्यों: 1वाँ पर्सनैलिटी प्रॉब्लम——Box हमेशा एक बॉक्स लौटाता है, "नहीं मिला" जैसा कुछ नहीं। टारगेट इमेज में न हो, तब भी वह चार किनारे दे देता है। गेटकीपिंग का समाधान ऑफिशियल पहले से लिख चुका है: उसी रिक्वेस्ट में एक Noul जोड़ें।
ऑफिशियल वैक्सीन रिकॉर्ड उदाहरण ठीक ऐसे ही कॉन्फ़िगर है (Noul पूछता है "है या नहीं", Box पूछता है "कहाँ है"):
questions = {
"mug_visible": Noul(instructions="Is there a coffee mug in `photo`?"),
"mug": Box(instructions="the coffee mug in `photo`"),
}इस्तेमाल एक लाइन में: Noul ना कहे, तो mug के बॉक्स को नज़रअंदाज़ करें। दोनों क्वेश्चन समानांतर में आँके जाते हैं, एक रिक्वेस्ट, और हर उत्तर अपनी ID से जुड़ा होता है।
बाकी तीन हाई-फ्रीक्वेंसी कॉम्बिनेशन ट्रिक्स, सब ऑफिशियल "Writing Box questions" गाइडलाइन से हैं:
| परिदृश्य | तरीका |
|---|---|
| इमेज में एक से ज़्यादा टारगेट हो सकते हैं | शब्दों से केवल एक तक सीमित करें: "the mug nearest the sink in `photo` " |
| शब्दों से साफ़ न हो कि कितने हैं | साथ में एक Choice जोड़ें, विकल्प none / one / several; उत्तर several हो तो इमेज के टुकड़े करें, हर टुकड़े को अलग से दोबारा पूछें |
| बड़ी इमेज में छोटा टारगेट ढूँढना | पहले Choice से इमेज के कई tile में से टारगेट वाला tile चुनें, फिर उसी tile पर Box पूछें |
| किसी इमेज को टारगेट बनाना | टारगेट सीधे instructions में लिखें: "the person in `photo` who matches this badge photo: 9a21c7d3-badge" |
आख़िरी बात इमेज रेफ़रेंस का दूसरा पहलू है: criteria और instructions में भी इमेज रखी जा सकती हैं। ऑफिशियल डॉक्यूमेंटेशन का कुत्ता ढूँढने वाला उदाहरण इसी मैकेनिज़्म का इस्तेमाल करता है: मिले हुए कुत्ते की फ़ोटो state में रखी जाती है, और खोए हुए कुत्ते की सूचना की फ़ोटो सीधे क्वेश्चन में लिखी जाती है, और पूछा जाता है "क्या यह वही कुत्ता है"।
आपको यह दिखना चाहिए: एक रिक्वेस्ट में Noul और Box (और उसके साथ Choice / Score भी) साथ रहते हैं, हर एक अपना उत्तर देता है; mug_visible कम होने पर आपका कोड mug के बॉक्स को सीधे स्किप कर देता है।
- मेरे Box रिक्वेस्ट में एक गेटकीपिंग क्वेश्चन है (Noul या Choice), "नहीं मिला" के लिए कोड में साफ़ एग्ज़िट है
चेकपॉइंट ✅
- मुझे पता है कि Images / Box एक्सपेरिमेंटल फ़ीचर हैं (dreamer-ready): फ़ॉर्मेट बदल सकता है, सटीकता बदल सकती है, ऑफिशियल सीधे प्रोडक्शन में लगाने की सलाह नहीं देता
- मैं चारों किनारों को स्पष्ट बता सकता/सकती हूँ:
left/rightचौड़ाई का अनुपात हैं,top/bottomऊँचाई का अनुपात हैं, मूल बिंदु ऊपरी-बाएँ कोने पर है - मैंने
TypeSafe-Danger-Zone-Images: trueवाले अनुरोध को सफलतापूर्वक चलाया, और पिक्सेल में बदलकर लक्ष्य को काट (crop) सकता/सकती हूँ - मेरे Box उत्तर में confidence थ्रेशोल्ड है; थ्रेशोल्ड से नीचे होने पर मैं किनारे बढ़ाता/बढ़ाती हूँ या दूसरी इमेज लेकर दोबारा पूछता/पूछती हूँ
- मेरे "नहीं मिला" परिदृश्य में एक Noul / Choice की जाँच-परत है, खाली फ्रेम को सही नहीं मानते
आम गलतियों की चेतावनी
❌ इमेज में कोई समस्या नहीं, अनुरोध 400 / 413
400: Images are not turned on
413: The request is over a size limitतीन चीज़ों की स्वयं-जाँच करें:
- क्या किसी भी इमेज या Box प्रश्न वाले अनुरोध में
TypeSafe-Danger-Zone-Images: trueहेडर जोड़ा गया है? (400) - क्या इमेज का आकार सीमा से बाहर है? प्रत्येक भुजा 280–1568, कुल पिक्सेल 78,400–2,458,624, एक फ़ाइल ≤ 16 MiB—सीमा पार होने पर सीधे अस्वीकार, स्वतः स्केल नहीं होता (
413या400) - क्या एक बैच की इमेजें मिलाकर 32 MiB से अधिक हो गईं? API प्रोसेसिंग के समय री-एनकोड करता है, प्रोसेस की गई इमेज आपकी भेजी फ़ाइल से भी बड़ी हो सकती है—ढेर सारी छोटी इमेजें भेजने पर भी सीमा छू सकती है (
413)
आधिकारिक तौर पर यह भी कहा गया है: एक अनुरोध में कई समस्याएँ होने पर त्रुटि केवल उनमें से एक बताती है, सीमा तालिका के अनुसार एक-एक करके जाँचें।
❌ पोर्ट्रेट मोड में ली गई फ़ोटो को वर्टिकल इमेज मानकर इस्तेमाल करना
इमेज व्यूअर में ठीक वर्टिकल दिखती है, लेकिन मॉडल की नज़र में वह हॉरिज़ॉन्टल है—API सारा मेटाडेटा (EXIF ओरिएंटेशन सहित) हटा देता है और उसे लागू नहीं करता। आप पूछते हैं "इमेज के नीचे का कप", मॉडल एक हॉरिज़ॉन्टल इमेज में कप देख रहा होता है।
सही तरीका: भेजने से पहले ImageOps.exif_transpose से पिक्सेल को स्वयं सीधा करें (चरण 1 की Pillow की तीन पंक्तियाँ)। केवल मेटाडेटा बदलना काफ़ी नहीं है।
❌ काटा गया फ्रेम लक्ष्य से मेल नहीं खाता
पहले जाँचें कि रूपांतरण उल्टा तो नहीं: ऊपर-नीचे के लिए ऊँचाई से गुणा, बाएँ-दाएँ के लिए चौड़ाई से गुणा; फिर जाँचें कि Pillow crop का पैरामीटर क्रम (left, top, right, bottom) है। दोनों में से कोई भी उल्टा हो तो फ्रेम इमेज के बाहर चला जाता है या कहीं और टेढ़ा हो जाता है।
फिर भी गलती? confidence देखें—कम विश्वास वाले फ्रेम पहले से ही टेढ़े हो सकते हैं। थ्रेशोल्ड से नीचे होने पर पहले किनारे बढ़ाएँ (चरण 4 का PAD), या काटे हुए क्षेत्र को बड़ा करके वही Box प्रश्न दोबारा पूछें।
❌ एक ही Box से "सभी कॉफ़ी कपों की स्थिति" पूछना
Box प्रत्येक प्रश्न में केवल एक फ्रेम देता है, यह डिज़ाइन है। कई लक्ष्यों की कई स्थितियाँ चाहिए तो: प्रत्येक लक्ष्य के लिए अलग प्रश्न (उसी अनुरोध में भेजें); एक जैसे लक्ष्यों में भेद न हो पाए तो Choice जोड़ें (none / one / several), उत्तर several हो तो टुकड़े करके अलग-अलग दोबारा पूछें। "सभी X ढूँढो" को एक instructions में न ठूँसें।
❌ लक्ष्य इमेज में है ही नहीं, फिर भी फ्रेम मिल जाता है
Box में "नहीं मिला" जैसा कुछ नहीं है। इमेज में कप न हो तो भी उत्तर चार किनारे ही होगा—आपका क्रॉप कोड खुशी-खुशी बैकग्राउंड का एक टुकड़ा काट लेगा।
सही तरीका वही है जो चरण 5 में है: के बगल में एक Noul जोड़ें ("Is there a coffee mug in `photo` ?"); Noul की प्रायिकता कम हो तो उस फ्रेम को नज़रअंदाज़ करें। आधिकारिक वैक्सीन रिकॉर्ड, इनवॉइस सत्यापन और बर्ड-फीडर कैमरा—तीनों cookbook इसी तरीके के हैं।
उन्नत तकनीकें (वैकल्पिक)
तीन तरीकों में से परिदृश्य के अनुसार चुनें। ऑटो-रेफ़रेंस के अलावा, SDK में और भी बारीक नियंत्रण के दो तरीके हैं:
assetsपैरामीटर—अपनी रेफ़रेंस का नाम खुद रखें, टकराने की संभावना कम वाले डिलिमीटर का उपयोग करें (आधिकारिक उदाहरण<product>है):state="Inspect this returned product: <product>"के साथassets={"<product>": Image(photo)}client.attach_assets—इमेज को client से जोड़ें,str(asset)को मुख्य पाठ में रखें:state=f"The customer says {photo} arrived scratched."। अनिवार्य रूप सेwith client.attach_assets(photo):कॉन्टेक्स्ट मैनेजर का उपयोग करें;withके बिना SDK पाठ की रेफ़रेंस को इमेज डेटा से नहीं जोड़ पाता (आधिकारिक चेतावनी के मूल शब्द)
PIL ऑब्जेक्ट सीधे भेजें, एक बार डिस्क पर सहेजना बचाएँ। क्रॉप या स्केल करने के बाद पहले सहेजकर दोबारा पढ़ने की ज़रूरत नहीं—Image.from_pil(pil_image) से सीधे भेजें (JPEG के लिए quality 95 से एनकोड करें; पारदर्शिता या पैलेट वाली इमेज के लिए format="png" भेजें)। इंस्टॉल: .venv/bin/pip install "typesafe-sdk[pil]"। आधिकारिक OCR cookbook इसी रास्ते का उपयोग करता है: पूरे पेज पर फ़ील्ड ढूँढना, क्षेत्र काटकर बड़ा करना, फिर क्रॉप की गई इमेज पर बारीक प्रश्न पूछना।
स्कैन किए दस्तावेज़ों को top किनारे के अनुसार क्रमबद्ध पढ़ें। वैक्सीन रिकॉर्ड cookbook की तरकीब: प्रत्येक पंक्ति के लिए एक Box, box["box"]["top"] छोटा हो तो आगे रखें—सिर्फ़ कोड से बिखरी हुई पंक्तियों को क्रमबद्ध रिकॉर्ड में पढ़ा जा सकता है। पूरा उदाहरण इमेज का व्यावहारिक उपयोग में है।
इमेज का कोई अलग मूल्य नहीं है। प्रत्येक इमेज इनपुट टोकन के अनुसार बिल होती है, पाठ के समान मूल्य पर; usage.input_tokens में सभी इमेजों के टोकन शामिल हैं। इमेज कॉन्टेक्स्ट लंबाई भी घेरती है (64k per-request / 32k per-question)—बड़ी इमेजें ज़्यादा भरने पर max_tokens_exceeded हो सकता है, विवरण मॉडल और मूल्य में देखें।
SDK का उत्तर-संग्रह। Box को response.boxes["target"] से भी लिया जा सकता है—यह response.answers["target"] वाली उन्हीं उत्तरों का Box-विशेष प्रवेशद्वार है।
इस पाठ का सारांश
✅ Jev Box का उपयोग: Image को state में रखें, Box(instructions=...) में एक वाक्य में बताएँ कि क्या ढूँढना है, Danger Zone हेडर चालू करते ही पूछा जा सकता है।
✅ उत्तर पढ़ना: चारों किनारे 0–1 के अनुपात में होते हैं (left/right को चौड़ाई से, top/bottom को ऊँचाई से गुणा करें), किसी भी इमेज आकार पर वही उत्तर मान्य रहता है।
✅ confidence: Box में पहले से आता है, कोई आधिकारिक अनुशंसित थ्रेशोल्ड नहीं—आपकी अपनी निर्धारित सीमा से नीचे हो तो किनारे बढ़ाकर काटें, या बेहतर इमेज लेकर दोबारा पूछें।
✅ जाँच-परत: Box हमेशा एक फ्रेम लौटाता है; Noul पूछता है "है या नहीं", उत्तर कम हो तो फ्रेम को नज़रअंदाज़ करें।
✅ प्रायोगिक विशेषता: dreamer-ready, प्रारूप और सटीकता संस्करण के साथ बदल सकते हैं, प्रोटोटाइप चरण के लिए सबसे उपयुक्त।
मुख्य कॉन्फ़िगरेशन फ़ील्ड की समीक्षा:
| फ़ील्ड | अनुशंसित लेखन शैली | विवरण |
|---|---|---|
type | "box" | निश्चित मान |
instructions | एक वाक्य: क्या ढूँढना है, किस इमेज में | प्रश्न होना ज़रूरी नहीं; criteria नहीं |
| अनुरोध हेडर | extra_headers={"TypeSafe-Danger-Zone-Images": "true"} | इमेज/Box वाले प्रत्येक अनुरोध में आवश्यक |
Image(...) | पथ / bytes / from_base64 / from_pil | from_pil के लिए आवश्यक typesafe-sdk[pil] |
| इमेज आकार | प्रत्येक भुजा 280–1568 पिक्सेल, सबसे लंबी भुजा ≤ 1568 | पहले सीधा करें (EXIF लागू नहीं होता), सीमा पार होने पर सीधे अस्वीकार |
| उत्तर तक पहुँच | response.answers["id"].box / response.boxes["id"] | .box चार किनारे देता है, .confidence 0–1 |
Box का वास्तविक प्रोजेक्ट में पूरा उपयोग देखना चाहते हैं: इमेज प्रैक्टिस: स्कैन किए गए दस्तावेज़ पढ़ना, OCR परिणाम सत्यापित करना — टीका रिकॉर्ड की लाइन-दर-लाइन लोकेशन, इनवॉइस OCR का फ़ील्ड-दर-फ़ील्ड सत्यापन, और बर्ड फ़ीडर कैमरे की स्पीशीज़ लॉग — तीन cookbook की पूरी प्रक्रिया।
सामान्य प्रश्न
Jev क्या सॉफ़्टवेयर है?
Jev एक निर्णय मॉडल है जो TypeSafe द्वारा प्रदान किया जाता है और API कॉल के ज़रिए उपयोग होता है; यह कोई ऐसा स्थानीय सॉफ़्टवेयर नहीं है जिसे इंस्टॉल करना हो। इस पृष्ठ पर प्रयुक्त संस्करण jev-1.14.0 है (jev-latest अब इसी की ओर इशारा करता है), Python SDK typesafe-sdk से अनुरोध भेजें, चरण 2 का कोड देखें।
Jev का डिप्लॉयमेंट कैसे करें?
Jev को आपको स्वयं डिप्लॉय करने की ज़रूरत नहीं है: यह सर्वर साइड पर चलता है, आप बस .venv में typesafe-sdk इंस्टॉल करें और TYPESAFE_API_KEY को एनवायरनमेंट वेरिएबल में सेट करें, फिर अनुरोध भेज सकते हैं। इस पृष्ठ पर इसे सुझाने के कारणों में से यह भी एक है — बिना किसी समर्पित विज़न मॉडल को ट्रेन या डिप्लॉय किए इमेज लोकलाइज़ेशन की जा सकती है।
Jev का आधिकारिक दस्तावेज़ कहाँ देखें?
इमेज अनुरोधों की आधिकारिक सीमाएँ और दिशानिर्देश इस पृष्ठ पर उद्धृत images.md में हैं; मॉडल संस्करण और बिलिंग विवरण के लिए मॉडल और कीमतें देखें, और सीधे HTTP कनेक्ट करने का curl multipart उदाहरण API क्विक रेफ़रेंस में देखें।
Jev का वैक्सीन रिकॉर्ड से क्या संबंध है?
वैक्सीन रिकॉर्ड आधिकारिक cookbook का एक उदाहरण परिदृश्य है: स्कैन किए गए वैक्सीन रिकॉर्ड पर Box से हर पंक्ति को लोकलाइज़ किया जाता है, फिर box["box"]["top"] के आधार पर बिखरी हुई पंक्तियों को क्रमबद्ध रिकॉर्ड में व्यवस्थित किया जाता है। पूरा केस इमेज व्यावहारिक उदाहरण में देखें।
अगले पाठ की झलक
एकल प्रश्न का उपयोग यहीं पूरा हो गया: पांच तरह के पूछने के तरीके (Choice / Score / Noul / confidence / Box) आप पार कर चुके हैं। अब उन्हें सिस्टम में जोड़ें। अगला पाठ: कुशल वर्कफ़्लो: चार आर्किटेक्चर पैटर्न और coding agent के साथ सहयोग।
आप सीखेंगे:
- एक ही अनुरोध में एक बैच प्रश्न पूछने का समानांतर पैटर्न: आधिकारिक परीक्षण में 12.2 गुना लागत में कटौती, 10 गुना गति में वृद्धि
- कॉन्फ़िडेंस-गेटेड रूटिंग: जवाब बताता है「क्या है」, confidence बताता है「क्या करना है」
- जटिल निर्णय को अणु Score में तोड़कर कोड से भारित मर्ज करने वाली कॉम्बिनेशन स्कोरिंग
- Claude Code को TypeSafe Agent Skill से सुसज्जित करें, जो सीधे आपके लिए Jev कॉल करने वाला कोड लिखता है