Skip to content

Box والصور: اجعل Jev يجد الأشياء في الصورة ​

كان ما يوضع في state في الدروس الخمسة الأولى نصًا دائمًا. لكن احتياجات الحكم الحقيقية كثيرًا ما تكمن في الصور: هل في صورة جرس الباب شخص، وأين التوقيع على الجدول الممسوح ضوئيًا، وأين يقف الطائر في هذا الإطار من كاميرا إطعام الطيور. لو سلّمت صورة كهذه إلى GPT، لفظ فقرة وصفية — أما أنت فتريد إحداثيات يمكن قصّها مباشرة وإدخالها مباشرة إلى if.

يتناول هذا الدرس Jev Box: تعطيه صورة وجملة واحدة، فيعيد الحواف الأربعة لأصغر مستطيل يحيط بالهدف. المدة الكاملة 10 دقيقة.

لنقل الصريح منذ البداية: Images وBox ميزتان تجريبيتان. الوصف الرسمي لهما dreamer-ready — أي لم تصل بعد إلى معايير الإنتاج التي يضمنونها، وقد يتغير تنسيق الطلب والدقة مع الإصدارات. ممتازتان لبناء النماذج الأولية والتحقق من الأفكار؛ أما للإنتاج فزِن الأمر بنفسك.

ماذا ستستطيع أن تفعل بعد الدرس ​

  • استخدام Image من Python SDK لوضع صورة في state، وإرسال أول طلب Box بترويسة Danger Zone
  • قراءة إجابة Box: الحواف الأربعة top / bottom / left / right كل منها نسبة من عرض الصورة أو ارتفاعها، وتحويلها إلى إحداثيات بكسل لقص الهدف
  • استخدام confidence المرفق بإجابة Box لتقرر استخدام المربع مباشرة، أم توسيع الحواف قبل القص، أم تجربة صورة أفضل والسؤال مرة أخرى
  • استخدام مسألة Noul واحدة كحاجز، لحل مشكلة «ليس لدى Box إجابة ’لم أجد‘»
  • ذكر قيود طلبات الصور: الصيغة والأبعاد والحجم، وما رمز الخطأ الذي تحصل عليه عند تجاوز الحدود

مأزقك الحالي ​

  • عندما تطلب من GPT إيجاد شيء في صورة، يرد بنص نثري مثل «يوجد كوب في الجزء الأيسر من المشهد» — الاتجاه موجود، والإحداثيات غير موجودة، ولا يمكن كتابة كود القص
  • استخدام نموذج كشف متخصص يتطلب بيانات معنونة وتدريبًا وضبطًا للمعاملات، والمطلوب فقط إيجاد موقع كوب — لا يستحق العناء
  • النماذج متعددة الوسائط تعيد إحداثيات بصيغ مختلفة في كل مرة، وتضطر إلى كتابة محلل يتعامل مع ردود متنوعة مثل «غير واضح» و«لم يتم العثور عليه»

متى تستخدم هذه الحيلة ​

عندما تحتاج إلى:

  • موقع هدف داخل صورة: توقيع على مستند ممسوح ضوئيًا، أو شخص في صورة جرس الباب، أو منتج معين في صورة رف
  • موقع يمكن إدخاله مباشرة إلى الكود: قص منطقة الهدف وإرسالها إلى OCR، أو رسم مربع للتعليق، أو الترتيب بحسب حافة top
  • السؤال عن الحكم والموقع معًا: هل ما في يد الشخص طرد أم كيس، وهل الهدف موجود في الصورة

ولا تريد:

  • تدريب نموذج رؤية مخصص أو نشره
  • تحليل أوصاف إحداثيات بلغة طبيعية يرتجلها النموذج
  • بناء بنية تحتية كاملة لقدرات الرؤية في مرحلة النموذج الأولي

🎒 تجهيزات قبل البدء ​

  • أن تكون قد أكملت حالة State: أن تعرف ما هي state وكيف تشير المسائل إلى حقولها عبر مسارات محددة بعلامة backtick
  • أن تكون قد شغّلت بنجاحالطلب الأول: .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(路径) (أي Image(path)) مباشرة في state وانتهى الأمر (الخطوة 2).

مفتاح واحد: ترويسة Danger Zone. الصور وBox معطّلة افتراضيًا. كل طلب يحتوي صورة أو Box يجب أن يُضاف إليه:

text
TypeSafe-Danger-Zone-Images: true

في SDK الأمر هو تمرير 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 ميجابكسل تصبح عادة 1568×1176
  • التدوير الصحيح: تُزيل الـ API جميع البيانات الوصفية (EXIF وغيرها) ولا تطبّق اتجاه EXIF——ما يظهر عموديًا في عارض الصور قد يصل أفقيًا إلى النموذج. دوّر البكسلات نفسها ولا تعتمد على EXIF
  • تغيير الصيغة: حوّل GIF وWebP وHEIC أولًا إلى PNG أو JPEG؛ صيغة JPEG القياسية baseline ذات 8-bit هي الأكثر استقرارًا

لتجهيز صورة واحدة، تكفي ثلاثة أسطر بـ Pillow (تدوير صحيح + تصغير + تحويل إلى JPEG قياسي):

python
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 والقص):

bash
.venv/bin/pip install pillow

يفترض أن ترى: نجح توليد photo-ready.jpg؛ افتحها بعارض الصور، الاتجاه صحيح والوضوح لم يتدهور.

  • صورتي بصيغة PNG/JPEG، كل حافة 280–1568 بكسل، والاتجاه مصحّح مسبقًا

الخطوة 2: أرسل أول طلب Jev Box باستخدام Image من Python SDK ​

لماذا: مع HTTP المباشر عليك بناء multipart بنفسك وإدارة المراجع والتحويل إلى base64؛ أما Python SDK (يدعم Image وBox منذ الإصدار v0.7.5) فيتولى كل ذلك——ضع كائن Image في المحتوى، فيُولَّد المرجع تلقائيًا ويُرفع الملف تلقائيًا.

يدعم Image أربع طرق للتحميل:

الطريقةالصياغةالسيناريو
مسار ملفImage(Path("kitchen.jpg"))الأكثر شيوعًا
بايتات خامImage(data)بايتات من بث شبكي أو قاعدة بيانات
نص base64Image.from_base64(data_base64)عند استقبال رفع من طرف آخر
كائن PILImage.from_pil(pil_image)إرسال مباشر بعد القص/التصغير، توفير لكتابة ملف على القرص؛ يتطلب typesafe-sdk[pil]

أنشئ box_kitchen.py. استخدم photo-ready.jpg الخاصة بك، واختر هدفًا في الصورة (المثال الرسمي فنجان قهوة، استبدله بشيء موجود فعلًا في صورتك):

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

شغّل:

bash
.venv/bin/python box_kitchen.py

يفترض أن ترى (القيم تعتمد على صورتك وهدفك):

text
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 يحصل على نفس البنية):

json
{
  "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):

الحقلالقيمةالتحويلالموضع بالبكسل
left0.440.44 × 1568على بعد 690px من اليسار
right0.840.84 × 1568على بعد 1317px من اليسار
top0.250.25 × 1176على بعد 294px من الأعلى
bottom0.820.82 × 1176على بعد 964px من الأعلى

كود القص الرسمي (الدالة crop في Pillow تستقبل إحداثيات بالبكسل، والترتيب هو left, top, right, bottom):

python
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 تجد الهدف الذي سألت عنه بالضبط — فنجان القهوة محاط بإحكام، بلا خلفية زائدة تقريبًا من كل الجهات.

  • نتيجة القص لدي أطّرت الهدف، ولم أخلط الحواف الأربع في التحويل (يسار/يمين تُضرب في العرض، أعلى/أسفل تُضرب في الارتفاع)

الخطوة 4: استخدام confidence لتحديد ما إذا سيتم القص أم المراجعة ​

لماذا: تأتي إجابة Box مع confidence (0–1، وكلما ارتفعت زادت الثقة). كما في الدرس السابق: الثقة العالية تُستخدم مباشرة، والثقة المنخفضة تحتاج مزيدًا من العناية — إطار واحد مائل في القص يعني أن خط المعالجة بأكمله يعمل على بيانات خاطئة لاحقًا.

الرواية الرسمية: لا يوجد حد موصى به، اضبطه على صورك بنفسك. عند النزول دون حدك، تقدم الوثائق الرسمية طريقين:

الطريقةكيفية التنفيذمتى تُستخدم
اسأل مجددًا بصورة أفضلأرسل نسخة أكبر، أو قص منطقة قرب الإطار وضخّمها ثم أعد نفس سؤال Boxعندما تكون دقة الصورة الأصلية منخفضة والهدف صغيرًا جدًا
وسّع الحواف أولًا ثم اقصحرّك الحواف الأربع قليلًا نحو الخارج ثم نفّذ crop، مع البقاء داخل حدود الصورةعندما يجب ألا يقطع القص أي جزء من الهدف إطلاقًا

كود توسيع الحواف الرسمي (PAD هو نسبة التوسيع الخارجي لكل حافة، انسخه كما هو ثم اضبطه حسب صورتك):

python
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، ومن الأفضل إبقاء شيء زائد من الخلفية على قطع نصف مقبض الكوب.

يجب أن ترى: الإجابات ذات confidence العالية تُستخدم كما هي؛ والإجابات دون الحد فإما أن يصبح إطارها أكبر بدرجة، وإما أنها سلكت طريق «التضخيم وإعادة السؤال».

  • حددت حدًا لـ confidence لإجابات Box لدي، وعند النزول عنه لدي مسار معالجة واضح (توسيع الحواف أو إعادة السؤال)

الخطوة 5: استخدام Noul كبوابة حماية مع أسئلة مختلطة دفعة واحدة ​

لماذا: السلوك الغريب رقم 1 — Box يُرجع دائمًا مربعًا، ولا وجود لـ«لم يتم العثور عليه». إذا لم يكن الهدف داخل الصورة، فإنه يعطي أربعة حدود رغم ذلك. الحل الحارس مكتوب رسميًا: أضف Noul واحدًا إلى الطلب نفسه.

مثال سجلات التطعيم الرسمي مضبوط هكذا بالضبط (Noul يسأل «هل هو موجود»، و Box يسأل «أين هو»):

python
questions = {
    "mug_visible": Noul(instructions="Is there a coffee mug in `photo`?"),
    "mug": Box(instructions="the coffee mug in `photo`"),
}

الاستخدام في جملة واحدة: إذا قال Noul إنه غير موجود، فتجاهل إطار mug. السؤالان يُقيّمان بالتوازي، في طلب واحد، ولكل إجابة معرّفها الخاص.

ثلاث تقنيات أخرى عالية التكرار للدمج، كلها من قواعد «Writing Box questions» الرسمية:

السيناريوالطريقة
قد يحتوي على أكثر من هدف واحد في الصورةقيّده نصيًا إلى هدف وحيد: "the mug nearest the sink in `photo` "
عندما لا يستطيع النص توضيح العددأضف بجانبه سؤال Choice، بالخيارات none / one / several؛ إذا كانت الإجابة several فقسّم الصورة إلى قطع وأعد السؤال لكل قطعة على حدة
البحث عن هدف صغير في صورة كبيرةاستخدم Choice أولًا لاختيار الـ tile الذي يقع فيه الهدف من بين عدة tiles للصورة، ثم اطرح سؤال Box على ذلك الـ tile
استخدام صورة كهدفاكتب الهدف مباشرة في 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، وأستطيع التحويل بالبكسل لقص الهدف
  • إجابة Box لدي بها عتبة confidence، وما دون العتبة أوسّع الإطار أو أبدّل الصورة وأعيد السؤال
  • سيناريو «لم يُعثر عليه» لدي بوابة Noul / Choice، فلن أعتبر إطارًا فارغًا حقيقيًا

تنبيهات من العثرات الشائعة ​

❌ الصورة سليمة، والطلب يرجع 400 / 413 ​

text
400: Images are not turned on
413: The request is over a size limit

ثلاث نقاط للفحص الذاتي:

  • هل أضفت ترويسة TypeSafe-Danger-Zone-Images: true إلى كل طلب يتضمن صورة أو سؤال Box؟ (400)
  • هل تجاوزت أبعاد الصورة الحدود؟ لكل ضلع 280–1568، وإجمالي البكسلات 78,400–2,458,624، وحجم الملف الواحد ≤ 16 MiB — التجاوز يُرفض مباشرة دون تصغير تلقائي (413 أو 400)
  • هل تجاوز مجموع دفعة الصور 32 MiB؟ يعيد الـ API الترميز أثناء المعالجة، وقد تكون الصورة بعد المعالجة أكبر من الملف الذي أرسلته — إرسال مجموعة صور صغيرة قد يصطدم بالحد أيضًا (413)

تشير الوثائق الرسمية أيضًا إلى: عند وجود عدة مشكلات في طلب واحد، يُبلَّغ عن الخطأ لواحدة منها فقط، فراجع جدول الحدود بندًا بندًا.

❌ استخدام صورة ملتقطة عموديًا كصورة عمودية ​

تبدو عمودية تمامًا في برنامج عرض الصور، لكنها أفقية في عين النموذج — يجرّد الـ API كل البيانات الوصفية (بما فيها اتجاه EXIF) ولا يطبّقها. تسأل عن «الكوب في أسفل الصورة»، بينما النموذج ينظر إلى كوب في صورة أفقية.

الطريقة الصحيحة: قبل الإرسال استخدم ImageOps.exif_transpose لتدوير البكسلات نفسها (أسطر Pillow الثلاثة في الخطوة 1). لا تكتفِ بتعديل البيانات الوصفية.

❌ الإطار المقصوص لا يطابق الهدف ​

تحقق أولًا من عدم عكس عملية التحويل: الأعلى/الأسفل يُضرب في الارتفاع، واليسار/اليمين يُضرب في العرض؛ ثم تحقق من أن ترتيب معاملات Pillow crop هو (left, top, right, bottom). عكس أيٍّ من الاثنين يجعل الإطار يطير خارج الصورة أو ينحرف إلى مكان آخر.

ما زال الخطأ؟ انظر إلى confidence — الإطارات منخفضة الثقة قد تنحرف بطبيعتها. ما دون العتبة: وسّع الإطار أولًا (PAD في الخطوة 4)، أو كبّر المنطقة المقصوصة وأعد سؤال Box نفسه مرة أخرى.

❌ سؤال Box واحد عن «مواقع كل أكواب القهوة» ​

يعيد Box إطارًا واحدًا فقط لكل سؤال، وهذا بالتصميم. لعدة مواقع لعدة أهداف: سؤال مستقل لكل هدف (داخل الطلب نفسه)؛ وعند تعذّر تمييز الأهداف من النوع نفسه أضف Choice (none / one / several)، فإذا كانت الإجابة several قسّم إلى قطع واسأل كلًّا على حدة. لا تحشر «اعثر على كل X» في تعليمات instructions واحدة.

❌ الهدف غير موجود في الصورة أصلًا، ومع ذلك يوجد إطار ​

لا يوجد في Box حالة «لم يُعثر عليه». إن لم يكن هناك كوب في الصورة، ستكون الإجابة أربع حواف رغم ذلك — وسيقص كود القص عندك قطعة من الخلفية بكل سرور.

الطريقة الصحيحة هي الخطوة 5: أضف بجانبه سؤال Noul ("Is there a coffee mug in `photo` ?")، فإذا كانت احتمالية Noul منخفضة تجاهل ذلك الإطار. كتب الطبخ الرسمية الثلاثة — سجلات التطعيم ومطابقة الفواتير وكاميرا إطعام الطيور — تتبع هذا النمط نفسه.

تقنيات متقدمة (اختيارية) ​

ثلاث طرق لتضمين المراجع، اختر حسب السيناريو. إلى جانب التضمين التلقائي، يوفر الـ 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 تستخدم هذا المسار: البحث عن الحقول في الصفحة كاملة، قص المنطقة وتكبيرها، ثم سؤال تفصيلي عن الصورة المقصوصة.

قراءة المستندات الممسوحة بترتيب حافة top. حيلة كتاب الطبخ لسجلات التطعيم: Box لكل سطر، وbox["box"]["top"] الأصغر يُرتَّب أولًا — بكود خالص تقرأ الأسطر المبعثرة كسجلات مرتبة. الحالة الكاملة فيتطبيقات الصور العملية.

لا سعر منفصل للصور. كل صورة تُحتسب برموز الإدخال، بنفس سعر النص؛ وusage.input_tokens يتضمن رموز كل الصور. الصور تستهلك أيضًا من طول السياق (64k لكل طلب / 32k لكل سؤال) — حشر صور كبيرة يسبب max_tokens_exceeded، والتفاصيل فيالنماذج والأسعار.

مجموعة إجابات الـ SDK. يمكن الحصول على Box أيضًا من response.boxes["target"] — وهو مدخل مخصص لـ Box من نفس دفعة إجابات response.answers["target"].

خلاصة هذا الدرس ​

✅ Jev طريقة استخدام Box: Image في الـ state، وBox(instructions=...) بجملة توضح ما تبحث عنه، وبمجرد تفعيل ترويسة Danger Zone يمكنك السؤال.

✅ قراءة الإجابة: الحواف الأربع كلها نسب ضمن 0–1 (يسار/يمين تُضرب في العرض، أعلى/أسفل تُضرب في الارتفاع)، فالإجابة نفسها تصح مع أي أبعاد للصورة.

✅ confidence: مدمج في Box، ولا توجد عتبة رسمية موصى بها — ما دون الخط الذي تحدده بنفسك وسّع الإطار ثم قص، أو بدّل بصورة أفضل وأعد السؤال.

✅ البوابة: يعيد Box إطارًا دائمًا؛ Noul يسأل «هل موجود؟»، فإذا كانت الإجابة منخفضة تجاهل الإطار.

✅ ميزة تجريبية: dreamer-ready، قد يتغير التنسيق والدقة بين الإصدارات، وهي الأنسب لمرحلة النماذج الأولية.

مراجعة حقول الإعداد الأساسية:

الحقلالكتابة الموصى بهاالشرح
type"box"قيمة ثابتة
instructionsجملة واحدة: ما تبحث عنه وفي أي صورةلا يلزم أن يكون سؤالًا؛ لا يوجد criteria
ترويسة الطلبextra_headers={"TypeSafe-Danger-Zone-Images": "true"}كل طلب يتضمن صورة أو Box يحتاجها
Image(...)مسار / bytes / from_base64 / from_pilfrom_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 لا يحتاج إلى نشر من جانبك: فهو يعمل على الخادم، ويكفي أن تثبّت typesafe-sdk داخل .venv وتضبط TYPESAFE_API_KEY في متغيرات البيئة لتتمكن من إرسال الطلبات. وهذا أحد أسباب توصيتنا به في هذه الصفحة — إذ يمكنك تحديد مواقع الصور دون تدريب أو نشر نموذج رؤية مخصص.

أين يمكن الاطلاع على الوثائق الرسمية لـ Jev؟ ​

القيود والإرشادات الرسمية لطلبات الصور موجودة في images.md المُقتبس في هذه الصفحة؛ أما تفاصيل إصدارات النماذج والتسعير فانظر النماذج والأسعار، ومثال curl multipart للاتصال المباشر عبر HTTP موجود في مرجع 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
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.