Annotations par lots
Na tej strani
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), disponible depuis le 31 août au même tarif, ou l’aliasmistral-ocr-latestqui 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 typedocument_base64présent dans d’anciens exemples n’existe ni dans la documentation ni dans le SDKmistralai, et ces exemples auraient échoué. Sources : OCR Processor · Document QnA. Corrigé le 3 novembre 2026 : le code lisait précédemmentpage.document_annotationpage par page ; dans le SDKmistralai3.7.0, l’annotation de document est un champ unique dans la réponse (response.document_annotation), et l’annotation d’image se lit depuisimage.image_annotation.
Passer à 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 de savoir exactement lesquels ont échoué.
Commence par le 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 tout le 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 d’un coup 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}")
Ključne ugotovitve
- Le traitement séquentiel convient aux petits volumes avec une gestion robuste des erreurs
- Le traitement parallèle avec
asyncioet 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 du suivi et des rapports pour tracer la progression et identifier les erreurs
- Exporte les résultats en CSV ou JSON pour l’intégration avec tes systèmes