Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Kinyerés strukturált metaadatok

10. lecke 16 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Csak azt nyerd ki, amire szükséged van
  2. Struktúra a laposítás helyett
  3. Ismétlődő adatok
  4. Jelölőnégyzetek és űrlapok
  5. End-to-end megvalósítás
  6. Főbb megállapítások

Frissítés: 2026. november 2. — OCR. Az OCR 4.0 (mistral-ocr-4-0) szolgáltatást 2026. szeptember 30-án megszüntették. Használd az OCR 4.1 (mistral-ocr-4-1) verziót, amely augusztus 31 óta általánosan elérhető ugyanazon az áron, vagy a mistral-ocr-latest aliast, amely július 16 óta erre mutat. Az OCR 4.1 blokk-szintű megbízhatósági pontszámokat (confidence scores) is biztosít. Kiegészítés: 2026. november 3.: A helyi PDF-fájlt base64 kódolással kell elküldeni így: {"type": "document_url", "document_url": "data:application/pdf;base64,…"}; a régebbi példákban szereplő document_base64 típus sem a dokumentációban, sem a mistralai SDK-ban nem létezik, és ezek a példák hibát okoztak volna. Források: OCR Processor · Document QnA. Javítva: 2026. november 3.: A korábbi kód oldalonként olvasta a page.document_annotation értéket; a mistralai SDK 3.7.0 verziójában a dokumentum-annotáció egyetlen mező a válaszban (response.document_annotation), míg a kép-annotációt az image.image_annotation útvonalról kell beolvasni.

Csak azt nyerd ki, amire szükséged van

A dokumentum-annotáció nem csupán a nyers szöveg visszanyeréséről szól. Strukturált, típusozott és validált adatokat állít elő, amelyek azonnal felhasználhatók a rendszereidben: egy adatbázisba beszúrt sor, egy referenciához hasonlított mező, vagy egy fizetés előtt ellenőrzött összeg. A kihívás teljes egészében a sématervezésre helyeződik át, és ez ennek a leckének a fókuszpontja.

Struktúra a laposítás helyett

A kinyerési sémának tükröznie kell a dokumentum valóságát. Egy számla egy jogi entitástól származik, amely rendelkezik cégnévvel, SIRET-számmal (francia vállalatazonosító) és címmel. Nyolc mező igazítása helyett, mint például az emetteur_rue, emetteur_ville, emetteur_siret, definiálj egy Adresse modellt, majd egy LegalEntity modellt, amely tartalmazza azt. Használd újra ezeket az építőköveket mind a kibocsátó, mind a címzett esetében. A TypeDocument enumeráció hasonló szerepet játszik: megakadályozza, hogy a modell kategóriákat találjon ki, és garantál egy olyan értéket, amelyet használhatsz egy if utasításban vagy útvonalválasztáshoz. Az Optional mezők kifejezetten jelzik, mi hiányozhat, míg az alapértelmezett értékek – például a default="France" az ország mezőnél – megkímélik a modellt a nyilvánvaló dolgok kitalálásától.

from pydantic import BaseModel, Field
from typing import Optional
from enum import Enum

class DocumentType(str, Enum):
    INVOICE = "facture"
    CONTRACT = "contrat"
    REPORT = "rapport"
    FORM = "formulaire"
    OTHER = "autre"

class Address(BaseModel):
    street: Optional[str] = Field(None, description="Numéro et street")
    postal_code: Optional[str] = Field(None, description="Code postal")
    city: Optional[str] = Field(None, description="Ville")
    country: str = Field(default="France", description="Pays")

class LegalEntity(BaseModel):
    name: str = Field(..., description="Raison sociale")
    siret: Optional[str] = Field(None, description="Numéro SIRET")
    address: Optional[Address] = Field(None, description="Address postale")
    email: Optional[str] = Field(None, description="Address email")

class DocumentExtraction(BaseModel):
    document_type: DocumentType = Field(
        ..., description="Type du document"
    )
    date: Optional[str] = Field(
        None, description="Date principale (YYYY-MM-DD)"
    )
    emetteur: LegalEntity = Field(
        ..., description="Entité qui émet le document"
    )
    destinataire: Optional[LegalEntity] = Field(
        None, description="Entité destinataire"
    )
    resume: str = Field(
        ..., description="Résumé en 2-3 phrases du contenu"
    )
    langue: str = Field(
        ..., description="Langue du document (code ISO 639-1)"
    )

Ismétlődő adatok

Számos dokumentum tartalmaz sorozatokat: számlasorokat, záradékokat vagy költségtételeket. Modellezd ezeket egy dedikált al-modell list[...] típusaként. A modell ekkor beolvassa a dokumentum táblázatát, és annyi LigneFacture objektumot hoz létre, ahány sort talál, beleértve mindegyikhez a leírást, mennyiséget, egységárat és végösszeget. Ez elég adatot biztosít ahhoz, hogy saját magad újraszámold a részösszeget, és ellenőrizd a dokumentum konzisztenciáját, mielőtt elfogadnád azt.

from pydantic import BaseModel, Field

class InvoiceLine(BaseModel):
    description: str = Field(..., description="Description du produit/service")
    quantity: float = Field(..., description="Quantité")
    unit_price: float = Field(..., description="Prix unitaire HT")
    amount: float = Field(..., description="Montant total HT de la ligne")

class DetailedInvoice(BaseModel):
    supplier: str = Field(..., description="Nom du supplier")
    number: str = Field(..., description="Numéro de facture")
    date: str = Field(..., description="Date (YYYY-MM-DD)")
    lines: list[InvoiceLine] = Field(
        ..., description="Lignes de la facture"
    )
    subtotal_excl_tax: float = Field(..., description="Sous-total HT")
    vat: float = Field(..., description="Montant TVA")
    total_incl_tax: float = Field(..., description="Total TTC")
    payment_terms: str = Field(
        ..., description="Conditions de paiement mentionnées"
    )

Jelölőnégyzetek és űrlapok

A beolvasott papíralapú űrlapok azok a területek, ahol a modell igazán ragyog. Egy bool típusú mező, amelyhez a kérdés címkéje társul, elegendő: a modell felismeri, be van-e jelölve a négyzet, kinyeri a megfelelő kérdést, és – ami orvosi vagy adminisztratív felhasználás esetén kritikus fontosságú – következtet arra, hogy egy mező hiányzik, ahelyett, hogy kitalálna egy értéket, ahogy azt a Mistral csapata is bemutatta. A telefonszám leírásában szereplő „null if not provided“ (null, ha nincs megadva) megjegyzés nem dekoráció; kifejezetten engedélyezi az üres értéket.

from pydantic import BaseModel, Field

class FormResponse(BaseModel):
    question: str = Field(..., description="Intitulé de la question")
    answer: bool = Field(..., description="True si coché, False sinon")

class MedicalForm(BaseModel):
    patient_name: str = Field(..., description="Nom complet du patient")
    age: Optional[int] = Field(None, description="Âge du patient")
    sex: Optional[str] = Field(None, description="Sexe (M/F)")
    patient_id: Optional[str] = Field(None, description="ID patient")
    phone: Optional[str] = Field(
        None, description="Numéro de téléphone (null si non fourni)"
    )
    responses: list[FormResponse] = Field(
        ..., description="Réponses aux questions du formulaire"
    )

End-to-end megvalósítás

Vedd a részletes számla példáját, és kösd össze egy base64-kódolt dokumentummal. Az annotációs prompt kiegészíti a sémát azáltal, hogy meghatározza a fájltípust, és hangsúlyozza a számlasorokra való odafigyelést; a visszatéréskor történő Pydantic validáció JSON karakterlánccá alakítja az objektumot, amelyet biztonságosan bejárhatóvá tesz.

import os
import json
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": f"data:application/pdf;base64,{document_base64}"
    },
    document_annotation_format=response_format_from_pydantic_model(
        DetailedInvoice
    ),
    document_annotation_prompt=(
        "Ce document est une invoice. Extrais toutes les lines "
        "de facturation avec leurs montants."
    )
)

# Kinyerés és validálás
if ocr_response.document_annotation:
    invoice = DetailedInvoice.model_validate_json(
        ocr_response.document_annotation
    )

    print(f"Facture {invoice.numero} - {invoice.fournisseur}")
    print(f"Date : {invoice.date}")
    print(f"\nLignes :")
    for line in invoice.lines:
        print(f"  - {line.description}: {line.quantite} x "
              f"{line.prix_unitaire}€ = {line.montant}€")
    print(f"\nTotal TTC : {invoice.total_incl_tax}€")

A gyenge kinyerési eredmények szinte mindig a sémából erednek, ritkán a modellből. Nézd át egyesével a leírásaidat: pontosnak és egyértelműnek kell lenniük, mivel a modell kizárólag ezekre támaszkodik elvárásaid megértéséhez. Írd őket a dokumentumaid nyelvén – a francia tökéletesen működik francia számlák esetén –, és az enumerációkat (enum) korlátozott értékkel rendelkező mezőkre, az al-modelleket pedig a sémák között újrahasznosítható struktúrákra tartogasd.

Főbb megállapítások

  • A Pydantic sémák lehetővé teszik típusozott és validált adatok kinyerését
  • Használj komplex típusokat (listák, enumok, beágyazott modellek) a pontos kinyerés érdekében
  • A modell megbízhatóan kezeli az opcionális mezőket és a jelölőnégyzeteket
  • A mezőleírások irányítják a kinyerést: légy pontos és kifejező
  • Kombináld a document_annotation_prompt-ot a sémával a maximális kontextus érdekében