Rozhranie API pre anotácie
Na tejto strane
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 aliasmistral-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 čítalpage.document_annotationna každej strane; v SDKmistralaiverzie 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ú zimage.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_annotationpre obrázky,document_annotationpre 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_promptusmerňuje extrakciu pomocou kontextových inštrukcií- Oba typy je možné kombinovať v jednom volaní