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

Anotări în lot

Lecția 11 din 16 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Scalarea procesului
  2. Începeți cu procesarea secvențială
  3. Paralelizare fără saturarea API-ului
  4. Când volumul justifică inferența în lot (Batch Inference)
  5. Urmărirea evenimentelor
  6. Puncte cheie

Actualizat la 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 începând cu 16 iulie. OCR 4.1 adaugă scoruri de încredere la nivel de bloc. Addendum 3 noiembrie 2026: Un PDF local este transmis în 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: OCR Processor · Document QnA. Corectat la 3 noiembrie 2026: Codul anterior citea page.document_annotation pagină cu pagină; în SDK-ul mistralai 3.7.0, anotarea documentului este un singur câmp în răspuns (response.document_annotation), iar anotarea imaginii se citește din image.image_annotation.

Scalarea procesului

Procesarea unui singur document pe rând funcționează pentru prototipare. În producție, realitatea este diferită: un departament de contabilitate primește sute de facturi zilnic, iar o firmă de avocatură digitalizează mii de documente în timpul due diligence-ului. Codul trebuie să se adapteze consecvent – nu mai este vorba doar de obținerea unui răspuns, ci de asigurarea faptului că niciun document nu se pierde pe parcurs și că știți exact care au eșuat.

Începeți cu procesarea secvențială

Păstrați lucrurile simple la început. Bucla de mai jos parcurge un dosar de fișiere PDF, encodează fiecare fișier în base64, îl trimite motorului OCR cu schema de anotare și acumulează rezultatele. Partea critică constă în blocul try/except: o factură ilizibilă sau un apel API eșuat nu trebuie să întrerupă niciodată întregul lot. Înregistrăm eroarea împreună cu numele fișierului și continuăm, lăsându-vă cu o listă finală în care fiecare intrare are un statut. Contorul afișat la fiecare iterație nu este doar un plus; atunci când procesați trei sute de fișiere, cunoașterea progresului vă împiedică să repetați o sarcină deja finalizată pe jumătate.

import os
import json
import time
from pathlib import Path
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model
from pydantic import BaseModel, Field

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

class ExtractionFacture(BaseModel):
    fournisseur: str = Field(..., description="Supplier name")
    numero: str = Field(..., description="Invoice number")
    montant_ttc: float = Field(..., description="Total amount including tax")
    date: str = Field(..., description="Date (YYYY-MM-DD)")

def traiter_dossier_factures(dossier: str) -> list[dict]:
    """Procesează toate facturile dintr-un dosar."""
    resultats = []
    chemin = Path(dossier)
    fichiers = list(chemin.glob("*.pdf"))

    print(f"Se procesează {len(fichiers)} fișiere...")

    for i, fichier in enumerate(fichiers):
        print(f"  [{i+1}/{len(fichiers)}] {fichier.name}")

        try:
            import base64
            with open(fichier, "rb") as f:
                doc_b64 = base64.b64encode(f.read()).decode("utf-8")

            response = client.ocr.process(
                model="mistral-ocr-latest",
                document={
                    "type": "document_url",
                    "document_url": f"data:application/pdf;base64,{doc_b64}"
                },
                document_annotation_format=response_format_from_pydantic_model(
                    ExtractionFacture
                ),
                table_format="markdown"
            )

            if response.document_annotation:
                facture = ExtractionFacture.model_validate_json(
                    response.document_annotation
                )
                resultats.append({
                    "fichier": fichier.name,
                    "fournisseur": facture.fournisseur,
                    "numero": facture.numero,
                    "montant_ttc": facture.montant_ttc,
                    "date": facture.date,
                    "statut": "ok"
                })

        except Exception as e:
            resultats.append({
                "fichier": fichier.name,
                "statut": "erreur",
                "erreur": str(e)
            })

    return resultats

Paralelizare fără saturarea API-ului

Procesarea secvențială își petrece majoritatea timpului așteptând rețeaua. Apelurile asincrone elimină această pierdere, cu condiția să limitați concurența: lansarea a trei sute de cereri simultan va declanșa erori de limitare a ratei (rate-limit) și vă va lăsa cu un lot neterminat. Semaforul asyncio gestionează exact acest aspect – max_concurrent=5 înseamnă un maxim de cinci documente în curs de execuție în orice moment, indiferent câte fișiere sunt în coadă. Funcția individuală menține aceeași disciplină ca versiunea secvențială: captează excepțiile și returnează un dicționar de statut, în loc să permită ca gather să se blocheze.

import os
import asyncio
import base64
from pathlib import Path
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model

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

async def traiter_document(chemin_fichier: Path, schema) -> dict:
    """Procesează un document în mod asincron."""
    try:
        with open(chemin_fichier, "rb") as f:
            doc_b64 = base64.b64encode(f.read()).decode("utf-8")

        response = client.ocr.process(
            model="mistral-ocr-latest",
            document={
                "type": "document_url",
                "document_url": f"data:application/pdf;base64,{doc_b64}"
            },
            document_annotation_format=response_format_from_pydantic_model(
                schema
            )
        )

        annotations = []
        if response.document_annotation:
            annotations.append(response.document_annotation)

        return {
            "fichier": chemin_fichier.name,
            "annotations": annotations,
            "statut": "ok"
        }

    except Exception as e:
        return {
            "fichier": chemin_fichier.name,
            "statut": "erreur",
            "erreur": str(e)
        }


async def traiter_batch(
    dossier: str,
    schema,
    max_concurrent: int = 5
) -> list[dict]:
    """Procesează un dosar cu paralelism controlat."""
    chemin = Path(dossier)
    fichiers = list(chemin.glob("*.pdf"))

    semaphore = asyncio.Semaphore(max_concurrent)

    async def traiter_avec_limite(fichier):
        async with semaphore:
            return await traiter_document(fichier, schema)

    taches = [traiter_avec_limite(f) for f in fichiers]
    resultats = await asyncio.gather(*taches)

    return list(resultats)

# Execuție
# résultats = asyncio.run(traiter_batch("./factures/", ExtractionFacture))

Când volumul justifică inferența în lot (Batch Inference)

Dincolo de un anumit prag, întrebarea se mută de la viteză la cost. Mistral oferă un serviciu dedicat de inferență în lot (Batch Inference) care este mai economic decât apelurile individuale. Trimiteți un fișier JSONL conținând o cerere pe linie. Câmpul custom_id – aici, numele fișierului fără extensie – vă permite să mapați fiecare răspuns la documentul său original atunci când lotul se finalizează.

import json

def preparer_batch_jsonl(dossier: str, sortie: str) -> int:
    """Pregătește un fișier JSONL pentru procesarea în lot."""
    chemin = Path(dossier)
    fichiers = list(chemin.glob("*.pdf"))
    compte = 0

    with open(sortie, "w") as f:
        for fichier in fichiers:
            with open(fichier, "rb") as pdf:
                doc_b64 = base64.b64encode(pdf.read()).decode("utf-8")

            requete = {
                "custom_id": fichier.stem,
                "model": "mistral-ocr-latest",
                "document": {
                    "type": "document_url",
                    "document_url": f"data:application/pdf;base64,{doc_b64}"
                }
            }

            f.write(json.dumps(requete) + "\n")
            compte += 1

    print(f"{compte} cereri pregătite în {sortie}")
    return compte

Urmărirea evenimentelor

Procesarea în masă fără metrici este o cutie neagră. Clasa de date (dataclass) de mai jos numără succesele și erorile, calculează timpul scurs și derivează o viteză în documente pe secundă. Această viteză vă indică dacă setarea max_concurrent este optimă, în timp ce lista fișierelor eșuate alimentează procesul de recuperare a incidentelor.

import time
from dataclasses import dataclass, field

@dataclass
class StatsBatch:
    total: int = 0
    succes: int = 0
    erreurs: int = 0
    temps_debut: float = field(default_factory=time.time)
    fichiers_erreur: list = field(default_factory=list)

    @property
    def duree(self) -> float:
        return time.time() - self.temps_debut

    @property
    def vitesse(self) -> float:
        if self.duree > 0:
            return self.succes / self.duree
        return 0.0

    def rapport(self) -> str:
        return (
            f"Processing completed in {self.duree:.1f}s\n"
            f"  Successes: {self.succes}/{self.total}\n"
            f"  Errors: {self.erreurs}\n"
            f"  Speed: {self.vitesse:.2f} docs/s\n"
            f"  Failed files: {self.fichiers_erreur}"
        )

În final, exportați rezultatele scriptului. CSV merge în foaia de calcul a departamentului de contabilitate, JSON în aplicația dumneavoastră; în ambele cazuri, asigurați-vă că utilizați codificarea UTF-8 și ensure_ascii=False, altfel caracterele accentuate vor apărea ca secvențe ilizibile pentru destinatar.

import csv
import json

def exporter_csv(resultats: list[dict], chemin: str) -> None:
    """Exportă rezultatele în CSV."""
    if not resultats:
        return

    cles = resultats[0].keys()

    with open(chemin, "w", newline="", encoding="utf-8") as f:
        writer = csv.DictWriter(f, fieldnames=cles)
        writer.writeheader()
        writer.writerows(resultats)

    print(f"Export CSV: {chemin}")


def exporter_json(resultats: list[dict], chemin: str) -> None:
    """Exportă rezultatele în JSON."""
    with open(chemin, "w", encoding="utf-8") as f:
        json.dump(resultats, f, ensure_ascii=False, indent=2)

    print(f"Export JSON: {chemin}")

Puncte cheie

  • Procesarea secvențială se potrivește volumelor mici, cu o gestionare robustă a erorilor
  • Procesarea paralelă cu asyncio și semafoare accelerează volumele mari
  • Serviciul Batch Inference de la Mistral este soluția cea mai eficientă din punct de vedere al costurilor pentru volume foarte mari
  • Adăugați monitorizare și raportare pentru a urmări progresul și a identifica erorile
  • Exportați rezultatele în CSV sau JSON pentru integrarea cu sistemele dumneavoastră