Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

API za anotacije

Lekcija 9 od 16 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Više od izvlačenja teksta
  2. Dvije razine analize
  3. Pydantic shema kao ugovor
  4. Anotiranje cijelog dokumenta
  5. Opisivanje vizuala jedan po jedan
  6. Vođenje izvlačenja putem prompta
  7. Ključne točke

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 alias mistral-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 čitao page.document_annotation na svakoj stranici; u SDK-u mistralai verzije 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 iz image.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_annotation za slike, document_annotation za cijeli dokument
  • Pydantic sheme definiraju strukturu podataka za izvlačenje
  • Koristi response_format_from_pydantic_model() za pretvorbu sheme
  • document_annotation_prompt vodi izvlačenje kontekstualnim uputama
  • Obje se vrste mogu kombinirati u jednom pozivu