Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

API d'annotations

Nodarbība 9 no 16 Atjaunota 2026. gada 3. novembris Programmētājs
Šajā lapā
  1. Au-delà de l’extraction de texte
  2. Deux niveaux d’analyse
  3. Le schéma Pydantic fait office de contrat
  4. Annoter un document entier
  5. Décrire les visuels un par un
  6. Guider l’extraction avec un prompt
  7. Galvenās atziņas

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’alias mistral-ocr-latest qui 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 lisait page.document_annotation sur chaque page ; dans le SDK mistralai 3.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 via image.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. 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 à parser 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 boîte englobante (bbox_annotation) se concentrent sur les images et graphiques que l’OCR a isolés. Le modèle de vision traite chaque boîte englobante individuellement pour décrire son contenu. Dans un rapport annuel, ce mécanisme te permet de décrire des graphiques et diagrammes, de classer des images (photo, logo, schéma, graphe) 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 pour le traitement en masse, celui que tu brancheras sur tes flux de factures, formulaires et contrats.

Le schéma Pydantic fait office de 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 pèse autant 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, peuplé 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ûr.

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 couvre 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 un 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."
    )
)

Galvenās atziņas

  • 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
  • Utilise 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