L'API Annotations

Au-delà de l’extraction de texte

L’OCR vous restitue le texte brut : fidèle, complet, mais indifférencié. Vous récupérez du Markdown, pas des données. Les Annotations franchissent l’étape suivante : elles extraient des données structurées depuis vos documents à partir d’un schéma que vous définissez à l’avance. Vous décrivez ce que vous cherchez, le modèle l’extrait automatiquement, et votre application reçoit des champs typés au lieu d’un mur de texte à découper à coups d’expressions régulières.

Deux niveaux de lecture

Document AI distingue deux annotations selon l’échelle à laquelle elles travaillent.

L’annotation par bounding box (bbox_annotation) porte sur les images et graphiques que l’OCR a détourés. Le modèle de vision traite chaque bounding box individuellement pour décrire son contenu. Sur un rapport annuel, c’est ce mécanisme qui vous permet de décrire les graphiques et diagrammes, de classifier les images (photo, logo, schéma, graphique) et d’extraire le contenu textuel des images intégrées — trois informations qu’une extraction de texte classique laisse systématiquement de côté.

L’annotation de document (document_annotation) prend le fichier dans son ensemble. Le modèle analyse le Markdown extrait ainsi que les 8 premières images, puis restitue ce que vous lui demandez : des champs structurés comme un nom, une date ou un montant, le type de document, un résumé du contenu, ou la réponse à une question précise. C’est l’instrument du traitement de masse, celui que vous brancherez sur vos flux de factures, de formulaires et de contrats.

Le schéma Pydantic tient lieu de contrat

Les annotations s’appuient sur les modèles Pydantic pour définir la structure de sortie. Chaque attribut devient un champ à extraire, et sa description sert d’instruction au modèle : elle vaut autant que le nom du champ lui-même.

from pydantic import BaseModel, Field
from typing import Optional

class ExtractionFacture(BaseModel):
    fournisseur: str = Field(..., description="Nom du fournisseur")
    numero_facture: str = Field(..., description="Numéro de la facture")
    date_emission: str = Field(..., description="Date d'émission (YYYY-MM-DD)")
    montant_ht: float = Field(..., description="Montant hors taxes")
    montant_ttc: float = Field(..., description="Montant TTC")
    devise: str = Field(default="EUR", description="Devise (code ISO)")

Annoter un document entier

L’appel reste celui de l’OCR : vous ajoutez simplement le paramètre document_annotation_format, alimenté par response_format_from_pydantic_model() qui traduit votre modèle en schéma exploitable par l’API. Au retour, l’annotation arrive sous forme de chaîne JSON, que vous revalidez avec Pydantic pour obtenir un objet Python sûr.

import os
from mistralai 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="Nom du fournisseur")
    numero_facture: str = Field(..., description="Numéro de la facture")
    date_emission: str = Field(..., description="Date d'émission (YYYY-MM-DD)")
    montant_ht: float = Field(..., description="Montant hors taxes")
    montant_ttc: float = Field(..., description="Montant TTC")

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

# Accéder aux annotations
for page in ocr_response.pages:
    if page.document_annotation:
        facture = ExtractionFacture.model_validate_json(
            page.document_annotation
        )
        print(f"Fournisseur : {facture.fournisseur}")
        print(f"Montant TTC : {facture.montant_ttc}")

Décrire les visuels un par un

Pour les images, le principe est identique mais le paramètre change et les résultats se lisent dans page.images plutôt que sur la page. Notez include_image_base64=True : sans lui, vous perdez les visuels que le modèle vient de décrire.

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

class DescriptionImage(BaseModel):
    type_image: str = Field(
        ..., description="Type: graph, table, photo, logo, schema"
    )
    description: str = Field(
        ..., description="Description courte de l'image en français"
    )
    contenu_pertinent: str = Field(
        ..., description="Résumé du contenu informatif de l'image"
    )

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

# Accéder aux annotations des images
for page in ocr_response.pages:
    for image in page.images:
        if image.annotation:
            desc = DescriptionImage.model_validate_json(image.annotation)
            print(f"Image {image.id}: {desc.type_image}")
            print(f"  Description: {desc.description}")

Rien n’oblige à choisir entre les deux : sur un rapport illustré, vous voudrez généralement les métadonnées du document et la description de ses graphiques, ce qu’un seul appel couvre en passant les deux formats.

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://exemple.com/rapport.pdf"
    },
    bbox_annotation_format=response_format_from_pydantic_model(
        DescriptionImage
    ),
    document_annotation_format=response_format_from_pydantic_model(
        ExtractionFacture
    ),
    include_image_base64=True
)

Guider l’extraction par un prompt

Un schéma décrit la forme attendue, pas le contexte du document. Quand vos champs sont ambigus — plusieurs dates, plusieurs montants, deux parties qui se ressemblent — document_annotation_prompt sert à lever le doute en donnant au modèle la nature du document et ce qu’il doit privilégier. Sur un contrat commercial français, cette phrase de cadrage fait souvent la différence entre une extraction exploitable et un remplissage approximatif.

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://exemple.com/contrat.pdf"
    },
    document_annotation_format=response_format_from_pydantic_model(
        ExtractionContrat
    ),
    document_annotation_prompt=(
        "Ce document est un contrat commercial français. "
        "Extrais les informations des parties contractantes, "
        "la durée du contrat et les clauses principales."
    )
)

Points clés à retenir

• Deux types d’annotations : bbox_annotation pour les images, document_annotation pour le document entier
• Les schémas Pydantic définissent la structure des données à extraire
• Utilisez response_format_from_pydantic_model() pour convertir le schéma
• Le document_annotation_prompt guide l’extraction avec des instructions contextuelles
• Les deux types peuvent être combinés dans un seul appel