Die Annotations-API
Auf dieser Seite
Aktualisiert am 2. November 2026 — OCR. OCR 4.0 (
mistral-ocr-4-0) wurde am 30. September 2026 eingestellt. Nutzen Sie OCR 4.1 (mistral-ocr-4-1), der seit dem 31. August zum gleichen Preis allgemein verfügbar ist, oder den Aliasmistral-ocr-latest, der seit dem 16. Juli darauf verweist. OCR 4.1 fügt Vertrauenswerte auf Blockebene hinzu. Ergänzung vom 3. November: Das vorherige Beispiel laspage.document_annotationauf jeder Seite aus; immistralaiSDK 3.7.0 gehört dieses Feld zur OCR-Antwort (ocr_response.document_annotation), während Seiten nur ihren Inhalt und Bilder enthalten; Bildannotationen werden ausimage.image_annotationgelesen.
Über die reine Textextraktion hinaus
OCR liefert Ihnen rohen Text: treu und vollständig, aber nicht differenziert. Sie erhalten Markdown, keine Daten. Annotationen gehen einen Schritt weiter: Sie extrahieren strukturierte Daten aus Ihren Dokumenten basierend auf einem Schema, das Sie im Voraus definieren. Sie beschreiben, wonach Sie suchen, das Modell extrahiert es automatisch, und Ihre Anwendung erhält typisierte Felder statt einer Textwand, die mit regulären Ausdrücken geparst werden muss.
Zwei Ebenen der Analyse
Document AI unterscheidet zwischen zwei Arten von Annotationen basierend auf der Skala, auf der sie operieren.
Bounding-Box-Annotationen (bbox_annotation) konzentrieren sich auf die Bilder und Grafiken, die OCR isoliert hat. Das Vision-Modell verarbeitet jede Bounding Box einzeln, um ihren Inhalt zu beschreiben. In einem Jahresbericht ermöglicht dieser Mechanismus die Beschreibung von Diagrammen und Schemata, die Klassifizierung von Bildern (Foto, Logo, Schema, Graph) und die Extraktion von Textinhalten aus eingebetteten Bildern – drei Informationsarten, die die Standard-Textextraktion systematisch übersehen.
Dokumentenannotationen (document_annotation) behandeln die Datei als Ganzes. Das Modell analysiert den extrahierten Markdown-Zusammenhang sowie die ersten acht Bilder und liefert daraufhin, was Sie angefordert haben: strukturierte Felder wie einen Namen, ein Datum oder einen Betrag; die Dokumentart; eine Inhaltszusammenfassung; oder eine Antwort auf eine spezifische Frage. Dies ist das Werkzeug für die Massenverarbeitung, das Sie in Ihre Workflows für Rechnungen, Formulare und Verträge einbinden.
Das Pydantic-Schema wirkt als Vertrag
Annotationen stützen sich auf Pydantic-Modelle, um die Ausgabestruktur zu definieren. Jedes Attribut wird zu einem Extraktionsfeld, und seine description dient als Anweisung für das Modell: Sie trägt so viel Gewicht wie der Feldname selbst.
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)")
Annotation eines gesamten Dokuments
Der Aufruf bleibt derselbe wie bei OCR: Sie fügen lediglich den Parameter document_annotation_format hinzu, der durch response_format_from_pydantic_model() gefüllt wird. Dieser übersetzt Ihr Modell in ein Schema, das die API verwenden kann. Bei der Rückgabe kommt die Annotation als JSON-String an, den Sie mit Pydantic neu validieren, um ein sicheres Python-Objekt zu erhalten.
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
)
)
# Die Dokumentannotation wird vom Response-Objekt getragen, nicht von jeder Seite
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}")
Beschreibung von Bildern einzeln
Bei Bildern ist das Prinzip identisch, jedoch ändert sich der Parameter, und die Ergebnisse werden aus page.images statt von der Seite selbst gelesen. Beachten Sie include_image_base64=True: Ohne diese Option verlieren Sie die visuellen Inhalte, die das Modell gerade beschrieben hat.
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
)
# Zugriff auf Bildannotationen
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}")
Es besteht keine Notwendigkeit, sich zwischen den beiden zu entscheiden: Bei einem illustrierten Bericht werden Sie in der Regel sowohl die Metadaten des Dokuments als auch die Beschreibung seiner Diagramme wünschen, was ein einziger Aufruf abdeckt, indem beide Formate übergeben werden.
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
)
Extraktion durch einen Prompt leiten
Ein Schema beschreibt die erwartete Form, nicht den Kontext des Dokuments. Wenn Ihre Felder mehrdeutig sind – mehrere Daten, mehrere Beträge, zwei ähnliche Abschnitte – hilft document_annotation_prompt, die Unsicherheit aufzulösen, indem es dem Modell die Natur des Dokuments und die Prioritäten mitteilt. Bei einem französischen Handelsvertrag macht diese Rahmensatz oft den Unterschied zwischen nutzbarer Extraktion und einer ungenauen Ausfüllung aus.
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."
)
)
Kernaussagen
- Zwei Arten von Annotationen:
bbox_annotationfür Bilder,document_annotationfür das gesamte Dokument - Pydantic-Schemata definieren die Struktur der zu extrahierenden Daten
- Verwenden Sie
response_format_from_pydantic_model(), um das Schema zu konvertieren - Der
document_annotation_promptleitet die Extraktion durch kontextbezogene Anweisungen - Beide Arten können in einem einzigen Aufruf kombiniert werden