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

La API de anotaciones

Lección 9 de 16 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Más allá de la extracción de texto
  2. Dos niveles de análisis
  3. El esquema Pydantic actúa como contrato
  4. Anotar un documento completo
  5. Describir elementos visuales uno a uno
  6. Guiar la extracción con un prompt
  7. Puntos clave

Actualizado el 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 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. Addenda del 3 de noviembre: El ejemplo anterior leía page.document_annotation en cada página; en el SDK mistralai 3.7.0, este campo pertenece a la respuesta OCR (ocr_response.document_annotation), mientras que las páginas contienen solo su contenido e imágenes; las anotaciones de imagen se leen desde image.image_annotation.

Más allá de la extracción de texto

El OCR te proporciona texto crudo: fiel y completo, pero indiferenciado. Obtienes Markdown, no datos. Las anotaciones dan el siguiente paso: extraen datos estructurados de tus documentos basándose en un esquema que defines de antemano. Describes qué estás buscando, el modelo lo extrae automáticamente y tu aplicación recibe campos tipados en lugar de un muro de texto que debas analizar con expresiones regulares.

Dos niveles de análisis

Document AI distingue entre dos tipos de anotaciones según la escala a la que operan.

Las anotaciones de cuadro delimitador (bbox_annotation) se centran en las imágenes y gráficos que el OCR ha aislado. El modelo de visión procesa cada cuadro delimitador individualmente para describir su contenido. En un informe anual, este mecanismo te permite describir gráficos y diagramas, clasificar imágenes (fotografía, logotipo, esquema, gráfica) y extraer contenido textual de imágenes incrustadas: tres piezas de información que la extracción de texto estándar pasa por alto sistemáticamente.

Las anotaciones de documento (document_annotation) tratan el archivo como un todo. El modelo analiza el Markdown extraído junto con las primeras ocho imágenes y devuelve lo que has solicitado: campos estructurados como un nombre, una fecha o un importe; el tipo de documento; un resumen del contenido; o una respuesta a una pregunta específica. Esta es la herramienta para el procesamiento por lotes, la que integrarás en tus flujos de trabajo de facturas, formularios y contratos.

El esquema Pydantic actúa como contrato

Las anotaciones dependen de modelos Pydantic para definir la estructura de salida. Cada atributo se convierte en un campo que extraer, y su description sirve como instrucción para el modelo: tiene tanto peso como el propio nombre del campo.

from pydantic import BaseModel, Field
from typing import Optional

class InvoiceExtraction(BaseModel):
    vendor: str = Field(..., description="Vendor name")
    invoice_number: str = Field(..., description="Invoice number")
    issue_date: str = Field(..., description="Issue date (YYYY-MM-DD)")
    amount_excl_tax: float = Field(..., description="Amount excluding tax")
    amount_incl_tax: float = Field(..., description="Amount including tax")
    currency: str = Field(default="EUR", description="Currency (ISO code)")

Anotar un documento completo

La llamada sigue siendo la misma que para el OCR: simplemente añades el parámetro document_annotation_format, poblado mediante response_format_from_pydantic_model(), que traduce tu modelo a un esquema que la API puede utilizar. Al retornar, la anotación llega como una cadena JSON, que vuelves a validar con Pydantic para obtener un objeto Python seguro.

import os
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 InvoiceExtraction(BaseModel):
    vendor: str = Field(..., description="Vendor name")
    invoice_number: str = Field(..., description="Invoice number")
    issue_date: str = Field(..., description="Issue date (YYYY-MM-DD)")
    amount_excl_tax: float = Field(..., description="Amount excluding tax")
    amount_incl_tax: float = Field(..., description="Amount including tax")

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://example.com/invoice.pdf"
    },
    document_annotation_format=response_format_from_pydantic_model(
        InvoiceExtraction
    )
)

# La anotación del documento la lleva la respuesta, no cada página
if ocr_response.document_annotation:
    invoice = InvoiceExtraction.model_validate_json(
        ocr_response.document_annotation
    )
    print(f"Vendor: {invoice.vendor}")
    print(f"Amount incl. tax: {invoice.amount_incl_tax}")

Describir elementos visuales uno a uno

Para las imágenes, el principio es idéntico pero el parámetro cambia, y los resultados se leen desde page.images en lugar de desde la página en sí. Ten en cuenta include_image_base64=True: sin ello, pierdes los elementos visuales que el modelo acaba de describir.

from pydantic import BaseModel, Field
from mistralai.extra import response_format_from_pydantic_model

class ImageDescription(BaseModel):
    image_type: str = Field(
        ..., description="Type: graph, table, photo, logo, schematic"
    )
    description: str = Field(
        ..., description="Short description of the image in English"
    )
    relevant_content: str = Field(
        ..., description="Summary of the informative content of the image"
    )

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://example.com/report.pdf"
    },
    bbox_annotation_format=response_format_from_pydantic_model(
        ImageDescription
    ),
    include_image_base64=True
)

# Acceso a las anotaciones de imagen
for page in ocr_response.pages:
    for image in page.images:
        if image.image_annotation:
            desc = ImageDescription.model_validate_json(image.image_annotation)
            print(f"Image {image.id}: {desc.image_type}")
            print(f"  Description: {desc.description}")

Nada te obliga a elegir entre ambas opciones: en un informe ilustrado, generalmente querrás tanto los metadatos del documento como la descripción de sus gráficos, algo que una única llamada cubre pasando ambos formatos.

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://example.com/report.pdf"
    },
    bbox_annotation_format=response_format_from_pydantic_model(
        ImageDescription
    ),
    document_annotation_format=response_format_from_pydantic_model(
        InvoiceExtraction
    ),
    include_image_base64=True
)

Guiar la extracción con un prompt

Un esquema describe la forma esperada, no el contexto del documento. Cuando tus campos son ambiguos —múltiples fechas, múltiples importes, dos secciones similares—, document_annotation_prompt ayuda a resolver la duda indicando al modelo la naturaleza del documento y qué debe priorizar. En un contrato mercantil francés, esta frase de encuadre suele marcar la diferencia entre una extracción usable y un relleno aproximado.

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://example.com/contract.pdf"
    },
    document_annotation_format=response_format_from_pydantic_model(
        ContractExtraction
    ),
    document_annotation_prompt=(
        "This document is a French commercial contract. "
        "Extract information about the contracting parties, "
        "the contract duration, and the main clauses."
    )
)

Puntos clave

  • Dos tipos de anotaciones: bbox_annotation para imágenes, document_annotation para todo el documento
  • Los esquemas Pydantic definen la estructura de los datos a extraer
  • Usa response_format_from_pydantic_model() para convertir el esquema
  • El document_annotation_prompt guía la extracción con instrucciones contextuales
  • Ambos tipos pueden combinarse en una única llamada