Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

De Annotations API

Les 9 van 16 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Meer dan alleen tekstextractie
  2. Twee analyse-niveaus
  3. Het Pydantic-schema als contract
  4. Een volledig document annoteren
  5. Visuals één voor één beschrijven
  6. Extractie sturen met een prompt
  7. Belangrijkste punten

Bijgewerkt op 2 november 2026 — OCR. OCR 4.0 (mistral-ocr-4-0) is op 30 september 2026 buiten gebruik gesteld. Gebruik OCR 4.1 (mistral-ocr-4-1), dat sinds 31 augustus algemeen beschikbaar is tegen dezelfde prijs, of het alias mistral-ocr-latest, dat sinds 16 juli daarnaar verwijst. OCR 4.1 voegt betrouwbaarheidsscores toe op blokniveau. Addendum van 3 november: Het vorige voorbeeld las page.document_annotation op elke pagina; in mistralai SDK 3.7.0 behoort dit veld tot het OCR-antwoord (ocr_response.document_annotation), terwijl pagina’s alleen hun inhoud en afbeeldingen bevatten; afbeeldingsannotaties leest u uit image.image_annotation.

Meer dan alleen tekstextractie

OCR levert u ruwe tekst: getrouw en compleet, maar ongeordend. U krijgt Markdown, geen gestructureerde data. Annotaties zetten de volgende stap: ze halen gestructureerde gegevens uit uw documenten op basis van een schema dat u vooraf definieert. U beschrijft wat u zoekt, het model haalt het automatisch op, en uw applicatie ontvangt getypte velden in plaats van een muur van tekst die u met reguliere expressies moet parseren.

Twee analyse-niveaus

Document AI maakt onderscheid tussen twee soorten annotaties, afhankelijk van de schaal waarop ze opereren.

Bounding box-annotaties (bbox_annotation) richten zich op de afbeeldingen en grafieken die OCR heeft geïsoleerd. Het visiemodel verwerkt elke bounding box individueel om de inhoud te beschrijven. In een jaarverslag stelt dit mechanisme u in staat grafieken en diagrammen te beschrijven, afbeeldingen te classificeren (foto, logo, schema, grafiek) en tekstuele inhoud uit ingesloten afbeeldingen te extraheren—drie informatiepunten die standaard tekstextractie systematisch over het hoofd ziet.

Documentannotaties (document_annotation) behandelen het bestand als geheel. Het model analyseert de geëxtraheerde Markdown samen met de eerste acht afbeeldingen en retourneert vervolgens wat u hebt gevraagd: gestructureerde velden zoals een naam, datum of bedrag; het documenttype; een inhoudssamenvatting; of een antwoord op een specifieke vraag. Dit is het instrument voor bulkverwerking, dat u integreert in uw workflows voor facturen, formulieren en contracten.

Het Pydantic-schema als contract

Annotaties vertrouwen op Pydantic-modellen om de uitvoerstructuur te definiëren. Elk attribuut wordt een te extraheren veld, en de description dient als instructie voor het model: deze heeft evenveel gewicht als de veldnaam zelf.

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

Een volledig document annoteren

De aanroep blijft hetzelfde als bij OCR: u voegt eenvoudig de parameter document_annotation_format toe, gevuld met response_format_from_pydantic_model(), die uw model vertaalt naar een schema dat de API kan gebruiken. Bij terugkeer komt de annotatie aan als een JSON-tekenreeks, die u opnieuw valideert met Pydantic om een veilig Python-object te verkrijgen.

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

# De documentannotatie wordt door het antwoord gedragen, niet door elke pagina
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}")

Visuals één voor één beschrijven

Voor afbeeldingen is het principe identiek, maar de parameter verandert en de resultaten worden gelezen uit page.images in plaats van de pagina zelf. Let op include_image_base64=True: zonder dit verliest u de visuals die het model zojuist heeft beschreven.

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
)

# Toegang tot afbeeldingsannotaties
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}")

Niets dwingt u om tussen de twee te kiezen: bij een geïllustreerd rapport wilt u doorgaans zowel de documentmetadata als de beschrijving van de grafieken, wat een enkele aanroep dekt door beide formaten door te geven.

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
)

Extractie sturen met een prompt

Een schema beschrijft de verwachte vorm, niet de context van het document. Wanneer uw velden dubbelzinnig zijn—meerdere datums, meerdere bedragen, twee vergelijkbare secties—helpt document_annotation_prompt de twijfel op te lossen door het model de aard van het document en de prioriteiten mee te geven. Bij een Frans handelscontract maakt deze kaderstellende zin vaak het verschil tussen bruikbare extractie en een benaderende invulling.

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

Belangrijkste punten

  • Twee soorten annotaties: bbox_annotation voor afbeeldingen, document_annotation voor het volledige document
  • Pydantic-schema’s definiëren de structuur van de te extraheren gegevens
  • Gebruik response_format_from_pydantic_model() om het schema om te zetten
  • De document_annotation_prompt stuurt de extractie met contextuele instructies
  • Beide typen kunnen in één aanroep worden gecombineerd