Anotácie vo veľkom
Na tejto strane
Aktualizované 2. novembra 2026 — OCR. Verzia OCR 4.0 (
mistral-ocr-4-0) bola vyradená 30. septembra 2026. Používaj OCR 4.1 (mistral-ocr-4-1), ktorá je všeobecne dostupná od 31. augusta za rovnakú cenu, alebo aliasmistral-ocr-latest, ktorý na ňu odkazuje od 16. júla. OCR 4.1 pridáva skóre spoľahlivosti na úrovni blokov. Dodatok z 3. novembra 2026: Lokálny súbor PDF sa odosiela v kódovaní base64 ako{"type": "document_url", "document_url": "data:application/pdf;base64,…"}; typdocument_base64zo starších príkladov neexistuje ani v dokumentácii, ani v SDKmistralaia tieto príklady by zlyhali. Zdroje: OCR Processor · Document QnA. Opravené 3. novembra 2026: Kód predtým čítalpage.document_annotationstránku po stránke; v SDKmistralai3.7.0 je anotácia dokumentu jediným poľom v odpovedi (response.document_annotation) a anotácia obrázka sa číta zimage.image_annotation.
Škálovanie procesu
Spracovanie jedného dokumentu naraz funguje pri prototypovaní. V produkcii je však realita iná: účtovné oddelenie dostáva stovky faktúr denne a advokátska kancelária digitalizuje tisíce dokumentov počas due diligence. Kód sa musí prispôsobiť – už nejde len o získanie odpovede, ale o zabezpečenie toho, že sa žiadny dokument nestratí a budeš presne vedieť, ktoré zlyhali.
Začni sekvenčným spracovaním
Najprv to udrž jednoduché. Nasledujúca slučka prechádza priečinkom so súbormi PDF, každý súbor zakóduje do base64, odošle ho do OCR engine so schémou anotácií a zhromažďuje výsledky. Kľúčová časť spočíva v bloku try/except: nečitateľná faktúra alebo zlyhané volanie API nesmie nikdy prerušiť celú dávku. Chybu zaznamenáme spolu s názvom súboru a pokračujeme ďalej, čím získame konečný zoznam, kde každá položka má pole status. Počítadlo zobrazované pri každej iterácii nie je len pekným doplnkom; pri spracovaní tristo súborov ti znalosť postupu zabráni reštartovať úlohu, ktorá je už z polovice hotová.
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]:
"""Spracuje všetky faktúry v priečinku."""
resultats = []
chemin = Path(dossier)
fichiers = list(chemin.glob("*.pdf"))
print(f"Spracúvam {len(fichiers)} súborov...")
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
Paralelizácia bez preťaženia API
Sekvenčné spracovanie trávi väčšinu času čakáním na sieť. Asynchrónne volania tento odpad eliminujú, za predpokladu, že obmedzíš súbežnosť: spustenie tristo požiadaviek naraz vyvolá chyby týkajúce sa limitu rýchlosti (rate-limit) a zostaneš s nedokončenou dávkou. Semafór asyncio rieši presne toto – max_concurrent=5 znamená maximálne päť dokumentov vo vzduchu v ktoromkoľvek okamihu, bez ohľadu na to, koľko súborov je v rade. Individuálna funkcia zachováva rovnakú disciplínu ako sekvenčná verzia: zachytáva výnimky a vracia slovník so statusom, namiesto toho, aby nechala gather zlyhať.
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:
"""Asynchrónne spracuje dokument."""
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]:
"""Spracuje priečinok s riadenou paralelizáciou."""
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)
# Execution
# résultats = asyncio.run(traiter_batch("./factures/", ExtractionFacture))
Keď objem odôvodňuje batch inferenciu
Po prekročení určitej hranice sa otázka posúva od rýchlosti k nákladom. Mistral ponúka vyhradenú službu Batch Inference, ktorá je úspornejšia ako jednotlivé volania. Odošleš súbor JSONL obsahujúci jednu požiadavku na riadok. Pole custom_id – tu názov súboru bez prípony – ti umožní po dokončení dávky priradiť každú odpoveď späť k pôvodnému dokumentu.
import json
def preparer_batch_jsonl(dossier: str, sortie: str) -> int:
"""Pripraví súbor JSONL pre batch spracovanie."""
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} požiadaviek pripravených v {sortie}")
return compte
Sledovanie toho, čo sa stalo
Hromadné spracovanie bez metrík je čierna skrinka. Nasledujúca malá dátová trieda počíta úspechy a chyby, vypočítava uplynutý čas a odvodzuje rýchlosť v dokumentoch za sekundu. Táto rýchlosť ti povie, či je tvoje nastavenie max_concurrent optimálne, zatiaľ čo zoznam zlyhaných súborov slúži ako vstup pre proces obnovy po incidentoch.
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"Spracovanie dokončené za {self.duree:.1f}s\n"
f" Úspechy: {self.succes}/{self.total}\n"
f" Chyby: {self.erreurs}\n"
f" Rýchlosť: {self.vitesse:.2f} docs/s\n"
f" Zlyhané súbory: {self.fichiers_erreur}"
)
Nakoniec exportuj výsledky skriptu. CSV ide do tabuľky účtovného oddelenia, JSON do tvojej aplikácie; v oboch prípadoch zabezpeč kódovanie UTF-8 a ensure_ascii=False, inak sa tvoje znaky s diakritikou príjemcovi zobrazia ako nečitateľné sekvencie.
import csv
import json
def exporter_csv(resultats: list[dict], chemin: str) -> None:
"""Exportuje výsledky do 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:
"""Exportuje výsledky do JSON."""
with open(chemin, "w", encoding="utf-8") as f:
json.dump(resultats, f, ensure_ascii=False, indent=2)
print(f"Export JSON: {chemin}")
Kľúčové poznatky
- Sekvenčné spracovanie vyhovuje malým objemom vďaka robustnému ošetreniu chýb
- Paralelné spracovanie s
asyncioa semaformi urýchľuje veľké objemy - Služba Batch Inference od Mistralu je najnákladovo efektívnejším riešením pre veľmi veľké objemy
- Pridaj monitorovanie a reportovanie na sledovanie postupu a identifikáciu chýb
- Exportuj výsledky do CSV alebo JSON pre integráciu s tvojimi systémami