Salt la conținutul principal
Română— Alege o limbă
Meniu

Extragerea metadatelor structurate

Lecția 10 din 16 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Extrageți exact ceea ce aveți nevoie
  2. Structură în loc de aplatizare
  3. Date repetitive
  4. Casete de bifat și formulare
  5. Implementare cap-la-capăt
  6. Puncte cheie

Actualizare 2 noiembrie 2026 — OCR. OCR 4.0 (mistral-ocr-4-0) a fost retras la 30 septembrie 2026. Utilizați OCR 4.1 (mistral-ocr-4-1), disponibil din 31 august la același preț, sau aliasul mistral-ocr-latest, care indică spre acesta din 16 iulie. OCR 4.1 adaugă scoruri de încredere la nivel de bloc. Addendum 3 noiembrie 2026: Un fișier PDF local este transmis în format base64 sub forma {"type": "document_url", "document_url": "data:application/pdf;base64,…"}; tipul document_base64 din exemplele mai vechi nu există nici în documentație, nici în SDK-ul mistralai, iar acele exemple ar fi eșuat. Surse: Procesor OCR · Întrebări și răspunsuri despre documente. Corectat la 3 noiembrie 2026: Codul anterior citea page.document_annotation pagină cu pagină; în SDK-ul mistralai versiunea 3.7.0, adnotarea documentului este un singur câmp în răspuns (response.document_annotation), iar adnotarea imaginii se citește din image.image_annotation.

Extrageți exact ceea ce aveți nevoie

Adnotarea documentelor nu se rezumă la recuperarea textului brut. Aceasta produce date structurate, tipizate și validate, gata de utilizare imediată în sistemele dumneavoastră: un rând inserat într-o bază de date, un câmp comparat cu o referință sau o sumă verificată înainte de plată. Provocarea se mută în întregime pe proiectarea schemei, aspect care constituie focusul acestei lecții.

Structură în loc de aplatizare

O schemă de extragere trebuie să reflecte realitatea documentului. O factură provine de la o entitate juridică având o denumire socială, un număr SIRET (identificator de afacere francez) și o adresă. În loc să aliniați opt câmpuri precum emetteur_rue, emetteur_ville, emetteur_siret, definiți un model Adresse, apoi un model LegalEntity care îl conține. Reutilizați aceste blocuri de construcție atât pentru emitent, cât și pentru destinatar. Enumerarea TypeDocument joacă un rol similar: aceasta împiedică modelul să inventeze o categorie și garantează o valoare pe care o puteți utiliza într-o instrucțiune if sau pentru rutare. Câmpurile Optional declară explicit ce poate lipsi, în timp ce valorile implicite—cum ar fi default="France" pentru țară—scutesc modelul de a ghici evidentul.

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ăr și stradă")
    postal_code: Optional[str] = Field(None, description="Cod poștal")
    city: Optional[str] = Field(None, description="Oraș")
    country: str = Field(default="France", description="Țară")

class LegalEntity(BaseModel):
    name: str = Field(..., description="Denumire socială")
    siret: Optional[str] = Field(None, description="Număr SIRET")
    address: Optional[Address] = Field(None, description="Adresă poștală")
    email: Optional[str] = Field(None, description="Adresă de email")

class DocumentExtraction(BaseModel):
    document_type: DocumentType = Field(
        ..., description="Tipul documentului"
    )
    date: Optional[str] = Field(
        None, description="Data principală (YYYY-MM-DD)"
    )
    emetteur: LegalEntity = Field(
        ..., description="Entitatea care emite documentul"
    )
    destinataire: Optional[LegalEntity] = Field(
        None, description="Entitatea destinatar"
    )
    resume: str = Field(
        ..., description="Rezumat în 2-3 fraze al conținutului"
    )
    langue: str = Field(
        ..., description="Limba documentului (cod ISO 639-1)"
    )

Date repetitive

Multe documente conțin serii: linii de facturare, clauze sau elemente de cheltuieli. Modelați acestea ca o listă list[...] dintr-un sub-model dedicat. Modelul scanează apoi tabelul documentului și produce câte obiecte LigneFacture găsește rânduri, incluzând descrierea, cantitatea, prețul unitar și totalul pentru fiecare. Acest lucru vă oferă suficiente date pentru a recalcula singur subtotalul și pentru a verifica consistența documentului înainte de a-l accepta.

from pydantic import BaseModel, Field

class InvoiceLine(BaseModel):
    description: str = Field(..., description="Descrierea produsului/serviciului")
    quantity: float = Field(..., description="Cantitate")
    unit_price: float = Field(..., description="Preț unitar fără TVA")
    amount: float = Field(..., description="Total HT al liniei")

class DetailedInvoice(BaseModel):
    supplier: str = Field(..., description="Numele furnizorului")
    number: str = Field(..., description="Numărul facturii")
    date: str = Field(..., description="Data (YYYY-MM-DD)")
    lines: list[InvoiceLine] = Field(
        ..., description="Linii de factură"
    )
    subtotal_excl_tax: float = Field(..., description="Subtotal fără TVA")
    vat: float = Field(..., description="Suma TVA")
    total_incl_tax: float = Field(..., description="Total cu TVA")
    payment_terms: str = Field(
        ..., description="Condițiile de plată menționate"
    )

Casete de bifat și formulare

Formularele pe hârtie scanate sunt domeniul în care modelul excelează. Un câmp de tip bool asociat cu eticheta întrebării este suficient: modelul recunoaște dacă o casetă este bifată, extrage întrebarea corespunzătoare și—crucial pentru uz medical sau administrativ—deduce că un câmp lipsește în loc să inventeze o valoare, așa cum a demonstrat echipa Mistral. Nota „null dacă nu este furnizat“ din descrierea numărului de telefon nu este decorativă; aceasta autorizează explicit o valoare goală.

from pydantic import BaseModel, Field

class FormResponse(BaseModel):
    question: str = Field(..., description="Titlul întrebării")
    answer: bool = Field(..., description="True dacă este bifat, False în caz contrar")

class MedicalForm(BaseModel):
    patient_name: str = Field(..., description="Numele complet al pacientului")
    age: Optional[int] = Field(None, description="Vârsta pacientului")
    sex: Optional[str] = Field(None, description="Sex (M/F)")
    patient_id: Optional[str] = Field(None, description="ID pacient")
    phone: Optional[str] = Field(
        None, description="Număr de telefon (null dacă nu este furnizat)"
    )
    responses: list[FormResponse] = Field(
        ..., description="Răspunsuri la întrebările formularului"
    )

Implementare cap-la-capăt

Luați exemplul facturii detaliate și conectați-l la un document codificat în base64. Promptul de adnotare completează schema specificând tipul de fișier și subliniind atenția acordată liniilor de facturare; validarea Pydantic la returnare convertește șirul JSON într-un obiect pe care îl puteți parcurge în siguranță.

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

# Extracție și validare
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}€")

Rezultatele slabe de extracție provin aproape întotdeauna din schemă, rareori din model. Revizuiți descrierile una câte una: acestea trebuie să fie precise și neambigue, deoarece modelul se bazează exclusiv pe ele pentru a înțelege așteptările dumneavoastră. Scrieți-le în limba documentelor dumneavoastră—franceza funcționează perfect pentru facturile franceze—și rezervați enumerările pentru câmpurile cu valori limitate, iar sub-modelele pentru structurile pe care le veți reutiliza între scheme.

Puncte cheie

  • Schemele Pydantic permit extragerea de date tipizate și validate
  • Utilizați tipuri complexe (liste, enumerări, modele imbricate) pentru extrageri precise
  • Modelul gestionează câmpurile opționale și casetele de bifat în mod fiabil
  • Descrierile câmpurilor ghidează extragerea: fiți precis și explicit
  • Combinați document_annotation_prompt cu schema pentru un context maxim