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

Extraer metadatos estructurados

Lección 10 de 16 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Extrae exactamente lo que necesitas
  2. Estructura en lugar de aplanar
  3. Datos repetidos
  4. Casillas de verificación y formularios
  5. Implementación de extremo a extremo
  6. Puntos clave

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 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 · Preguntas y respuestas sobre documentos. 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.

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_prompt con el esquema para obtener el máximo contexto