Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Strukturierte Metadaten extrahieren

Lektion 10 von 16 Aktualisiert am 3. November 2026 Entwickler
Auf dieser Seite
  1. Extrahieren Sie genau das, was Sie benötigen
  2. Struktur statt Abflachung
  3. Wiederholende Daten
  4. Checkboxen und Formulare
  5. End-to-End-Implementierung
  6. Kernaussagen

Update vom 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), das seit dem 31. August allgemein verfügbar ist und zum gleichen Preis angeboten wird, oder den Alias mistral-ocr-latest, der seit dem 16. Juli darauf verweist. OCR 4.1 fügt Vertrauenswerte auf Blockebene hinzu. Ergänzung vom 3. November 2026: Ein lokales PDF wird als base64-Kodierung übermittelt: {"type": "document_url", "document_url": "data:application/pdf;base64,…"}; der Typ document_base64 aus älteren Beispielen existiert weder in der Dokumentation noch im mistralai SDK, und diese Beispiele wären gescheitert. Quellen: OCR Processor · Document QnA. Korrektur vom 3. November 2026: Der Code las zuvor page.document_annotation Seite für Seite; im mistralai SDK 3.7.0 ist die Dokumentenannotation ein einzelnes Feld in der Antwort (response.document_annotation), und die Bilddatenannotation wird aus image.image_annotation gelesen.

Extrahieren Sie genau das, was Sie benötigen

Dokumentenannotationen beschränken sich nicht auf die Rückgabe von rohem Text. Sie erzeugen strukturierte, typisierte und validierte Daten, die sofort in Ihren Systemen nutzbar sind: eine Zeile, die in eine Datenbank eingefügt wird, ein Feld, das mit einem Referenzwert verglichen wird, oder ein Betrag, der vor der Zahlung verifiziert wird. Die Herausforderung verschiebt sich vollständig auf das Schema-Design, worauf sich diese Lektion konzentriert.

Struktur statt Abflachung

Ein Extraktionsschema sollte die Realität des Dokuments widerspiegeln. Eine Rechnung stammt von einer juristischen Person mit Firmenname, SIRET-Nummer (französische Unternehmens-ID) und Adresse. Anstatt acht Felder wie emetteur_rue, emetteur_ville, emetteur_siret auszurichten, definieren Sie ein Adresse-Modell und ein LegalEntity-Modell, das dieses enthält. Wiederverwenden Sie diese Bausteine sowohl für den Absender als auch für den Empfänger. Die TypeDocument-Aufzählung spielt eine ähnliche Rolle: Sie verhindert, dass das Modell eine Kategorie erfindet, und garantiert einen Wert, den Sie in einer if-Anweisung verwenden oder für die Routing-Logik nutzen können. Optional-Felder geben explizit an, was fehlen kann, während Standardwerte – wie default="France" für das Land – das Modell davon abhalten, das Offensichtliche zu erraten.

from pydantic import BaseModel, Field
from typing import Optional
from enum import Enum

class DocumentType(str, Enum):
    INVOICE = "facture"
    CONTRACT = "contrat"
    REPORT = "rapport"
    FORM = "formulaire"
    OTHER = "autre"

class Address(BaseModel):
    street: Optional[str] = Field(None, description="Numéro et street")
    postal_code: Optional[str] = Field(None, description="Code postal")
    city: Optional[str] = Field(None, description="Ville")
    country: str = Field(default="France", description="Pays")

class LegalEntity(BaseModel):
    name: str = Field(..., description="Raison sociale")
    siret: Optional[str] = Field(None, description="Numéro SIRET")
    address: Optional[Address] = Field(None, description="Address postale")
    email: Optional[str] = Field(None, description="Address email")

class DocumentExtraction(BaseModel):
    document_type: DocumentType = Field(
        ..., description="Type du document"
    )
    date: Optional[str] = Field(
        None, description="Date principale (YYYY-MM-DD)"
    )
    emetteur: LegalEntity = Field(
        ..., description="Entité qui émet le document"
    )
    destinataire: Optional[LegalEntity] = Field(
        None, description="Entité destinataire"
    )
    resume: str = Field(
        ..., description="Résumé en 2-3 phrases du contenu"
    )
    langue: str = Field(
        ..., description="Langue du document (code ISO 639-1)"
    )

Wiederholende Daten

Viele Dokumente enthalten Serien: Rechnungspositionen, Klauseln oder Ausgabenposten. Modellieren Sie diese als list[...] eines dedizierten Untermodells. Das Modell durchsucht dann die Dokumententabelle und erzeugt so viele LigneFacture-Objekte, wie es Zeilen findet, einschließlich Beschreibung, Menge, Einheitspreis und Gesamtbetrag für jede. Dies gibt Ihnen genügend Daten, um den Zwischensummenbetrag selbst neu zu berechnen und die Konsistenz des Dokuments zu überprüfen, bevor Sie es akzeptieren.

from pydantic import BaseModel, Field

class InvoiceLine(BaseModel):
    description: str = Field(..., description="Description du produit/service")
    quantity: float = Field(..., description="Quantité")
    unit_price: float = Field(..., description="Prix unitaire HT")
    amount: float = Field(..., description="Montant total HT de la ligne")

class DetailedInvoice(BaseModel):
    supplier: str = Field(..., description="Nom du supplier")
    number: str = Field(..., description="Numéro de facture")
    date: str = Field(..., description="Date (YYYY-MM-DD)")
    lines: list[InvoiceLine] = Field(
        ..., description="Lignes de la facture"
    )
    subtotal_excl_tax: float = Field(..., description="Sous-total HT")
    vat: float = Field(..., description="Montant TVA")
    total_incl_tax: float = Field(..., description="Total TTC")
    payment_terms: str = Field(
        ..., description="Conditions de paiement mentionnées"
    )

Checkboxen und Formulare

Gescannte Papierformulare sind der Bereich, in dem das Modell glänzt. Ein bool-Feld, gepaart mit der Fragebezeichnung, reicht aus: Das Modell erkennt, ob ein Kästchen angekreuzt ist, extrahiert die entsprechende Frage und – was für medizinische oder administrative Anwendungen entscheidend ist – leitet korrekt ab, dass ein Feld fehlt, statt einen Wert zu erfinden, wie das Mistral-Team demonstrierte. Die Notiz „null if not provided” in der Telefonnummernbeschreibung ist kein Schmuck; sie autorisiert explizit einen leeren Wert.

from pydantic import BaseModel, Field

class FormResponse(BaseModel):
    question: str = Field(..., description="Intitulé de la question")
    answer: bool = Field(..., description="True si coché, False sinon")

class MedicalForm(BaseModel):
    patient_name: str = Field(..., description="Nom complet du patient")
    age: Optional[int] = Field(None, description="Âge du patient")
    sex: Optional[str] = Field(None, description="Sexe (M/F)")
    patient_id: Optional[str] = Field(None, description="ID patient")
    phone: Optional[str] = Field(
        None, description="Numéro de téléphone (null si non fourni)"
    )
    responses: list[FormResponse] = Field(
        ..., description="Réponses aux questions du formulaire"
    )

End-to-End-Implementierung

Nehmen Sie das Beispiel der detaillierten Rechnung und verbinden Sie es mit einem base64-kodierten Dokument. Der Annotations-Prompt ergänzt das Schema, indem er die Dateityp angibt und die Aufmerksamkeit auf die Rechnungspositionen lenkt; die Pydantic-Validierung beim Rückgabewert wandelt den JSON-String in ein Objekt um, das Sie sicher durchsuchen können.

import os
import json
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": f"data:application/pdf;base64,{document_base64}"
    },
    document_annotation_format=response_format_from_pydantic_model(
        DetailedInvoice
    ),
    document_annotation_prompt=(
        "Ce document est une invoice. Extrais toutes les lines "
        "de facturation avec leurs montants."
    )
)

# Extraktion und Validierung
if ocr_response.document_annotation:
    invoice = DetailedInvoice.model_validate_json(
        ocr_response.document_annotation
    )

    print(f"Facture {invoice.numero} - {invoice.fournisseur}")
    print(f"Date : {invoice.date}")
    print(f"\nLignes :")
    for line in invoice.lines:
        print(f"  - {line.description}: {line.quantite} x "
              f"{line.prix_unitaire}€ = {line.montant}€")
    print(f"\nTotal TTC : {invoice.total_incl_tax}€")

Schlechte Extraktionsergebnisse stammen fast immer aus dem Schema, selten vom Modell. Überprüfen Sie Ihre Beschreibungen einzeln: Sie müssen präzise und unmissverständlich sein, da das Modell sich allein auf sie verlässt, um Ihre Erwartungen zu verstehen. Schreiben Sie sie in der Sprache Ihrer Dokumente – Französisch funktioniert für französische Rechnungen perfekt – und reservieren Sie Aufzählungen für Felder mit begrenzten Werten und Untermodelle für Strukturen, die Sie über mehrere Schemata hinweg wiederverwenden werden.

Kernaussagen

  • Pydantic-Schemata ermöglichen die Extraktion von typisierten und validierten Daten
  • Nutzen Sie komplexe Typen (Listen, Aufzählungen, verschachtelte Modelle) für präzise Extraktionen
  • Das Modell verarbeitet optionale Felder und Checkboxen zuverlässig
  • Feldbeschreibungen leiten die Extraktion: Seien Sie präzise und explizit
  • Kombinieren Sie document_annotation_prompt mit dem Schema für maximalen Kontext