استخراج القيم: التواريخ والبريد الإلكتروني والهاتف والمبالغ
💡 خلاصة بسطر واحد: استخدم Jev استخراج المعلومات لبناء خط معالجة للحقول — التاريخ يُقسَّم إلى مكونات يجمعها الكود، والبريد الإلكتروني/الهاتف/المبالغ تُجمع مرشحينها أولًا بالتعابير النمطية ثم يختار Jev الصحيح، والقيم لا تأتي إلا من النص الأصلي.
لتغذية حقول المستند إلى قاعدة بيانات، أنت لا تريد «نصًا يبدو كإجابة». لهذا قدمت الجهة الرسمية كتابين للوصفات: Date extraction (استخراج التاريخ) يسأل عن مكونات التاريخ — أي شهر، وأي يوم، وهل كُتبت السنة، وهل هو تاريخ مطلق أم تاريخ نسبي مثل «الخميس القادم»، وكل حسابات التقويم تُترك للكود؛ أما Pre-parsed value extraction (استخراج القيم المُحلَّلة مسبقًا) فهو إيجاد المرشحين بالتعابير النمطية، واختيار Jev الصحيح، ونسخ الكود حرفيًا. التقسيم واحد فقط: النموذج يقرأ النص، والحساب والتطبيع في الكود.
لماذا يستحق هذا الخط درسًا مستقلًا؟ الجهة الرسمية تقولها بوضوح في Pre-parsed: TypeSafe يختار فقط من بين المرشحين الذين وجدتهم التعابير النمطية، لذلك لا يمكنه أن يخترع قيمة، ولا يمكنه أن ينسخ الأرقام بتبديل خاطئ. نتائج القياس الرسمي الفعلي: ستة أمثلة للتاريخ كلها صحيحة (بما فيها تاريخ لم يُذكر إطلاقًا في المستند، فحُكم عليه بشكل صحيح بأنه «لا يمكن تقديم تاريخ» وأُحيل بثقة 0.46 إلى مراجعة بشرية)؛ ومن أربعة عناوين في البريد اختير صندوق المستلم الصحيح بثقة 0.97؛ ومن ثلاثة أرقام هاتف اختير رقم المحمول الصحيح وطُبِّع إلى +14155550177؛ ومن أربعة مبالغ في الفاتورة اختير الإجمالي والخصم، واحتمالات credit / charge كانت 0.03 مقابل 0.98. يستغرق هذا الدرس نحو 15 دقيقة لتشغيله بالكامل — ومنها جزء البريد الإلكتروني/الهاتف/المبالغ الذي يعيد إنتاج جميع الأرقام الرسمية بدون أي مفتاح بعد تنزيل ذاكرة التخزين المؤقت الرسمية (تم التحقق فعليًا في هذه الصفحة؛ أما لماذا لا ينطبق ذلك على جزء التواريخ، فستوضحه الخطوة 1).
ماذا ستستطيع أن تفعل بعد إتمام الدرس
- كتابة
extract_date(document, role): أعطه مستندًا وسؤالًا واحدًا «ما الموعد النهائي لإعادة النموذج؟»، فتحصل علىdateمع confidence؛ ويكمل السنة إذا لم تُكتب، ويحل «الخميس القادم» إلى تاريخ محدد، ويبلغ عن خطأ للتواريخ التي لا يمكن تجميعها - استخدام ثنائي
find+pickلسحب القيم: التعابير النمطية تلتقط مرشحي البريد الإلكتروني/الهاتف/المبالغ، وJev يختار الصحيح، والإجابة هي نسخة حرفية من المرشح — بلا اختلاق وبلا تبديل خاطئ في النسخ - تطبيع القيم المختارة: البريد الإلكتروني إلى أحرف صغيرة، والهاتف إلى صيغة E.164 الدولية، والمبالغ إلى
Decimalمع وسم credit / charge - إعادة إنتاج أرقام استخراج القيم الرسمية دون إنفاق قرش واحد: إعادة تشغيل ذاكرة
json_cache.jsonالرسمية بلا أي طلبات
لماذا نستخدم Jev بدلًا من ترك LLM يسحب مباشرة؟
«دع LLM يستخرج التاريخ من العقد» هو رد الفعل الأول للكثيرين — يعمل، لكن كل حرف يعيد كتابته من جديد.
| القدرة | السحب المباشر بواسطة LLM | Jev استخراج المعلومات |
|---|---|---|
| مصدر القيمة | ❌ النموذج يعيد توليدها، وقد يخترع قيمة أو يكتب 14 بدلًا من 41 | ✅ الخيارات هي المرشحون الذين وجدتهم التعابير النمطية، والإجابة هي نسخة أصلية من أحدهم أو none — بنص الجهة الرسمية: لا يمكن invent ولا يمكن transpose |
| حسابات التقويم | ❌ «ما تاريخ الخميس القادم» و«هل في 2 يوم 30» تُترك للنموذج، وهو غير موثوق | ✅ النموذج يقرأ المكونات فقط (أغسطس / 14 / السنة غير مكتوبة)، والتجميع والاستنتاج والتحقق كلها في الكود |
| القيم غير المذكورة في المستند | ❌ يميل إلى تقديم تاريخ على أي حال | ✅ ثلاثة مخارج للنجاة: mode=none و year=none و pick=none — الموقف الرسمي: المكونات الناقصة يجب أن تُبلَّغ، لا أن تُخمَّن |
| درجة اليقين | ❌ عليك أن تسأل «هل أنت متأكد؟» والإجابة غير مستقرة | ✅ كل مكون يحمل confidence، ويأخذ التاريخ أضعف ثقة بين المكونات المستخدمة، وما دون 0.60 يُحال إلى مراجعة بشرية |
| شكل الإجابة | ❌ نص حر أو JSON، وسيفشل التحليل في المراحل التالية | ✅ إجابات مُنمَّطة مع توزيعات احتمالية، يستخدمها الكود مباشرة |
بسطر واحد: LLM يعيد كتابة المستند بدلًا عنك، أما Jev فييقرأ لك المستند فقط — والأرقام المكتوبة تخرج دائمًا من النص الأصلي.
معضلتك الحالية
- «طلبت من LLM استخراج إجمالي الفاتورة، فحوّل أحيانًا
$1,315.50إلى$1,351.50— إزاحة خانة واحدة، فتصبح كل الفواتير اللاحقة خاطئة، ولا يمكن تحديد أي خطوة أخطأت» - «العقد لا يذكر تاريخ التسليم إطلاقًا، ومع ذلك يخترع النموذج واحدًا لك؛ فأنا مضطر لكتابة طبقة تحقق إضافية لاصطياد هلوساته»
- «التواريخ النسبية مثل "يُعاد قبل الجمعة القادمة" تجعل النموذج يحسب التقويم، فتختلف الإجابة في كل تشغيل»
متى تستخدم هذه الحيلة
عندما تحتاج إلى:
- استخراج حقول منظمة من العقود والرسائل والفواتير والنماذج: التواريخ والبريد الإلكتروني وأرقام الهواتف والمبالغ، لتدخل مباشرة إلى قاعدة البيانات أو تدفق الفواتير
- قيم يجب أن تأتي حرفيًا من المستند — لا اختلاق ولا نقل خاطئ للخانات، وإذا نقص شيء فيجب الإبلاغ عن نقصه بوضوح
- تحليل التواريخ النسبية («اليوم» «الخميس القادم») إلى تواريخ ملموسة، مع كتابة قواعد التحليل في الكود البرمجي الخاص بك، فتغيّر القواعد دون تغيير السؤال
وعندما لا تريد:
- تحليل JSON الذي يُخرجه LLM ثم كتابة طبقة تحقق من نوع «هل اختلق شيئًا مرة أخرى؟»
- أن تجعل نموذج التوليد يقوم بحسابات التقويم
- إعادة ضبط الـ prompt في كل مرة تتغير فيها الوثيقة
🎒 التحضير قبل البدء
- أكملت أسئلة Noul الصح/الخطأ: تحديد credit / charge للمبالغ يعتمد على Noul، 0.5 = خمسين-خمسين
- أكملت أسئلة Choice الاختيارية: أسئلة التواريخ السبعة كلها من نوع Choice، يجب أن تعرف كيف تكتب خريطة خيارات
criteriaوأن تفهم قراءةchoiceوconfidence - يُنصح بأن تكون قرأت درجة الثقة Confidence: أن تعرف كيف يُضبط خط المراجعة 0.60 حسب المخاطر
- شغّلت بنجاحالتثبيت وأول طلب:
.venvمتاح. جزء استخراج القيم يعمل بدون Key (الخطوة 1 توفر ذاكرة التخزين المؤقت الرسمية)؛ أما جزء التواريخ فيحتاج إلىTYPESAFE_API_KEY - كوب ماء ☕ — هذا الدرس مشروع صغير متكامل: دالة تواريخ واحدة + ثلاثة أنواع من سيناريوهات القيم، النموذج يقرأ النص فقط، والحساب والتوحيد كلهما في الكود
نفّذ معي خطوة بخطوة
لنتفق أولًا على طريقة التشغيل: أنشئ value_extraction.py، والصق كتل الكود في كل خطوة أدناه بالترتيب في الملف نفسه. هذا الدرس جزآن وطريقتا تشغيل:
- الخطوة 2–4 (التواريخ): مفتاح ذاكرة التخزين المؤقت الرسمية لا يطابق مفتاح الكود الحالي (التفاصيل في الخطوة 1)، فاضبط
TYPESAFE_API_KEYللتشغيل الفعلي — ستة أمثلة بإجمالي 6 طلبات، تُخزَّن الإجابات محليًا في الذاكرة المؤقتة، فلا تتكرر التكلفة عند إعادة التشغيل - الخطوة 5–6 (البريد/الهاتف/المبالغ): بعد تنزيل
json_cache.jsonالرسمي، إعادة إنتاج جميع الأرقام الرسمية بدون Key
لا تملك Key مؤقتًا؟ انتقل مباشرة إلى الخطوة 5 لتشغيل استخراج القيم أولًا، واقرأ جزء التواريخ بالاعتماد على الأرقام الرسمية المسجلة داخل الصفحة — كل خطوة موثّقة.
الخطوة 1: تثبيت البيئة، تنزيل الذاكرة المؤقتة الرسمية، وتجهيز مجموعتَي أمثلة الاستخراج
لماذا: يأتي كل من المثالين الرسميين مع ذاكرة تخزين مؤقت لإجابات مسجلة مسبقًا json_cache.json — ذاكرة استخراج القيم أثبتت عمليًا إمكانية إعادة تشغيلها حرفيًا بدون Key؛ أما ذاكرة التواريخ فمفتاحها لا يطابق الكود الحالي ولا يمكن تشغيلها إلا مباشرة (live). بتجهيز المواد أولًا، ستكون لكل خطوة لاحقة إجابة للمقارنة بها.
ثبّت التبعيات (دمج أوامر التثبيت من cookbook الرسميين، ونطاق إصدار typesafe-sdk مثبّت صراحةً وفق إعلان التبعيات في cooksafe 0.2.0 وهو typesafe-sdk<0.8.0,>=0.7.0؛ cooksafe هي مكتبة الأدوات المرافقة لـ cookbook الرسمي، وصفها الذاتي على PyPI هو «Shared helpers for the TypeSafe cookbooks»، وهذه الصفحة تستخدم ذاكرة التخزين المؤقت JsonCache منها):
pip install 'typesafe-sdk>=0.7.0,<0.8.0' ipython phonenumbers 'cooksafe>=0.2.0,<0.3.0'نزّل الذاكرة المؤقتة الرسمية لاستخراج القيم (رابط raw مباشر، مُجرَّب ويعمل):
curl -sL -o values_cache.json https://raw.githubusercontent.com/typesafe-ai/typesafe-public-examples/main/cookbooks/pre_parsed_value_extraction_cookbook/json_cache.jsonأنشئ value_extraction.py والصق ترويسة الملف — العميل يحمل ذاكرتين مؤقتتين، واحدة للتواريخ وأخرى للقيم:
import os
import re
from datetime import date, timedelta
from decimal import Decimal
from pathlib import Path
import phonenumbers
from cooksafe import JsonCache
from typesafe_sdk import Choice, Noul, TypeSafeClient
# 官方录制版本:Date extraction 用 jev-1.12,
# Pre-parsed value extraction 用 jev-1.14.0。
# live 跑日期部分时换成你锁定的版本 ID;jev-latest 别名会随版本漂移。
DATE_MODEL = "jev-1.14.0"
VALUE_MODEL = "jev-1.14.0"
client = TypeSafeClient(
api_key=os.environ.get("TYPESAFE_API_KEY", "cache-only"), # cached re-renders need no key
base_url=os.environ.get("TYPESAFE_BASE_URL"),
timeout=30.0,
)
# 日期:缓存你自己 live 跑的答案(官方那份对不上,见下方提示框)
date_cache = JsonCache(Path("date_cache.json"))
# 值:官方缓存,零 Key 重放第 5、6 步全部官方数字
values_cache = JsonCache(Path("values_cache.json"))
print("setup ok")شغّل python value_extraction.py.
يفترض أن ترى: setup ok — هذه الخطوة مجرد تجميع، لم يُرسل أي طلب بعد.
⚠️ لماذا لا ننزّل الذاكرة المؤقتة الرسمية للتواريخ
نشر المستودع الرسمي أيضًا ذاكرة التخزين المؤقت لجزء التواريخ، لكنني جرّبت عمليًا: باستخدام كود هذه الصفحة (أي الكود الحالي في الوثائق الرسمية) مع إعادة تشغيل cooksafe 0.2.0، جاءت النداءات الستة كلها دون مطابقة — مفتاح الذاكرة المؤقتة لا يطابق (على الأرجح لأن سكربت التسجيل غير متزامن مع كود الوثائق الحالي)، فيحاول SDK إرسال طلب حقيقي، وبدون Key تكون النتيجة 401. لذا استخدم ملف date_cache.json الخاص بك لجزء التواريخ؛ الأرقام الرسمية منقولة في هذه الصفحة لتقارن بها إجاباتك. أما ذاكرة استخراج القيم الرسمية فقد أثبتت عمليًا إعادة تشغيل حرفية، فاستخدمها بثقة.
setup okطُبع، وvalues_cache.jsonموجود في مجلد التشغيل
الخطوة 2: أسئلة التواريخ السبعة — Jev استخراج المعلومات يقرأ المكونات أولًا ولا يقوم بالحساب
لماذا: مطالبة النموذج بالإجابة مباشرة عن «ما هو تاريخ الاستحقاق» تعني تكليفه بحسابات التقويم. نهج التفكيك الرسمي يجعل كل مكوّن من مكوّنات التاريخ يقع ضمن مجموعة مغلقة صغيرة: اثنا عشر شهرًا، الأيام من 1–31، ونطاق سنوات محدد، فيصبح كل مكوّن سؤال Choice، وتُطرح جميعها بالتوازي في طلب واحد (آلية السؤال المتعدد في طلب واحد مشروحة فيالأسئلة المتوازية والتوسع الاستباقي). النموذج يقرأ النص، والكود يحسب التقويم.
جهّز أولًا مستندات الأمثلة الرسمية الأربعة، ثم الصق تعريف الأسئلة السبعة:
CONTRACT = "This agreement is effective January 1, 2025 and expires December 31, 2027."
FORM = "Please return the signed form by August 14."
SURVEY = "Heads up - the customer survey closes today at 5pm."
REVIEW = "Let's schedule the design review for next Thursday."
MONTHS = {
"January": 1, "February": 2, "March": 3, "April": 4,
"May": 5, "June": 6, "July": 7, "August": 8,
"September": 9, "October": 10, "November": 11, "December": 12,
}
WEEKDAYS = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]
YEAR_WINDOW = list(range(1900, 2051)) # 1900..2050
def date_questions(role: str) -> dict[str, Choice]:
"""Seven typed choices that read a date's shape and parts off the text -- no math."""
absent = "The document does not state this, or it is not this kind of date."
return {
"mode": Choice(
instructions=(
f"How is {role} written? 'absolute' = a calendar date naming a month (e.g. "
"'August 14', 'the 3rd of March'); 'relative' = given relative to today (today, "
"tomorrow, the day after tomorrow, or a named weekday such as 'next Thursday'); "
"'none' = the document does not state this date."
),
criteria={"absolute": None, "relative": None, "none": None},
),
"month": Choice(
instructions=f"If {role} is an absolute calendar date, which month is it in?",
criteria={m: None for m in MONTHS} | {"none": absent},
),
"day": Choice(
instructions=f"If {role} is an absolute calendar date, which day of the month (1-31)?",
criteria={str(d): None for d in range(1, 32)} | {"none": absent},
),
"year": Choice(
instructions=(
f"If {role} is an absolute calendar date, which year? Pick 'none' if the document "
"states no year (code infers it), or 'out_of_range' if a year is stated but not "
"in the list."
),
criteria={str(y): None for y in YEAR_WINDOW}
| {
"out_of_range": "A year is stated for this date but is outside the listed range.",
"none": "No year is stated for this date.",
},
),
"day_anchor": Choice(
instructions=(
f"If {role} is relative to today, which day is it? 'today', 'tomorrow', "
"'day_after' (the day after tomorrow), or 'weekday' (a named day of the week)."
),
criteria={
"today": None, "tomorrow": None, "day_after": None,
"weekday": None, "none": absent,
},
),
"weekday": Choice(
instructions=f"If {role} names a day of the week, which one?",
criteria={w: None for w in WEEKDAYS} | {"none": absent},
),
"week_offset": Choice(
instructions=(
f"If {role} names a weekday, which week is it in? 'next' for 'next Thursday' or "
"'Thursday next week'; 'current' for 'this Thursday'; 'none' for a bare weekday "
"with no qualifier (just 'Thursday' / 'on Thursday')."
),
criteria={"current": None, "next": None, "none": absent},
),
}توزيع أدوار الأسئلة السبعة — mode يحدد كيفية كتابة هذا التاريخ (مطلق / نسبي / غير مذكور)، والأسئلة الستة الأخرى تقرأ المكونات: التاريخ المطلق يحتاج month + day + year، والتاريخ النسبي يحتاج day_anchor (اليوم / غدًا / بعد غد / يوم أسبوع معيّن)، وعند ذكر يوم أسبوع بعينه يحدد weekday و week_offset أيّ يوم وأيّ أسبوع. الكود يقرأ فقط الأسئلة التي يحتاجها وفق mode.
لاحظ مسارَي الهروب في year: none = النص لم يذكر السنة، فيكملها الكود؛ out_of_range = ذُكرت لكنها ليست ضمن 1900–2050، فتُبلَّغ بدلًا من التخمين. قدّم الجانب الرسمي أيضًا بديلًا لقوائم الخيارات الطويلة جدًا، انظرتقنيات متقدمة.
ثم الصق دالة إرسال الطلب، وشغّل معها حالة تاريخ سريان العقد:
@date_cache
def read_parts(document: str, role: str) -> dict:
"""One TypeSafe call -> {part: {choice, confidence}} for the seven questions."""
answers = client.system_one(
state=document, questions=date_questions(role), model=DATE_MODEL
).answers
return {
part: {"choice": ans.choice, "confidence": ans.confidence}
for part, ans in answers.items()
}
parts = read_parts(CONTRACT, "the date the agreement takes effect")
for name, part in sorted(parts.items()):
print(f"{name:<12}{part['choice']:<11}(conf {part['confidence']:.2f})")شغّل python value_extraction.py. إذا ضبطت Key فسيُرسل طلب حقيقي فعلًا (jev-1.14.0)، وتدخل الإجابة في date_cache.json.
يفترض أن ترى (الأرقام الرسمية المسجلة بـ jev-1.12؛ عند تشغيلك المباشر يجب أن تتطابق اختيارات المكونات، مع اختلافات طفيفة في درجات الثقة):
day 1 (conf 0.98)
day_anchor none (conf 0.89)
mode absolute (conf 1.00)
month January (conf 1.00)
week_offset none (conf 0.99)
weekday none (conf 0.86)
year 2025 (conf 0.97)ثلاث قراءات:
النموذج لم يقم بأي حساب: قال فقط «January» و«1» و«2025»، ولم يقل أي يوم أسبوع هو أو كم يبعد عن اليوم — ذلك عمل الكود في الخطوة 3
المكونات غير المنطبقة تُجاب بـ
none: التاريخ المطلق لا يحتاجday_anchor/weekday، فكلهاnoneبدرجات ثقة مرتفعةكل مكوّن يأتي مع confidence خاص به: هذه الآلة تعرف مدى ثبات كل قراءة من قراءاتها، وستُستخدم في الخطوة 4 لحساب درجة ثقة التاريخ الكامل
أستطيع أن أشرح ما يقرأه كل من الأسئلة السبعة، و
modeيحدد أيّها يقرأها الكود
الخطوة 3: الكود يركّب التاريخ — حسابات التقويم لا تدخل النموذج
لماذا: المكونات موجودة، وما تبقى كله عمل حتمي: السنوات غير المكتوبة تُكمل بتاريخ اليوم، و«next Thursday» تُفسَّر وفق الاتفاقية التي أعلنتها، والتوليفات المستحيلة مثل February 30 تُبلَّغ كأخطاء. يكتب المسؤول هذه القطعة كدالة نقية — لا طلبات مُرسلة ولا سجلات، ويمكن تشغيل اختبارات وحدات عليها منفردة.
الصق كود التجميع:
TODAY = date(2026, 7, 30) # fixed reference "today" so relative dates resolve reproducibly
REVIEW_BELOW = 0.60 # gate: a date below this confidence is flagged for a human
def resolve_weekday(today: date, weekday: str, week_offset: str) -> date:
"""Which date a named weekday points to, by our stated convention: a bare weekday is the next
occurrence on or after today; 'next' is the following calendar week; 'current' is this week."""
w = WEEKDAYS.index(weekday)
this_monday = today - timedelta(days=today.weekday())
if week_offset == "next":
return this_monday + timedelta(days=7 + w)
if week_offset == "current":
return this_monday + timedelta(days=w)
return today + timedelta(days=(w - today.weekday()) % 7)
def assemble(parts: dict, today: date = TODAY) -> dict:
"""Resolve the parts TypeSafe read into a concrete date, in code. Confidence is the weakest of
the parts the shape actually used."""
mode = parts["mode"]["choice"]
confs = [parts["mode"]["confidence"]]
def result(resolved: date | None, note: str) -> dict:
usable = [c for c in confs if c is not None]
confidence = min(usable) if usable else None
needs_review = resolved is None or confidence is None or confidence < REVIEW_BELOW
return {
"date": resolved,
"confidence": confidence,
"needs_review": needs_review,
"note": note,
}
if mode == "none":
return result(None, "no such date stated")
if mode == "absolute":
month, day, year = (
parts["month"]["choice"],
parts["day"]["choice"],
parts["year"]["choice"],
)
confs += [
parts["month"]["confidence"],
parts["day"]["confidence"],
parts["year"]["confidence"],
]
if "none" in (month, day) or not day.isdigit() or month not in MONTHS:
return result(None, "absolute date incomplete")
if year == "out_of_range": # a year is stated but off the list -> flag, don't guess
return result(None, f"year outside {YEAR_WINDOW[0]}-{YEAR_WINDOW[-1]}")
if year == "none": # no year stated -> infer this year, bumped to next if well past
try:
resolved = date(today.year, MONTHS[month], int(day))
except ValueError: # e.g. February 30 -- an inconsistent read, not a real date
return result(None, f"impossible date: {month} {day}")
if resolved < today - timedelta(days=31):
resolved = date(today.year + 1, MONTHS[month], int(day))
return result(resolved, "")
try: # a stated, in-range year
return result(date(int(year), MONTHS[month], int(day)), "")
except ValueError:
return result(None, f"impossible date: {year}-{month}-{day}")
if mode == "relative":
anchor = parts["day_anchor"]["choice"]
confs.append(parts["day_anchor"]["confidence"])
if anchor == "today":
return result(today, "")
if anchor == "tomorrow":
return result(today + timedelta(days=1), "")
if anchor == "day_after":
return result(today + timedelta(days=2), "")
if anchor == "weekday":
weekday, offset = parts["weekday"]["choice"], parts["week_offset"]["choice"]
confs += [parts["weekday"]["confidence"], parts["week_offset"]["confidence"]]
if weekday not in WEEKDAYS:
return result(None, "relative weekday not read")
return result(resolve_weekday(today, weekday, offset), "")
return result(None, "relative day not read")
return result(None, f"unrecognized mode: {mode}")
def extract_date(document: str, role: str) -> dict:
return assemble(read_parts(document, role))
print(extract_date(CONTRACT, "the date the agreement takes effect"))شغّل.
يجب أن ترى (تسجيل رسمي: المكونات الثلاثة المستخدمة 1.00 / 0.98 / 0.97، ويؤخذ الأضعف):
{'date': datetime.date(2025, 1, 1), 'confidence': 0.97, 'needs_review': False, 'note': ''}اقرأ القطع المنطقية الثلاث، لكل واحدة مخرجها الخاص:
- ** غموض «next Thursday» يحسمه الكود**: الاتفاقية المعلنة رسميًا — weekday مجرد = التالي بدءًا من اليوم (شامل اليوم)؛
next= أسبوع التقويم التالي؛current= هذا الأسبوع. يمكنك تغييرها إلى اتفاقية فريقك؛ ما يتغير هو الكود لا المشكلة - ** السنة غير المكتوبة تُستنتج**: أولًا يُجمَّع حسب السنة الحالية؛ وإذا كان قد مضى** أكثر من 31 يومًا** فيُقفز إلى السنة التالية — استمارة يوم 14 من الشهر 8 تُرى في يوم 30 من الشهر 7 على أنها السنة الحالية
- ** التاريخ المستحيل التجميع يُبلَّغ كـ impossible دون فرض تجميع**: قراءة متناقضة مثل February 30 تُرجع مباشرة
Noneمع note، والخطوة 4 سترسلها إلى المراجعة البشرية
💡 هذه هي القيمة الفريدة لـ Jev
الثقة هيالأضعف بين المكونات المستخدمة — التاريخ المطلق ينظر فقط إلى أربعة عناصر: mode + الشهر + اليوم + السنة، ولا يؤثر إطلاقًا ماذا أجاب day_anchor. أي مكون يسحب للأسفل يظهر بوضوح، ومن يراجع يعرف أي نصف جملة من النص الأصلي يجب أن ينظر إليه. LLM العادي لا يستطيع تقديم هذا: يبصق التاريخ النهائي دفعة واحدة ولا تعرف أي حلقة كانت تخمينًا.
- أستطيع أن أذكر قواعد الاستنتاج عند
year=none(تبدأ من السنة الحالية، ولا تقفز للسنة التالية إلا بعد أكثر من 31 يومًا)، واتفاقية تفسير weekday المجرد
الخطوة 4: ستة أمثلة رسمية لمطابقة الإجابات، وأقل من 0.60 يُرسل للمراجعة البشرية
لماذا: هل يمكن لمنظومة استخراج أن تدخل الإنتاج يتوقف على سلوكها عندما «لا يذكر المستند هذا التاريخ». الأمثلة الرسمية الستة تغطي أربع صيغ كتابة وفخًا واحدًا: تاريخان مكتوب فيهما السنة في العقد، وموعد نهائي لاستمارة بلا سنة، واستبيان يُغلق «اليوم»، ومراجعة تصميم «الخميس القادم»، إضافة إلى مكالمة kickoff لم يُذكر تاريخهاإطلاقًا في الاستمارة (توجد تواريخ في الاستمارة، لكنها ليست هذا التاريخ — علاج مخصص لعادة «استخراج أي تاريخ تراه»).
الصق الأمثلة ولوحة النتائج:
# (document, question phrase, expected date) -- the expected value is only for the scorecard.
EXAMPLES = [
(CONTRACT, "the date the agreement takes effect", date(2025, 1, 1)),
(CONTRACT, "the date the agreement expires", date(2027, 12, 31)),
(FORM, "the deadline to return the form", date(2026, 8, 14)),
(FORM, "the date of the kickoff call", None),
(SURVEY, "the date the survey closes", date(2026, 7, 30)),
(REVIEW, "the date of the design review", date(2026, 8, 6)),
]
print(f"{'':3}{'question':<38}{'expected':<12}{'got':<12}{'conf':>6} flags")
print("-" * 84)
for document, role, expected in EXAMPLES:
r = extract_date(document, role)
got = r["date"].isoformat() if r["date"] else "none"
exp = expected.isoformat() if expected else "none"
mark = "OK" if r["date"] == expected else "XX"
conf = f"{r['confidence']:.2f}" if r["confidence"] is not None else " n/a"
flags = " <== review" if r["needs_review"] else ""
if r["note"]:
flags += f" ({r['note']})"
print(f"{mark:<3}{role:<38}{exp:<12}{got:<12}{conf:>6}{flags}")
print()
confident = [(doc, role) for doc, role, _ in EXAMPLES if not extract_date(doc, role)["needs_review"]]
review = [(doc, role) for doc, role, _ in EXAMPLES if extract_date(doc, role)["needs_review"]]
print(f"auto-accept ({len(confident)}):")
for _doc, role in confident:
print(f" - {role}")
print(f"\nsend to review ({len(review)}):")
for _doc, role in review:
r = extract_date(_doc, role)
print(f" - {role} (conf {r['confidence']:.2f} / {r['note'] or 'low confidence'})")شغّل. ستة أمثلة بإجمالي 6 استدعاء — استدعاء الخطوة 2 موجود بالفعل في الكاش، فيرسل أول تشغيل 5 طلبات جديدة فقط؛ ثم يستدعي مقطعا auto-accept / review لاحقًا extract_date، وكلها من الكاش.
يجب أن ترى (تسجيل رسمي jev-1.12، TODAY = 2026-07-30، يوم خميس؛ الأرقام الحية ستختلف قليلًا):
question expected got conf flags
------------------------------------------------------------------------------------
OK the date the agreement takes effect 2025-01-01 2025-01-01 0.97
OK the date the agreement expires 2027-12-31 2027-12-31 0.91
OK the deadline to return the form 2026-08-14 2026-08-14 0.95
OK the date of the kickoff call none none 0.46 <== review (absolute date incomplete)
OK the date the survey closes 2026-07-30 2026-07-30 0.94
OK the date of the design review 2026-08-06 2026-08-06 0.92
auto-accept (5):
- the date the agreement takes effect
- the date the agreement expires
- the deadline to return the form
- the date the survey closes
- the date of the design review
send to review (1):
- the date of the kickoff call (conf 0.46 / absolute date incomplete)ثلاثة أمور تستحق التوقف عندها:
- ** التاريخ غير المكتوب يُبلَّغ بدلًا من أن يُخمَّن**: في سطر kickoff call، أجاب
modeبـabsoluteلكنmonthكانnone— يحكم الكود بـ «absolute date incomplete»، التاريخ فارغ، والثقة 0.46، وneeds_review. هذا بالضبط معنى صمّام الهروبnoneالذي أضافه المسؤول للمكونات: ** المكونات المفقودة تُبلَّغ بدلًا من أن تُؤلَّف ذهنيًا** - ** الاستمارة بلا سنة تكمل نفسها**: August 14 → 2026-08-14 (
TODAYهو 2026-07-30، وشهر 8 لم يمض بعد، فلا حاجة للقفز بين السنوات) - ** «اليوم» و«الخميس القادم» كلاهما هبط على أرض صلبة**: survey closes → 2026-07-30 (نفس اليوم)؛ design review → 2026-08-06 (شهر 7 يوم 30 هو خميس، و«next» = اليوم 4 من أسبوع التقويم التالي). شرط قابلية إعادة إنتاج التواريخ النسبية هو تثبيت
TODAY— عند تشغيلك بنفسك استبدلTODAYبـdate.today()، أو ثبّته موحدًا قبل تشغيل الدفعة
إجراء الدخول للإنتاج يحدده حقل needs_review واحد: False يدخل قاعدة البيانات مباشرة، True يُرسل للمراجعة البشرية — أما كيفية ضبط الثقة حسب المخاطر فانظر Confidence الثقة.
- لوحة النتائج ذات الأسطر الستة و auto-accept 5 / send to review 1 كلها تطابقت؛ أستطيع أن أوضح لماذا لا ينبغي أن يكون سطر kickoff call هو 2026-08-14
الخطوة 5: استخراج البريد الإلكتروني — التعبير النمطي يجد المرشحين، وJev يختار الصحيح منهم
لماذا: بدءًا من هذه الخطوة يمكن التشغيل بدون مفتاح. صعوبة البريد الإلكتروني ليست «إيجاد كل العناوين» — التعبير النمطي يُكتب في ساعة — بلأي من المرشحين الأربعة هو الذي تريده: إلى أي بريد تُرسل الوصل يعتمد على فهم جملة المتن «لا تستخدم الاسم المستعار للفواتير، أرسلها إلى بريدي الشخصي». وهذا بالضبط هو المنهج الرسمي ثلاثي الخطوات: التعبير النمطي يجد المرشحين (الإفراط في الالتقاط مقبول) → Jev يختار الصحيح → الكود ينسخ حرفيًا ويطبّع.
الصق الدوال المساعدة الأربع ومثال البريد:
NONE = "none" # the escape hatch on every selection: "none of the candidates fits"
EMAIL_RE = re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}")
PHONE_RE = re.compile(r"\(?\+?\d[\d\s()\-.]{6,}\d")
MONEY_RE = re.compile(r"[$€£¥]\s?\d[\d,]*(?:\.\d{2})?")
def find(pattern: re.Pattern, text: str) -> list[str]:
"""Code-side candidate finder: recall-tuned regex, deduped, in document order."""
seen: set[str] = set()
out: list[str] = []
for match in pattern.findall(text):
span = match.strip()
if span and span not in seen:
seen.add(span)
out.append(span)
return out
@values_cache
def pick(document: str, candidates: list[str], question: str) -> dict:
"""TypeSafe selects which found span plays the role. Returns {choice, confidence}.
The options ARE the candidate spans, so ``choice`` is a verbatim copy of one of them (or the
``none`` hatch). The model chooses; code owns the string."""
criteria = {c: None for c in candidates} | {NONE: "None of these is the requested value."}
answer = client.system_one(
state=document,
questions={"pick": Choice(instructions=question, criteria=criteria)},
model=VALUE_MODEL,
).answers["pick"]
return {"choice": answer.choice, "confidence": answer.confidence}
@values_cache
def classify(document: str, question: str, options: list[str]) -> dict:
"""A small Choice over a fixed label set (currency, country, ...). Returns {choice, confidence}."""
answer = client.system_one(
state=document,
questions={"q": Choice(instructions=question, criteria={o: None for o in options})},
model=VALUE_MODEL,
).answers["q"]
return {"choice": answer.choice, "confidence": answer.confidence}
@values_cache
def is_true(document: str, question: str) -> float:
"""A yes/no Noul. Returns P(yes)."""
return (
client.system_one(
state=document,
questions={"q": Noul(instructions=question)},
model=VALUE_MODEL,
)
.answers["q"]
.noul
)
EMAIL_DOC = """From: Jane Doe <jane.doe@example.com>
To: billing@example.com
Cc: orders@example.com
Reply-To: jane.personal@example.net
Hi team - please don't use the billing alias for this one. Send my receipt to my
personal address instead. Thanks, Jane."""
emails = find(EMAIL_RE, EMAIL_DOC)
receipt = pick(EMAIL_DOC, emails, "Which email address does the sender want their receipt sent to?")
sender = pick(EMAIL_DOC, emails, "Which email address did this message come from (the From line)?")
print("candidates :", emails)
# code copies the picked value verbatim and normalizes (lowercase); it never re-types it
print(f"receipt -> : {receipt['choice'].lower():<28} (conf {receipt['confidence']:.2f})")
print(f"sender -> : {sender['choice'].lower():<28} (conf {sender['confidence']:.2f})")شغّل python value_extraction.py — كلها تصيب الكاش الرسمي، بلا إرسال أي طلب.
يجب أن ترى (تسجيل رسمي jev-1.14.0؛ وهذا ما أعاد إنتاجه الاختبار الفعلي في هذه الصفحة حرفيًا):
candidates : ['jane.doe@example.com', 'billing@example.com', 'orders@example.com', 'jane.personal@example.net']
receipt -> : jane.personal@example.net (conf 0.97)
sender -> : jane.doe@example.com (conf 1.00)نقطتان تصميميتان:
- ** خيارات
pickهي المرشحون أنفسهم**:criteriaهو أربعة نصوص عناوين مضافًا إليهاnone، لذلك لا يمكن لـchoiceأن يكون إلا نسخة حرفية حرفًا بحرف من أحدها — لا يمكن اختلاق عنوان خامس حتى لو أردت، ولا يوجد ما يسمى خطأ نقل لأن «إعادة الكتابة» أصلًا ليست خطوة موجودة - ** إذا لم يستطع الاختيار يقول ذلك**: حين لا يطابق أي مرشح تكون الإجابة
none، ويتعامل معها الكود كحالة «لم يُعثر» بدلًا من انتقاء واحد قسرًا - ** سؤالان، طلبان، ونفس مجموعة المرشحين**: عنوان الاستلام ينظر إلى المتن (نريد البريد الشخصي)، والمرسل ينظر إلى سطر
From— الحكم يقع بين السطور، وهذا بالضبط الجزء الذي لا يستطيع التعبير النمطي فعله
💡 هذه هي القيمة الفريدة لـ Jev
التعبير النمطي مسؤول عنالاستدعاء (التقاط كل المحتمل، والإفراط لا يضر)، وJev مسؤول عنالاختيار (فهم المتن واختيار الصحيح)، والكود مسؤول عنالأمانة (نسخ حرفي + تطبيع بالأحرف الصغيرة). ثلاث قطع لكل منها دورها، وإذا تعطلت أي قطعة يمكن إصلاحها منفردة — أما الاستخراج المباشر بالـ LLM فيخلط الأمور الثلاثة في توليد واحد، وإذا أخطأ لا تعرف في أي قطعة وقع الخطأ.
- بدون مفتاح حصلت على receipt 0.97 / sender 1.00؛ أستطيع أن أشرح لماذا يستحيل أن يرجع
pickعنوانًا ليس بين المرشحين
الخطوة 6: الهاتف والمبلغ — التطبيع إلى E.164 و Decimal
لماذا: اختيار القيمة الصحيحة هو نصف المعركة فقط؛ يجب أيضًا تحويلها إلى شكل يمكن للنظام استخدامه. صعوبة الهاتف: الأرقام الثلاثة تبدو متطابقة تمامًا، أيها رقم الهاتف المحمول وفي أي دولة — ** الأرقام نفسها لا تحمل هذه المعلومات، بل النص المحيط بها هو ما يحملها**. صعوبة المبلغ: انتقاء الإجمالي لا يكفي، بل يجب معرفة ما إذا كان charge أم credit، وإلا فإن Decimal لن يستطيع حتى تحديد الإشارة.
الصق مثال الهاتف:
PHONE_DOC = """Reach our San Francisco office at these numbers: main desk (415) 555-0199,
billing fax (415) 555-0142, and my direct cell (415) 555-0177. Call the cell if it's urgent."""
phones = find(PHONE_RE, PHONE_DOC)
mobile = pick(PHONE_DOC, phones, "Which of these is the direct mobile / cell number?")
region = classify(PHONE_DOC, "In what country is this office located?", ["US", "GB", "DE", "FR", "CA", "AU"])
# code copies the picked value and normalizes it with the model-supplied country
parsed = phonenumbers.parse(mobile["choice"], region["choice"])
e164 = phonenumbers.format_number(parsed, phonenumbers.PhoneNumberFormat.E164)
print("candidates :", phones)
print(f"mobile -> : {mobile['choice']} (conf {mobile['confidence']:.2f})")
print(f"country -> : {region['choice']} (conf {region['confidence']:.2f})")
print(f"E.164 -> : {e164}")ثم الصق مثال المبلغ:
MONEY_DOC = """Invoice INV-2087.
Subtotal: $1,200.00
Sales tax: $115.50
Total due: $1,315.50
A $50.00 courtesy credit from last month has already been applied."""
amounts = find(MONEY_RE, MONEY_DOC)
currency = classify(MONEY_DOC, "What currency are these amounts in?", ["USD", "EUR", "GBP", "JPY", "CAD"])
total = pick(MONEY_DOC, amounts, "Which amount is the total the customer must pay?")
credit = pick(MONEY_DOC, amounts, "Which amount is the courtesy credit that was applied?")
def to_decimal(value: str) -> Decimal:
"""Copy the picked value and parse the number in code (US grouping/decimal here)."""
return Decimal(re.sub(r"[^\d.]", "", value))
for label, chosen in [("total due", total), ("credit", credit)]:
is_credit = is_true(
MONEY_DOC,
f"Is the amount {chosen['choice']} a credit or refund to the customer, not a charge?",
)
kind = "credit" if is_credit > 0.5 else "charge"
print(
f"{label:<10}: {chosen['choice']:<10} -> {to_decimal(chosen['choice'])} {currency['choice']} "
f"({kind}, P(credit)={is_credit:.2f})"
)
print("\ncandidates :", amounts)شغّل.
يجب أن ترى (تسجيل رسمي jev-1.14.0؛ وهذا ما أعاد إنتاجه الاختبار الفعلي في هذه الصفحة حرفيًا):
candidates : ['(415) 555-0199', '(415) 555-0142', '(415) 555-0177']
mobile -> : (415) 555-0177 (conf 1.00)
country -> : US (conf 1.00)
E.164 -> : +14155550177
total due : $1,315.50 -> 1315.50 USD (charge, P(credit)=0.03)
credit : $50.00 -> 50.00 USD (credit, P(credit)=0.98)
candidates : ['$1,200.00', '$115.50', '$1,315.50', '$50.00']لنلقِ نظرة على المقاطع الأربعة منفصلة:
- الهاتف: Jev ينتقي الرقم ويقرأ الدولة، و
phonenumbersمسؤول عن التنسيق — لا يوجد أي رقم في(415) 555-0177يقول «أنا هاتف محمول» أو «أنا في الولايات المتحدة»؛ هاتان المعلومتان تأتيان من عبارات مثل «my direct cell» و«San Francisco office»؛ تجميع E.164 هو كود خالص، حيث تُمرَّر الدولة كمعامل - المبلغ: سؤال Noul واحد يحدد الإشارة — «هل هذا المبلغ credit أم charge للعميل» يحصل على 0.03 و0.98 على التوالي، والاحتمال المنحاز بوضوح يمنح إشارة
Decimalأساسًا؛ و0.5قاطع بلا استثناء: ما يقترب من 0.5 يجب أن يُحوَّل إلى مراجعة بشرية (Noul لا يملك confidence) - تسميات
classifyهي مجموعة مغلقة تحددها أنت: الدول[US, GB, DE, FR, CA, AU]، والعملات[USD, EUR, GBP, JPY, CAD]— غيّر هاتين القائمتين لتناسب منطقة عملك؛ وإذا كانت القائمة الرسمية المقترحة قد لا تغطي كل شيء، أضف خيارother/none of the aboveليتيح للنموذج مكانًا يقول فيه «لا يشبه أيًّا منها» pickيأتي مع confidence: في الكاش الرسمي، سؤال الانتقاء الخاص بـ total سُجِّل بـ 0.56 (لم يُطبع في المخرجات لكنه مسجل في الكاش) — الإجابة انتُقيت بشكل صحيح، لكن اليقين متوسط. أما ما إذا كانت القيم منخفضة الثقة تحتاج إلى مراجعة، فاكتب القاعدة في كودك باتباع نهجREVIEW_BELOWمن الخطوة 4
أشار المسؤولون في نهاية الصفحة إلى حدّين؛ سجّلهما الآن، ويتوسع فيهما تقنيات متقدمة:
سؤال Choice واحد يتسع لحد أقصى 255 خيارًا، وإذا زادت المرشحات فقسّم الانتقاء إلى مرحلتين
إيجاد المرشحات هو الجزء الشاق حقًا — البريد الإلكتروني والهاتف والمبالغ محظوظة بما يغطيها، أما أسماء الأشخاص فلا يوجد لها تعبير نمطي جيد، ويجب أن تأتي المرشحات من قائمة الموظفين أو NER
تشغيل E.164
+14155550177وP(credit) 0.03 / 0.98 بدون أي Key؛ أستطيع أن أقول من الذي يحدد رقم الهاتف المحمول والدولة على حدة، ومن الذي يجمع E.164
📋 Prompt السحري
«Prompt» في هذه الصفحة هو أسئلة وقوالب كود موجهة إلى API — انسخها واستبدل العناصر النائبة 【】 (تلك التي تحمل ? اختيارية) لتوصيلها بمستنداتك الخاصة. ثلاثة عناصر: سؤال مكونات التاريخ، وسؤال انتقاء المرشحات، وخط أنابيب التطبيع.
📝 أسئلة مكونات التاريخ السبعة (نسخة Choice)
التأثير المتوقع: أي حاجة «لسؤال التاريخ حسب الدور» — تاريخ سريان العقد، وتاريخ انتهاء النموذج، وتاريخ تغيير الموعد الاجتماع — نفس السؤال يعمل مع تغيير role فقط، والإجابة تكون دائمًا مكونات لا تاريخًا جاهزًا.
# 必填项:【日期角色】换成你要问的那个日期的自然语言描述
DATE_QUESTIONS = {
"mode": Choice(
instructions="【这个日期是怎么写的?absolute=点名月份的日历日期;relative=相对今天;none=文档没写】",
criteria={"absolute": None, "relative": None, "none": None},
),
"month": Choice(
instructions="【若是绝对日期,是几月?】",
criteria={【m: None for m in 十二个月】} | {"none": "文档没写或不是这种日期"},
),
"day": Choice(
instructions="【若是绝对日期,是几号(1-31)?】",
criteria={【str(d): None for d in range(1, 32)】} | {"none": "文档没写或不是这种日期"},
),
"year": Choice(
instructions="【若是绝对日期,是哪年?没写选 none,超出范围选 out_of_range】",
criteria={【str(y): None for y in 你的年份窗口】}
| {"out_of_range": "写了年份但在列表外", "none": "没写年份,代码来补"},
),
"day_anchor": Choice(
instructions="【若是相对日期,锚在哪天?today / tomorrow / day_after / weekday】",
criteria={"today": None, "tomorrow": None, "day_after": None, "weekday": None,
"none": "文档没写或不是这种日期"},
),
"weekday": Choice(
instructions="【若点名了星期几,是哪一个?】",
criteria={【w: None for w in 七个星期】} | {"none": "文档没写或不是这种日期"},
),
"week_offset": Choice(
instructions="【若点名星期几,是哪一周?next=下一日历周;current=本周;none=光秃秃没限定】",
criteria={"current": None, "next": None, "none": "文档没写或不是这种日期"},
),
}
# 选填项:窗口按你的业务改——1950–2035 或未来十年;列表太长见进阶技巧的预筛做法?
# 输出规范:每题 answer.choice + answer.confidence;代码只读 mode 用得上的部件
# 约束条件:
# ✅ 每道不适用的部件都给 none 出口——缺的部件要被报出来,不是被猜出来
# ✅ 日历数学(补年份、解析「下周四」、校验 2 月 30)全放代码
# ❌ 不要问「截止日期是几月几号」——那是让模型做数学+回答二合一✅ سؤال انتقاء المرشحات (نسخة pick)
التأثير المتوقع: أي حقل «يجد التعبير النمطي مرشحات له، لكن معرفة أيها يُنتقى تتطلب فهم السياق» — بريد المستلم، ورقم الهاتف المحمول، وإجمالي الفاتورة، ومعرّف موظف خدمة العملاء — ينطبق عليه هذا القالب الواحد.
from typesafe_sdk import Choice
# 必填项:candidates 传正则抓出的候选(去重、按文档序),问题问「角色」不问「形状」
picked = client.system_one(
state=【整份文档原文】,
questions={
"pick": Choice(
instructions="【哪个候选是……?例如:寄件人希望收据寄到的那个邮箱】",
criteria={c: None for c in 【candidates】}
| {"none": "None of these is the requested value."},
)
},
).answers["pick"]
# 选填项:同一批候选换一个 role 再问一次(发件人 vs 收件人)——两次请求、同一副选项?
# 输出规范:answer.choice 是某个候选的逐字拷贝或 "none";answer.confidence 可接复核线
# 约束条件:
# ✅ 选项就是候选字符串本身——答案是拷贝,不是重新生成
# ✅ 正则调召回不调精度:多抓的让 Jev 挑掉,漏抓的谁也救不回来
# ❌ 候选超过 255 个别硬塞——先分区块挑,再挑区块内的 span(见 C4)🔧 التطبيع والمراجعة (نسخة الكود)
التأثير المتوقع: القيمة المنتقاة تتحول إلى شكل قابل للاستخدام المباشر من النظام، وكل خطوة كود خالص قابل لاختبار الوحدة ولا يكلف شيئًا.
# 必填项:按字段类型选规范化器
normalized = {
"email": lambda v: v.lower(), # 逐字拷贝 + 小写
"phone": lambda v: phonenumbers.format_number( # 读国家 + E.164
phonenumbers.parse(v, region["choice"]),
phonenumbers.PhoneNumberFormat.E164),
"amount": lambda v: Decimal(re.sub(r"[^\d.]", "", v)), # $1,315.50 -> 1315.50
"date": assemble, # 部件 -> date,见第 3 步
}
# 选填项:credit/charge 用一道 Noul 定符号——P(credit) > 0.5 是 credit,贴着 0.5 转人工?
# 输出规范:值 + provenance(来自哪个候选/哪些部件)+ confidence + needs_review
# 约束条件:
# ✅ 规范化只处理「选中的那个字符串」,绝不重新生成
# ✅ 复核线(日期 0.60 起步)按风险调:进账单的金额从严,进统计报表的可松
# ❌ 别假设逗号一定是千分位——欧式格式 €1.315,50 正相反,先问一道 Noul「这份文档用逗号当小数点吗」再分支نقطة تفتيش ✅
- الخطوتان 5 و6 تعيدان إنتاج جميع أرقام المسؤولين بدون Key: receipt 0.97 / sender 1.00 / E.164
+14155550177/ total P(credit)=0.03 / credit P(credit)=0.98 - أستطيع أن أقول ما يقرؤه كل من أسئلة التاريخ السبعة، وأن
modeيحدد أي المكونات يقرؤها الكود - أعرف أن confidence التاريخ هو الأضعف بين المكونات المستخدمة؛ إذا قل عن 0.60 يُحوَّل إلى مراجعة بشرية؛ والتاريخ غير المذكور في المستند يُبلَّغ بـ
none+ note، لا أن يُختلق واحد - أستطيع أن أشرح لماذا يستحيل على
pickاختلاق قيمة أو نقلها بمنزلة خاطئة: الخيارات هي المرشحات نفسها، والإجابة نسخ حرفي - أعرف الحدّين: Choice يتسع لحد أقصى 255 خيارًا (إذا تجاوزتها فقسّم الانتقاء إلى مرحلتين)؛ والقيم التي لا يوجد لها تعبير نمطي جيد كأسماء الأشخاص، تأتي مرشحاتها من قائمة الموظفين أو NER أو اقتراح LLM
تنبيهات للمزالق
❌ جعل LLM «يعيد كتابة» القيمة
جوهر الاستخراج المباشر بواسطة LLM هو جعله يعيد كتابة $1,315.50 وإخراجه من جديد — إزاحة منزلة واحدة في النقل ($1,351.50)، أو اختلاق قيمة غير موجودة في المستند، كلها تحدث في خطوة «إعادة التوليد». الطريقة الرسمية ذات الخطوات الثلاث تحذف هذه الخطوة تمامًا: التعبير النمطي يجد المرشحات ← Jev ينتقي بينها ← الكود ينسخ حرفيًا ثم يطبّع. أقوى ما قالته الصياغة الرسمية: TypeSafe ينتقي فقط بين المرشحات التي وجدها التعبير النمطي، لذلك يستحيل عليه اختراع قيمة أو نقل الأرقام بمنزلة خاطئة.
❌ ضبط التعبير النمطي بإفراط في الصرامة فتفوت القيمة الحقيقية خارج المرشحات
خيارات pick هي المرشحات التي تعطيها له — ما ليس بين المرشحات لا يستطيع انتقاؤه مهما كان ذكيًا. حددت الوثيقة الرسمية مهمة الخطوة الأولى بأنها الاستدعاء: عند ضبط التعبير النمطي، من الأفضل الإمساك بالكثير (حتى لو أمسكتَ بمعرّف الطلب أو رقم الفاكس أو المجموع الفرعي، فلا بأس، إذ سينتقي Jev الصحيح) بدلًا من أن تفوتك القيمة الحقيقية. تكلفة الإمساك الزائد هي بضعة خيارات إضافية في طلب واحد؛ أما تكلفة الفوات فأن هذا السجل يبقى خاطئًا إلى الأبد.
❌ الاعتماد على إعادة تشغيل كاش التاريخ بدون Key
مفتاح الكاش الخاص بـ json_cache.json للتاريخ الذي نشرته المستودعات الرسمية لا يطابق كود الوثائق الحالي (اختبارنا في هذه الصفحة: الاستدعاءات الستة كلها miss، فيتحول SDK إلى طلب حقيقي، وبدون Key يظهر 401) — على الأرجح توقيع الدالة وقت التسجيل غير متزامن مع الكود الحالي. لجزء التاريخ اضبط TYPESAFE_API_KEY وشغّل كاشك الخاص؛ وعند مقارنة الأرقام الرسمية اعتمد على لوحة النتائج المنقولة حرفيًا في هذه الصفحة. كاش استخراج القيم الرسمي غير متأثر، وقد أثبت الاختبار إعادة تشغيله حرفيًا.
❌ استخدام to_decimal فور رؤية مبلغ، وتطبيقها مباشرة فور رؤية مستند صيني
كلا الأمرين عرضة للتعثر. أولًا: Decimal(re.sub(r"[^\d.]", "", value)) يفترض أن «الفاصلة = فاصل الآلاف، والنقطة = الفاصلة العشرية» — وهذا صحيح لـ $1,315.50، وعكسه تمامًا لـ €1.315,50؛ توصي الوثيقة الرسمية بسؤال Noul أولًا «هل يستخدم هذا المستند الفاصلة كفاصلة عشرية؟» والتفرع حسب الإجابة. ثانيًا: تذكر الوثيقة الرسمية أن Jev مدرَّب بشكل أساسي على الإنجليزية، وأناللغات الأخرى (بما فيها الصينية) تعمل لكن بدقة أقل — قبل إطلاق العقود والفواتير الصينية، شغّل دفعة من مستنداتك الخاصة أولًا وانظر توزيع الاحتمالات؛ ولشرح دعم اللغات راجعالنماذج والأسعار.
تقنيات متقدمة (اختياري)
قائمة السنوات طويلة جدًا؟ صفِّها مسبقًا. يملك 1900–2050 الخاص بـ year 151 خيارًا، والمسؤولون أنفسهم يقولون «إذا كان هذا يزعجك، فاستخرج أولًا الأرقام التي تشبه السنوات من النص وقدّم تلك فقط للنموذج كخيارات» — كلما صغرت نافذة المرشحات، صار السؤال أكثر تركيزًا. وهذا نفس فكرة الخطوة 5: توليد المرشحات الذي يمكن إسناده إلى الكود لا يُكلَّف به النموذج.
تجاوزت المرشحات 255: انتقِ على مرحلتين. الأسلوب الذي قدمه المسؤولون: انتقِ أولًا الكتلة (أي فقرة / أي جدول)، ثم انتقِ span داخل الكتلة — كل سؤال Choice يبقى ضمن 255. والبحث سطرًا بسطر في البحث والمطابقة يعرض المرحلة الأولى: أعطِ كل سطر معرّفًا، ودع Choice يشير إلى السطر المطابق.
أسماء الأشخاص لا يوجد لها تعبير نمطي جيد. تقول الوثيقة الرسمية صراحة: إيجاد المرشحات هو الجزء الشاق — البريد الإلكتروني والهاتف والمبالغ لها تعابير نمطية جاهزة، أما أسماء الأشخاص فلا. يمكن أن تأتي المرشحات من قائمة موظفين لديك أصلًا (نظام الموارد البشرية، قائمة العملاء)، أو من اقتراح NER / LLM، بينما Jev مسؤول عن الانتقاء الأخير.
جرّب الأمثلة الرسمية مجانًا. في أسفل صفحة cookbook الرسمية توجد روابط مشاركة Playground جاهزة — سؤال pick الخاص بنص البريد الإلكتروني مع أربعة عناوين مرشحة، افتحه (https://console.typesafe.ai/playground) لتتمكن من تعديل الصياغة ومشاهدة توزيع الاحتمالات في المتصفح. لتوليد رابطك الخاص:
from cooksafe import make_playground_link
link = make_playground_link(EMAIL_DOC, {
"receipt": Choice(
instructions="Which email address does the sender want their receipt sent to?",
criteria={c: None for c in emails} | {"none": "None of these is the requested value."},
),
})
print(link) # 链接里带着完整 state 和问题,别放敏感数据اربطه بمسار مستنداتك. السؤال ثابت ولا يتغير سوى الـ state — استبدل EMAIL_DOC بنص البريد الذي حللته، وMONEY_DOC بنص الفاتورة الناتج عن OCR، وأسئلة التواريخ السبعة وأسئلة القيم الثلاثة تُعاد استخدامها كما هي. يختلف تكوين مفتاح التخزين المؤقت بين الجزأين، وفهم ذلك جيدًا يوفر وقتًا كبيرًا في استكشاف الأخطاء: مفتاح جزء القيم يتضمن المستند والمرشحين والسؤال (جميع معاملات pick / classify / is_true) — أي تغيير في المستند أو التعابير النمطية أو السؤال يسبب miss وطلبًا حقيقيًا تلقائيًا؛ أما مفتاح جزء التواريخ فيتضمن المستند والدور فقط — تعديل الأسئلة داخل date_questions لن** يسبب** miss (الأسئلة داخل جسم الدالة، ووثيقة cookbook تنص صراحة على أن تعديل جسم الدالة لا يُبطل التخزين المؤقت)، فتُعاد الإجابات القديمة كما هي، وإذا أردت تشغيلًا حقيقيًا بعد تعديل الأسئلة فاحذف date_cache.json. عندما يكبر حجم الاستخراج اطّلع علىالاستخراج المتتالي: النموذج الرخيص يقوم بالعمل الخشن أولًا، وJev يتولى فقط التحقق حقلًا بحقل.
خلاصة هذا الدرس
✅ Jev استخراج المعلومات، هكذا تُحل التواريخ: سبعة أسئلة Choice في طلب واحد تقرأ الشكل والمكونات، وكل حسابات التقويم (استكمال السنة، تحليل «الخميس القادم»، التحقق من شهر 2 بيوم 30) تتم في assemble()؛ confidence = أضعف مكون مستخدم، وإذا انخفض عن 0.60 يُحوَّل إلى مراجعة بشرية.
✅ القيمة = مرشحو التعابير النمطية + اختيار Jev + نسخ حرفي: find يتكفل بالاستدعاء، وpick يتكفل بالاختيار (الخيارات هي المرشحون، والإجابة لا تكون إلا نسخة حرفية من النص الأصلي أو none)، والكود يتكفل بالتسوية — لا اختلاق ولا نقل خاطئ للمواضع.
✅ تسوية الأنواع الثلاثة من القيم وتنفيذها: البريد الإلكتروني بأحرف صغيرة 0.97 / 1.00، والهاتف بصيغة E.164 +14155550177 (تُقرأ الدولة من classify)، والمبالغ بـ Decimal مع إضافة رمز credit/charge (Noul 0.03 / 0.98).
✅ إعادة إنتاج الأرقام الرسمية بدون مفتاح API: جزء استخراج القيم أُعيد تشغيله حرفيًا من التخزين المؤقت الرسمي بالاختبار الفعلي؛ أما جزء التواريخ فتبين بالاختبار الفعلي أن مفتاح التخزين المؤقت لا يتطابق، فشُغّل live باستخدام تخزينك المؤقت الخاص (6 طلبات)، ولوحة النتائج تعتمد التسجيل الرسمي.
مراجعة حقول الإعداد الرئيسية:
| الحقل | القيمة في هذه الصفحة | الشرح |
|---|---|---|
DATE_MODEL / VALUE_MODEL | jev-1.14.0 | التسجيل الرسمي: التواريخ jev-1.12 والقيم jev-1.14.0؛ وفي التشغيل live ثبّت معرّف نسختك الخاصة ولا تستخدم jev-latest المتغير باستمرار |
TODAY | date(2026, 7, 30) | تثبيت «اليوم» يجعل التواريخ النسبية قابلة لإعادة الإنتاج؛ عند التشغيل بنفسك استبدل date.today() أو ثبّته موحدًا قبل التشغيل الدفعي |
REVIEW_BELOW | 0.60 | خط مراجعة ثقة التواريخ؛ اضبط المستوى حسب المخاطر |
YEAR_WINDOW | 1900–2050 + none / out_of_range | نافذة خيارات السنة مع مخرجين للطوارئ |
| ثلاثة تعابير نمطية | EMAIL_RE / PHONE_RE / MONEY_RE | الاستدعاء أولًا؛ إزالة تكرار المرشحين وترتيبهم حسب ترتيب المستند |
| الحد الأقصى لخيارات Choice | 255 | عند التجاوز اختر الكتلة أولًا ثم الـ span (انظر C4) |
| عدد الطلبات لكل مستند | التواريخ 1 طلب واحد (سبعة أسئلة متوازية)؛ وكل قيمة 1–3 طلبًا (pick / classify / is_true) | كل ذلك يمر عبر التخزين المؤقت، ولا يحدث miss إلا عند تغيير المستند أو تعديل الأسئلة |
دروس ذات صلة:
- الاستخراج المتتالي: النموذج الرخيص يعمل، وJev يتحقق، والنموذج الغالي يتدخل عند الحاجة — النسخة الصناعية لخط المعالجة في هذه الصفحة: كيف توفر الاستدلال حقلًا بحقل من النموذج الكبير عندما تكثر الحقول
- البحث والمطابقة: إعادة الترتيب، البحث سطرًا بسطر، محاذاة الكيانات — تطبيق عملي للتقليص على مرحلتين عندما يتجاوز المرشحون 255، وبحث دلالي سطرًا بسطر في مستند من 218 سطرًا
- ثقة Confidence — مبدأ خط المراجعة 0.60، وطريقة الاستخدام ثلاثية المستويات «تنفيذ آلي للثقة العالية / وسم للمتوسطة / تحويل للمراجعة البشرية للمنخفضة»
استعراض الدرس التالي
استخرجنا الحقول، والسؤال التالي: ماذا نفعل بالنص الذي فُقد تنسيقه؟ الدرس التالي: استعادة البنية: إعادة النص الخالص إلى Markdown.
ستتعلم:
- طلبان لإعادة النص الخالص الذي فُقد تنسيقه إلى Markdown: الأول سؤال Noul لكل زوج من الأسطر المتجاورة لإعادة ربط الجمل التي قطعتها فواصل الأسطر القسرية؛ والثاني سؤال Choice لكل كتلة لتصنيفها إلى عنوان / فقرة / قائمة / اقتباس / كود / صندوق تنبيه
- لماذاكل حرف في المخرجات يأتي من المدخلات — النموذج يقوم بالحكم فقط، والعرض كله بالكود، والنموذج الذي يعيد كتابة النص سيغيّر كلماتك
- نفس تقسيم العمل كما في هذه الصفحة: النموذج يقرأ النص والكود ينفذ العمل، لكن هذه المرة ما نستعيده ليس قيمًا بل بنية