Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Estrazzjoni ta' Metadejta Strutturata

Lezzjoni 10 / 16 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Estrai eżattament dak li għandek bżonn
  2. Struttura minflok ċattament
  3. Dejta ripetuta
  4. Kaxxi tal-għażla u forom
  5. Implimentazzjoni minn tarf għal tarf
  6. Punti Ewlenin

Aġġornament 2 ta’ Novembru, 2026 — OCR. L-OCR 4.0 (mistral-ocr-4-0) ġie rtirat fit-30 ta’ Settembru, 2026. Uża OCR 4.1 (mistral-ocr-4-1), disponibbli ġeneralment mill-31 ta’ Awwissu bl-istess prezz, jew l-alias mistral-ocr-latest, li jipponta lejh mis-16 ta’ Lulju. L-OCR 4.1 iżid punteġġi ta’ kunfidenza fil-livell tal-blokki. Addendum 3 ta’ Novembru, 2026: PDF lokali jiġi trażmess f’base64 bħala {"type": "document_url", "document_url": "data:application/pdf;base64,…"}; it-tip document_base64 minn eżempji aktar antiki ma jeżistix fid-dokumentazzjoni u lanqas fl-SDK mistralai, u dawk l-eżempji kienu jfallu. Sorsi: OCR Processor · Document QnA. Ikkoreġut fit-3 ta’ Novembru, 2026: Il-kodiċi preċedenti jaqra page.document_annotation paġna b’paġna; fl-SDK mistralai 3.7.0, l-annotazzjoni tad-dokument hija qasam wieħed fir-risposta (response.document_annotation), u l-annotazzjoni tal-immaġni tinqara minn image.image_annotation.

Estrai eżattament dak li għandek bżonn

L-annotazzjoni tad-dokumenti mhix biss dwar l-irkupru ta’ test mhux ipproċessat. Tipproduċi dejta strutturata, ittajpjata u vvalidata lesta għall-użu immedjat fis-sistemi tiegħek: ringiela mdaħħla f’database, qasam imqabbel ma’ referenza, jew ammont ivverifikat qabel il-ħlas. L-isfida tinbidel kompletament għad-disinn tal-iskema, li huwa l-fokus ta’ din il-lezzjoni.

Struttura minflok ċattament

Skema ta’ estrazzjoni għandha tirrifletti r-realtà tad-dokument. Fattura tiġi minn entità legali b’isem tal-kumpanija, numru SIRET (ID tan-negozju Franċiż), u indirizz. Minflok ma tallinja tmien oqsma bħal emetteur_rue, emetteur_ville, emetteur_siret, iddefinixxi mudell Adresse, imbagħad mudell LegalEntity li fih. Uża dawn il-blokok tal-bini kemm għall-emittent kif ukoll għar-riċevitur. L-enumerazzjoni TypeDocument tilgħab rwol simili: tipprevjeni lill-mudell milli jinventa kategorija u tiggarantixxi valur li tista’ tuża fi stqarrija if jew għar-routing. L-oqsma Optional jiddikjaraw b’mod espliċitu x’jista’ jkun nieqes, filwaqt li l-valuri default—bħal default="France" għall-pajjiż—jiffrankaw lill-mudell milli jissupponi l-oċċanti.

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

Dejta ripetuta

Ħafna dokumenti fihom serje: linji tal-fatturar, klawżoli, jew oġġetti ta’ spejjeż. Immudella dawn bħala list[...] ta’ mudell sekondarju ddedikat. Il-mudell imbagħad jiskennja t-tabella tad-dokument u jipproduċi kemm oġġetti LigneFacture kemm isib ringieli, inkluża d-deskrizzjoni, il-kwantità, il-prezz unitarju u t-total għal kull waħda. Dan jagħtik biżżejjed dejta biex terġa’ tikkalkula s-sottotal int stess u tivverifika l-konsistenza tad-dokument qabel ma taċċettah.

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

Kaxxi tal-għażla u forom

Il-forom tal-karta skannjati huma fejn il-mudell jirnexxi. Qasam bool imqabbel mat-tikketta tal-mistoqsija huwa biżżejjed: il-mudell jirrikonoxxi jekk kaxxa hijiex immarkata, jestratti l-mistoqsija korrispondenti, u—kruċjali għall-użu mediku jew amministrattiv—jiddeduċi li qasam huwa nieqes minflok ma jinventa valur, kif wera t-tim ta’ Mistral. In-nota “null if not provided” fid-deskrizzjoni tan-numru tat-telefon mhix dekorattiva; tawtorizza b’mod espliċitu valur vojt.

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

Implimentazzjoni minn tarf għal tarf

Ħu l-eżempju tal-fattura dettaljata u qabbadha ma’ dokument kodifikat f’base64. Il-prompt tal-annotazzjoni jissupplimenta l-iskema billi jispeċifika t-tip tal-fajl u jenfasizza l-attenzjoni għal-linji tal-fatturar; il-validazzjoni ta’ Pydantic fir-ritorn tikkonverti l-string JSON f’oġġett li tista’ tgħaddi minnu b’mod sikur.

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

# Estrazzjoni u validazzjoni
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}€")

Riżultati fqar ta’ estrazzjoni kważi dejjem ġejjin mill-iskema, rari mill-mudell. Irrevedi d-deskrizzjonijiet tiegħek waħda waħda: iridu jkunu preċiżi u mingħajr ambigwità, peress li l-mudell jiddependi biss fuqhom biex jifhem l-aspettattivi tiegħek. Iktebhom fil-lingwa tad-dokumenti tiegħek—il-Franċiż jaħdem perfettament għall-fatturi Franċiżi—u rriżerva l-enums għal oqsma b’valuri limitati u s-mudelli sekondarji għal strutturi li se terġa’ tuża bejn l-iskemi.

Punti Ewlenin

  • L-iskemi ta’ Pydantic jippermettu l-estrazzjoni ta’ dejta ttajpjata u vvalidata
  • Uża tipi kumplessi (listi, enums, mudelli mbejjna) għal estrazzjonijiet preċiżi
  • Il-mudell jimmaniġġja oqsma fakultattivi u kaxxi tal-għażla b’mod affidabbli
  • Id-deskrizzjonijiet tal-oqsma jiggwidaw l-estrazzjoni: kun preċiż u espliċitu
  • Għaqqad document_annotation_prompt mal-iskema għall-kuntest massimu