API d'annotations
Šiame puslapyje
Mis à jour le 2 novembre 2026 — OCR. OCR 4.0 (
mistral-ocr-4-0) a été retiré le 30 septembre 2026. Utilise OCR 4.1 (mistral-ocr-4-1), disponible depuis le 31 août au même tarif, ou l’aliasmistral-ocr-latestqui le cible depuis le 16 juillet. OCR 4.1 ajoute des scores de confiance au niveau des blocs. Addendum du 3 novembre : L’exemple précédent lisaitpage.document_annotationsur chaque page ; dans le SDKmistralai3.7.0, ce champ appartient à la réponse OCR (ocr_response.document_annotation), tandis que les pages ne contiennent que leur contenu et leurs images ; les annotations d’image se lisent viaimage.image_annotation.
Au-delà de l’extraction de texte
L’OCR te fournit du texte brut : fidèle et complet, mais indifférencié. Tu obtiens du Markdown, pas des données structurées. Les annotations franchissent l’étape suivante : elles extraient des données structurées de tes documents selon un schéma que tu définis à l’avance. Tu décris ce que tu cherches, le modèle l’extrait automatiquement, et ton application reçoit des champs typés au lieu d’un mur de texte à analyser avec des expressions régulières.
Deux niveaux d’analyse
Document AI distingue deux types d’annotations selon l’échelle à laquelle elles opèrent.
Les annotations de zone de délimitation (bbox_annotation) se concentrent sur les images et graphiques que l’OCR a isolés. Le modèle de vision traite chaque zone individuellement pour décrire son contenu. Dans un rapport annuel, ce mécanisme te permet de décrire des graphiques et des diagrammes, de classifier des images (photo, logo, schéma, graphique) et d’extraire le contenu textuel des images intégrées — trois informations que l’extraction de texte standard ignore systématiquement.
Les annotations de document (document_annotation) traitent le fichier dans son ensemble. Le modèle analyse le Markdown extrait ainsi que les huit premières images, puis renvoie ce que tu as demandé : des champs structurés comme un nom, une date ou un montant ; le type de document ; un résumé du contenu ; ou une réponse à une question précise. C’est l’outil idéal pour le traitement en masse, celui que tu intégreras à tes flux de travail de factures, de formulaires et de contrats.
Le schéma Pydantic agit comme un contrat
Les annotations s’appuient sur des 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 a autant de poids que le nom du champ lui-même.
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)")
Annoter un document entier
L’appel reste identique à celui de l’OCR : tu ajoutes simplement le paramètre document_annotation_format, rempli par response_format_from_pydantic_model(), qui traduit ton modèle en un schéma utilisable par l’API. Au retour, l’annotation arrive sous forme de chaîne JSON, que tu revalides avec Pydantic pour obtenir un objet Python sécurisé.
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
)
)
# L'annotation du document est portée par la réponse, pas par chaque page
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}")
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 depuis page.images plutôt que depuis la page elle-même. Note include_image_base64=True : sans cela, tu perds 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 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
)
# Accès aux annotations d'image
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}")
Rien ne t’oblige à choisir entre les deux : sur un rapport illustré, tu voudras généralement à la fois les métadonnées du document et la description de ses graphiques, ce qu’un seul appel permet de couvrir en passant les deux formats.
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
)
Guider l’extraction avec une invite (prompt)
Un schéma décrit la forme attendue, pas le contexte du document. Lorsque tes champs sont ambigus — plusieurs dates, plusieurs montants, deux sections similaires — document_annotation_prompt aide à lever le doute en indiquant au modèle la nature du document et ce qu’il doit prioriser. 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://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."
)
)
Svarbiausi punktai
- Deux types d’annotations :
bbox_annotationpour les images,document_annotationpour le document entier - Les schémas Pydantic définissent la structure des données à extraire
- Utilise
response_format_from_pydantic_model()pour convertir le schéma - Le
document_annotation_promptguide l’extraction avec des instructions contextuelles - Les deux types peuvent être combinés dans un seul appel