Extraktion strukturovaných metadat
Na této stránce
Aktualizace 2. listopadu 2026 — OCR. Verze OCR 4.0 (
mistral-ocr-4-0) byla 30. září 2026 vyřazena z provozu. Používej OCR 4.1 (mistral-ocr-4-1), které je obecně dostupné od 31. srpna za stejnou cenu, nebo aliasmistral-ocr-latest, který na něj odkazuje od 16. července. OCR 4.1 přidává skóre důvěryhodnosti na úrovni bloků. Dodatek ze 3. listopadu 2026: Lokální PDF se přenáší v base64 jako{"type": "document_url", "document_url": "data:application/pdf;base64,…"}; typdocument_base64ze starších příkladů neexistuje ani v dokumentaci, ani v SDKmistralaia tyto příklady by selhaly. Zdroje: OCR Processor · Document QnA. Opraveno 3. listopadu 2026: Kód dříve četlpage.document_annotationstránku po stránce; v SDKmistralaiverze 3.7.0 je anotace dokumentu jediným polem v odpovědi (response.document_annotation) a anotace obrázku se čte zimage.image_annotation.
Extrahuj přesně to, co potřebuješ
Anotace dokumentů není jen o získávání surového textu. Produkuje strukturovaná, typovaná a validovaná data připravená k okamžitému použití ve tvých systémech: řádek vložený do databáze, pole porovnané s referencí nebo částka ověřená před platbou. Výzva se zcela přesouvá k návrhu schématu, což je zaměření této lekce.
Struktura místo zplošťování
Schéma extrakce by mělo odrážet realitu dokumentu. Faktura pochází od právnické osoby s názvem společnosti, číslem SIRET (francouzské firemní ID) a adresou. Místo zarovnání osmi polí jako emetteur_rue, emetteur_ville, emetteur_siret definuj model Adresse a poté model LegalEntity, který jej obsahuje. Tyto stavební kameny znovu použij jak pro vydavatele, tak pro příjemce. Výčet TypeDocument hraje podobnou roli: zabraňuje modelu vymýšlet si kategorii a garantuje hodnotu, kterou můžeš použít v příkazu if nebo pro směrování. Pole Optional explicitně uvádějí, co může chybět, zatímco výchozí hodnoty – jako default="France" pro zemi – šetří model před hádáním samozřejmostí.
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="Číslo a ulice")
postal_code: Optional[str] = Field(None, description="PSČ")
city: Optional[str] = Field(None, description="Město")
country: str = Field(default="France", description="Země")
class LegalEntity(BaseModel):
name: str = Field(..., description="Obchodní název")
siret: Optional[str] = Field(None, description="Číslo SIRET")
address: Optional[Address] = Field(None, description="Poštovní adresa")
email: Optional[str] = Field(None, description="E-mailová adresa")
class DocumentExtraction(BaseModel):
document_type: DocumentType = Field(
..., description="Typ dokumentu"
)
date: Optional[str] = Field(
None, description="Hlavní datum (RRRR-MM-DD)"
)
emetteur: LegalEntity = Field(
..., description="Subjekt vydávající dokument"
)
destinataire: Optional[LegalEntity] = Field(
None, description="Příjemce dokumentu"
)
resume: str = Field(
..., description="Shrnutí obsahu ve 2–3 větách"
)
langue: str = Field(
..., description="Jazyk dokumentu (kód ISO 639-1)"
)
Opakující se data
Mnoho dokumentů obsahuje série: fakturační řádky, klauzule nebo položky výdajů. Modeluj je jako list[...] vyhrazeného podmodelu. Model pak prohledá tabulku v dokumentu a vytvoří tolik objektů LigneFacture, kolik najde řádků, včetně popisu, množství, jednotkové ceny a celkové částky pro každý z nich. To ti poskytne dostatek dat k vlastnímu přepočtu mezisoučtu a ověření konzistence dokumentu před jeho přijetím.
from pydantic import BaseModel, Field
class InvoiceLine(BaseModel):
description: str = Field(..., description="Popis produktu/služby")
quantity: float = Field(..., description="Množství")
unit_price: float = Field(..., description="Jednotková cena bez DPH")
amount: float = Field(..., description="Celková částka řádku bez DPH")
class DetailedInvoice(BaseModel):
supplier: str = Field(..., description="Název dodavatele")
number: str = Field(..., description="Číslo faktury")
date: str = Field(..., description="Datum (RRRR-MM-DD)")
lines: list[InvoiceLine] = Field(
..., description="Řádky faktury"
)
subtotal_excl_tax: float = Field(..., description="Mezisoučet bez DPH")
vat: float = Field(..., description="Částka DPH")
total_incl_tax: float = Field(..., description="Celková částka s DPH")
payment_terms: str = Field(
..., description="Uvedené platební podmínky"
)
Zaškrtávací políčka a formuláře
Skenované papírové formuláře jsou oblastí, kde model vyniká. Pole bool spárované s popiskem otázky stačí: model rozpozná, zda je políčko zaškrtnuto, extrahuje odpovídající otázku a – což je zásadní pro lékařské nebo administrativní použití – odvodí, že pole chybí, místo aby si vymýšlel hodnotu, jak demonstroval tým Mistral. Poznámka „null if not provided“ (null, pokud není uvedeno) v popisu telefonního čísla není ozdobná; explicitně povoluje prázdnou hodnotu.
from pydantic import BaseModel, Field
class FormResponse(BaseModel):
question: str = Field(..., description="Znění otázky")
answer: bool = Field(..., description="True pokud zaškrtnuto, jinak False")
class MedicalForm(BaseModel):
patient_name: str = Field(..., description="Celé jméno pacienta")
age: Optional[int] = Field(None, description="Věk pacienta")
sex: Optional[str] = Field(None, description="Pohlaví (M/F)")
patient_id: Optional[str] = Field(None, description="ID pacienta")
phone: Optional[str] = Field(
None, description="Telefonní číslo (null pokud není uvedeno)"
)
responses: list[FormResponse] = Field(
..., description="Odpovědi na otázky ve formuláři"
)
Implementace od začátku do konce
Vezmi podrobný příklad faktury a propoj jej s dokumentem kódovaným v base64. Prompt pro anotaci doplňuje schéma specifikací typu souboru a zdůrazněním pozornosti věnované fakturačním řádkům; validace Pydantic při návratu převede řetězec JSON na objekt, kterým můžeš bezpečně procházet.
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."
)
)
# Extrakce a validace
if ocr_response.document_annotation:
invoice = DetailedInvoice.model_validate_json(
ocr_response.document_annotation
)
print(f"Faktura {invoice.numero} - {invoice.fournisseur}")
print(f"Datum: {invoice.date}")
print(f"\nŘádky:")
for line in invoice.lines:
print(f" - {line.description}: {line.quantite} x "
f"{line.prix_unitaire}€ = {line.montant}€")
print(f"\nCelkem s DPH: {invoice.total_incl_tax}€")
Špatné výsledky extrakce téměř vždy pramení ze schématu, zřídka z modelu. Projdi své popisy jeden po druhém: musí být přesné a jednoznačné, protože se na ně model spoléhá výhradně při pochopení tvých očekávání. Piš je jazykem svých dokumentů – francouzština funguje perfektně pro francouzské faktury – a vyhraď výčty (enums) pro pole s omezeným počtem hodnot a podmodely pro struktury, které budeš znovu používat napříč schématy.
Klíčové poznatky
- Schémata Pydantic umožňují extrakci typovaných a validovaných dat
- Pro přesné extrakce používej složité typy (seznamy, výčty, vnořené modely)
- Model spolehlivě zpracovává volitelná pole a zaškrtávací políčka
- Popisy polí řídí extrakci: buď přesný a explicitní
- Zkombinuj
document_annotation_promptse schématem pro maximální kontext