API pro anotace
Na této stránce
Aktualizováno 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 aliasmistral-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: Předchozí příklad četlpage.document_annotationna každé stránce; v SDKmistralaiverze 3.7.0 patří toto pole odpovědi OCR (ocr_response.document_annotation), zatímco stránky obsahují pouze svůj obsah a obrázky; anotace obrázků se čtou zimage.image_annotation.
Víc než jen extrakce textu
OCR ti dodá surový text: věrný a úplný, ale nediferencovaný. Získáš Markdown, nikoliv data. Anotace dělají další krok: extrahují strukturovaná data z tvých dokumentů na základě schématu, které předem definuješ. Popíšeš, co hledáš, model to automaticky extrahuje a tvoje aplikace obdrží typovaná pole místo zdi textu, kterou bys musel parsovat pomocí regulárních výrazů.
Dvě úrovně analýzy
Document AI rozlišuje dva typy anotací podle měřítka, ve kterém pracují.
Anotace ohraničujících rámečků (bbox_annotation) se zaměřují na obrázky a grafiku, které OCR izolovalo. Vizionářský model zpracovává každý ohraničující rámeček jednotlivě a popisuje jeho obsah. Ve výroční zprávě ti tento mechanismus umožní popsat grafy a diagramy, klasifikovat obrázky (fotografie, logo, schéma, graf) a extrahovat textový obsah z vložených obrázků – tři informace, které standardní extrakce textu systematicky přehlíží.
Anotace dokumentu (document_annotation) zacházejí se souborem jako s celkem. Model analyzuje extrahovaný Markdown spolu s prvními osmi obrázky a vrátí to, co jsi požadoval: strukturovaná pole, jako je jméno, datum nebo částka; typ dokumentu; shrnutí obsahu; nebo odpověď na konkrétní otázku. Toto je nástroj pro hromadné zpracování, ten, který zapojíš do svých pracovních postupů pro faktury, formuláře a smlouvy.
Schéma Pydantic jako smlouva
Anotace spoléhají na modely Pydantic pro definici výstupní struktury. Každý atribut se stane polem k extrakci a jeho description slouží jako instrukce pro model: nese stejnou váhu jako samotný název pole.
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)")
Anotování celého dokumentu
Volání zůstává stejné jako u OCR: jednoduše přidáš parametr document_annotation_format, který vyplníš pomocí response_format_from_pydantic_model(). Tato funkce převede tvůj model na schéma, které API dokáže použít. Při návratu dorazí anotace jako řetězec JSON, který znovu validuješ pomocí Pydantic, abys 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
)
)
# Anotace dokumentu je součástí odpovědi, nikoliv každé stránky
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}")
Popis vizuálů jeden po druhém
U obrázků je princip totožný, ale parametr se mění a výsledky se čtou z page.images místo ze samotné stránky. Všimni si include_image_base64=True: bez toho ztratíš vizuály, které model právě popsal.
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
)
# Přístup k anotacím obrázků
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}")
Nic tě nenutí vybírat si pouze jeden z těchto přístupů: u ilustrované zpravy budeš obvykle chtít jak metadata dokumentu, tak popis jeho grafů, což pokryje jediné volání předáním obou formátů.
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
)
Řízení extrakce pomocí promptu
Schéma popisuje očekávaný tvar, nikoliv kontext dokumentu. Když jsou tvá pole nejednoznačná – více dat, více částek, dvě podobné sekce – document_annotation_prompt pomáhá rozřešit pochybnosti tím, že modelu sdělí povahu dokumentu a co má upřednostnit. U francouzské obchodní smlouvy často tato rámcující věta rozhoduje mezi použitelnou extrakcí a přibližným vyplnění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."
)
)
Klíčové poznatky
- Dva typy anotací:
bbox_annotationpro obrázky,document_annotationpro celý dokument - Schémata Pydantic definují strukturu dat k extrakci
- Použij
response_format_from_pydantic_model()pro převod schématu document_annotation_promptřídí extrakci pomocí kontextových instrukcí- Oba typy lze kombinovat v jediném volání