Extraer metadatos estructurados
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 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 · Preguntas y respuestas sobre documentos. 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.
Extrae exactamente lo que necesitas
La anotación de documentos no consiste solo en recuperar texto sin formato. Produce datos estructurados, tipados y validados, listos para su uso inmediato en tus sistemas: una fila insertada en una base de datos, un campo comparado con una referencia o un importe verificado antes del pago. El desafío cambia por completo al diseño del esquema, que es el foco de esta lección.
Estructura en lugar de aplanar
Un esquema de extracción debe reflejar la realidad del documento. Una factura proviene de una entidad legal con un nombre de empresa, un número SIRET (identificador empresarial francés) y una dirección. En lugar de alinear ocho campos como emetteur_rue, emetteur_ville, emetteur_siret, define un modelo Address y luego un modelo LegalEntity que lo contenga. Reutiliza estos bloques de construcción tanto para el emisor como para el destinatario. La enumeración DocumentType desempeña un papel similar: evita que el modelo invente una categoría y garantiza un valor que puedes usar en una sentencia if o para el enrutamiento. Los campos Optional indican explícitamente qué puede estar ausente, mientras que los valores por defecto, como default="France" para el país, evitan que el modelo tenga que adivinar lo obvio.
from pydantic import BaseModel, Field
from typing import Optional
from enum import Enum
class DocumentType(str, Enum):
INVOICE = "facture"
CONTRACT = "contrat"
REPORT = "rapport"
FORM = "formulaire"
OTHER = "autre"
class Address(BaseModel):
street: Optional[str] = Field(None, description="Número y calle")
postal_code: Optional[str] = Field(None, description="Código postal")
city: Optional[str] = Field(None, description="Ciudad")
country: str = Field(default="France", description="País")
class LegalEntity(BaseModel):
name: str = Field(..., description="Razón social")
siret: Optional[str] = Field(None, description="Número SIRET")
address: Optional[Address] = Field(None, description="Dirección postal")
email: Optional[str] = Field(None, description="Dirección de correo electrónico")
class DocumentExtraction(BaseModel):
document_type: DocumentType = Field(
..., description="Tipo de documento"
)
date: Optional[str] = Field(
None, description="Fecha principal (YYYY-MM-DD)"
)
emetteur: LegalEntity = Field(
..., description="Entidad que emite el documento"
)
destinataire: Optional[LegalEntity] = Field(
None, description="Entidad destinataria"
)
resume: str = Field(
..., description="Resumen en 2-3 frases del contenido"
)
langue: str = Field(
..., description="Idioma del documento (código ISO 639-1)"
)
Datos repetidos
Muchos documentos contienen series: líneas de facturación, cláusulas o conceptos de gastos. Modela estos datos como una list[...] de un submodelo dedicado. El modelo escanea entonces la tabla del documento y produce tantos objetos InvoiceLine como filas encuentre, incluyendo la descripción, la cantidad, el precio unitario y el total de cada una. Esto te proporciona suficientes datos para recalcular tú mismo el subtotal y verificar la coherencia del documento antes de aceptarlo.
from pydantic import BaseModel, Field
class InvoiceLine(BaseModel):
description: str = Field(..., description="Descripción del producto/servicio")
quantity: float = Field(..., description="Cantidad")
unit_price: float = Field(..., description="Precio unitario sin impuestos")
amount: float = Field(..., description="Importe total sin impuestos de la línea")
class DetailedInvoice(BaseModel):
supplier: str = Field(..., description="Nombre del proveedor")
number: str = Field(..., description="Número de factura")
date: str = Field(..., description="Fecha (YYYY-MM-DD)")
lines: list[InvoiceLine] = Field(
..., description="Líneas de la factura"
)
subtotal_excl_tax: float = Field(..., description="Subtotal sin impuestos")
vat: float = Field(..., description="Importe del IVA")
total_incl_tax: float = Field(..., description="Total con impuestos")
payment_terms: str = Field(
..., description="Condiciones de pago mencionadas"
)
Casillas de verificación y formularios
Los formularios en papel escaneados son donde el modelo brilla. Un campo bool emparejado con la etiqueta de la pregunta es suficiente: el modelo reconoce si una casilla está marcada, extrae la pregunta correspondiente y, lo que es crucial para el uso médico o administrativo, infiere que falta un campo en lugar de inventar un valor, tal como demostró el equipo de Mistral. La nota “null if not provided” (nulo si no se proporciona) en la descripción del número de teléfono no es decorativa; autoriza explícitamente un valor vacío.
from pydantic import BaseModel, Field
class FormResponse(BaseModel):
question: str = Field(..., description="Enunciado de la pregunta")
answer: bool = Field(..., description="True si está marcado, False en caso contrario")
class MedicalForm(BaseModel):
patient_name: str = Field(..., description="Nombre completo del paciente")
age: Optional[int] = Field(None, description="Edad del paciente")
sex: Optional[str] = Field(None, description="Sexo (M/F)")
patient_id: Optional[str] = Field(None, description="ID del paciente")
phone: Optional[str] = Field(
None, description="Número de teléfono (null si no se proporciona)"
)
responses: list[FormResponse] = Field(
..., description="Respuestas a las preguntas del formulario"
)
Implementación de extremo a extremo
Toma el ejemplo de la factura detallada y conéctalo a un documento codificado en base64. El prompt de anotación complementa el esquema especificando el tipo de archivo y haciendo hincapié en la atención a las líneas de facturación; la validación de Pydantic al retorno convierte la cadena JSON en un objeto que puedes recorrer de forma segura.
import os
import json
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": f"data:application/pdf;base64,{document_base64}"
},
document_annotation_format=response_format_from_pydantic_model(
DetailedInvoice
),
document_annotation_prompt=(
"Este documento es una factura. Extrae todas las líneas "
"de facturación con sus importes."
)
)
# Extracción y validación
if ocr_response.document_annotation:
invoice = DetailedInvoice.model_validate_json(
ocr_response.document_annotation
)
print(f"Factura {invoice.number} - {invoice.supplier}")
print(f"Fecha : {invoice.date}")
print(f"\nLíneas :")
for line in invoice.lines:
print(f" - {line.description}: {line.quantity} x "
f"{line.unit_price}€ = {line.amount}€")
print(f"\nTotal con impuestos : {invoice.total_incl_tax}€")
Los resultados de extracción deficientes casi siempre provienen del esquema, rara vez del modelo. Revisa tus descripciones una por una: deben ser precisas y no ambiguas, ya que el modelo depende únicamente de ellas para entender tus expectativas. Escríbelas en el idioma de tus documentos (el francés funciona perfectamente para facturas francesas) y reserva las enumeraciones para campos con valores limitados y los submodelos para estructuras que vayas a reutilizar en varios esquemas.
Puntos clave
- Los esquemas de Pydantic permiten la extracción de datos tipados y validados
- Utiliza tipos complejos (listas, enumeraciones, modelos anidados) para extracciones precisas
- El modelo gestiona campos opcionales y casillas de verificación de forma fiable
- Las descripciones de los campos guían la extracción: sé preciso y explícito
- Combina
document_annotation_promptcon el esquema para obtener el máximo contexto