Canalización de producción
En esta página
Actualización 2 de noviembre de 2026 — OCR. OCR 4.0 (
mistral-ocr-4-0) se retiró el 30 de septiembre de 2026. Utiliza OCR 4.1 (mistral-ocr-4-1), disponible de forma general 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 · Document 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 una imagen se lee desdeimage.image_annotation.
De la prueba de concepto a la producción
Has aprendido a utilizar OCR, anotaciones y Document AI QnA. Queda una brecha costosa: la distancia entre un script que funciona en tu portátil y un servicio del que dependen tus compañeros cada mañana. Esta última lección ensambla los bloques de construcción anteriores en una canalización robusta, completa con recuperación de errores, supervisión y control de costes.
Los seis componentes de una canalización completa
- Cola de ingesta: Recibe y prioriza documentos.
- Preprocesamiento: Valida, convierte formatos y mejora imágenes.
- OCR + Anotaciones: Extrae texto y datos estructurados.
- Postprocesamiento: Valida, limpia y enriquece datos.
- Almacenamiento: Bases de datos, almacenes vectoriales y archivado.
- Interfaz de consulta: API de QnA, paneles de control e integraciones.
El código de esta lección cubre el núcleo de la cadena —pasos 3 y 4— porque es ahí donde se concentran las dificultades operativas.
Una clase que encapsula el procesamiento
La clase PipelineDocumentAI establece una configuración de una vez por todas —el esquema de anotación, el formato de tabla y el número de reintentos— y luego la aplica a cada documento. Tres mecanismos merecen tu atención. En primer lugar, el reintento con retroceso exponencial (time.sleep(2 ** tentative)) espacia los intentos en uno, luego dos, luego cuatro segundos. Esto da tiempo a que se resuelva la saturación transitoria de la API en lugar de empeorarla. En segundo lugar, el registro (logging) rastrea cada éxito con su número de páginas y duración, y cada fallo con su número de intento; sin estas líneas, solo descubrirás incidentes cuando te llame el departamento de contabilidad. Por último, el diccionario stats alimenta el informe de fin de lote.
Ten en cuenta que el método devuelve siempre un ResultatTraitement, incluso tras agotar los reintentos: el llamador nunca tiene que gestionar una excepción, simplemente lee el campo erreur.
import os
import time
import base64
import logging
from pathlib import Path
from dataclasses import dataclass, field
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model
from pydantic import BaseModel, Field
from typing import Optional
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("document_ai_pipeline")
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
@dataclass
class ResultatTraitement:
fichier: str
pages: int = 0
texte: str = ""
annotations: Optional[dict] = None
duree_secondes: float = 0.0
erreur: Optional[str] = None
class PipelineDocumentAI:
def __init__(
self,
schema_annotation=None,
table_format: str = "markdown",
max_retries: int = 3,
):
self.schema_annotation = schema_annotation
self.table_format = table_format
self.max_retries = max_retries
self.stats = {"total": 0, "succes": 0, "erreurs": 0}
def traiter_document(self, chemin: str) -> ResultatTraitement:
"""Procesa un documento con reintentos y supervisión."""
debut = time.time()
self.stats["total"] += 1
for tentative in range(self.max_retries):
try:
# Leer y codificar
with open(chemin, "rb") as f:
doc_b64 = base64.b64encode(f.read()).decode("utf-8")
# Parámetros de llamada
params = {
"model": "mistral-ocr-latest",
"document": {
"type": "document_url",
"document_url": f"data:application/pdf;base64,{doc_b64}"
},
"table_format": self.table_format,
}
if self.schema_annotation:
params["document_annotation_format"] = (
response_format_from_pydantic_model(
self.schema_annotation
)
)
# Llamada OCR
response = client.ocr.process(**params)
# Extraer texto
texte = "\n\n".join(
p.markdown for p in response.pages
)
# Extraer anotaciones
annotations = None
if self.schema_annotation:
if response.document_annotation:
annotations = response.document_annotation
duree = time.time() - debut
self.stats["succes"] += 1
logger.info(
f"OK: {chemin} ({len(response.pages)} páginas, "
f"{duree:.1f}s)"
)
return ResultatTraitement(
fichier=chemin,
pages=len(response.pages),
texte=texte,
annotations=annotations,
duree_secondes=duree,
)
except Exception as e:
logger.warning(
f"Intento {tentative + 1}/{self.max_retries} "
f"fallido para {chemin}: {e}"
)
if tentative < self.max_retries - 1:
time.sleep(2 ** tentative) # Retroceso exponencial
# Todos los intentos fallaron
self.stats["erreurs"] += 1
return ResultatTraitement(
fichier=chemin,
duree_secondes=time.time() - debut,
erreur="Fallo tras todos los intentos",
)
def traiter_dossier(self, dossier: str) -> list[ResultatTraitement]:
"""Procesa todos los PDFs en una carpeta."""
chemin = Path(dossier)
fichiers = sorted(chemin.glob("*.pdf"))
resultats = []
for fichier in fichiers:
resultat = self.traiter_document(str(fichier))
resultats.append(resultat)
return resultats
def rapport(self) -> str:
"""Genera un informe de procesamiento."""
return (
f"Documentos procesados: {self.stats['total']}\n"
f"Éxitos: {self.stats['succes']}\n"
f"Errores: {self.stats['erreurs']}\n"
f"Tasa de éxito: "
f"{self.stats['succes']/max(self.stats['total'],1)*100:.1f}%"
)
En la práctica, la misma clase cubre ambas necesidades: instanciada sin un esquema, simplemente extrae texto; instanciada con un modelo Pydantic, también produce datos estructurados.
# Canalización simple (solo OCR)
pipeline = PipelineDocumentAI(table_format="markdown")
resultats = pipeline.traiter_dossier("./factures/")
print(pipeline.rapport())
# Canalización con anotaciones
from pydantic import BaseModel, Field
class ExtractionFacture(BaseModel):
fournisseur: str = Field(..., description="Nombre del proveedor")
montant_ttc: float = Field(..., description="Importe con IVA")
date: str = Field(..., description="Fecha (AAAA-MM-DD)")
pipeline_annote = PipelineDocumentAI(
schema_annotation=ExtractionFacture,
table_format="markdown"
)
resultats = pipeline_annote.traiter_dossier("./factures/")
Anticipar la factura
El control de costes es esencial en producción, y comienza por entender qué se te factura.
| Elemento | Base de facturación |
|---|---|
| OCR | Por página procesada |
| Anotaciones | Incluidas en la llamada OCR (sin coste adicional) |
| QnA | Tokens de entrada/salida basados en el modelo de chat |
| Embeddings | Tokens de entrada |
El hecho de que las anotaciones no tengan coste adicional cambia el diseño: extrae los metadatos durante la pasada de OCR en lugar de ejecutar una llamada LLM separada después. La función de estimación siguiente te permite tarificar un proyecto antes de lanzarlo; sus tarifas son cifras de orden de magnitud para ajustar, siendo la tabla de referencia publicada por Mistral la autoridad definitiva.
def estimer_cout(
nombre_pages: int,
avec_qna: bool = False,
modele_qna: str = "mistral-small-latest"
) -> dict:
"""Estima el coste de procesamiento."""
# Tarifas aproximadas (comprueba las tarifas actuales)
cout_ocr_par_page = 0.001 # Ajustar según el nivel
cout_qna_par_1k_tokens = {
"mistral-small-latest": 0.001,
"mistral-large-latest": 0.008,
}
cout_ocr = nombre_pages * cout_ocr_par_page
cout_qna = 0.0
if avec_qna:
# Estimación: ~500 tokens por página de media
tokens_estimes = nombre_pages * 500
cout_qna = (
tokens_estimes / 1000
* cout_qna_par_1k_tokens.get(modele_qna, 0.001)
)
return {
"cout_ocr": round(cout_ocr, 4),
"cout_qna": round(cout_qna, 4),
"cout_total": round(cout_ocr + cout_qna, 4),
}
Supervisar la salud del servicio
Una canalización se degrada lenta y silenciosamente: un nuevo proveedor envía escaneos de baja calidad, la tasa de error sube del 2 % al 15 %, y nadie se da cuenta hasta el cierre mensual. Cuatro métricas bastan para detectar la deriva —volumen procesado, duración media, tasa de error y coste estimado—, siempre que las emitas sistemáticamente y las envíes a tu herramienta habitual, ya sea Datadog, Prometheus u otra.
import json
from datetime import datetime
def log_metrique(nom: str, valeur: float, tags: dict = None) -> None:
"""Registra una métrica de supervisión."""
metrique = {
"timestamp": datetime.utcnow().isoformat(),
"nom": nom,
"valeur": valeur,
"tags": tags or {}
}
# En producción: enviar a Datadog, Prometheus, etc.
logger.info(f"METRIQUE: {json.dumps(metrique)}")
# Ejemplo de métricas a seguir
log_metrique("ocr.pages_traitees", 150, {"batch": "factures_mars"})
log_metrique("ocr.duree_moyenne_secondes", 2.3)
log_metrique("ocr.taux_erreur", 0.02)
log_metrique("ocr.cout_estime_usd", 0.15)
Hacia dónde ir a continuación
Ahora tienes las bases para construir un sistema completo de Document AI, y se abren varias extensiones dependiendo de tus restricciones. Volúmenes muy altos justifican un despliegue local del modelo OCR en una GPU dedicada; documentos muy específicos de tu negocio pueden motivar un ajuste fino (fine-tuning), un tema que debes abordar directamente con Mistral. En el lado de la integración, el reto es conectar la canalización con tus sistemas existentes —ERP, CRM— y construir un panel de control para que tus equipos puedan consultar documentos por sí mismos sin pasar por ti. El paso final es eliminar el desencadenamiento manual: la canalización se ejecuta automáticamente cuando llegan nuevos documentos.
Resumen del curso
Estas dieciséis lecciones te han llevado a través de todo el ciclo. Comenzaste con los fundamentos —qué es Document AI, el modelo OCR 4 y casos de uso— antes de pasar al OCR avanzado con la API, extracción de tablas, cabeceras/pies de página y optimización. Las anotaciones te dieron luego extracción estructurada, procesamiento por lotes y control de cumplimiento, seguidas de Document QnA, que abrió la consulta en lenguaje natural, desde documentos aislados hasta corpus indexados en RAG. Ahora tienes los bloques de construcción necesarios para equipar la gestión documental de tu organización con Mistral Document AI.
Puntos clave
- Una canalización de producción incluye reintentos, registro, supervisión y gestión de costes.
- El retroceso exponencial protege contra errores transitorios de la API.
- Estima tus costes antes de escalar (OCR por página, QnA por token).
- La supervisión continua permite detectar degradación del rendimiento.
- Document AI cubre todo el ciclo de vida del documento, desde la ingesta hasta la operación.
Pon a prueba tus conocimientos
OCR, anotaciones, QnA: valida la cadena documental completa.
1. ¿Qué produce la API OCR de Mistral a partir de un documento?
Respuesta: El contenido estructurado del documento —texto, tablas, diseño— listo para uso programático: OCR 4 lee el documento como una fuente de datos, no como una imagen.
2. ¿Cuál es el propósito de la API de Anotaciones?
Respuesta: Extraer metadatos estructurados según tu esquema (campos de factura, cláusulas de contrato), ya sea individualmente o por lotes para grandes volúmenes.
3. ¿Qué permite Document QnA?
Respuesta: Hacer preguntas en lenguaje natural sobre uno o más documentos y obtener respuestas basadas en su contenido: la capa conversacional sobre la extracción.
4. ¿Cómo optimizas la precisión del OCR?
Respuesta: Mediante la calidad de entrada (resolución, nitidez, orientación) y el manejo de áreas difíciles —cabeceras, pies de página, paginación—, que el curso te enseña a gestionar explícitamente.
5. ¿Por qué combinar OCR y RAG?
Respuesta: El OCR transforma documentos escaneados en texto indexable, mientras que RAG los hace consultables a escala: juntos, permiten la búsqueda semántica en archivos completos.
Extracción, anotación, pregunta y respuesta, indexación: la canalización de producción anterior encadena las cuatro; tu papeleo se convierte en una base de datos.