Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Extraktion strukturovaných metadat

Lekce 10 z 16 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Extrahuj přesně to, co potřebuješ
  2. Struktura místo zplošťování
  3. Opakující se data
  4. Zaškrtávací políčka a formuláře
  5. Implementace od začátku do konce
  6. Klíčové poznatky

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 alias mistral-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,…"}; typ document_base64 ze starších příkladů neexistuje ani v dokumentaci, ani v SDK mistralai a tyto příklady by selhaly. Zdroje: OCR Processor · Document QnA. Opraveno 3. listopadu 2026: Kód dříve četl page.document_annotation stránku po stránce; v SDK mistralai verze 3.7.0 je anotace dokumentu jediným polem v odpovědi (response.document_annotation) a anotace obrázku se čte z image.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_prompt se schématem pro maximální kontext