Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

API za opombe

Lekcija 9 od 16 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Več kot le ekstrakcija besedila
  2. Dve ravni analize
  3. Shema Pydantic kot pogodba
  4. Opombanje celotnega dokumenta
  5. Opisovanje vizualnih elementov enega za drugim
  6. Vodenje ekstrakcije s pozivom
  7. Ključne ugotovitve

Posodobljeno 2. novembra 2026 — OCR. Različica OCR 4.0 (mistral-ocr-4-0) je bila ukinjena 30. septembra 2026. Uporabljaj OCR 4.1 (mistral-ocr-4-1), ki je splošno dostopen od 31. avgusta po enaki ceni, ali alias mistral-ocr-latest, ki kaže nanj od 16. julija. OCR 4.1 dodaja ocene zanesljivosti na ravni blokov. Dodatek z dne 3. novembra: Prejšnji primer je bral page.document_annotation na vsaki strani; v SDK mistralai različice 3.7.0 to polje pripada odgovoru OCR (ocr_response.document_annotation), medtem ko strani vsebujejo le svojo vsebino in slike; opombe k slikam se berejo iz image.image_annotation.

Več kot le ekstrakcija besedila

OCR ti da surovo besedilo: zvesto in popolno, a nediferencirano. Dobiš Markdown, ne pa podatkov. Opombe naredijo naslednji korak: iz tvojih dokumentov izvlečejo strukturirane podatke na podlagi sheme, ki jo vnaprej določiš. Opišeš, kaj iščeš, model to samodejno izvleče in tvoja aplikacija prejme tipizirana polja namesto zidu besedila, ki bi ga moral parsati z regularnimi izrazi.

Dve ravni analize

Document AI razlikuje med dvema vrstama opomb glede na obseg, na katerem delujeta.

Opombe omejevalnih okvirjev (bbox_annotation) se osredotočajo na slike in grafiko, ki jih je OCR izoliral. Vidni model vsak omejevalni okvir obdela posebej, da opiše njegovo vsebino. V letnem poročilu ti ta mehanizem omogoča opisovanje grafikov in diagramov, razvrščanje slik (fotografija, logotip, shema, graf) in ekstrakcijo besedilne vsebine iz vgrajenih slik – trije podatki, ki jih standardna ekstrakcija besedila sistematično spregleda.

Opombe k dokumentu (document_annotation) obravnavajo datoteko kot celoto. Model analizira izvlečeni Markdown skupaj s prvimi osmimi slikami, nato pa vrne tisto, kar si zahteval: strukturirana polja, kot so ime, datum ali znesek; vrsto dokumenta; povzetek vsebine ali odgovor na specifično vprašanje. To je orodje za serijsko obdelavo, ki ga boš vključil v svoja delovna opravila za račune, obrazce in pogodbe.

Shema Pydantic kot pogodba

Opombe se zanašajo na modele Pydantic za definiranje izhodne strukture. Vsak atribut postane polje za ekstrakcijo, njegov description pa služi kot navodilo modelu: nosi enako težo kot 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)")

Opombanje celotnega dokumenta

Klic ostane enak kot pri OCR: preprosto dodaš parameter document_annotation_format, ki ga napolniš z response_format_from_pydantic_model(). Ta tvojo shemo prevede v shemo, ki jo API lahko uporabi. Ob vrnitvi pride opomba kot niz JSON, ki ga ponovno validiraš s Pydanticom, da dobiš varen objekt Python.

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
    )
)

# Opomba k dokumentu je del odgovora, ne vsake strani posebej
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}")

Opisovanje vizualnih elementov enega za drugim

Pri slikah je načelo enako, vendar se parameter spremeni, rezultate pa beremo iz page.images in ne neposredno iz strani. Upoštevaj include_image_base64=True: brez tega izgubiš vizualne elemente, ki jih je model pravkar opisal.

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
)

# Dostop do opomb slik
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}")

Nihče te ne sili, da bi izbiral med obema: pri ilustriranem poročilu boš običajno želel tako metapodatke dokumenta kot opis njegovih grafikov, kar zajame en sam klic z uporabo obeh formatov.

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
)

Vodenje ekstrakcije s pozivom

Shema opisuje pričakovano obliko, ne pa konteksta dokumenta. Ko so tvoja polja dvoumna – več datumov, več zneskov, dva podobna razdelka – document_annotation_prompt pomaga razrešiti dvom tako, da modelu pove naravo dokumenta in kaj naj ima prednost. Pri francoski komercialni pogodbi ta okvirni stavek pogosto naredi razliko med uporabno ekstrakcijo in približnim polnjenjem.

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 ugotovitve

  • Dve vrsti opomb: bbox_annotation za slike, document_annotation za celoten dokument
  • Sheme Pydantic določajo strukturo podatkov za ekstrakcijo
  • Uporabi response_format_from_pydantic_model() za pretvorbo sheme
  • document_annotation_prompt vodi ekstrakcijo s kontekstualnimi navodili
  • Obe vrsti lahko združiš v enem samem klicu