L'API Annotations

Au-delà de l’extraction de texte

L’OCR extrait le texte brut. Les Annotations vont plus loin : elles permettent d’extraire des données structurées depuis vos documents en définissant un schéma de données précis. Vous décrivez ce que vous cherchez, et le modèle l’extrait automatiquement.

Deux types d’annotations

1. Annotation par bounding box (bbox_annotation)

Annote les images et graphiques extraits par l’OCR. Le modèle de vision traite chaque bounding box individuellement pour décrire son contenu.

Cas d’usage :

• Décrire les graphiques et diagrammes
• Classifier les images (photo, logo, schéma, graphique)
• Extraire le contenu textuel des images intégrées

2. Annotation de document (document_annotation)

Annote le document dans son ensemble. Le modèle analyse le Markdown extrait et les 8 premières images pour extraire les informations demandées.

Cas d’usage :

• Extraire des champs structurés (nom, date, montant)
• Classifier le type de document
• Résumer le contenu
• Répondre à des questions spécifiques

Définir un schéma avec Pydantic

Les annotations utilisent les modèles Pydantic pour définir la structure de sortie :

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)")

Appel API avec annotations de document

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}")

Appel API avec annotations bounding box

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}")

Combiner les deux types d’annotations

Vous pouvez utiliser les deux simultanément :

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
)

Le paramètre document_annotation_prompt

Pour affiner l’extraction, ajoutez un prompt de guidage :

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