BroadRouter

استخراج بيانات الفواتير والإيصالات والنماذج إلى JSON بنموذج رؤية

بقلم فريق BroadNet Inference · قراءة في 4 دقائق · تاريخ النشر

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

A paper invoice headed "فاتورة" (invoice) with tabs labelled Vendor, Date and Total, and the text "Turn documents into useful data."
Illustrative example.

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

كيف يبدو المسار؟

  1. جهّز كل صفحة: حوّل ملفات PDF إلى صور، وصحّح الدوران، وغيّر الحجم.
  2. استخرج: طلب واحد لكل مستند مع أمر يفصّل الحقول حقلًا حقلًا، وJSON فقط.
  3. تحقّق: حلّل الناتج، وافحص المخطط، وافحص الحساب.
  4. أعد المحاولة مرة واحدة مع رسالة الخطأ إذا فشل التحقق.
  5. راجع: كل ما يظل فاشلًا يذهب إلى شخص، مع الصورة والمسودة.
  6. قِس دقة الحقول على عينة مصنّفة، وأعد القياس كلما غيّرت النموذج أو الأمر.

كيف تجهّز صور المستندات؟

حوّل ملفات PDF إلى صور باستخدام PyMuPDF، وأبقِ أصغر نص واضحًا دون إرسال بكسلات أكثر مما يلزم:

# pip install pymupdf pillow
import base64, io
import pymupdf  # older code imports it as fitz
from PIL import Image

def pdf_pages_as_data_urls(path, long_edge=1800):
    urls = []
    for page in pymupdf.open(path):
        pix = page.get_pixmap(dpi=200)
        img = Image.open(io.BytesIO(pix.tobytes("png"))).convert("RGB")
        img.thumbnail((long_edge, long_edge))
        buf = io.BytesIO()
        img.save(buf, format="JPEG", quality=90)
        urls.append("data:image/jpeg;base64," + base64.b64encode(buf.getvalue()).decode())
    return urls

في BroadNet Inference، تُرسل الصور داخل الرسالة كروابط data: بنوع MIME صحيح، وفي الدفع حسب الاستخدام تُحتسب كرموز إدخال؛ والصور الأكبر تستهلك أكثر. قِس الرموز لكل صفحة مرة واحدة عبر كتلة usage، وحدّد أحجام دفعاتك بناءً عليها؛ ويبيّن مقال عدّ الرموز قبل الإرسال الطريقة، ويحوّل مقال تكلفة نماذج الرؤية لكل صورة الرموز إلى تكلفة لكل صفحة. ولتقدير الرموز لكل صفحة قبل إرسال أي شيء، ضع نموذجًا ممسوحًا ضوئيًا في حاسبة رموز الصور.

كيف تكتب أمر الاستخراج؟

كن دقيقًا في المفاتيح والأنواع والصيغ والقيم المفقودة. وإذا أردت أيضًا مخطط JSON Schema للتحقق، أو للمزوّدين الذين يفرضون مخططًا، فإن مولّد مخطط JSON المجاني يبنيه من فاتورة نموذجية:

PROMPT = """Extract this invoice. Reply with one JSON object only, no prose.
Keys:
- vendor_name: string, as printed
- vendor_tax_id: string or null
- invoice_number: string
- invoice_date: string, YYYY-MM-DD
- currency: ISO 4217 code, e.g. USD, EUR, SAR
- line_items: list of {description: string, quantity: number, unit_price: number, line_total: number}
- subtotal: number
- tax: number or null
- total: number
Rules: numbers without currency symbols or thousands separators. If a field is not on the page, use null. Never guess."""

العبارة “Never guess” (لا تخمّن أبدًا) مع null صريحة هي الأهم. فدونها تملأ النماذج الفجوات بقيم معقولة الشكل، وهذا أسوأ من حقل فارغ لأنه يجتاز الفحص الساذج.

كيف تحصل على مخرجات مهيكلة وتتحقق منها؟

هناك مستويان من المخرجات المهيكلة. يضمن وضع JSON أن يكون JSON صالحًا. وتضمن المخرجات المقيّدة بمخطط الشكل أيضًا. ويقولها دليل OpenAI بوضوح: كلاهما ينتج JSON صالحًا، لكن Structured Outputs وحدها تضمن الالتزام بالمخطط. ويتفاوت دعم كل منهما بحسب المزوّد والنموذج، فتحقّق في الشيفرة أيًا كان ما تعد به الواجهة:

import json, os
from decimal import Decimal
from pydantic import BaseModel, ValidationError, model_validator
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

class Line(BaseModel):
    description: str
    quantity: Decimal
    unit_price: Decimal
    line_total: Decimal

class Invoice(BaseModel):
    vendor_name: str
    vendor_tax_id: str | None = None
    invoice_number: str
    invoice_date: str
    currency: str
    line_items: list[Line]
    subtotal: Decimal
    tax: Decimal | None = None
    total: Decimal

    @model_validator(mode="after")
    def sums(self):
        tol = Decimal("0.02")
        if abs(sum(l.line_total for l in self.line_items) - self.subtotal) > tol:
            raise ValueError("line_totals do not sum to subtotal")
        if abs(self.subtotal + (self.tax or 0) - self.total) > tol:
            raise ValueError("subtotal + tax != total")
        return self

def extract(image_urls, model="broadnet/qwen3.8-27b"):
    content = [{"type": "text", "text": PROMPT}] + [
        {"type": "image_url", "image_url": {"url": u}} for u in image_urls]
    messages = [{"role": "user", "content": content}]
    for attempt in range(2):
        r = client.chat.completions.create(model=model, messages=messages, max_tokens=4000, temperature=0)
        raw = (r.choices[0].message.content or "").strip().removeprefix("```json").removesuffix("```")
        try:
            return Invoice.model_validate(json.loads(raw)), r.usage
        except (json.JSONDecodeError, ValidationError, ValueError) as e:
            messages += [{"role": "assistant", "content": raw},
                         {"role": "user", "content": f"That failed validation: {e}. Re-read the image and reply with corrected JSON only."}]
    return None, r.usage  # send to human review

استخدم Decimal لا float للمبالغ المالية. واجعل max_tokens سخيًا: فـ Qwen3.8 27B يستدل قبل أن يجيب، والاستدلال يُحتسب ضمن الحد؛ والسقف الصغير يعيد سلسلة فارغة. راجع لماذا تعيد نماذج الاستدلال ردودًا فارغة.

ما الفحوص التي تكشف أكثر الأخطاء؟

الفحص ما يكشفه التكلفة
تحليل JSON ينجح نص نثري حول JSON، أو بتر مجاني
المخطط صحيح مفاتيح مفقودة، وأنواع خاطئة مجاني
مجموع البنود يساوي المجموع الفرعي أرقام مقروءة خطأً، وبنود متخطاة مجاني
المجموع الفرعي + الضريبة = الإجمالي إجمالي أو ضريبة مقروءان خطأً مجاني
التاريخ قابل للتحليل وليس في المستقبل تبديل اليوم والشهر، وضوضاء OCR مجاني
الرقم الضريبي للمورّد يطابق قائمة مورّديك مورّد خاطئ، واحتيال بحث واحد
تكرار رقم الفاتورة لدى المورّد نفسه دفع مزدوج استعلام واحد

الفحوص الحسابية هي الأعلى قيمة: فرقم واحد مقروء خطأً يكسر المجموع في كل الحالات تقريبًا. وكثيرًا ما تفتقر الإيصالات إلى تفاصيل على مستوى البنود، فافحص ما هو موجود واقبل فحوصًا أقل لها.

كيف تقيس الدقة قبل الإطلاق؟

صنّف يدويًا ما بين 50 و100 مستند حقيقي، وشغّل المسار، وقيّم لكل حقل، لا لكل مستند. والإجماليات والتواريخ تستحق معيارًا أشد من الأوصاف. تتبّع ثلاثة أرقام: دقة الحقول، ونسبة المستندات التي تجتاز التحقق دون إعادة محاولة، ونسبة ما يُرسل إلى المراجعة. أما كيفية تصميم خطوة المراجعة تلك، بما في ذلك التدقيق العشوائي في المستندات التي اجتازت، ففي جعل المراجعة البشرية جزءًا من مسار الذكاء الاصطناعي للمستندات. وحين تجرّب نموذجًا آخر، شغّل المجموعة نفسها؛ ويغطي مقال تقييم نموذج LLM قبل الانتقال الطريقة.

ما نماذج الرؤية المناسبة على BroadNet Inference؟

النموذج الصور السياق ملاحظات
Qwen3.8 27B نعم 262,144 الأدوات والمخرجات المهيكلة والاستدلال مدرجة؛ اختبرته BroadNet على العربية
Gemma 4 VL 26B نعم 32,768 أقل سعر في BroadNet؛ يعمل على الرصيد المجاني والمفتاح بالساعة
DeepSeek V4.1 Flash نعم 1,048,576 الصور مشمولة في الخطط غير المحدودة

الأسعار لكل مليون رمز موجودة في صفحة الأسعار؛ واضرب الرموز المقيسة لكل صفحة في الحجم الشهري باستخدام حاسبة تكلفة LLM API.

أين تناسب BroadNet Inference

تقبل BroadNet Inference الصور في ثلاثة نماذج محادثة عبر صيغة رسائل OpenAI القياسية، ولا تحتفظ بالأوامر أو الصور أو الإجابات بعد الطلب، وهذا مهم لفواتير مليئة بالأسماء والأرقام الضريبية والتفاصيل المصرفية (عدم الاحتفاظ بالبيانات). وتذكر وثائقها المخرجات المهيكلة لـ Qwen3.8 27B لكنها لا توثّق معاملات المخطط، فاعتمد على طبقة التحقق أعلاه لا على الواجهة لفرض مخططك. ولا تنشر BroadNet حدًا لحجم الصور ولا منتجًا مخصصًا لذكاء المستندات، وتصف وثائقها إدخال الصور لا رفع ملفات PDF، فحوّل الصفحات إلى صور أولًا. وللتشغيلات الكبيرة بميزانية ثابتة، تشمل خطة DeepSeek V4.1 Flash غير المحدودة الصور.

أسئلة شائعة

هل يمكن لنموذج LLM للرؤية أن يحل محل OCR في الفواتير؟

في كثير من التخطيطات، نعم. يقرأ نموذج الرؤية الصورة ويربط النص بالحقول في خطوة واحدة، دون قوالب لكل مورّد. لكنه يخطئ أحيانًا في قراءة الأرقام، فاحتفظ بالتحقق وبطابور للمراجعة.

كيف أحصل على JSON موثوق من نموذج رؤية؟

اذكر في الأمر المفاتيح والأنواع والصيغ بدقة، واطلب JSON فقط، وحلّله في الشيفرة. وإذا كان النموذج يدعم مخرجات مقيّدة بمخطط، فاستخدمها. وفي الحالتين تحقّق باستخدام مكتبة مخططات، وأعد المحاولة مرة واحدة مع الخطأ.

كيف أستخرج البيانات من فاتورة PDF متعددة الصفحات؟

حوّل كل صفحة إلى صورة، ثم أرسل جميع صفحات الفاتورة الواحدة في طلب واحد إذا كانت تتسع في سياق النموذج، حتى يمكن مطابقة الإجماليات في الصفحة الأخيرة مع البنود في الصفحة الأولى.

ما الدقة المناسبة لصور الفواتير؟

دقة تكفي لتكون أصغر الأرقام واضحة، ولا أكثر. فالصور الأكبر تستهلك رموز إدخال أكثر. وطول للضلع الأطول بين 1,500 و2,000 بكسل تقريبًا نقطة بداية معقولة لصفحة A4؛ واختبر على مستنداتك.

كيف أقيس دقة الاستخراج؟

صنّف يدويًا ما بين 50 و100 مستند حقيقي، وقيّم حقلًا بحقل. وتتبّع الإجماليات والتواريخ بمعزل عن الحقول النصية الحرة مثل أسماء المورّدين، لأن تكلفة أخطائها مختلفة.

اقرأها بصيغة Markdownاسأل ChatGPTاسأل Claudeاسأل Perplexity