Annotatsioonide API
Sellel lehel
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 aliastmistral-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äljapage.document_annotation;mistralaiSDK 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äljaimage.image_annotationkaudu.
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_annotationpiltide jaoks jadocument_annotationkogu dokumendi jaoks - Pydanticu skeemid määratlevad eraldatavate andmete struktuuri
- Kasuta funktsiooni
response_format_from_pydantic_model()skeemi teisendamiseks document_annotation_promptjuhendab eraldamist kontekstipõhiste juhistega- Mõlemat tüüpi saab kombineerida ühes päringus