BroadRouter

Fatura, fiş ve formlardan görsel LLM ile JSON veri çıkarma

BroadNet Inference ekibi · 4 dk okuma · Yayımlandı

Her sayfayı görüntüye çevirin, her alanı ve biçimini adlandıran bir istemle görsel modele gönderin ve yalnızca JSON isteyin. Ardından kodda doğrulayın: ayrıştırın, şemayı kontrol edin, satır kalemlerinin toplamı verip vermediğine bakın ve hatayla bir kez yeniden deneyin. Tekrar başarısız olanları bir kişiye yönlendirin.

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

Faturalar, fişler ve formlar aynı sorunu paylaşır: veri bir resmin içindedir ve siz onu bir veritabanında istersiniz. Şablon tabanlı OCR her yeni tedarikçi düzeninde bozulur. Bir görsel dil modeli sayfayı okur ve alanları doğrudan döndürür. İşin püf noktası şu: kendinden emin bir şekilde yanılabilir, bu yüzden asıl iş onun etrafındaki hatta. Bu yazı her dil için geçerli genel hattı anlatıyor. Arapça belgeler için kurulumda Arapça faturaları görsel modelle okuma kılavuzuna, klasik OCR’ın ne zaman daha iyi araç olduğu için Arapça OCR ve görsel LLM’ler yazısına bakın.

Hat nasıl görünüyor?

  1. Hazırlayın: her sayfa için PDF’leri görüntüye çevirin, döndürmeyi düzeltin, boyutlandırın.
  2. Çıkarın: belge başına alan alan bir istemle tek istek, yalnızca JSON.
  3. Doğrulayın: ayrıştırma, şema kontrolü, aritmetik kontrol.
  4. Doğrulama başarısız olursa hata mesajıyla bir kez yeniden deneyin.
  5. İnceleyin: hâlâ başarısız olan her şey görüntü ve taslakla birlikte bir kişiye gider.
  6. Etiketli bir örnek üzerinde alan doğruluğunu ölçün ve model veya istem değiştirdiğinizde yeniden çalıştırın.

Belge görüntüleri nasıl hazırlanır?

PDF’leri PyMuPDF ile görüntüye çevirin; en küçük metni net tutarken gerekenden fazla piksel göndermeyin:

# 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’ta görüntüler mesajın içinde doğru MIME türüyle data: URL’leri olarak gider ve kullandıkça öde modelinde girdi token’ı olarak faturalandırılır; büyük görüntüler daha fazlasını harcar. Sayfa başına token sayısını usage bloğuyla bir kez ölçün ve toplu işlerinizi buna göre boyutlandırın; nasıl yapılacağını göndermeden önce token sayma yazısı, token’ları sayfa başına maliyete çevirmeyi ise görüntü başına görsel LLM maliyeti yazısı gösteriyor. Hiçbir şey göndermeden önce sayfa başına token tahmini için örnek bir taramayı görüntü token hesaplayıcısına bırakın.

Veri çıkarma istemi nasıl yazılmalı?

Anahtarlar, türler, biçimler ve eksik değerler konusunda kesin olun. Doğrulama için ya da şemayı zorunlu kılan sağlayıcılar için bir JSON Schema da istiyorsanız ücretsiz JSON şema oluşturucu onu örnek bir faturadan üretir:

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."""

En çok önemli olan “Never guess” (asla tahmin etme) ifadesi ve açık bir null. Bunlar olmadan modeller boşlukları makul görünen değerlerle doldurur; bu da boş bırakmaktan kötüdür, çünkü basit bir kontrolden geçer.

Yapılandırılmış çıktı nasıl alınır ve doğrulanır?

Yapılandırılmış çıktının iki seviyesi var. JSON modu geçerli JSON’u garanti eder. Şemayla kısıtlanmış çıktı ise biçimi de garanti eder. OpenAI’ın kılavuzu bunu açıkça söylüyor: ikisi de geçerli JSON üretir, ancak şemaya bağlılığı yalnızca Structured Outputs sağlar. İkisinin desteği de sağlayıcıya ve modele göre değişir; bu yüzden API ne vaat ederse etsin kodda doğrulayın:

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

Para için float değil Decimal kullanın. max_tokens değerini cömert tutun: Qwen3.8 27B yanıt vermeden önce akıl yürütür ve akıl yürütme sınıra dahildir; küçük bir sınır boş bir dize döndürür. Akıl yürütme modelleri neden boş yanıt döndürür kılavuzuna bakın.

Hangi kontroller en çok hatayı yakalar?

Kontrol Yakaladığı Maliyet
JSON ayrıştırılıyor JSON çevresindeki düz metin, kesilme Ücretsiz
Şema doğrulanıyor Eksik anahtarlar, yanlış türler Ücretsiz
Satırların toplamı ara toplamı veriyor Yanlış okunan rakamlar, atlanan satırlar Ücretsiz
Ara toplam + vergi = genel toplam Yanlış okunan toplam veya vergi Ücretsiz
Tarih ayrıştırılıyor ve gelecekte değil Gün/ay yer değiştirmesi, OCR gürültüsü Ücretsiz
Tedarikçi vergi numarası tedarikçi listenizle eşleşiyor Yanlış tedarikçi, dolandırıcılık Tek sorgulama
Tedarikçi başına mükerrer fatura numarası Çift ödeme Tek sorgu

En iyi getiriyi aritmetik kontroller sağlar: tek bir yanlış okunan rakam neredeyse her zaman bir toplamı bozar. Fişlerde çoğu zaman satır düzeyinde ayrıntı yoktur; mevcut olanı kontrol edin ve fişler için daha az kontrolü kabul edin.

Canlıya geçmeden önce doğruluk nasıl ölçülür?

50 ile 100 gerçek belgeyi elle etiketleyin, hattı çalıştırın ve belge başına değil alan başına puanlayın. Toplamlar ve tarihler, açıklamalardan daha sıkı bir çıtayı hak eder. Üç sayıyı izleyin: alan doğruluğu, yeniden denemeye gerek kalmadan doğrulamadan geçen belgelerin payı ve incelemeye gönderilenlerin payı. Geçen belgelerin rastgele denetimi dahil bu inceleme adımının nasıl tasarlanacağı insan incelemesini belge yapay zekâsı iş akışınızın parçası yapmak yazısında. Başka bir model denediğinizde aynı seti çalıştırın; yöntemi geçiş yapmadan önce LLM değerlendirme yazısı anlatıyor.

BroadNet Inference’ta hangi görsel modeller uygun?

Model Görüntü Bağlam Notlar
Qwen3.8 27B Evet 262.144 Araçlar, yapılandırılmış çıktı ve akıl yürütme listelenmiş; BroadNet tarafından Arapçada test edildi
Gemma 4 VL 26B Evet 32.768 BroadNet’in en düşük fiyatı; ücretsiz kredide ve saatlik anahtarda çalışır
DeepSeek V4.1 Flash Evet 1.048.576 Sınırsız planlarda görüntüler dahil

1M token başına fiyatlar fiyatlar sayfasında; ölçtüğünüz sayfa başına token sayısını aylık hacimle LLM API maliyet hesaplayıcısında çarpın.

BroadNet Inference nerede devreye giriyor?

BroadNet Inference, üç sohbet modelinde standart OpenAI mesaj biçimiyle görüntü kabul ediyor ve istekten sonra istemleri, görüntüleri veya yanıtları saklamıyor; bu, isimler, vergi numaraları ve banka bilgileriyle dolu faturalar için önemli (sıfır veri saklama). Belgeleri Qwen3.8 27B için yapılandırılmış çıktıyı listeliyor ama şema parametrelerini belgelemiyor; bu yüzden şemanızı zorunlu kılması için API’ye değil, yukarıdaki doğrulama katmanına güvenin. BroadNet bir görüntü boyutu sınırı veya özel bir belge yapay zekâsı ürünü yayımlamıyor ve belgeleri PDF yüklemeyi değil, görüntü girdisini anlatıyor; bu yüzden önce sayfaları görüntüye çevirin. Sabit bütçeyle yüksek hacimli çalışmalar için sınırsız DeepSeek V4.1 Flash planı görüntüleri de kapsıyor.

Sık sorulan sorular

Görsel bir LLM faturalarda OCR'ın yerini alabilir mi?

Birçok düzende evet. Görsel model görüntüyü okur ve metni tek adımda alanlara eşler; tedarikçi başına şablon gerekmez. Yine de zaman zaman rakamları yanlış okur; doğrulamayı ve inceleme kuyruğunu koruyun.

Görsel modelden güvenilir JSON nasıl alırım?

İstemde tam anahtarları, türleri ve biçimleri listeleyin, yalnızca JSON isteyin ve kodda ayrıştırın. Model şemayla kısıtlanmış çıktıyı destekliyorsa kullanın. Her iki durumda da bir şema kütüphanesiyle doğrulayın ve hatayla bir kez yeniden deneyin.

Çok sayfalı bir PDF faturadan nasıl veri çıkarırım?

Her sayfayı görüntüye çevirin, ardından modelin bağlamına sığıyorsa bir faturanın tüm sayfalarını tek istekte gönderin; böylece son sayfadaki toplamlar ilk sayfadaki satırlarla eşleştirilebilir.

Fatura görüntüleri hangi çözünürlükte olmalı?

En küçük rakamların net olacağı kadar yüksek, daha fazla değil. Büyük görüntüler daha fazla girdi token'ı kullanır. A4 sayfa için uzun kenarda yaklaşık 1.500 ile 2.000 piksel makul bir başlangıç noktası; kendi belgelerinizde test edin.

Veri çıkarma doğruluğunu nasıl ölçerim?

50 ile 100 gerçek belgeyi elle etiketleyin ve alan alan puanlayın. Toplamları ve tarihleri, tedarikçi adı gibi serbest metin alanlarından ayrı izleyin; çünkü hatalarının maliyeti farklıdır.

Markdown olarak okuChatGPT asistanına sorClaude asistanına sorPerplexity asistanına sor