Az Annotations API
Ezen az oldalon
Frissítve: 2026. november 2. — OCR. Az OCR 4.0 (
mistral-ocr-4-0) szolgáltatást 2026. szeptember 30-án megszüntettük. Használd az OCR 4.1 (mistral-ocr-4-1) verziót, amely augusztus 31. óta általánosan elérhető ugyanazon az áron, vagy amistral-ocr-latestaliast, amely július 16. óta erre mutat. Az OCR 4.1 blokk szintű megbízhatósági pontszámokat (confidence scores) is biztosít. Kiegészítés november 3-tól: A korábbi példa minden oldalon apage.document_annotationmezőt olvasta; amistralaiSDK 3.7.0 verziójában ez a mező az OCR válaszhoz tartozik (ocr_response.document_annotation), míg az oldalak csak a tartalmukat és képeiket tartalmazzák; a kép-annotációkat azimage.image_annotationmezőből olvashatod ki.
Túl a szövegkinyerésen
Az OCR nyers szöveget ad: hűségeset és teljest, de differenciálatlant. Markdownet kapsz, nem pedig adatot. Az annotációk teszik meg a következő lépést: egy előre definiált séma alapján strukturált adatokat vonnak ki a dokumentumaidból. Leírod, mit keresel, a modell automatikusan kinyeri azt, és az alkalmazásod típusos mezőket kap regularis kifejezésekkel parseolandó szövegfal helyett.
Két elemzési szint
A Document AI két típusú annotációt különböztet meg a működési skálájuk alapján.
A bounding box annotációk (bbox_annotation) az OCR által izolált képekre és grafikákra fókuszálnak. A vision modell minden egyes bounding boxot egyedileg dolgoz fel, hogy leírja annak tartalmát. Egy éves jelentésben ez a mechanizmus lehetővé teszi diagramok és ábrák leírását, képek osztályozását (fotó, logó, sematikus ábra, grafikon), valamint a beágyazott képek szöveges tartalmának kinyerését – három információdarabot, amelyet a szabványos szövegkinyerés rendszeresen figyelmen kívül hagy.
A dokumentum-annotációk (document_annotation) a fájlt egészében kezelik. A modell elemzi a kinyert Markdown tartalmat az első nyolc képpel együtt, majd visszaadja azt, amit kértél: strukturált mezőket, mint például nevet, dátumot vagy összeget; a dokumentum típusát; egy tartalmi összefoglalót; vagy választ egy specifikus kérdésre. Ez a tömeges feldolgozás eszköze, amelyet a számla-, űrlap- és szerződésfolyamataidba integrálsz.
A Pydantic séma mint szerződés
Az annotációk Pydantic modellekre támaszkodnak a kimeneti struktúra meghatározásához. Minden attribútum egy kinyerendő mezővé válik, és annak description (leírása) utasításként szolgál a modell számára: ugyanolyan súllyal bír, mint maga a mezőnév.
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)")
Egy teljes dokumentum annotálása
A hívás ugyanaz marad, mint az OCR esetében: egyszerűen hozzáadod a document_annotation_format paramétert, amelyet a response_format_from_pydantic_model() tölt fel; ez lefordítja a modelledet egy olyan sémává, amelyet az API használni tud. Visszatéréskor az annotáció JSON sztringként érkezik, amelyet újraérvényesítesz Pydantic segítségével, hogy egy biztonságos Python objektumot kapj.
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
)
)
# A dokumentum-annotációt a válasz hordozza, nem az egyes oldalak
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}")
A vizuális elemek egyesével történő leírása
Képek esetén az elv ugyanaz, de a paraméter megváltozik, és az eredményeket nem magából az oldalból, hanem a page.images elemből olvasod ki. Figyeld meg az include_image_base64=True beállítást: enélkül elveszíted azokat a vizuális elemeket, amelyeket a modell éppen leírt.
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ép-annotációk hozzáférése
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}")
Semmi sem kényszerít arra, hogy a kettő között válassz: egy illusztrált jelentésnél általában mind a dokumentum metaadatait, mind az ábráinak leírását szeretnéd, amit egyetlen hívás is lefed, ha mindkét formátumot átadod.
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
)
A kinyerés irányítása prompttal
A séma a várt alakzatot írja le, nem a dokumentum kontextusát. Amikor a mezőid ambivalensek – több dátum, több összeg, két hasonló szakasz –, a document_annotation_prompt segít feloldani a kétséget azáltal, hogy közli a modellel a dokumentum jellegét és azt, minek kell elsőbbséget élveznie. Egy francia kereskedelmi szerződésnél ez a keretbe foglaló mondat gyakran teszi a különbséget a használható kinyerés és a hozzávetőleges kitöltés között.
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."
)
)
Főbb megállapítások
- Két típusú annotáció létezik:
bbox_annotationképekhez,document_annotationa teljes dokumentumhoz - A Pydantic sémák határozzák meg a kinyerendő adatok szerkezetét
- Használd a
response_format_from_pydantic_model()függvényt a séma konvertálásához - A
document_annotation_promptkontextuális utasításokkal irányítja a kinyerést - Mindkét típus kombinálható egyetlen hívásban