Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Anotácie vo veľkom

Lekcia 11 z 16 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Škálovanie procesu
  2. Začni sekvenčným spracovaním
  3. Paralelizácia bez preťaženia API
  4. Keď objem odôvodňuje batch inferenciu
  5. Sledovanie toho, čo sa stalo
  6. Kľúčové poznatky

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 alias mistral-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,…"}; typ document_base64 zo starších príkladov neexistuje ani v dokumentácii, ani v SDK mistralai a tieto príklady by zlyhali. Zdroje: OCR Processor · Document QnA. Opravené 3. novembra 2026: Kód predtým čítal page.document_annotation stránku po stránke; v SDK mistralai 3.7.0 je anotácia dokumentu jediným poľom v odpovedi (response.document_annotation) a anotácia obrázka sa číta z image.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 asyncio a 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