Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Annotations par lots

Nodarbība 11 no 16 Atjaunota 2026. gada 3. novembris Programmētājs
Šajā lapā
  1. Passage à l’échelle
  2. Commence par un traitement séquentiel
  3. Parallélise sans saturer l’API
  4. Quand le volume justifie l’inférence par lots
  5. Suivre ce qu’il s’est passé
  6. Galvenās atziņas

Mis à jour le 2 novembre 2026 — OCR. OCR 4.0 (mistral-ocr-4-0) a été retiré le 30 septembre 2026. Utilise OCR 4.1 (mistral-ocr-4-1), généralement disponible depuis le 31 août au même tarif, ou l’alias mistral-ocr-latest, qui le cible depuis le 16 juillet. OCR 4.1 ajoute des scores de confiance au niveau des blocs. Addendum du 3 novembre 2026 : un PDF local est transmis en base64 sous la forme {"type": "document_url", "document_url": "data:application/pdf;base64,…"} ; le type document_base64 présent dans d’anciens exemples n’existe ni dans la documentation ni dans le SDK mistralai, et ces exemples auraient échoué. Sources : OCR Processor · Document QnA. Corrigé le 3 novembre 2026 : le code lisait précédemment page.document_annotation page par page ; dans le SDK mistralai 3.7.0, l’annotation de document est un champ unique dans la réponse (response.document_annotation), et l’annotation d’image se lit depuis image.image_annotation.

Passage à l’échelle

Traiter un document à la fois fonctionne pour le prototypage. En production, la réalité est différente : un service comptable reçoit des centaines de factures quotidiennement, et un cabinet d’avocats numérise des milliers de documents lors d’une due diligence. Le code doit évoluer en conséquence : il ne s’agit plus seulement d’obtenir une réponse, mais de garantir qu’aucun document ne se perde en cours de route et que tu saches exactement lesquels ont échoué.

Commence par un traitement séquentiel

Garde les choses simples au début. La boucle ci-dessous parcourt un dossier de PDF, encode chaque fichier en base64, l’envoie au moteur OCR avec le schéma d’annotation, et accumule les résultats. L’élément critique réside dans le bloc try/except : une facture illisible ou un appel API échoué ne doit jamais interrompre l’ensemble du lot. Nous journalisons l’erreur avec le nom du fichier et continuons, te laissant avec une liste finale où chaque entrée possède un statut. Le compteur affiché à chaque itération n’est pas un simple luxe ; lors du traitement de trois cents fichiers, connaître ta progression t’évite de relancer une tâche déjà à moitié terminée.

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]:
    """Traite toutes les factures d'un dossier."""
    resultats = []
    chemin = Path(dossier)
    fichiers = list(chemin.glob("*.pdf"))

    print(f"Traitement de {len(fichiers)} fichiers...")

    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

Parallélise sans saturer l’API

Le traitement séquentiel passe la majeure partie de son temps à attendre le réseau. Les appels asynchrones éliminent cette perte, à condition de limiter la concurrence : lancer trois cents requêtes simultanément déclenchera des erreurs de limite de débit et te laissera avec un lot à moitié terminé. Le sémaphore asyncio gère exactement cela : max_concurrent=5 signifie un maximum de cinq documents en cours de traitement à tout moment, quel que soit le nombre de fichiers en file d’attente. La fonction individuelle maintient la même discipline que la version séquentielle : elle attrape les exceptions et renvoie un dictionnaire de statut plutôt que de laisser gather planter.

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:
    """Traite un document de manière asynchrone."""
    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]:
    """Traite un dossier avec un parallélisme contrôlé."""
    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)

# Exécution
# résultats = asyncio.run(traiter_batch("./factures/", ExtractionFacture))

Quand le volume justifie l’inférence par lots

Au-delà d’un certain seuil, la question passe de la vitesse au coût. Mistral propose un service d’inférence par lots (Batch Inference) dédié, plus économique que les appels individuels. Tu soumets un fichier JSONL contenant une requête par ligne. Le champ custom_id — ici, le nom du fichier sans extension — te permet de mapper chaque réponse à son document d’origine une fois le lot terminé.

import json

def preparer_batch_jsonl(dossier: str, sortie: str) -> int:
    """Prépare un fichier JSONL pour le traitement par lots."""
    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} requêtes préparées dans {sortie}")
    return compte

Suivre ce qu’il s’est passé

Le traitement de masse sans métriques est une boîte noire. La petite dataclass ci-dessous compte les succès et les erreurs, calcule le temps écoulé et déduit une vitesse en documents par seconde. Cette vitesse t’indique si ton paramètre max_concurrent est optimal, tandis que la liste des fichiers échoués alimente ton processus de récupération d’incidents.

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"Traitement terminé en {self.duree:.1f}s\n"
            f"  Succès : {self.succes}/{self.total}\n"
            f"  Erreurs : {self.erreurs}\n"
            f"  Vitesse : {self.vitesse:.2f} docs/s\n"
            f"  Fichiers échoués : {self.fichiers_erreur}"
        )

Enfin, exporte les résultats du script. Le CSV va vers le tableur du service comptable, le JSON vers ton application ; dans les deux cas, assure-toi d’utiliser l’encodage UTF-8 et ensure_ascii=False, sinon tes caractères accentués apparaîtront comme des séquences illisibles pour le destinataire.

import csv
import json

def exporter_csv(resultats: list[dict], chemin: str) -> None:
    """Exporte les résultats en 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:
    """Exporte les résultats en JSON."""
    with open(chemin, "w", encoding="utf-8") as f:
        json.dump(resultats, f, ensure_ascii=False, indent=2)

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

Galvenās atziņas

  • Le traitement séquentiel convient aux petits volumes avec une gestion robuste des erreurs
  • Le traitement parallèle avec asyncio et des sémaphores accélère les gros volumes
  • Le service Batch Inference de Mistral est la solution la plus économique pour les très gros volumes
  • Ajoute de la surveillance et des rapports pour suivre la progression et identifier les erreurs
  • Exporte les résultats en CSV ou JSON pour l’intégration avec tes systèmes