Ανnotaciones par lot
Σε αυτήν τη σελίδα
Actualizado el 2 de noviembre de 2026 — OCR. OCR 4.0 (
mistral-ocr-4-0) fue retirado el 30 de septiembre de 2026. Utilice OCR 4.1 (mistral-ocr-4-1), disponible generalmente desde el 31 de agosto al mismo precio, o el aliasmistral-ocr-latest, que apunta a él desde el 16 de julio. OCR 4.1 añade puntuaciones de confianza a nivel de bloque. Addendum 3 de noviembre de 2026: Un PDF local se transmite en base64 como{"type": "document_url", "document_url": "data:application/pdf;base64,…"}; el tipodocument_base64de ejemplos anteriores no existe ni en la documentación ni en el SDKmistralai, y esos ejemplos habrían fallado. Fuentes: Procesador OCR · Documento QnA. Corregido el 3 de noviembre de 2026: El código leía anteriormentepage.document_annotationpágina por página; en el SDKmistralai3.7.0, la anotación del documento es un único campo en la respuesta (response.document_annotation), y la anotación de imagen se lee desdeimage.image_annotation.
Escalando el proceso
Procesar un documento a la vez funciona para la creación de prototipos. En producción, la realidad es diferente: un departamento de contabilidad recibe cientos de facturas diariamente, y un bufete de abogados digitaliza miles de documentos durante la debida diligencia. El código debe cambiar en consecuencia: ya no se trata solo de obtener una respuesta, sino de asegurar que ningún documento se pierda en el camino y de saber exactamente cuáles han fallado.
Comience con el procesamiento secuencial
Manténgalo simple al principio. El bucle siguiente itera a través de una carpeta de PDFs, codifica cada archivo en base64, lo envía al motor OCR con el esquema de anotación y acumula los resultados. La parte crítica reside en el bloque try/except: una factura ilegible o una llamada a la API fallida nunca debe interrumpir todo el lote. Registramos el error con el nombre del archivo y continuamos, dejándole con una lista final donde cada entrada tiene un status. El contador mostrado en cada iteración no es solo un extra; al procesar trescientos archivos, conocer su progreso le evita reiniciar un trabajo que ya está a la mitad.
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]:
"""Processes all invoices in a folder."""
resultats = []
chemin = Path(dossier)
fichiers = list(chemin.glob("*.pdf"))
print(f"Processing {len(fichiers)} files...")
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
Paralelizar sin saturar la API
El procesamiento secuencial pasa la mayor parte del tiempo esperando a la red. Las llamadas asíncronas eliminan este desperdicio, siempre que limite la concurrencia: lanzar trescientas solicitudes a la vez desencadenará errores de límite de tasa y le dejará con un lote a medio terminar. El semáforo asyncio se encarga exactamente de esto: max_concurrent=5 significa un máximo de cinco documentos en vuelo en cualquier momento, independientemente de cuántos archivos estén en cola. La función individual mantiene la misma disciplina que la versión secuencial: captura excepciones y devuelve un diccionario de estado en lugar de dejar que gather falle.
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:
"""Processes a document asynchronously."""
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]:
"""Processes a folder with controlled parallelism."""
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))
Cuando el volumen justifica la inferencia por lotes
Más allá de cierto umbral, la pregunta cambia de velocidad a coste. Mistral ofrece un servicio dedicado de Inferencia por Lotes (Batch Inference) que es más económico que las llamadas individuales. Envía un archivo JSONL que contiene una solicitud por línea. El campo custom_id —aquí, el nombre del archivo sin extensión— le permite mapear cada respuesta de vuelta a su documento original cuando el lote se completa.
import json
def preparer_batch_jsonl(dossier: str, sortie: str) -> int:
"""Prepares a JSONL file for batch processing."""
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} requests prepared in {sortie}")
return compte
Seguimiento de lo ocurrido
El procesamiento masivo sin métricas es una caja negra. La pequeña clase de datos siguiente cuenta éxitos y errores, calcula el tiempo transcurrido y deriva una velocidad en documentos por segundo. Esta velocidad le indica si su configuración de max_concurrent es óptima, mientras que la lista de archivos fallidos alimenta su proceso de recuperación de incidentes.
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"Processing completed in {self.duree:.1f}s\n"
f" Successes: {self.succes}/{self.total}\n"
f" Errors: {self.erreurs}\n"
f" Speed: {self.vitesse:.2f} docs/s\n"
f" Failed files: {self.fichiers_erreur}"
)
Finalmente, exporte los resultados del script. CSV va a la hoja de cálculo del departamento de contabilidad, JSON a su aplicación; en ambos casos, asegure la codificación UTF-8 y ensure_ascii=False, de lo contrario sus caracteres acentuados aparecerán como secuencias ilegibles para el destinatario.
import csv
import json
def exporter_csv(resultats: list[dict], chemin: str) -> None:
"""Exports results to 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"CSV export: {chemin}")
def exporter_json(resultats: list[dict], chemin: str) -> None:
"""Exports results to JSON."""
with open(chemin, "w", encoding="utf-8") as f:
json.dump(resultats, f, ensure_ascii=False, indent=2)
print(f"JSON export: {chemin}")
Βασικά σημεία
- El procesamiento secuencial es adecuado para volúmenes pequeños con un manejo robusto de errores
- El procesamiento paralelo con
asyncioy semáforos acelera grandes volúmenes - El servicio de Inferencia por Lotes de Mistral es la solución más rentable para volúmenes muy grandes
- Añada monitoreo e informes para rastrear el progreso e identificar errores
- Exporte los resultados a CSV o JSON para la integración con sus sistemas