Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Ανnotaciones par lot

Μάθημα 11 / 16 Ενημερώθηκε 3 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Escalando el proceso
  2. Comience con el procesamiento secuencial
  3. Paralelizar sin saturar la API
  4. Cuando el volumen justifica la inferencia por lotes
  5. Seguimiento de lo ocurrido
  6. Βασικά σημεία

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 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 · Documento 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.

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 asyncio y 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