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

Annotazzjonijiet Batch

Lezzjoni 11 / 16 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Tkabbir tal-Iskala (Scaling Up)
  2. Ibda bl-Ipproċessar Sekwenzjali
  3. Parallelizza mingħajr ma Tisatura l-API
  4. Meta l-Volum Jiġġustifika l-Inferenza Batch
  5. Traċċar ta’ X’Ġara
  6. Punti Ewlenin

Aġġornat fit-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 fit-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 la 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 kien 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.

Tkabbir tal-Iskala (Scaling Up)

L-ipproċessar ta’ dokument wieħed kull darba jaħdem għall-prototipar. Fil-produzzjoni, ir-realtà hija differenti: dipartiment tal-kontabbiltà jirċievi mijiet ta’ fatturi kuljum, u ditta tal-avukati tiddiġitalizza eluf ta’ dokumenti waqt id-diliġenza dovuta. Il-kodiċi jrid jinbidel skont dan—ma għadx biss dwar li tikseb tweġiba, iżda li tiżgura li l-ebda dokument ma jintilef fit-triq u li tkun taf eżattament liema falla.

Ibda bl-Ipproċessar Sekwenzjali

Żommha sempliċi fil-bidu. Il-luk ta’ hawn taħt jgħaddi minn folder ta’ PDFs, jikkodifika kull fajl f’base64, jibgħatu lill-magna tal-OCR bl-iskema tal-annotazzjoni, u jakkumula r-riżultati. Il-parti kritika tinsab fil-blokk try/except: fattura li ma tistax tinqara jew sejħa API falluta qatt m’għandha tinterrompi l-batch kollu. Nirreġistraw l-iżball bl-isem tal-fajl u nkomplu, u jħalluk b’lista finali fejn kull entrata għandha status. Il-kontur muri f’kull iterazzjoni mhux sempliċiment xi ħaġa sabiħa li jkollok; meta tipproċessa tliet mitt fajl, li tkun taf il-progress tiegħek jipprevjenik milli terġa’ tibda xogħol li diġà huwa nofsu lest.

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]:
    """Jipproċessa l-fatturi kollha f'folder."""
    resultats = []
    chemin = Path(dossier)
    fichiers = list(chemin.glob("*.pdf"))

    print(f"Qiegħed nipproċessa {len(fichiers)} fajls...")

    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

Parallelizza mingħajr ma Tisatura l-API

L-ipproċessar sekwenzjali jqatta’ ħafna mill-ħin jistenna n-netwerk. Is-sejħiet asinkroni jeliminaw din l-iskart, sakemm tirregola l-konkorrenza: it-tnedija ta’ tliet mitt talba f’daqqa se tikkawża żbalji ta’ limitu tar-rata (rate-limit) u tħallik b’batch nofsu lest. Is-semaforu asyncio jimmaniġġja eżattament dan—max_concurrent=5 ifisser massimu ta’ ħames dokumenti fl-ajru f’kull ħin, irrispettivament minn kemm-il fajl ikun fil-kju. Il-funzjoni individwali żżomm l-istess dixxiplina bħall-verżjoni sekwenzjali: taqbad l-eċċezzjonijiet u tirritorna dizzjunarju ta’ status minflok ma tħalli lill-gather jikkraċċja.

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:
    """Jipproċessa dokument b'mod asinkronu."""
    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]:
    """Jipproċessa folder b'parallelizmu kkontrollat."""
    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)

# Eżekuzzjoni
# résultats = asyncio.run(traiter_batch("./factures/", ExtractionFacture))

Meta l-Volum Jiġġustifika l-Inferenza Batch

Lil hinn minn ċerta limitu, il-mistoqsija tinbidel mill-veloċità għall-ispiża. Mistral toffri servizz dedikat ta’ Inferenza Batch li huwa aktar ekonomiku minn sejħiet individwali. Tibgħat fajl JSONL li fih talba waħda kull linja. Il-qasam custom_id—hawnhekk, l-isem tal-fajl mingħajr estensjoni—jippermettilek timmappja kull risposta lura għad-dokument oriġinali tagħha meta l-batch jitlesta.

import json

def preparer_batch_jsonl(dossier: str, sortie: str) -> int:
    """Jipprepara fajl JSONL għall-ipproċessar batch."""
    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} talbiet imħejjija f'{sortie}'")
    return compte

Traċċar ta’ X’Ġara

L-ipproċessar tal-massa mingħajr metrika huwa kaxxa sewda. Id-dataclass żgħira hawn taħt tgħodd is-suċċessi u l-iżbalji, tikkalkula l-ħin li għadda, u tidderiva veloċità f’dokumenti kull sekonda. Din il-veloċità tgħidlek jekk is-setting max_concurrent tiegħek huwiex ottimali, filwaqt li l-lista ta’ fajls falluti titma’ l-proċess ta’ rkupru tal-inċidenti tiegħek.

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"Ipproċessar imlesti f'{self.duree:.1f}s\n"
            f"  Suċċessi: {self.succes}/{self.total}\n"
            f"  Żbalji: {self.erreurs}\n"
            f"  Veloċità: {self.vitesse:.2f} docs/s\n"
            f"  Fajls falluti: {self.fichiers_erreur}"
        )

Fl-aħħar nett, esporta r-riżultati tal-iskritt. CSV imur għall-folja tal-kalkolu tad-dipartiment tal-kontabbiltà, JSON għall-applikazzjoni tiegħek; fiż-żewġ każijiet, żgura l-kodifika UTF-8 u ensure_ascii=False, inkella l-karattri aċċentwati tiegħek se jidhru bħala sekwenzi li ma jistgħux jinqraw għar-riċevitur.

import csv
import json

def exporter_csv(resultats: list[dict], chemin: str) -> None:
    """Jesporta r-riżultati f'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"Esportazzjoni CSV: {chemin}")


def exporter_json(resultats: list[dict], chemin: str) -> None:
    """Jesporta r-riżultati f'JSON."""
    with open(chemin, "w", encoding="utf-8") as f:
        json.dump(resultats, f, ensure_ascii=False, indent=2)

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

Punti Ewlenin

  • L-ipproċessar sekwenzjali huwa adattat għal volumi żgħar b’ġestjoni robusta tal-iżbalji
  • L-ipproċessar parallel b’asyncio u semafuri jħaffef volumi kbar
  • Is-servizz ta’ Inferenza Batch ta’ Mistral huwa l-aktar soluzzjoni kost-effettiva għal volumi kbar ħafna
  • Żid monitoraġġ u rappurtar biex issegwi l-progress u tidentifika l-iżbalji
  • Esporta r-riżultati f’CSV jew JSON għall-integrazzjoni mas-sistemi tiegħek