API za anotacije
Na ovoj stranici
Ažurirano 2. studenoga 2026. — OCR. Verzija OCR 4.0 (
mistral-ocr-4-0) povučena je iz upotrebe 30. rujna 2026. Koristi OCR 4.1 (mistral-ocr-4-1), koji je općenito dostupan od 31. kolovoza po istoj cijeni, ili aliasmistral-ocr-latest, koji na njega pokazuje od 16. srpnja. OCR 4.1 dodaje ocjene pouzdanosti na razini blokova. Dodatak od 3. studenoga: Prethodni je primjer čitaopage.document_annotationna svakoj stranici; u SDK-umistralaiverzije 3.7.0 ovo polje pripada OCR odgovoru (ocr_response.document_annotation), dok stranice sadrže samo svoj sadržaj i slike; anotacije slika čitaju se izimage.image_annotation.
Više od izvlačenja teksta
OCR ti daje sirovi tekst: vjeran i potpun, ali nediferenciran. Dobivaš Markdown, a ne podatke. Anotacije čine sljedeći korak: izvlače strukturirane podatke iz tvojih dokumenata na temelju sheme koju unaprijed definiraš. Opisuješ što tražiš, model to automatski izvlači, a tvoja aplikacija prima tipizirana polja umjesto zida teksta koji moraš parsirati regularnim izrazima.
Dvije razine analize
Document AI razlikuje dvije vrste anotacija ovisno o mjerilu u kojem djeluju.
Anotacije okvirnih polja (bbox_annotation) fokusiraju se na slike i grafiku koje je OCR izolirao. Model vizije obrađuje svaki okvirno polje pojedinačno kako bi opisao njegov sadržaj. U godišnjem izvješću ovaj mehanizam omogućuje opisivanje grafikona i dijagrama, klasificiranje slika (fotografija, logotip, shema, graf) i izvlačenje tekstualnog sadržaja iz ugrađenih slika — tri informacije koje standardno izvlačenje teksta sustavno previdi.
Anotacije dokumenata (document_annotation) tretiraju datoteku kao cjelinu. Model analizira izvučeni Markdown zajedno s prvih osam slika, a zatim vraća ono što si zatražio: strukturirana polja poput imena, datuma ili iznosa; vrstu dokumenta; sažetak sadržaja; ili odgovor na specifično pitanje. Ovo je alat za masovnu obradu, onaj koji ćeš uključiti u svoje radne tokove za fakture, obrasce i ugovore.
Pydantic shema kao ugovor
Anotacije se oslanjaju na Pydantic modele za definiranje izlazne strukture. Svaki atribut postaje polje za izvlačenje, a njegov description služi kao instrukcija modelu: nosi jednaku težinu kao i samo ime polja.
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)")
Anotiranje cijelog dokumenta
Poziv ostaje isti kao i za OCR: jednostavno dodaš parametar document_annotation_format, popunjen s response_format_from_pydantic_model(), koji prevodi tvoj model u shemu koju API može koristiti. Po povratku, anotacija stiže kao JSON niz, koji ponovno validiraš s Pydanticom kako bi dobio siguran 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
)
)
# Anotacija dokumenta nalazi se u odgovoru, a ne na svakoj stranici
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}")
Opisivanje vizuala jedan po jedan
Za slike je princip identičan, ali se parametar mijenja, a rezultati se čitaju iz page.images, a ne iz same stranice. Obrati pažnju na include_image_base64=True: bez njega gubiš vizuale koje je model upravo opisao.
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
)
# Pristup anotacijama slika
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šta te ne prisiljava da biraš između ta dva: na ilustriranom izvješću obično ćeš htjeti i metapodatke dokumenta i opis njegovih grafikona, što jedan poziv pokriva prosljeđivanjem obaju formata.
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
)
Vođenje izvlačenja putem prompta
Shema opisuje očekivani oblik, a ne kontekst dokumenta. Kada su tvoja polja dvosmislena — više datuma, više iznosa, dva slična odjeljka — document_annotation_prompt pomaže razriješiti nedoumicu govoreći modelu o prirodi dokumenta i tome što treba prioritizirati. Na francuskom komercijalnom ugovoru ova okvirna rečenica često čini razliku između upotrebljivog izvlačenja i približnog popunjavanja.
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."
)
)
Ključne točke
- Dvije vrste anotacija:
bbox_annotationza slike,document_annotationza cijeli dokument - Pydantic sheme definiraju strukturu podataka za izvlačenje
- Koristi
response_format_from_pydantic_model()za pretvorbu sheme document_annotation_promptvodi izvlačenje kontekstualnim uputama- Obje se vrste mogu kombinirati u jednom pozivu