Extragerea metadatelor structurate
Pe această pagină
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 aliasulmistral-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,…"}; tipuldocument_base64din exemplele mai vechi nu există nici în documentație, nici în SDK-ulmistralai, iar acele exemple ar fi eșuat. Surse: Procesor OCR · Întrebări și răspunsuri despre documente. Corectat la 3 noiembrie 2026: Codul anterior citeapage.document_annotationpagină cu pagină; în SDK-ulmistralaiversiunea 3.7.0, adnotarea documentului este un singur câmp în răspuns (response.document_annotation), iar adnotarea imaginii se citește dinimage.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_promptcu schema pentru un context maxim