L-API tal-Annotazzjonijiet
F'din il-paġna
Aġġornat fit-2 ta’ Novembru, 2026 — OCR. L-OCR 4.0 (
mistral-ocr-4-0) ġie rtirat fit-30 ta’ Settembru, 2026. Uża l-OCR 4.1 (mistral-ocr-4-1), li ilu disponibbli ġeneralment mill-31 ta’ Awwissu bl-istess prezz, jew l-aliasmistral-ocr-latest, li jipponta lejh mis-16 ta’ Lulju. L-OCR 4.1 iżid punteġġi ta’ kunfidenza fil-livell tal-blokki. Addendum mit-3 ta’ Novembru: L-eżempju preċedenti kien jaqrapage.document_annotationfuq kull paġna; fl-SDKmistralai3.7.0, dan il-qasam jappartjeni għar-rispons tal-OCR (ocr_response.document_annotation), filwaqt li l-paġni fihom biss il-kontenut u l-immaġnijiet tagħhom; l-annotazzjonijiet tal-immaġni jinqraw minnimage.image_annotation.
Aktar mill-Estrazzjoni tat-Test
L-OCR jagħtitek test raw: fidil u sħiħ, iżda mingħajr differenzazzjoni. Tikseb Markdown, mhux dejta. L-annotazzjonijiet jieħdu l-pass li jmiss: jestrattu dejta strutturata mid-dokumenti tiegħek ibbażata fuq skema li tiddefinixxi minn qabel. Tiddeskrivi x’inhu qed tfittex, il-mudell jestrah awtomatikament, u l-applikazzjoni tiegħek tirċievi oqsma ttajpjjati minflok ħajt ta’ test li trid tanalizza b’espressjonijiet regolari.
Żewġ Livelli ta’ Analiżi
Id-Document AI jiddistingwi bejn żewġ tipi ta’ annotazzjonijiet ibbażati fuq l-iskala li fuqha joperaw.
L-annotazzjonijiet tal-kaxxa tal-limitu (bbox_annotation) jiffukaw fuq l-immaġnijiet u l-grafika li l-OCR iżola. Il-mudell tal-viżjoni jipproċessa kull kaxxa tal-limitu individwalment biex jiddeskrivi l-kontenut tagħha. F’rapport annwali, dan il-mekkaniżmu jħallik tiddeskrivi grafiċi u dijagrammi, tikklassifika immaġnijiet (ritratt, logo, skematiku, grafu), u testratti kontenut testwali minn immaġnijiet inkorporati—tliet biċċiet ta’ informazzjoni li l-estrazzjoni standard tat-test titlifha sistematikament.
L-annotazzjonijiet tad-dokument (document_annotation) jittrattaw il-fajl bħala totalità. Il-mudell janalizza l-Markdown estratt flimkien mal-ewwel tmien immaġnijiet, imbagħad jirritorna dak li tlift: oqsma strutturati bħal isem, data, jew ammont; it-tip tad-dokument; sommarju tal-kontenut; jew tweġiba għal mistoqsija speċifika. Dan huwa l-għodda għall-ipproċessar bil-kwantità, dik li se tikkonnettja mal-flussi tax-xogħol tal-fatturi, il-formoli u l-kuntratti tiegħek.
L-Iskema Pydantic Taġixxi bħala l-Kuntratt
L-annotazzjonijiet jiddependu fuq mudelli Pydantic biex jiddefinixxu l-istruttura tal-output. Kull attribut isir qasam li għandu jiġi estratt, u d-description tiegħu sservi bħala istruzzjoni għall-mudell: iġorr daqsxejn l-istess piż bħall-isem tal-qasam innifsu.
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)")
L-Annotazzjoni ta’ Dokument Sħiħ
Is-sejħa tibqa’ l-istess bħall-OCR: sempliċiment iżżid il-parametru document_annotation_format, mimli minn response_format_from_pydantic_model(), li jittrasforma l-mudell tiegħek f’iskema li l-API tista’ tuża. Fir-ritorn, l-annotazzjoni tasal bħala stringa JSON, li terġa’ tivvalida ma’ Pydantic biex tikseb oġġett Python sikur.
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
)
)
# L-annotazzjoni tad-dokument tinġarr mir-rispons, mhux minn kull paġna
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}")
Id-Deskrizzjoni tal-Viżwali Waħda waħda
Għall-immaġnijiet, il-prinċipju huwa identiku iżda l-parametru jinbidel, u r-riżultati jinqraw minn page.images minflok mill-paġna nnifisha. Innota include_image_base64=True: mingħajru, titlef il-viżwali li l-mudell għadu kemm iddeskriva.
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
)
# Aċċess għall-annotazzjonijiet tal-immaġni
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}")
Xejn ma jfurzak tagħżel bejn iż-żewġ: fuq rapport illustrat, ġeneralment se tkun trid kemm il-metadejta tad-dokument kif ukoll id-deskrizzjoni tal-grafiki tiegħu, li sejħa waħda tkopri billi tgħaddi ż-żewġ formati.
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
)
Gwida tal-Estrazzjoni b’Prompt
Skema tiddeskrivi l-forma mistennija, mhux il-kuntest tad-dokument. Meta l-oqsma tiegħek ikunu ambigwi—diversi dati, diversi ammonti, żewġ taqsimiet simili—document_annotation_prompt jgħin biex issolvi d-dubju billi jgħid lill-mudell in-natura tad-dokument u x’għandu jipprivileġġja. Fuq kuntratt kummerċjali Franċiż, din is-sentenza ta’ qafas spiss tagħmel id-differenza bejn estrazzjoni użabbli u mimli approssimattiv.
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."
)
)
Punti Ewlenin
- Żewġ tipi ta’ annotazzjonijiet:
bbox_annotationgħall-immaġnijiet,document_annotationgħad-dokument kollu - L-iskemi Pydantic jiddefinixxu l-istruttura tad-dejta li għandha tiġi estratta
- Uża
response_format_from_pydantic_model()biex tikkonverti l-iskema - Il-
document_annotation_promptjiggwida l-estrazzjoni b’istruzzjonijiet kuntestwali - Iż-żewġ tipi jistgħu jiġu kkombinati f’sejħa waħda