Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Annotatsioonide API

Õppetund 9 / 16 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Rohkem kui lihtsalt teksti eraldamine
  2. Kaks analüüsi taset
  3. Pydanticu skeem lepinguna
  4. Terve dokumendi annoteerimine
  5. Visuaalide kirjeldamine ükshaaval
  6. Eraldamise juhtimine vihjega
  7. Peamised punktid

Uuendatud 2. novembril 2026 — OCR. OCR 4.0 (mistral-ocr-4-0) võeti kasutusest välja 30. septembril 2026. Kasuta OCR 4.1 (mistral-ocr-4-1), mis on olnud üldkasutatav alates 31. augustist sama hinnaga, või aliast mistral-ocr-latest, mis on sellele viidanud alates 16. juulist. OCR 4.1 lisab usaldusväärsuse hinnangud ploki tasandil. Lisandus 3. novembrist: Eelmine näide kasutas igal lehel välja page.document_annotation; mistralai SDK versioonis 3.7.0 kuulub see väli OCR-i vastusele (ocr_response.document_annotation), samas kui lehed sisaldavad vaid oma sisu ja pilte; pildi annotatsioonid loetakse välja image.image_annotation kaudu.

Rohkem kui lihtsalt teksti eraldamine

OCR annab sulle toorteksti: täpse ja täieliku, kuid liigendamata. Saad Markdowni, mitte andmeid. Annotatsioonid astuvad järgmise sammu: need eraldavad dokumentidest struktureeritud andmeid sinu eelnevalt määratletud skeemi põhjal. Kirjeldad, mida otsid, mudel eraldab selle automaatselt ja sinu rakendus saab tüübitud väljad, mitte tekstiseina, mida peaksid regulaaravaldistega parsima.

Kaks analüüsi taset

Document AI eristab kahte tüüpi annotatsioone sõltuvalt skaalast, millel need toimivad.

Piirava kasti annotatsioonid (bbox_annotation) keskenduvad piltidele ja graafikale, mille OCR on eraldanud. Visioonimudel töötleb iga piiravat kasti eraldi, et kirjeldada selle sisu. Aastaaruandes võimaldab see mehhanism kirjeldada diagramme ja skeeme, liigitada pilte (foto, logo, skeem, graafik) ja eraldada tekstisisu manustatud piltidest – kolm teavetükki, mida standardne teksti eraldamine süstemaatiliselt ignoreerib.

Dokumendi annotatsioonid (document_annotation) käsitlevad faili tervikuna. Mudel analüüsib eraldatud Markdowni koos esimese kaheksa pildiga ja tagastab siis selle, mida küsisid: struktureeritud väljad nagu nimi, kuupäev või summa; dokumendi tüüp; sisukokkuvõte või vastus konkreetsele küsimusele. See on tööriist mahutöötluseks, mille ühendad oma arvete, vormide ja lepingute töövoogudesse.

Pydanticu skeem lepinguna

Annotatsioonid tuginevad väljundstruktuuri defineerimisel Pydanticu mudelitele. Iga atribuut muutub eraldatavaks väljaks ja selle description toimib mudelile juhendina: see kannab sama palju kaalu kui välja nimi ise.

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

Terve dokumendi annoteerimine

Päring jääb samaks nagu OCR-i puhul: lisad lihtsalt parameetri document_annotation_format, mis täidetakse funktsiooniga response_format_from_pydantic_model(). See tõlgib sinu mudeli skeemiks, mida API kasutada saab. Tagastamisel saabub annotatsioon JSON-stringina, mille valideerid uuesti Pydanticuga, et saada turvaline Pythoni 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
    )
)

# Dokumendi annotatsioon kuulub vastusele, mitte igale lehele eraldi
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}")

Visuaalide kirjeldamine ükshaaval

Piltide puhul on printsiip identne, kuid parameeter muutub ja tulemusi loetakse page.images seast, mitte lehelt endalt. Pane tähele include_image_base64=True: ilma selleta kaotad visuaalid, mida mudel just kirjeldas.

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
)

# Ligipääs pildi annotatsioonidele
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}")

Midagi ei sunni sind kahe variandi vahel valima: illustreeritud aruande puhul soovid tavaliselt nii dokumendi metaandmeid kui ka selle diagrammide kirjeldust, mida üksainus päring katab, kui edastad mõlemad formaadid.

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
)

Eraldamise juhtimine vihjega

Skeem kirjeldab oodatavat kuju, mitte dokumendi konteksti. Kui sinu väljad on mitmetimõistetavad – mitu kuupäeva, mitu summat, kaks sarnast lõiku – aitab document_annotation_prompt kahtluse lahendada, öeldes mudelile dokumendi olemuse ja selle, millele keskenduda. Prantsuse äri lepingu puhul teeb see raamistav lause sageli vahet kasutatava eraldamise ja ligikaudse täitmise vahel.

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

Peamised punktid

  • Kahte tüüpi annotatsioonid: bbox_annotation piltide jaoks ja document_annotation kogu dokumendi jaoks
  • Pydanticu skeemid määratlevad eraldatavate andmete struktuuri
  • Kasuta funktsiooni response_format_from_pydantic_model() skeemi teisendamiseks
  • document_annotation_prompt juhendab eraldamist kontekstipõhiste juhistega
  • Mõlemat tüüpi saab kombineerida ühes päringus