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

Rozhranie API pre anotácie

Lekcia 9 z 16 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Viac než len extrakcia textu
  2. Dve úrovne analýzy
  3. Schéma Pydantic ako zmluva
  4. Anotovanie celého dokumentu
  5. Popisovanie vizuálov jeden po druhom
  6. Usmerňovanie extrakcie pomocou promptu
  7. Kľúčové poznatky

Aktualizované 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 ňu odkazuje od 16. júla. OCR 4.1 pridáva hodnoty spoľahlivosti na úrovni blokov. Doplnok z 3. novembra: Predchádzajúci príklad čítal page.document_annotation na každej strane; v SDK mistralai verzie 3.7.0 patrí toto pole do odpovede OCR (ocr_response.document_annotation), zatiaľ čo strany obsahujú iba svoj obsah a obrázky; anotácie obrázkov sa čítajú z image.image_annotation.

Viac než len extrakcia textu

OCR ti poskytne surový text: verný a úplný, ale nediferencovaný. Získavaš Markdown, nie dáta. Anotácie robia ďalší krok: extrahujú štruktúrované dáta z tvojich dokumentov na základe schémy, ktorú definuješ vopred. Popíšeš, čo hľadáš, model to automaticky extrahuje a tvoja aplikácia dostane typované polia namiesto steny textu, ktorú by si musel parsovať pomocou regulárnych výrazov.

Dve úrovne analýzy

Document AI rozlišuje dva typy anotácií podľa mierky, v akej pracujú.

Anotácie ohraničujúcich boxov (bbox_annotation) sa zameriavajú na obrázky a grafiku, ktoré OCR izoloval. Víziový model spracúva každý ohraničujúci box jednotlivo, aby popísal jeho obsah. Vo výročnej správe ti tento mechanizmus umožní popísať grafy a diagramy, klasifikovať obrázky (fotografia, logo, schéma, graf) a extrahovať textový obsah z vložených obrázkov – tri informácie, ktoré štandardná extrakcia textu systematicky prehliada.

Anotácie dokumentov (document_annotation) zaobchádzajú so súborom ako s celkom. Model analyzuje extrahovaný Markdown spolu s prvými ôsmimi obrázkami a vráti to, o čo si požiadal: štruktúrované polia, ako je meno, dátum alebo suma; typ dokumentu; zhrnutie obsahu alebo odpoveď na konkrétnu otázku. Toto je nástroj pre hromadné spracovanie, ten, ktorý zapojíš do svojich workflow pre faktúry, formuláre a zmluvy.

Schéma Pydantic ako zmluva

Anotácie sa spoliehajú na modely Pydantic na definovanie výstupnej štruktúry. Každý atribút sa stane poľom na extrakciu a jeho description slúži ako inštrukcia pre model: nesie rovnakú váhu ako samotný názov poľa.

from pydantic import BaseModel, Field
from typing import Optional

class InvoiceExtraction(BaseModel):
    vendor: str = Field(..., description="Vendor name")
    invoice_number: str = Field(..., description="Invoice number")
    issue_date: str = Field(..., description="Issue date (YYYY-MM-DD)")
    amount_excl_tax: float = Field(..., description="Amount excluding tax")
    amount_incl_tax: float = Field(..., description="Amount including tax")
    currency: str = Field(default="EUR", description="Currency (ISO code)")

Anotovanie celého dokumentu

Volanie zostáva rovnaké ako pri OCR: jednoducho pridáš parameter document_annotation_format, vyplnený funkciou response_format_from_pydantic_model(), ktorá preloží tvoj model do schémy použiteľnej pre API. Pri návrate dorazí anotácia ako reťazec JSON, ktorý znovu overíš pomocou Pydantic, aby si získal bezpečný Python objekt.

import os
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model
from pydantic import BaseModel, Field

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

class InvoiceExtraction(BaseModel):
    vendor: str = Field(..., description="Vendor name")
    invoice_number: str = Field(..., description="Invoice number")
    issue_date: str = Field(..., description="Issue date (YYYY-MM-DD)")
    amount_excl_tax: float = Field(..., description="Amount excluding tax")
    amount_incl_tax: float = Field(..., description="Amount including tax")

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://example.com/invoice.pdf"
    },
    document_annotation_format=response_format_from_pydantic_model(
        InvoiceExtraction
    )
)

# Anotácia dokumentu je súčasťou odpovede, nie každej strany
if ocr_response.document_annotation:
    invoice = InvoiceExtraction.model_validate_json(
        ocr_response.document_annotation
    )
    print(f"Vendor: {invoice.vendor}")
    print(f"Amount incl. tax: {invoice.amount_incl_tax}")

Popisovanie vizuálov jeden po druhom

Pri obrázkoch je princíp rovnaký, ale parameter sa mení a výsledky sa čítajú z page.images namiesto samotnej strany. Všimni si include_image_base64=True: bez neho stratíš vizuály, ktoré model práve popísal.

from pydantic import BaseModel, Field
from mistralai.extra import response_format_from_pydantic_model

class ImageDescription(BaseModel):
    image_type: str = Field(
        ..., description="Type: graph, table, photo, logo, schematic"
    )
    description: str = Field(
        ..., description="Short description of the image in English"
    )
    relevant_content: str = Field(
        ..., description="Summary of the informative content of the image"
    )

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://example.com/report.pdf"
    },
    bbox_annotation_format=response_format_from_pydantic_model(
        ImageDescription
    ),
    include_image_base64=True
)

# Prístup k anotáciám obrázkov
for page in ocr_response.pages:
    for image in page.images:
        if image.image_annotation:
            desc = ImageDescription.model_validate_json(image.image_annotation)
            print(f"Image {image.id}: {desc.image_type}")
            print(f"  Description: {desc.description}")

Nič ťa nenúti vybrať si len jedno: pri ilustrovanej správe budeš zvyčajne chcieť mať metadáta dokumentu aj popis jeho grafov, čo pokryje jediné volanie odovzdaním oboch formátov.

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://example.com/report.pdf"
    },
    bbox_annotation_format=response_format_from_pydantic_model(
        ImageDescription
    ),
    document_annotation_format=response_format_from_pydantic_model(
        InvoiceExtraction
    ),
    include_image_base64=True
)

Usmerňovanie extrakcie pomocou promptu

Schéma opisuje očakávaný tvar, nie kontext dokumentu. Keď sú tvoje polia nejednoznačné – viacero dátumov, viacero súm, dve podobné sekcie – document_annotation_prompt pomáha vyriešiť pochybnosti tým, že modelu povie povahu dokumentu a čo má uprednostniť. Pri francúzskej obchodnej zmluve táto rámujúca veta často rozhoduje medzi použiteľnou extrakciou a približným vyplnením.

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://example.com/contract.pdf"
    },
    document_annotation_format=response_format_from_pydantic_model(
        ContractExtraction
    ),
    document_annotation_prompt=(
        "This document is a French commercial contract. "
        "Extract information about the contracting parties, "
        "the contract duration, and the main clauses."
    )
)

Kľúčové poznatky

  • Dva typy anotácií: bbox_annotation pre obrázky, document_annotation pre celý dokument
  • Schémy Pydantic definujú štruktúru dát na extrakciu
  • Na konverziu schémy použi response_format_from_pydantic_model()
  • document_annotation_prompt usmerňuje extrakciu pomocou kontextových inštrukcií
  • Oba typy je možné kombinovať v jednom volaní