Ir al contenido principal
Español— Elegir un idioma
Menú

Anotaciones por lotes

Lección 11 de 16 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Escalado del proceso
  2. Comienza con el procesamiento secuencial
  3. Paralelización sin saturar la API
  4. Cuándo justifica el volumen la inferencia por lotes
  5. Seguimiento de lo ocurrido
  6. Puntos clave

Actualizado el 2 de noviembre de 2026 — OCR. El modelo OCR 4.0 (mistral-ocr-4-0) se retiró el 30 de septiembre de 2026. Utiliza OCR 4.1 (mistral-ocr-4-1), disponible generalmente desde el 31 de agosto al mismo precio, o el alias mistral-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 tipo document_base64 de ejemplos anteriores no existe ni en la documentación ni en el SDK mistralai, y esos ejemplos habrían fallado. Fuentes: Procesador OCR · Document QnA. Corregido el 3 de noviembre de 2026: El código leía anteriormente page.document_annotation página por página; en el SDK mistralai 3.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 desde image.image_annotation.

Escalado del proceso

Procesar un documento a la vez funciona para la creación de prototipos. En producción, la realidad es distinta: un departamento de contabilidad recibe cientos de facturas diarias 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 garantizar que no se pierda ningún documento en el camino y de saber exactamente cuáles han fallado.

Comienza con el procesamiento secuencial

Mantén la simplicidad al principio. El bucle siguiente recorre una carpeta de archivos PDF, 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 no deben interrumpir nunca todo el lote. Registramos el error con el nombre del archivo y continuamos, dejándote con una lista final donde cada entrada tiene un status. El contador mostrado en cada iteración no es solo un detalle agradable; al procesar trescientos archivos, conocer tu progreso te evita reiniciar un trabajo que ya está a medio hacer.

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="Nombre del proveedor")
    numero: str = Field(..., description="Número de factura")
    montant_ttc: float = Field(..., description="Importe total con impuestos")
    date: str = Field(..., description="Fecha (AAAA-MM-DD)")

def traiter_dossier_factures(dossier: str) -> list[dict]:
    """Procesa todas las facturas de una carpeta."""
    resultats = []
    chemin = Path(dossier)
    fichiers = list(chemin.glob("*.pdf"))

    print(f"Procesando {len(fichiers)} archivos...")

    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

Paralelización 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 limites la concurrencia: lanzar trescientas solicitudes a la vez provocará errores de límite de tasa y te dejará con un lote a medio terminar. El semáforo de 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 haya 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 permitir 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:
    """Procesa un documento de forma asíncrona."""
    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]:
    """Procesa una carpeta con paralelismo controlado."""
    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)

# Ejecución
# résultats = asyncio.run(traiter_batch("./factures/", ExtractionFacture))

Cuándo justifica el volumen la inferencia por lotes

Más allá de cierto umbral, la pregunta cambia de la velocidad al coste. Mistral ofrece un servicio dedicado de Inferencia por Lotes (Batch Inference) que es más económico que las llamadas individuales. Envías un archivo JSONL que contiene una solicitud por línea. El campo custom_id —aquí, el nombre del archivo sin extensión— te permite mapear cada respuesta a su documento original cuando finaliza el lote.

import json

def preparer_batch_jsonl(dossier: str, sortie: str) -> int:
    """Prepara un archivo JSONL para el procesamiento por lotes."""
    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} solicitudes preparadas en {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 te indica si tu configuración de max_concurrent es óptima, mientras que la lista de archivos fallidos alimenta tu 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"Procesamiento completado en {self.duree:.1f}s\n"
            f"  Éxitos: {self.succes}/{self.total}\n"
            f"  Errores: {self.erreurs}\n"
            f"  Velocidad: {self.vitesse:.2f} docs/s\n"
            f"  Archivos fallidos: {self.fichiers_erreur}"
        )

Finalmente, exporta los resultados del script. El CSV va a la hoja de cálculo del departamento de contabilidad y el JSON a tu aplicación; en ambos casos, asegúrate de usar la codificación UTF-8 y ensure_ascii=False, de lo contrario, tus caracteres acentuados aparecerán como secuencias ilegibles para el destinatario.

import csv
import json

def exporter_csv(resultats: list[dict], chemin: str) -> None:
    """Exporta los resultados a 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"Exportación CSV: {chemin}")


def exporter_json(resultats: list[dict], chemin: str) -> None:
    """Exporta los resultados a JSON."""
    with open(chemin, "w", encoding="utf-8") as f:
        json.dump(resultats, f, ensure_ascii=False, indent=2)

    print(f"Exportación JSON: {chemin}")

Puntos clave

  • El procesamiento secuencial es adecuado para volúmenes pequeños con una gestión robusta de errores
  • El procesamiento paralelo con asyncio y semáforos acelera los grandes volúmenes
  • El servicio de Inferencia por Lotes de Mistral es la solución más rentable para volúmenes muy grandes
  • Añade monitorización e informes para seguir el progreso e identificar errores
  • Exporta los resultados a CSV o JSON para integrarlos con tus sistemas