Annotations API
Tällä sivulla
Päivitetty 2. marraskuuta 2026 — OCR. OCR 4.0 (
mistral-ocr-4-0) poistettiin käytöstä 30. syyskuuta 2026. Käytä OCR 4.1:tä (mistral-ocr-4-1), joka on ollut yleisesti saatavilla 31. elokuuta lähtien samaan hintaan, tai aliastamistral-ocr-latest, joka on viitannut siihen 16. heinäkuuta lähtien. OCR 4.1 lisää luottamusluvut lohko tasolla. Lisäys 3. marraskuuta: Edellinen esimerkki lukipage.document_annotationjokaiselta sivulta;mistralaiSDK 3.7.0:ssa tämä kenttä kuuluu OCR-vastaukseen (ocr_response.document_annotation), kun taas sivut sisältävät vain sisältönsä ja kuvansa; kuva-annotoinnit luetaan kohdastaimage.image_annotation.
Tekstin erottelun tuolla puolen
OCR tarjoaa raakatekstiä: uskollista ja täydellistä, mutta erottelutonta. Saat Markdownia, et dataa. Annotoinnit vievät askeleen pidemmälle: ne erottavat jäsenneltyä dataa dokumenteistasi etukäteen määrittelemäsi skeeman perusteella. Kuvailet, mitä etsit, malli poimii sen automaattisesti, ja sovelluksesi vastaanottaa tyypitetyt kentät säännöllisillä lausekkeilla parsittavan tekstiseinän sijaan.
Kaksi analyysitasoa
Document AI erottaa kaksi annotointityyppiä niiden toimintaskaalan perusteella.
Rajauslaatikkoannotoinnit (bbox_annotation) keskittyvät kuviin ja grafiikkaan, jotka OCR on eristänyt. Visiomalli käsittelee jokaisen rajauslaatikon erikseen kuvatakseen sen sisällön. Vuosikertomuksessa tämä mekanismi mahdollistaa kaavioiden ja diagrammien kuvaamisen, kuvien luokittelun (valokuva, logo, kaavio, graafi) ja upotettujen kuvien tekstisisällön erottamisen – kolme tietoa, jotka vakiotekstierottelu systemaattisesti ohittaa.
Dokumenttiannotoinnit (document_annotation) käsittelevät tiedostoa kokonaisuutena. Malli analysoi erotetun Markdownin yhdessä kahdeksan ensimmäisen kuvan kanssa ja palauttaa pyytämäsi: jäsennellyt kentät kuten nimen, päivämäärän tai summan; dokumenttityypin; sisältöyhteenvedon; tai vastauksen tiettyyn kysymykseen. Tämä on työkalu massakäsittelyyn, se jonka kytket lasku-, lomake- ja sopimusvirtoihisi.
Pydantic-skeema toimii sopimuksena
Annotoinnit luottavat Pydantic-malleihin määritelläkseen tulosteen rakenteen. Jokaisesta attribuutista tulee erotettava kenttä, ja sen description toimii ohjeena mallille: se painaa yhtä paljon kuin kentän nimi itse.
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)")
Koko dokumentin annotointi
Kutsu pysyy samana kuin OCR:ssä: lisäät vain parametrin document_annotation_format, jonka täytät funktiolla response_format_from_pydantic_model(). Tämä muuntaa mallisi skeemaksi, jota API voi käyttää. Paluuarvona annotointi saapuu JSON-merkkijonona, jonka validoit uudelleen Pydanticilla saadaksesi turvallisen Python-objektin.
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
)
)
# Dokumenttiannotointi kulkee vastauksen mukana, ei jokaisella sivulla
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}")
Visuaalisten elementtien kuvaaminen yksi kerrallaan
Kuvien osalta periaate on sama, mutta parametri muuttuu, ja tulokset luetaan kohdasta page.images eikä itse sivulta. Huomaa include_image_base64=True: ilman sitä menetät visuaaliset elementit, jotka malli juuri kuvasi.
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
)
# Käytä kuva-annotointeja
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}")
Mikään ei pakota sinua valitsemaan näiden välillä: kuvitetussa raportissa haluat yleensä sekä dokumentin metadataa että sen kaavioiden kuvauksen, mihin yksi kutsu riittää välittämällä molemmat formaatit.
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
)
Erottelun ohjaaminen kehotteella
Skeema kuvaa odotettua muotoa, ei dokumentin kontekstia. Kun kenttäsi ovat monitulkintaisia – useita päivämääriä, useita summia, kaksi samankaltaista osiota – document_annotation_prompt auttaa ratkaisemaan epäselvyyden kertomalla mallille dokumentin luonteen ja sen, mitä tulee priorisoida. Ranskalaisessa kaupallisessa sopimuksessa tämä kehystävä lause tekee usein eron käyttökelpoisen erottelun ja likimääräisen täytön välillä.
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."
)
)
Keskeiset asiat
- Kaksi annotointityyppiä:
bbox_annotationkuville,document_annotationkoko dokumentille - Pydantic-skeemat määrittelevät erotettavan datan rakenteen
- Käytä
response_format_from_pydantic_model()skeeman muuntamiseen document_annotation_promptohjaa erottelua kontekstuaalisilla ohjeilla- Molemmat tyypit voidaan yhdistää yhteen kutsuun