Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Extrahovanie štruktúrovaných metadát

Lekcia 10 z 16 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Extrahuj presne to, čo potrebuješ
  2. Štruktúra namiesto sploštenia
  3. Opakujúce sa dáta
  4. Zaškrtávacie políčka a formuláre
  5. Implementácia od začiatku do konca
  6. Kľúčové poznatky

Aktualizácia 2. novembra 2026 — OCR. Verzia OCR 4.0 (mistral-ocr-4-0) bola vyradená 30. septembra 2026. Používaj OCR 4.1 (mistral-ocr-4-1), ktoré je všeobecne dostupné od 31. augusta za rovnakú cenu, alebo alias mistral-ocr-latest, ktorý naň odkazuje od 16. júla. OCR 4.1 pridáva skóre spoľahlivosti na úrovni blokov. Dodatok z 3. novembra 2026: Lokálny PDF súbor sa odosiela v base64 ako {"type": "document_url", "document_url": "data:application/pdf;base64,…"}; typ document_base64 zo starších príkladov neexistuje ani v dokumentácii, ani v SDK mistralai a tieto príklady by zlyhali. Zdroje: OCR Processor · Document QnA. Opravené 3. novembra 2026: Kód predtým čítal page.document_annotation stránku po stránke; v SDK mistralai verzie 3.7.0 je anotácia dokumentu jedným poľom v odpovedi (response.document_annotation) a anotácia obrázka sa číta z image.image_annotation.

Extrahuj presne to, čo potrebuješ

Anotácia dokumentov nie je len o získavaní surového textu. Produkuje štruktúrované, typované a validované dáta pripravené na okamžité použitie vo vašich systémoch: riadok vložený do databázy, pole porovnané s referenčnou hodnotou alebo suma overená pred platbou. Výzva sa úplne presúva na návrh schémy, čo je zameranie tejto lekcie.

Štruktúra namiesto sploštenia

Schéma extrakcie by mala odrážať realitu dokumentu. Faktúra pochádza od právnickej osoby s názvom spoločnosti, číslom SIRET (francúzske identifikačné číslo firmy) a adresou. Namiesto zarovnania ôsmich polí ako emetteur_rue, emetteur_ville, emetteur_siret definuj model Adresse a potom model LegalEntity, ktorý ho obsahuje. Tieto stavebné bloky znovu použi pre vydavateľa aj príjemcu. Enumerácia TypeDocument hrá podobnú úlohu: zabraňuje modelu vymýšľať si kategóriu a garantuje hodnotu, ktorú môžeš použiť v príkaze if alebo na smerovanie. Polia Optional explicitne uvádzajú, čo môže chýbať, zatiaľ čo predvolené hodnoty – ako default="France" pre krajinu – ušetria model od hádania samozrejmostí.

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 ulica")
    postal_code: Optional[str] = Field(None, description="Poštové smerovacie číslo")
    city: Optional[str] = Field(None, description="Mesto")
    country: str = Field(default="France", description="Krajina")

class LegalEntity(BaseModel):
    name: str = Field(..., description="Obchodné meno")
    siret: Optional[str] = Field(None, description="Číslo SIRET")
    address: Optional[Address] = Field(None, description="Poštová 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ý dátum (RRRR-MM-DD)"
    )
    emetteur: LegalEntity = Field(
        ..., description="Entita, ktorá vydala dokument"
    )
    destinataire: Optional[LegalEntity] = Field(
        None, description="Prijímajúca entita"
    )
    resume: str = Field(
        ..., description="Zhrnutie obsahu v 2-3 vetách"
    )
    langue: str = Field(
        ..., description="Jazyk dokumentu (kód ISO 639-1)"
    )

Opakujúce sa dáta

Mnohé dokumenty obsahujú série: fakturačné riadky, klauzuly alebo položky výdavkov. Modeluj ich ako list[...] vyhradeného podmodelu. Model potom preskúma tabuľku v dokumente a vytvorí toľko objektov LigneFacture, koľko nájde riadkov, vrátane popisu, množstva, jednotkovej ceny a celkovej sumy pre každý z nich. To ti poskytne dostatok dát na vlastný prepočet medzisúčtu a overenie konzistencie dokumentu pred jeho akceptovaním.

from pydantic import BaseModel, Field

class InvoiceLine(BaseModel):
    description: str = Field(..., description="Popis produktu/služby")
    quantity: float = Field(..., description="Množstvo")
    unit_price: float = Field(..., description="Jednotková cena bez DPH")
    amount: float = Field(..., description="Celková suma riadku bez DPH")

class DetailedInvoice(BaseModel):
    supplier: str = Field(..., description="Názov dodávateľa")
    number: str = Field(..., description="Číslo faktúry")
    date: str = Field(..., description="Dátum (RRRR-MM-DD)")
    lines: list[InvoiceLine] = Field(
        ..., description="Riadky faktúry"
    )
    subtotal_excl_tax: float = Field(..., description="Medzisúčet bez DPH")
    vat: float = Field(..., description="Suma DPH")
    total_incl_tax: float = Field(..., description="Celková suma s DPH")
    payment_terms: str = Field(
        ..., description="Uvedené platobné podmienky"
    )

Zaškrtávacie políčka a formuláre

Skenované papierové formuláre sú oblasťou, kde model vyniká. Pole typu bool spárované s označením otázky stačí: model rozpozná, či je políčko zaškrtnuté, extrahuje zodpovedajúcu otázku a – čo je kľúčové pre lekárske alebo administratívne použitie – usúdi, že pole chýba, namiesto toho, aby si vymyslel hodnotu, ako demonštroval tím Mistral. Poznámka „null if not provided“ (null, ak nie je uvedené) v popise telefónneho čísla nie je dekoratívna; explicitne povoľuje prázdnu hodnotu.

from pydantic import BaseModel, Field

class FormResponse(BaseModel):
    question: str = Field(..., description="Znenie otázky")
    answer: bool = Field(..., description="True, ak je zaškrtnuté, inak False")

class MedicalForm(BaseModel):
    patient_name: str = Field(..., description="Celé meno pacienta")
    age: Optional[int] = Field(None, description="Vek pacienta")
    sex: Optional[str] = Field(None, description="Pohlavie (M/F)")
    patient_id: Optional[str] = Field(None, description="ID pacienta")
    phone: Optional[str] = Field(
        None, description="Telefónne číslo (null, ak nie je uvedené)"
    )
    responses: list[FormResponse] = Field(
        ..., description="Odpovede na otázky vo formulári"
    )

Implementácia od začiatku do konca

Vezmi príklad podrobnej faktúry a prepoj ho s dokumentom kódovaným v base64. Výzva na anotáciu dopĺňa schému špecifikáciou typu súboru a dôrazom na pozornosť venovanú fakturačným riadkom; validácia Pydantic pri návrate konvertuje reťazec JSON na objekt, ktorým môžeš bezpečne prechádzať.

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=(
        "Tento dokument je faktúra. Extrahuj všetky fakturačné riadky "
        "s ich sumami."
    )
)

# Extrakcia a validácia
if ocr_response.document_annotation:
    invoice = DetailedInvoice.model_validate_json(
        ocr_response.document_annotation
    )

    print(f"Faktúra {invoice.number} - {invoice.supplier}")
    print(f"Dátum: {invoice.date}")
    print(f"\nRiadky:")
    for line in invoice.lines:
        print(f"  - {line.description}: {line.quantity} x "
              f"{line.unit_price}€ = {line.amount}€")
    print(f"\nCelková suma s DPH: {invoice.total_incl_tax}€")

Slabé výsledky extrakcie takmer vždy pramenia zo schémy, zriedka z modelu. Prejdi si svoje popisy jeden po druhom: musia byť presné a jednoznačné, keďže sa na ne model spolieha výlučne pri pochopení tvojich očakávaní. Píš ich v jazyku svojich dokumentov – francúzština dokonale funguje pre francúzske faktúry – a enumerácie vyhraď pre polia s obmedzeným počtom hodnôt a podmodely pre štruktúry, ktoré budeš znovu používať naprieč schémami.

Kľúčové poznatky

  • Schémy Pydantic umožňujú extrakciu typovaných a validovaných dát
  • Na presné extrakcie používaj komplexné typy (zoznamy, enumerácie, vnorené modely)
  • Model spoľahlivo spracováva voliteľné polia a zaškrtávacie políčka
  • Popisy polí usmerňujú extrakciu: buď presný a explicitný
  • Kombinuj document_annotation_prompt so schémou pre maximálny kontext