Annotazzjonijiet Batch
F'din il-paġna
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-aliasmistral-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-tipdocument_base64minn eżempji aktar antiki ma jeżistix la fid-dokumentazzjoni u lanqas fl-SDKmistralai, 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 jaqrapage.document_annotationpaġna b’paġna; fl-SDKmistralai3.7.0, l-annotazzjoni tad-dokument hija qasam wieħed fir-risposta (response.document_annotation), u l-annotazzjoni tal-immaġni tinqara minnimage.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’
asynciou 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