Extrahovanie štruktúrovaných metadát
Na tejto strane
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 aliasmistral-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,…"}; typdocument_base64zo starších príkladov neexistuje ani v dokumentácii, ani v SDKmistralaia tieto príklady by zlyhali. Zdroje: OCR Processor · Document QnA. Opravené 3. novembra 2026: Kód predtým čítalpage.document_annotationstránku po stránke; v SDKmistralaiverzie 3.7.0 je anotácia dokumentu jedným poľom v odpovedi (response.document_annotation) a anotácia obrázka sa číta zimage.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_promptso schémou pre maximálny kontext