تطبيقات عملية على الصور: قراءة المستندات الممسوحة ضوئيًا والتحقق من نتائج OCR
💡 الخلاصة في جملة: استخدم Jev للتعرف على الصور لبناء مسارين لمعالجة المستندات الورقية — للمستندات الممسوحة «Noul يحدد الوجود، وBox يحدد المكان، وChoice يقرأ القيمة»، ولنتائج OCR «تحقق على الصفحة الكاملة، ثم فحص دقيق على القصاصة»، والدرجات المنخفضة تُحوَّل إلى المراجعة اليدوية.
تعلمت في الدرس التمهيدي Box والصور كيفية إرسال الطلبات المصحوبة بصور وقراءة الحواف الأربع. هذا الدرس يجمع ذلك في مشروع كامل. توفر الجهة الرسمية ثلاثة أدلة عملية للصور: Reading a scanned vaccination record (قراءة سجل تطعيم ممسوح ضوئيًا)، وOCR confidence and bounding boxes (التحقق من قيم OCR للفواتير)، وFeeder-cam visit log (سجل أنواع كاميرا مراقبة الطيور). يغطي هذا الدرس الدليلين الأولين، ويُدمج الثالث في قسم التقنيات المتقدمة.
لنعرض أولاً الأرقام الرسمية لنرى الأثر الفعلي لهذه الطريقة: 16 لقاحًا مرشحًا حُكم عليها جميعها بشكل صحيح في طلب واحد — اللقاحات 6 الموجودة في السجل باحتمال 0.97 فأكثر، بينما «لقاح التهاب الكبد A و B المدمج» الشبيه جدًا حصل على 0.02 فقط؛ التاريخ المغطى بملصق أجاب عنه النموذج بـ «غير مقروء» بدلًا من التخمين؛ أخطاء القراءة الثلاثة في OCR الفاتورتين (AN400074، وINV03070، و16/09/2028) كُشفت جميعها بالفحصين. يستغرق هذا الدرس حوالي 20 دقيقة؛ وتأتي الأمثلة الرسمية مع ذاكرة تخزين مؤقت للإجابات json_cache.json — وفقًا للشرح الرسمي، عندما تكون الذاكرة المؤقتة في مجلد التشغيل يعيد السكربت تشغيل الذاكرة بدلًا من إرسال طلبات فعلية، ويمكن الحصول على نفس الأرقام الواردة في هذه الصفحة حتى بدون مفتاح.
ماذا ستستطيع أن تفعل بعد إتمام الدرس
- كتابة مسار لقراءة المستندات الممسوحة ضوئيًا: Noul + Box للعثور على كل صف تريده في الجدول، وChoice لقراءة القيمة، والحصول على
unreadableبدلًا من سنة مُخمَّنة عند عدم وضوح القراءة - فصل «قراءة الصورة» عن «الحكم بناءً على القراءة» إلى طلبين — الاختبار الرسمي الفعلي: النسخة التي تدمجهما في سؤال واحد أدت إلى إفلات مشكلتين معًا من خط المراجعة
- التحقق من قيم استخراج OCR: فحص كل حقل على الصفحة الكاملة ثم فحص دقيق على الصورة المقصوصة، وأقل من 0.25 يُحوَّل إلى المراجعة اليدوية، مع رسم إطار المراجعة على الصورة الأصلية
- استخدام نفس مجموعة الأسئلة لمعالجة إطارات الفيديو المتتالية: وجود طائر في إطارات كاميرا مراقبة الطيور الـ 101 حُكم عليه بشكل صحيح بالكامل (101/101)، والتعرف على الأنواع 132/133
لماذا نستخدم Jev للتعرف على الصور بدلًا من ترك LLM متعدد الوسائط ينظر إلى الصورة مباشرة؟
«إرسال المستند الممسوح ضوئيًا إلى GPT ليقرأه لي» هو رد الفعل الأول للكثيرين — يعمل، لكن ما تحصل عليه هو فقرة نصية، وليس حكمًا يمكن استخدامه في الكود.
| القدرة | LLM متعدد الوسائط ينظر إلى الصورة مباشرة | Jev التعرف على الصور |
|---|---|---|
| المحتوى غير الواضح | ❌ يميل إلى إعطاء إجابة على أي حال — التاريخ تحت الملصق «يُقرأ» بنفس الطريقة | ✅ وضع خيار unreadable في Choice، وفي المثال الرسمي اختاره النموذج فعلًا، وكان احتمال قابلية القراءة لـ Noul المجاور 0.05 |
| معلومات الموقع | ❌ وصف نثري من نوع «صف يقع أعلى منتصف الجدول قليلًا» | ✅ يعيد Box نسب الحواف الأربع، فتُقص الصف مباشرة ليراها من يقوم بالمراجعة |
| درجة الثقة | ❌ كل مرة تسأل «هل أنت متأكد؟» تتغير الإجابة | ✅ كل سؤال مصحوب باحتمال: اللقاح الموجود في الصفحة 0.97+، وغير الموجود 0.02، والعتبة مكتوبة في الكود الخاص بك |
| الحكم وقراءة الصورة | ❌ أمر prompt واحد يشمل كل شيء، وعند الخطأ لا يُعرف إن كان عدم قراءة صحيحة أم حكمًا خاطئًا | ✅ قراءة الصورة في طلب، والحكم بناءً على القراءة في طلب آخر — كل خطوة أخطأت تظهر بوضوح منفصل |
| شكل الإجابة | ❌ نص حر، وعلى المرحلة التالية كتابة محلل | ✅ إجابات مُنمَّطة + توزيع احتمالات، وif يُستخدم مباشرة |
باختصار: LLM «يصف» لك الصورة، وJev «يحكم» على الصورة لك — الحكم فقط له احتمالات، وبالاحتمالات يمكن وضع خط للمراجعة.
مأزقك الحالي
- «مستندات ورقية ممسوحة ضوئيًا مكومة كالجبال يجب إدخالها إلى النظام، وقد انتهى تشغيل OCR، لكن لا أحد يعرف أي الحقول قُرئت خطأ — وقت التحقق واحدًا واحدًا أطول من الكتابة اليدوية»
- «تركت نموذجًا متعدد الوسائط يقرأ المستندات الممسوحة، فالتاريخ المغطى بالبقعة يجرؤ على إعطائي سنة، وعند الخطأ لا ينبّه إطلاقًا»
- «أريد من النموذج أن يخبرني بموقع الهدف في الصورة، فيرد عليّ بنص نثري من نوع «في الجزء الأيسر قليلًا من المشهد»، ولا يمكن كتابة كود القص أصلًا»
متى تستخدم هذه الطريقة
عندما تحتاج إلى:
- قراءة معلومات منظمة من مستندات ممسوحة ضوئيًا أو مصوّرة بالكاميرا: صفوف الجداول، والتواريخ، والأرقام، والمبالغ
- أن يكون OCR قد استخرج القيم بالفعل، لكنك تريد شيئًا يتحقق من كل حقل: هل القيمة صحيحة، وهل هي موجودة في الصفحة، وهل قُرئت خطأً
- الحصول على الحكم والموقع معًا: ماذا يقول هذا الصف، وفي أي مكان من الصورة يقع (لتقصّه بسهولة لمراجعته بشريًا)
ولا تريد:
- تدريب أو نشر نموذج رؤية متخصص
- تحليل الردود بلغة طبيعية يكتبها نموذج متعدد الوسائط بحرية
- التخمين في أي خطوة أخطأت داخل إجابة تخلط «قراءة الصورة» و«الحكم» معًا
🎒 التحضير قبل البدء
- اكتملت Box والصور: تعرف كيفية إرسال الصور عبر
Imageفي Python SDK، وتعرف ترويسةTypeSafe-Danger-Zone-Images: true، وتستطيع قراءة نسب الحواف الأربعة - يُنصح بقراءة أسئلة Noul نعم/لا وأسئلة Choice الاختيارية: كل خطوة في هذا الدرس هي مزيج من هذين النوعين من الأسئلة مع Box
- نجحت في تشغيلالتثبيت وأول طلب:
.venvمتاح. النصف الأول من هذا الدرس يعمل حتى بدون مفتاح(إعادة تشغيل الكاش الرسمي)؛ لإرسال طلبات حقيقية قم بتعيينTYPESAFE_API_KEY - فنجان قهوة ☕——هذا الدرس هو الختام في مسار C: ثلاثة أدلة رسمية (cookbook)، قراءة مستندات ممسوحة، التحقق من الفواتير، ومراقبة الطيور، كلها بنفس المنهجية: «بوابة + تحديد موقع + قراءة قيمة»
اتبع خطواتي
أنشئ image_docs.py، والصق كتل الكود لكل خطوة أدناه بالترتيب في نفس الملف. الخطوة 1–5 هي مستند سجل تطعيم ممسوح (مثال رسمي)، والخطوة 6 تنتقل إلى التحقق من OCR للفواتير (مثال رسمي آخر، حجم التغيير: تبديل الصورة وجدول الحقول). لا تملك مفتاحًا حاليًا؟ يمكنك التشغيل على أي حال——الملف الرسمي json_cache.json يحتوي على الاستجابات الأصلية لكل الأرقام في هذه الصفحة، وعندما يكتشف السكربت الكاش يعيد تشغيله دون إرسال طلبات حقيقية (للتشغيل الحقيقي احذف ملف الكاش).
الخطوة 1: تثبيت البيئة، وتنزيل مثال المستند الممسوح الرسمي والكاش
لماذا: الدليل الرسمي سجل كل استجابة API في json_cache.json——بنص رسمي: عندما يكون الكاش موجودًا، يعيد السكربت تشغيل هذه الاستجابات بدلًا من استدعاء API، لذا تحصل على نفس أرقام الجهة الرسمية. بتجهيز المواد أولًا، سيكون لديك أرقام رسمية للمقارنة في كل خطوة لاحقة.
ثبّت التبعيات (أمر التثبيت من دليل سجلات التطعيم الرسمي، مع إضافة pillow——سيستخدمها القص في الخطوة 5):
pip install ipython matplotlib pillow 'typesafe-sdk>=0.7.5,<0.8.0' \
'cooksafe>=0.2.0,<0.3.0'نزّل المستند الممسوح والكاش من مستودع الأمثلة الرسمي (typesafe-public-examples، ضعهما في نفس مجلد السكربت):
curl -sL -o vaccination_record.jpg https://raw.githubusercontent.com/typesafe-ai/typesafe-public-examples/main/cookbooks/reading_scanned_documents/vaccination_record.jpg
curl -sL -o json_cache.json https://raw.githubusercontent.com/typesafe-ai/typesafe-public-examples/main/cookbooks/reading_scanned_documents/json_cache.jsonالصق ترويسة الملف——العميل، وثوابت العتبات، ودالة الطلب مع الكاش:
import hashlib
import json
import os
from datetime import date
from pathlib import Path
from time import perf_counter
from cooksafe import JsonCache
from typesafe_sdk import Image, TypeSafeClient
TYPESAFE_MODEL = "jev-1.14.0" # Box questions need Jev 1.14
IMAGES_ON = {"TypeSafe-Danger-Zone-Images": "true"} # opt in to the image preview
READ_CUTOFF = 0.90 # below this, a person checks the reading against the paper
LEGIBLE_CUTOFF = 0.50 # the legibility Noul gets its own, lower cutoff
IN_DATE_CUTOFF = 0.50 # below this, a nurse checks whether the dose still covers the trip
client = TypeSafeClient(
api_key=os.environ.get("TYPESAFE_API_KEY", "cache-only"), # keyless kernels replay
timeout=120.0,
)
json_cache = JsonCache(Path("json_cache.json"))
PAGE = Path("vaccination_record.jpg")
PAGE_SHA = hashlib.sha256(PAGE.read_bytes()).hexdigest()[:16] # cache key for the scan
@json_cache
def ask(model: str, page_sha: str, questions_json: str) -> dict:
"""One request: the scan as the state, plus a set of questions about it."""
started = perf_counter()
response = client.system_one(
state={"page": Image(PAGE)},
questions=json.loads(questions_json),
model=model,
extra_headers=IMAGES_ON,
)
return {
"answers": {k: a.model_dump(mode="json") for k, a in response.answers.items()},
"seconds": round(perf_counter() - started, 2),
}
def ask_page(questions: dict) -> dict:
if not questions: # nothing to ask, such as a page with no rows found
return {"answers": {}}
return ask(TYPESAFE_MODEL, PAGE_SHA, json.dumps(questions, sort_keys=True))
print("setup ok")شغّل python image_docs.py.
يجب أن ترى: setup ok——هذه الخطوة مجرد تجهيز، لم يُرسل أي طلب بعد.
::: تحذير ⚠️ ميزة تجريبية، النص الرسمي يستحق أن يُعلّق على الجدار Images و Box في مرحلة المعاينة المبكرة (تسميها الجهة الرسمية dreamer-ready، ولم تصل لمعايير الإنتاج): الطلبات التي تحمل صورًا أو Box يجب أن تتضمن ترويسة TypeSafe-Danger-Zone-Images: true، وقد يتغير تنسيق الطلب بين الإصدارات. أسئلة Box تتطلب Jev 1.14——jev-latest يشير بالفعل إلى jev-1.14.0. في مرحلة النماذج الأولية جرّب بحرية، أما الإنتاج فقرّر بنفسك. للصور نفسها قيود: PNG/JPEG، 280–1568 بكسل لكل جانب، ملف واحد ≤ 16 MiB، فالمستندات الممسوحة عالية الدقة قلّصها قبل الإرسال، راجع جدول القيود في درس Box والصور. :::
setup okطُبع، وvaccination_record.jpgوjson_cache.jsonكلاهما في مجلد التشغيل
الخطوة 2: Jev السؤال الأول في التعرف على الصور——هل Noul موجود، وفي أي سطر يقع Box
لماذا: Jev لا يقوم بمهمة «تحويل الصورة إلى قائمة بيانات»——بل يجيب عنأسئلة حول الصورة. لذا فالتقسيم الرسمي هو: لديك قائمة (الـ 16 لقاحات التي سجلتها هذه العيادة)، ولكل مرشح تطرح سؤالين. هذا بالضبط حل Box يُرجع دائمًا مربعًا واحدًا: Noul مسؤول عن «هل موجود»، وBox مسؤول عن «أين»، وإذا قال Noul غير موجود فتجاهل ذلك المربع.
طلب واحد يحمل 33 سؤالًا: 16 لقاحات × (Noul + Box) + سؤال Noul 1 للتحقق «هل في الجدول لقاحات خارج القائمة»——السؤال الأخير أضافته الجهة الرسمية خصيصًا: الأسئلة الأخرى الـ 32 لا تلتقط حالة «القائمة ناقصة». آلية خلط أنواع الأسئلة والطرح المتوازي مشروحة فيالطرح المتوازي والتوسع الاحتمالي.
VACCINES = [
"Hepatitis A", "Hepatitis B", "Hepatitis A and B combined", "Typhoid",
"Hepatitis A and typhoid combined", "Yellow fever", "Rabies", "Japanese encephalitis",
"Tick-borne encephalitis", "Cholera", "MenACWY", "MenB",
"Tetanus, diphtheria and polio (Td/IPV)", "MMR", "Varicella", "Influenza",
]
PRESENT_CUTOFF = 0.5 # P(recorded) at or above this counts the vaccine as on the page
def find_questions() -> dict:
questions = {"unlisted": {
"type": "noul",
"instructions": {
"question": "Does the vaccines table in `page` record any vaccine that is not "
"in this list?",
"list": VACCINES,
},
}}
for i, vaccine in enumerate(VACCINES):
questions[f"vac_{i:02d}"] = {
"type": "noul",
"instructions": f"Is {vaccine} recorded in the vaccines table in `page`, with "
"exactly this name?",
}
questions[f"vac_{i:02d}|box"] = {
"type": "box",
"instructions": f"the whole {vaccine} row of the vaccines table in `page`",
}
return questions
found = ask_page(find_questions())
F = found["answers"]
present = []
for i, vaccine in enumerate(VACCINES):
p, box = F[f"vac_{i:02d}"]["noul"], F[f"vac_{i:02d}|box"]
print(f"{vaccine:<40}recorded {p:.2f} box top {box['box']['top']:.2f}")
if p >= PRESENT_CUTOFF:
present.append({"vaccine": vaccine, "present": p, "box": box["box"],
"box_confidence": box["confidence"]})
print(f"\nanother vaccine on the page: {F['unlisted']['noul']:.2f}")
rows = sorted(present, key=lambda r: r["box"]["top"]) # box tops give the page order
for n, row in enumerate(rows, 1):
row["id"], row["position"] = f"row-{n}", nشغّل python image_docs.py.
يجب أن ترى(أرقام مسجلة من jev-1.14.0 الرسمي):
Hepatitis A recorded 0.98 box top 0.33
Hepatitis B recorded 0.98 box top 0.40
Hepatitis A and B combined recorded 0.02 box top 0.36
Typhoid recorded 0.98 box top 0.48
Hepatitis A and typhoid combined recorded 0.01 box top 0.34
Yellow fever recorded 0.98 box top 0.55
Rabies recorded 0.97 box top 0.69
Japanese encephalitis recorded 0.01 box top 0.35
Tick-borne encephalitis recorded 0.01 box top 0.34
Cholera recorded 0.01 box top 0.34
MenACWY recorded 0.00 box top 0.34
MenB recorded 0.01 box top 0.35
Tetanus, diphtheria and polio (Td/IPV) recorded 0.98 box top 0.62
MMR recorded 0.01 box top 0.33
Varicella recorded 0.01 box top 0.34
Influenza recorded 0.01 box top 0.34
another vaccine on the page: 0.02ثلاث قراءات:
- الأسماء المتشابهة لا تخدعه: وُضعت في القائمة عمدًا أقارب مثل «لقاح التهاب الكبد A وB المركب» و«لقاح التهاب الكبد A والتيفوئيد المركب»——الأنواع الـ 6 الموجودة فعلًا في الصفحة كلها فوق 0.97، والأقارب كلها تحت 0.02، فاصل واضح تمامًا
box topهو رقم سطر مجاني: الصفوف الـ 6 مرتبة حسب الحافةtop، وهو بالضبط ترتيبها على الصفحة——قص الخطوة 5 وعرض النتائج للمراجع البشري يعتمدان كليًا على هذا الترتيب- اللقاحات خارج القائمة لم تُفلت: سؤال «Noul البوابة» أجاب 0.02——لا يوجد في الجدول لقاحات خارج القائمة. لو كان أعلى من 0.5، فالصفحة كلها تُعلَّم للفحص البشري (الخطوة 5)
تذكّر الجهة الرسمية بأمر آخر: 16 لقاحات و33 سؤالًا لا مشكلة فيه، لكنعندما تحتوي القائمة آلاف العناصر قد لا تتسع الأسئلة في طلب واحد(حد السياق)——قسّم أولًا حسب الفئة، مع سؤال Noul واحد لكل فئة لتضييق النطاق، ثم اسأل تفصيليًا عن كل عنصر في الفئات المطابقة.
::: نصيحة 💡 هذه هي القيمة الفريدة للتعرف على الصور عبر Jev احتمال واحد لكل مرشح يجعلك تحوّل «هل موجود» إلى مسألة عتبة: لا توجد منطقة رمادية بين 0.97 و0.02، وPRESENT_CUTOFF = 0.5 يفصل بحدة ونظافة. أما «أرى سجلات التهاب الكبد A وB» التي يعطيك إياها LLM متعدد الوسائط فلا يحتوي على هذه الأرقام، ولا يبقى لك سوى اختيار التصديق أو عدمه. :::
- 16 احتمالات الصفوف طُبعت: 6 أنواع ≥ 0.97، والأقارب ≤ 0.02، و
unlisted0.02؛ وأستطيع تفسير لماذا لا يمكن الاستغناء عن سؤال Noul الأخير
الخطوة 3: Choice يقرأ السنة، وإذا لم تكن واضحة يجيب unreadable
لماذا: إيجاد الصف نصف المعركة فقط، ويجب أيضًا قراءة سنة التطعيم لمعرفة ما إذا كانت الجرعة لا تزال صالحة. الفخ الأساسي: Choice سيختار دائمًا أحد الخيارات——عندما يكون التاريخ مغطى بملصق، وبدون مخرج طوارئ سيختار أقرب سنة تشبهها. الحل الرسمي: ضع other وunreadable في نهاية قائمة الخيارات ليتمكن النموذج من التصريح بـ «لا يمكن قراءته»؛ وأضف سؤال Noul مستقلًا «هل التاريخ مقروء بالكامل» كإشارة ثانية.
YEAR = {
**{f"y{n}": str(n) for n in range(2016, 2027)},
"other": "A year before 2016 or after 2026",
"unreadable": "The year is covered, stained, smudged or damaged and can't be read",
}
def read_questions(row: dict) -> dict:
where = f"the DATE GIVEN cell of the {row['vaccine']} row of the vaccines table in `page`"
i = row["id"]
return {
f"{i}|year": {
"type": "choice", "criteria": YEAR,
"instructions": "Dates on this record are written day/month/year, so the year "
f"is the last part. What year is written in {where}?",
},
f"{i}|legible": {
"type": "noul",
"instructions": f"Is the date in {where} fully legible, with nothing covering, "
"staining, smudging or blurring any of it?",
},
}
read = ask_page({k: q for row in rows for k, q in read_questions(row).items()})
A = read["answers"]
for row in rows:
i = row["id"]
row["year"], row["year_confidence"] = A[f"{i}|year"]["choice"], A[f"{i}|year"]["confidence"]
row["legible"] = A[f"{i}|legible"]["noul"]
UNRESOLVED = ("other", "unreadable") # picks that leave the row without a year
def year_given(row: dict) -> int | None:
return None if row["year"] in UNRESOLVED else int(row["year"][1:])
def as_text(row: dict) -> str:
year = year_given(row)
return str(year) if year else row["year"]
print(f"{'vaccine':<40}{'year':<12}legible")
for row in rows:
print(f"{row['vaccine']:<40}{as_text(row):<12}{row['legible']:.2f}")شغّل.
يجب أن ترى(أرقام مسجلة من jev-1.14.0 الرسمي):
vaccine year legible
Hepatitis A 2026 0.96
Hepatitis B 2026 0.86
Typhoid 2021 0.96
Yellow fever 2025 0.96
Tetanus, diphtheria and polio (Td/IPV) 2024 0.96
Rabies unreadable 0.05تفصيلان يستحقان التوقف عندهما:
صف داء الكلب، أجاب النموذج بـ
unreadable——تاريخه مغطى بملصق دفعة. وأعطى Noul القابلية للقراءة 0.05 في الوقت نفسه، فالإشارتان تؤكد إحداهما الأخرى. هذا معنى مخرج الطوارئ: «لا يمكن قراءته» يُبلَّغ عنه بدلًا من أن يُخمَّنالتواريخ المقروءة، حتى Noul القابلية للقراءة يعطي فقط 0.86–0.96 (منها الصف ذو 0.86 المُظلَّل بقلم تظليل)——أقل من ثقة Choice، لذا وضعت الجهة الرسمية لقابلية القراءة خط مراجعة 0.50 أدنى بشكل مستقل، بدلًا من استخدام 0.90. لكل سؤال مقياس درجات خاص به، فلا تستخدم عتبة واحدة للجميع
سنوات الصفوف الستة طُبعت؛ وأستطيع تفسير ما يحجبه كل من
otherوunreadable(سنوات خارج القائمة مقابل تواريخ غير قابلة للقراءة أصلًا)
الخطوة 4: طلب نصي خالص للتحقق من صلاحية الفترة — فصل قراءة الصورة عن الحكم
لماذا: هذه الخطوة تصميم جدير بالتعلم من cookbook. قراءة التاريخ الصحيحة لا تكفي — تطعيم التيفوئيد حُقن في 2021، والكتابة واضحة، لكن فترة الحماية نحو ثلاث سنوات، وعند المغادرة في شهر 11 من سنة 2026 كانت قد انقضت منذ زمن. هذا الحكم، رسميًا، لا يُترك للنموذج وهو ينظر إلى الصورة، بل يُرسل العام المقروء كنص خالص في طلب ثالث: لا تُرفَق الصورة، والحكم يتعلق فقط بـ«هل هذه الجرعة ما زالت سارية في يوم المغادرة»، وهو مفصول تمامًا عن قراءة الصورة.
حساب التواريخ (كم سنة مضت) يقوم به الكود ويضعه في state — مقارنة التواريخ نقطة ضعف معروفة لدى Jev، والحساب يبقى دائمًا في الكود.
DEPARTURE = date(2026, 11, 12) # from the traveller's booking
def before_departure(year: int) -> str:
years = DEPARTURE.year - year
return "less than a year" if years == 0 else f"about {years} year{'s' * (years != 1)}"
CHECK_CONTEXT = (
"Each entry is one line of an adult traveller's vaccination record, as read from a "
f"scan. The traveller leaves on {DEPARTURE.day} November {DEPARTURE.year}. Judge "
"only whether the dose will still protect the traveller on that date, by usual "
"travel-health guidance for adults."
)
IN_DATE_QUESTION = "Will this dose still protect the traveller on the departure date?"
IN_DATE_CRITERIA = {
"true": "The dose is within the usual protection period for this vaccine on the "
"departure date.",
"false": "The dose is past the usual protection period for this vaccine by the "
"departure date.",
}
def check_questions(readable: list[dict]) -> dict:
return {
row["id"]: {
"type": "noul",
"instructions": {"question": IN_DATE_QUESTION, "entry": row["id"]},
"criteria": IN_DATE_CRITERIA,
}
for row in readable
}
def check_state(readable: list[dict]) -> dict:
return {
"context": CHECK_CONTEXT,
"entries": [{"id": r["id"], "vaccine": r["vaccine"], "year_given": as_text(r),
"given_before_departure": before_departure(year_given(r))}
for r in readable],
}الطلب الثالث لا يحمل صورة ولا يضيف ترويسة images — الحكم يتعلق فقط بنص العام المقروء، ويُغلَّف بنفس ديكوراتور التخزين المؤقت:
@json_cache
def check(model: str, state_json: str, questions_json: str) -> dict:
started = perf_counter()
response = client.system_one(
state=json.loads(state_json), questions=json.loads(questions_json), model=model
)
return {
"answers": {k: a.noul for k, a in response.answers.items()},
"seconds": round(perf_counter() - started, 2),
}
readable = [r for r in rows if year_given(r) is not None]
checked = check(TYPESAFE_MODEL, json.dumps(check_state(readable)),
json.dumps(check_questions(readable))) if readable else {"answers": {}}
for row in rows:
row["in_date"] = checked["answers"].get(row["id"])
year = year_given(row)
ago = before_departure(year) if year else "-"
shown = " -" if row["in_date"] is None else f"{row['in_date']:.2f}"
print(f"{row['vaccine']:<40}{as_text(row):<12}{ago:<20}{shown}")شغّل.
يجب أن ترى(أرقام مسجلة من jev-1.14.0 الرسمي):
Hepatitis A 2026 less than a year 0.94
Hepatitis B 2026 less than a year 0.83
Typhoid 2021 about 5 years 0.38
Yellow fever 2025 about 1 year 0.95
Tetanus, diphtheria and polio (Td/IPV) 2024 about 2 years 0.93
Rabies unreadable - -تطعيم التيفوئيد 0.38 — أُبرز وحده. داء الكلب بلا درجة، لأن العام لم يُقرأ (الخطوة 3 أجابت بـ unreadable)، فالكود لا يرسله أصلًا إلى هذا الطلب.
لماذا يجب الفصل إلى طلبين؟ أجرى الفريق الرسمي تجربة مضادة في الملحق — طرح سؤال الصلاحية مباشرة على الصورة (تاريخ المغادرة مكتوب في ترويسة الصفحة):
vaccine from the image from the readings
Hepatitis A 0.88 0.94
Hepatitis B 0.85 0.83
Typhoid 0.50 0.38
Yellow fever 0.96 0.95
Tetanus, diphtheria and polio (Td/IPV) 0.84 0.93
Rabies 0.88 -السؤال على الصورة: داء الكلب 0.88 نجح (رغم أن التاريخ مغطى بملصق)؛ والتيفوئيد 0.50 على الحد تمامًا ونجح أيضًا. كشف الفريق الرسمي السبب: إجابة واحدة غطت خطوتين — لا تستطيع التمييز بين نموذج لم يقرأ التاريخ صحيحًا وحكمٍ خاطئ في ذاته. بعد الفصل (المسار الرئيسي في هذه الصفحة)، أُوقِف داء الكلب عند خطوة القراءة، ودرجة حكم التيفوئيد 0.38 أُرسلت أيضًا إلى المراجعة البشرية.
::: نصيحة 💡 هذه هي القيمة الفريدة للتعرف على الصور عبر Jev كل محطة في خط المعالجة لها احتمالاتها وخط مراجعتها الخاص؛ أي محطة تعثرت ومن يجب أن ينظر إليها مكتوب بوضوح في الإجابة. دمجها في سؤال واحد يعادل لحام جهازَي إنذار في واحد — ثم يتعطلان معًا. :::
- تيفوئيد 0.38 وداء الكلب
-كلاهما تطابق؛ وأستطيع أن أذكر، بالاستناد إلى المثال المضاد في الملحق، فائدتين لـ«فصل قراءة الصورة عن الحكم»
الخطوة 5: وسم الدرجات المنخفضة وقصّ الصفوف حسب Box وإرسالها للمراجعة البشرية
لماذا: ثلاث خطوات قراءة + خطوة حكم، والآن تُجمَّع كل الدرجات المنخفضة في قائمة مراجعة واحدة. القواعد كلها كود خالص — Jev يخرج الاحتمالات فقط، ومن يُرسَل إلى المراجعة البشرية يحدده عتبة تختارها أنت.
def reading_score(row: dict) -> float:
"""The weakest of the answers that say the row was found and read."""
return min(row["present"], row["year_confidence"])
def review_reasons(row: dict) -> list[str]:
reasons = []
if (row["year"] in UNRESOLVED or reading_score(row) < READ_CUTOFF
or row["legible"] < LEGIBLE_CUTOFF):
reasons.append("Check the reading")
if row["in_date"] is not None and row["in_date"] < IN_DATE_CUTOFF:
reasons.append("Check the dose")
return reasons
def page_reasons() -> list[str]:
"""Flags that belong to the whole page rather than to one row."""
if F["unlisted"]["noul"] >= PRESENT_CUTOFF:
return ["Check the page: it may record a vaccine outside the list"]
return []
for row in rows:
in_date = "–" if row["in_date"] is None else f"{row['in_date']:.2f}"
flags = ", ".join(review_reasons(row)) or "–"
print(f"| {row['vaccine']} | {as_text(row)} | {reading_score(row):.2f} | "
f"{row['legible']:.2f} | {in_date} | {flags} |")
print(f"page: {', '.join(page_reasons()) or 'not flagged'}")شغّل.
يجب أن ترى(أرقام مسجلة من jev-1.14.0 الرسمي):
| Hepatitis A | 2026 | 0.98 | 0.96 | 0.94 | – |
| Hepatitis B | 2026 | 0.98 | 0.86 | 0.83 | – |
| Typhoid | 2021 | 0.98 | 0.96 | 0.38 | Check the dose |
| Yellow fever | 2025 | 0.98 | 0.96 | 0.95 | – |
| Tetanus, diphtheria and polio (Td/IPV) | 2024 | 0.98 | 0.96 | 0.93 | – |
| Rabies | unreadable | 0.97 | 0.05 | – | Check the reading |
page: not flagged (another vaccine on the page: 0.02)قاعدتا وسم وقاعدة على مستوى الصفحة:
- «تحقق من القراءة»: العام يقع في
other/unreadable، أو درجة القراءة (الأضعف بينpresentوyear_confidence) أقل من 0.90، أو قابلية القراءة أقل من 0.50 — أي شرط يتحقق - «تحقق من الجرعة»: درجة الصلاحية أقل من 0.50. لاحظ درجة القراءة العالية للتيفوئيد لا تنقذ درجة الحكم المنخفضة — بالكلمات الرسمية: الحكم مبني على عام قد قُرئ خطأً، والوسمان لا يلغي أحدهما الآخر
- وسم على مستوى الصفحة: إذا كان Noul لـ
unlisted≥ 0.5 تُرسَل الصفحة كاملة للمراجعة — ذلك التطعيم لا يملك صفًّا خاصًا به، فقواعد مستوى الصفوف لا تلتقطه
وأخيرًا الجزء المعد للبشر: قصّ الصف الموسوم كاملًا حسب Box (الكود الرسمي يستخدم matplotlib للرسم، وهنا جوهر القص — box المحفوظ في الخطوة 2 يجد الآن موضعه):
PAD = 0.02 # fraction of the page added around each box before cropping
LOW_BOX_CONFIDENCE, LOW_PAD = 0.6, 0.05 # a less certain box gets a wider margin
def crop(box: dict, confidence: float):
from PIL import Image
page = Image.open(PAGE)
w, h = page.size
pad = LOW_PAD if confidence < LOW_BOX_CONFIDENCE else PAD
top, bottom = max(0.0, box["top"] - pad), min(1.0, box["bottom"] + pad)
left, right = max(0.0, box["left"] - pad), min(1.0, box["right"] + pad)
return page.crop((int(left * w), int(top * h), int(right * w), int(bottom * h)))
for row in rows:
if review_reasons(row):
crop(row["box"], row["box_confidence"]).save(f"review-{row['id']}.jpg")
print(f"saved review-{row['id']}.jpg ({', '.join(review_reasons(row))})")بعد التشغيل، review-row-3.jpg (تيفوئيد، تحقق من الجرعة) و review-row-6.jpg (داء الكلب، تحقق من القراءة) يقعان في مجلد التشغيل — المراجِع لا يحتاج للبحث في نسخة الصفحة الممسوحة كاملة، بل ينظر مباشرة إلى الصف المقصوص.
أعطى الفريق الرسمي أخيرًا نصيحة في ضبط المعاملات: هذه العتبات (0.90 / 0.50 / 0.50) نقطة بداية، وليست مرسومًا مقدسًا — استخدم السجلات التي راجعها البشر لضبط خطك الخاص. مبدأ فكرة العتبات في Confidence الثقة.
- الوسمان لا يلغي أحدهما الآخر: التيفوئيد وُسم للجرعة فقط، وداء الكلب وُسم للقراءة فقط؛ وملفات
review-*.jpgقُصّت لديّ
الخطوة 6: التحقق من OCR للفواتير — فحصان يكشفان ثلاثة أخطاء قراءة
لماذا: المسح الضوئي قُرئ، فماذا عن الاتجاه المعاكس؟ يستخرج OCR القيم من صور الفواتير — معظمها صحيح، لكن التحقق منها واحدًا واحدًا يستغرق مثل الإدخال اليدوي. نهج الفريق الرسمي: Jev يتحقق من كل قيمة مستخرجة مرتين — مرة مقابل الصفحة كاملة (تحقق الصفحة)، ومرة مقابل الصورة المقصوصة (تحقق القص)، وأي منهما أقل من 0.25 يُحوَّل إلى البشر. المراجِع ينظر فقط إلى القيم القليلة الموسومة.
المشهد واقعي جدًا: واحدة فاتورة كربونية بطيات عميقة (Milkwood، 1393×1080)، وأخرى في وسطها ظل (Siyakhula، 899×1599) — قرأ OCR 8 حقول (المورد، رقم الفاتورة، التاريخ، المبلغ المستحق، أربعة بنود بنكية)، منها ثلاثة قُرئت خطأً:
| فاتورة | حقل | ما استخرجه OCR | المطبوع على الورق |
|---|---|---|---|
| Milkwood | رقم الفاتورة | AN400074 | IN400074 |
| Siyakhula | رقم الفاتورة | INV03070 | INV03079 |
| Siyakhula | التاريخ | 16/09/2028 | 16/09/2026 |
أرقام الفريق الرسمي من jev-1.14.0 (تسجيل 2026-10-15). يتطلب هذا الجزء تثبيت امتداد typesafe-sdk[pil] إضافيًا وتنزيل مجموعة الأمثلة الثانية، التبعيات والتنزيل:
pip install ipython pillow 'typesafe-sdk[pil]>=0.7.5' 'cooksafe>=0.2.0,<0.3.0'صور الفواتير و extractions.json (القيم التي استخرجها OCR) ومجموعة json_cache.json الثانية تُنزَّل من دليل ocr_confidence_bounding_boxes في مستودع الأمثلة الرسمي، وتوضع الصور في مجلد inputs/. لاحظ أن هذه الذاكرة المؤقتة تحمل نفس اسم json_cache.json من الخطوة 1، ووضعها في نفس المجلد يجعلهما يستبدل أحدهما الآخر — افتح مجلدًا منفصلًا لأمثلة الفواتير، أو أكمل الخطوات الخمس الأولى قبل التنزيل. يقول الفريق الرسمي صراحة: خطوتا OCR و LLM (استخدموا Apple Vision مع LLM) غير موجودتين في الكود — أي مستخرج يفي بالغرض، لأن التحقق يحتاج فقط الصور والقيم المستخرجة.
ثلاثة طلبات، تُشغَّل لكل فاتورة. الطلب الأول: صورة الصفحة كاملة + سؤالان لكل حقل (Box لإيجاد الموضع، وNoul للتحقق «هل القيمة المستخرجة هي هذا الحقل»):
FIELDS = {
# field: what it is, in the words every question uses
"supplier_name": "the supplier's (seller's) business name",
"invoice_number": "the invoice or document number",
"invoice_date": "the invoice date",
"amount_due": "the final total amount payable",
"bank_name": "the name of the supplier's bank in the payment details",
"account_holder": "the account holder name in the supplier's bank details",
"account_number": "the supplier's bank account number",
"branch_code": "the supplier's bank branch code",
}
SAME_VALUE = "Ignore differences in spacing, punctuation, currency symbols and letter case."
# request 1: the whole photo, a Box + a Noul per field
def page_questions(values: dict) -> dict:
from typesafe_sdk import Box, Noul
questions = {}
for field, value in sorted(values.items()):
questions[f"box_{field}"] = Box(
instructions=f"{FIELDS[field]}, printed as “{value}” in `page`"
)
questions[f"fits_{field}"] = Noul(
instructions=f"Is “{value}” {FIELDS[field]} on `page`? {SAME_VALUE}"
)
return questionsالطلب الثاني يقصّ المنطقة المحيطة بإطار كل حقل ويعيد سؤال Box مكبَّرًا (المنطقة تغطي على الأقل 30% من عرض الصفحة و 15% من ارتفاعها، فحتى لو انحرف الإطار الأول لا يخرج عن المنطقة)؛ والطلب الثالث يقصّ كل إطار جديد (بهامش من الجهات الأربع) ويطرح سؤال Noul واحدًا: «هل هذه القيمة مطبوعة بوضوح على هذه الصورة المقصوصة؟ إذا كانت مقطوعة أو غير واضحة أو مختلفة فالجواب لا» — Ignore differences in spacing, punctuation... يجعل فروق المسافات وعلامات الترقيم وحالة الأحرف ورموز العملة لا تُحتسب خطأً. صورة القص لكل حقل مضمّنة في تعليمات سؤالها الخاص بها، وتُخرَج client.attach_assets() دفعة واحدة (آلية تضمين الصور في النص في تقنيات متقدمة من درس Box والصور).
كل ذلك يقع في دالة حكم واحدة: أي فحص أقل من BAR = 0.25 يعني review. لوحة النتائج بعد تشغيل الفريق الرسمي:
photo # field extracted fits page crop verdict
milkwood.jpg 1 supplier_name MILKWOOD mushrooms 0.98 0.95 ok
milkwood.jpg 2 invoice_number AN400074 0.88 0.18 REVIEW
milkwood.jpg 3 invoice_date 01/09/2026 0.53 0.82 ok
milkwood.jpg 4 amount_due 504.70 0.95 0.80 ok
milkwood.jpg 5 bank_name Standard Bank 0.98 0.53 ok
milkwood.jpg 6 account_holder MILKWOOD 0.90 0.57 ok
milkwood.jpg 7 account_number 080 11 4941 0.35 0.92 ok
siyakhula.jpg 1 supplier_name Siyakhula Trading Services 0.96 0.31 ok
siyakhula.jpg 2 invoice_number INV03070 0.02 0.04 REVIEW
siyakhula.jpg 3 invoice_date 16/09/2028 0.17 0.66 REVIEW
siyakhula.jpg 4 amount_due R1,305.65 0.97 0.84 ok
siyakhula.jpg 5 bank_name Standard Bank 0.97 0.98 ok
siyakhula.jpg 6 account_holder Siyakhula Trading 0.93 0.96 ok
siyakhula.jpg 7 account_number 10 13 205 260 5 0.96 0.78 ok
siyakhula.jpg 8 branch_code 051001 0.97 0.94 okانظر إلى درجات الأخطاء الثلاثة — هذا أهم جدول في الدرس كله:
AN400074(المطبوع على الورقIN400074، والحرف الأول I قُرئ A): تحقق الصفحة 0.88 سمح به (الخط الصغير في صورة الصفحة الكاملة صغير جدًا)، وتحقق القص 0.18 أمسك به16/09/2028(المطبوع على الورقة هو16/09/2026، والرقم الأخير 6 قُرئ خطأً على أنه 8): فحص الاقتصاص 0.66 سمح بمروره، بينما فحص الصفحة الكاملة 0.17 أمسك بهINV03070(المطبوع على الورقة هوINV03079، والرقم الأخير 9 قُرئ خطأً على أنه 0): كلاهما منخفض (0.02 / 0.04)، إسقاط مزدوج
القول الرسمي: لا يمكن التقاط القراءات الخاطئة الثلاث بالاعتماد على أي فحص منفرد. الفحصان متكاملان في وجهة النظر — الصفحة الكاملة تسأل «هل تبدو هذه القيمة منطقية في هذا التنسيق»، والاقتصاص يسأل «هل هذه الأحرف هي فعلًا هذه الأحرف». أما القيم الصحيحة كلها فقد مرت في الفحصين (الأدنى 0.35 / 0.31).
- أستطيع أن أشرح لكل قراءة خاطئة من الثلاثة أي فحص أمسك بها وأي فحص سمح بمرورها؛
BAR = 0.25الحكم فيه «أو» وليس «و»
📋 الـ Prompt السحري
«الـ Prompt» في هذه الصفحة هو قالب للمسألة والكود — انسخه واستبدل العناصر النائبة 【】 لتوصيله بمسحوكاتك الضوئية. ثلاث قطع: ثنائية إيجاد الصفوف، كبسولة نجاة لقراءة القيم، والفحص المزدوج للـ OCR.
📝 ثنائية إيجاد الصفوف (نسخة Noul + Box)
النتيجة المتوقعة: كل حاجة من نوع «شيء في القائمة قد يكون في المستند، نريد إيجاده وتحديد موضعه» — لقاحات، توقيعات، أختام، صفوف بنود — نفس السؤال يُستخدم بتغيير القائمة فقط.
# 必填项:【清单】换你要找的东西列表;instructions 里的 `page` 换你的图在 state 里的字段名
questions = {
"unlisted": Noul(instructions={
"question": "Does the table in `page` record any 【东西类型】 that is not in this list?",
"list": 【清单】,
}),
}
for i, item in enumerate(【清单】):
questions[f"item_{i:02d}"] = Noul(
instructions=f"Is 【东西】 recorded in the table in `page`, with exactly this name?")
questions[f"item_{i:02d}|box"] = Box(
instructions=f"the whole 【东西】 row of the table in `page`")
# 选填项:近亲名称故意放进清单里测区分度(官方放了 Hepatitis A and B combined)?
# 输出规范:P(yes) ≥ 0.5 视为在页上;按 box["box"]["top"] 排序得到页面顺序
# 约束条件:
# ✅ Noul 说不在页上,就不理会它那个 Box——Box 永远返回一个框
# ✅ unlisted 那道守门题保留:行级规则抓不到「列表漏了」
# ❌ 清单几千项别硬塞一个请求——先按组 Noul 预筛,再对命中组细问✅ كبسولة النجاة لقراءة القيم (نسخة Choice)
النتيجة المتوقعة: قراءة أي قيمة من مجموعة مغلقة من صورة (سنة، شهر، فئة، رقم إصدار)، وعند تعذر القراءة تحصل على unreadable صريح بدلًا من تخمين عشوائي.
# 必填项:【选项集】+ 两个逃生舱;【值在原文里的写法】写进 instructions 帮模型定位
VALUE = {
**{【你的选项集】},
"other": "【选项集之外的值】",
"unreadable": "The value is covered, stained, smudged or damaged and can't be read",
}
question = Choice(
instructions="【值在原文里怎么写的(如 day/month/year,年份是最后一部分)】"
"What 【值】 is written in 【位置描述,如 the DATE GIVEN cell of the X row】?",
criteria=VALUE,
)
# 选填项:旁边加一道 Noul 问「这段完全可读吗」做第二信号(官方:可读性的分数尺度更低,阈值单独设)?
# 输出规范:answer.choice + answer.confidence;other/unreadable 让该行无值可判,直接送人工
# 约束条件:
# ✅ Choice 永远挑一个——没有逃生舱它就硬猜,这是本模板存在的理由
# ❌ 不要把「读值」和「按值判断」合并成一道题对着图问(见第 4 步附录反例)🔧 خط الفحص المزدوج للـ OCR (نسخة الكود)
النتيجة المتوقعة: التحقق من كل حقل يستخرجه الـ OCR مرتين، وتحويل ما دون العتبة إلى مراجعة بشرية مع رسم إطار إعادة فحص.
BAR = 0.25 # a check scoring below this flags the field
def check_invoice(photo, values) -> dict:
first = find_fields(photo, values) # 请求 1:整页 Box + Noul 页面核对
tight = zoom_fields(photo, values, first["boxes"]) # 请求 2:放大重框
shown = check_crops(photo, values, tight["boxes"]) # 请求 3:裁剪 Noul 细看
return {
field: {
"value": values[field],
"box": tight["boxes"][field],
"fits": first["fits"][field], # 页面核对分
"shows": shown["shows"][field], # 裁剪核对分
"review": first["fits"][field] < BAR or shown["shows"][field] < BAR,
}
for field in sorted(values)
}
# 必填项:【照片】【values:OCR 抽出的字段 map】;阈值 BAR 按你的容错调
# 选填项:复核框画在原图上——review 橙色、通过蓝色,复核的人对着位置看?
# 输出规范:每字段 {value, box, fits, shows, review};review=True 进人工队列
# 约束条件:
# ✅ 任一检查低于阈值就转人工——「或」不是「且」(单次检查抓不全)
# ✅ SAME_VALUE 句式保留:空格、标点、大小写、货币符号差异不算错
# ❌ 别指望整页一次看全:小字要靠裁剪放大,两次检查视角互补نقاط التحقق ✅
- شغّلت المسار الكامل لمسحوص لقاحات: 33 سؤالًا لإيجاد الصفوف → قراءة السنة عبر Choice (
unreadableكبسولة نجاة) → طلب نصي خالص للتحقق من صلاحية المدة → وسم النتائج المنخفضة + اقتصاص - أستطيع أن أشرح لماذا تُفصل قراءة الصورة عن الحكم في طلبين، وما الذي أغفلته النسخة المدمجة (داء الكلب 0.88 نجا، والتيفوئيد 0.50 نجا بالكاد)
- أستطيع بالنظر إلى لوحة النتائج أن أشرح أي فحص أمسك بكل قراءة OCR خاطئة من الثلاث:
AN400074الاقتصاص،16/09/2028الصفحة الكاملة،INV03070الإسقاط المزدوج - كل عتباتي موسومة بجهتها: قراءة القيم 0.90، قابلية القراءة 0.50، صلاحية المدة 0.50، OCR 0.25 — وأعرف أنه يجب معايرتها بنفسي على عينات تم التحقق منها يدويًا
- أعرف أن الطلبين الأولين كليهما يحملان
TypeSafe-Danger-Zone-Images: true، وأن الطلب النصي الثالث لا يحتاجه
تنبيهات من العثرات
❌ بدون كبسولة نجاة، يقوم Choice بالتخمين العنيد
تاريخ مغطى بملصق، رقم ممسوح ببقعة — يقوم Choice دائمًا باختيار خيار؛ فحين لا يوجد مخرج «تعذرت القراءة» سيختار لك السنة الأكثر شبها، وبثقة ليست منخفضة أصلًا. الحل الرسمي مزدوج: ضع other (خارج القائمة) و unreadable (تعذرت القراءة) في نهاية قائمة الخيارات، وأضف بجانبها فحصًا مستقلًا لقابلية القراءة عبر Noul. في المثال الرسمي لسطر داء الكلب: أجاب Choice بـ unreadable، وقابلية القراءة عبر Noul 0.05، والإشارتان كلتاهما صحيحتان.
❌ دمج قراءة الصورة والحكم في سؤال واحد
«هل هذه الجرعة ما زالت صالحة بتاريخ المغادرة؟ تاريخ المغادرة في رأس الصفحة» — سؤال مباشر على الصورة، وفي الاختبار الرسمي نجا داء الكلب بـ 0.88 (رغم أن التاريخ مغطى)، ونجا التيفوئيد بالكاد بـ 0.50. السبب: إجابة واحدة غطت خطوتين، فلا تستطيع التمييز بين قراءة خاطئة وحكم خاطئ. الفصل الصحيح: طلب قراءة الصورة ينتج قراءة مهيكلة، وطلب الحكم يستقبل نصًا فقط — داء الكلب يُحجز في خطوة القراءة، وحكم التيفوئيد 0.38 يُحال للبشر.
❌ التعامل مع إطار Box على أنه حقيقة مباشرة
يعيد Box إطارًا دائمًا — حتى الأشياء غير الموجودة في الصورة يعيد لها أربعة حدود. في سجل اللقاحات 10 لقاحات غير موجودة على الصفحة، ولكل منها إطار مثل box top 0.33. الممارسة الصحيحة هي ثنائية الخطوة 2: لا تستخدم الإطار إلا إذا قال Noul إنه موجود (≥ 0.5)؛ وإذا كان Noul الحارس للخارج عن القائمة ≥ 0.5 فأرسل الصفحة الكاملة للمراجعة. وانتبه أيضًا: confidence في BoxAnswer قد يكون null وفق مخطط API (حين لا يقدمه النموذج)، فتحقق من الفراغ قبل مقارنة العتبة، ولا تدع الكود يرمي TypeError مباشرة.
❌ إرسال الصور الصغيرة كما هي وعدم تصغير الكبيرة
قيود الصور في API تتجاوزها فيرفض الطلب مباشرة، ولا يوجد تصغير تلقائي: صور PNG/JPEG ثابتة، كل ضلع 280–1568 بكسل، مجموع البكسلات 78,400–2,458,624، وملف واحد ≤ 16 MiB. للمسحوصات عالية الدقة اضغط أطول ضلع إلى 1568 أولًا؛ وبالعكس، الصور الصغيرة المقتطعة التي يقل ضلعها عن 280 يجب تكبيرها (رسميًا كُبّرت صورة منطقة إعادة التأطير المكبرة إلى 1200، وصورة فحص الاقتصاص كُبّرت إلى 800 قبل الإرسال، وإذا كانت صغيرة جدًا فالصقها في وسط لوحة بيضاء وسجّل موضعها على اللوحة لتحويله إلى إحداثيات). وهناك فخ خفي آخر: يقوم API عند المعالجة بـإعادة ترميز، فقد تكون الصورة بعد المعالجة أكبر من الملف الأصلي — إرسال مجموعة صور صغيرة قد يصطدم أيضًا بحد «مجموع جميع الصور في الطلب 32 MiB».
تقنيات متقدمة (اختياري)
نفس الأسلوب على إطارات فيديو متتابعة: سجل أنواع الطيور لكاميرا المغذية. كتاب الصور الرسمي الثالث (Feeder-cam visit log): مقطع فيديو لكاميرا مغذية طيور مدته 101 ثانية، تُقتطع إطار كل ثانية، ولكل إطار تُرسل 5 أسئلة — هل يوجد طائر (Noul)، كم عددًا (Choice: none/one/several)، أين أوضح طائر (Box)، وما نوع الطائرين الأيسر والأيمن (سؤالا Choice، 10 نوعًا من الطيور مع other، ونص كل خيار هو «كيف يبدو هذا الطائر في لقطة الكاميرا» لا وصف بطريقة دليل الحقول). النتيجة الرسمية: bird_present مطابق للوسم البشري 101/101 صحيح بالكامل، وأنواع صحيحة 132/133؛ الزمن الوسيط لكل إطار 0.54 ثانية، بتوازٍ في 4 خيوط.
ثلاثة تصاميم تستحق النسخ: أولًا، يعيد Box إطارًا واحدًا فقط لكل سؤال — حين يكون نوعان من الطيور في الإطار نفسه، يطلب الطلب الثاني باسم النوع إطارًا لكل نوع («the male northern cardinal (the bright red bird)»)؛ وإذا كان تداخل الإطارين (نسبة التقاطع على الاتحاد) ≥ 0.6 اعتُبرا الطائر نفسه معرفًا مرتين، فيُبقى ذو الثقة الأعلى. ثانيًا، يحوّل visits() أجوبة الإطارات إلى «سجل زيارات»، بثلاث معاملات (احتمال النوع ≥ 0.6، الانقطاع ≤ 2 إطار، وزيارة واحدة تُحتسب عند 2 إطارات على الأقل) كلها شأن الكود، وJev لا يراها — فتعديل المعاملات لا يتطلب إعادة إرسال الطلبات. ثالثًا، الطيور من النوع نفسه في سرب لا تنفصل — التوصية الرسمية: كاشف zero-shot (مثل SAM 3 من Meta) يجد أولًا كل الإطارات حسب «bird»، Jev ثم يُعرف نوع كل طائر مقتطع.
للمسحوصات الصينية اختبر قبل الإطلاق. التوضيح الرسمي يقول إن Jev دُرّب أساسًا على الإنجليزية، واللغات الأخرى (بما فيها الصينية) تعمل لكن بدقة أقل — قبل إطلاق المستندات الصينية شغّل دفعة على مسحوصاتك وركّز على توزيع الاحتمالات والثقة (لشرح دعم اللغات انظرالنماذج والأسعار).
اعرف التكلفة مسبقًا. لا يوجد تسعير منفصل للصور — كل صورة تُحاسَب كرموز إدخال وبنفس سعر النص، وusage.input_tokens يشمل رموز جميع الصور؛ كما أن الصور تستهلك من السياق (64k لكل طلب / 32k لكل سؤال)، وحشو عدد كبير من الصور في طلب واحد سيؤدي إلى max_tokens_exceeded. آلية التخزين المؤقت في المثال الرسمي توفّر عليك المال أثناء التطوير: تُخزَّن الاستجابات مؤقتًا حسب محتوى الطلب، فإعادة التشغيل لا تعني إعادة الإرسال.
اربط مستنداتك الخاصة. يصرّح المسؤول بأن هذا الأسلوب يناسب أي مستند «مجموعة إجاباته معروفة مسبقًا»: VACCINES استبدلها بقائمتك، YEAR استبدله بنطاق قيمك، واستبدل أسئلة صلاحية التاريخ بأحكام عملك، مع الإبقاء على مخرجَي الطوارئ other وunreadable. للنسخة النصية البحتة من استخراج القيم (التواريخ، البريد الإلكتروني، الهاتف، المبالغ) راجع استخراج القيم؛ أما كيفية توزيع الاستخراج والتحقق بين عدة نماذج لتوفير المال فارجع إلى الاستخراج المتتالي.
خلاصة هذا الدرس
✅ Jev التعرف على الصور لقراءة المستندات الممسوحة ضوئيًا: Noul يتحقق من وجود العنصر، وBox يحدد الصف (top ترتيب الحواف هو ترتيب الصفوف)، وChoice يقرأ القيمة مع مخرجَي الطوارئ other/unreadable — ما لا يمكن قراءته يُبلَّغ عنه ولا يُخمَّن.
✅ فصل قراءة الصورة عن الحكم: طلب القراءة يتضمن الصورة، وطلب الحكم نص بحت. المثال المضاد الرسمي: دمجهما في سؤال واحد أدى إلى اجتياز داء الكلب بـ 0.88 خطأً وتجاوز التيفود عتبة النجاح بـ 0.50 — إجابة واحدة تغطي خطوتين، فتتعطل جميع أجهزة الإنذار.
✅ الفحص المزدوج للـ OCR: تحقق للصفحة الكاملة + تحقق للجزء المقصوص، وأي منهما يقل عن 0.25 يُحوَّل إلى المراجعة البشرية. التقطت القراءات الخاطئة الثلاث جميعها، بينما يفلت بعضها من أي فحص منفرد. تُرسم مربعات المراجعة على الصورة الأصلية، فيراجع البشر المعلَّم فقط.
✅ الأسلوب نفسه لإطارات الفيديو: بوابات Noul + Box + سؤال نوع Choice، و101/101 يحددان وجود طائر من عدمه؛ عتبات سجل الزيارات كلها في الكود، فتعديل المعاملات لا يتطلب إعادة إرسال الطلبات.
مراجعة حقول الإعدادات الرئيسية:
| الحقل | القيمة في هذه الصفحة | الشرح |
|---|---|---|
TYPESAFE_MODEL | jev-1.14.0 | أسئلة Box تتطلب Jev 1.14؛ ثبّت معرّف الإصدار ولا تستخدم jev-latest المتغير باستمرار |
IMAGES_ON | {"TypeSafe-Danger-Zone-Images": "true"} | مطلوب لكل طلب يتضمن صورة/Box؛ طلبات النص البحت لا تحتاجه |
PRESENT_CUTOFF | 0.5 | لا تُستخدم Box إلا إذا كان P(على الصفحة) ≥ 0.5 |
READ_CUTOFF / LEGIBLE_CUTOFF | 0.90 / 0.50 | درجة القراءة ودرجة الوضوح على مقياسين مختلفين، فتُضبط عتبتاهما بشكل منفصل |
IN_DATE_CUTOFF | 0.50 | إذا انخفض حكم الصلاحية عنه يُحوَّل إلى البشر؛ ولا يلغي علامة القراءة والعكس |
BAR | 0.25 | خط المراجعة للفحص المزدوج للـ OCR؛ أي فحص ينخفض عنه يعني review |
unreadable / other | مخرجا الطوارئ | الأول يصدّ «غير قابل للقراءة»، والثاني يصدّ «خارج نطاق القيم» |
| قيود الصور | لكل جانب 280–1568 بكسل، وحجم الملف الواحد ≤ 16 MiB | تجاوز الحد يُرفض مباشرة دون تصغير؛ الصور المقصوصة الصغيرة يجب تكبيرها قبل الإرسال |
دروس ذات صلة:
- Box والصور — أساس هذه الصفحة: طريقة تضمين Image، وتحويل الحواف الأربع، وبوابة Noul
- استخراج القيم — استخراج نصي بحت للتواريخ والبريد الإلكتروني والهاتف والمبالغ: أسئلة مُجزَّأة + مرشحات بالتعبيرات النمطية
- ثقة Confidence — ثلاثة مستويات للاستخدام (تنفيذ تلقائي عند الثقة العالية / وضع علامة عند المتوسطة / تحويل للبشر عند المنخفضة) وضبط العتبات حسب المخاطر
استعراض الدرس القادم
بهذا تكتمل مسار C: أصبح لديك حكم النصوص، واستخراج القيم، والتعرف على الصور. ننتقل الآن إلى الدليل المتقدم — الشكل الآخر لـ Jev: وكيل المتصفح. الدرس القادم: الدليل المتقدم: Jev وكيل المتصفح Ultrafast ودليل تجنب الأخطاء.
ستتعلم:
- Jev ما هو Ultrafast: تعطيه هدفًا، فيختار Jev العمليات والعناصر، ولا يكتب نموذج LLM الصغير السلاسل النصية إلا عند الكتابة
- فضاء إجراءات بفهرسة ديناميكية: توليد جدول عناصر جديد مع كل ملاحظة، وتحديد العملية والهدف معًا في رحلة ذهاب وإياب واحدة
- كيف يُنجز 7 ثوانٍ بحثًا حقيقيًا على Google Flights، من حيث المبدأ والتثبيت
- Jev 1.13: 9 أنماط فشل معروفة — الوجه الآخر لفكرة «تفكيك المسألة» في هذه الصفحة