API-ul de Adnotări
Pe această pagină
Actualizat la 2 noiembrie 2026 — OCR. OCR 4.0 (
mistral-ocr-4-0) a fost retras la 30 septembrie 2026. Utilizați OCR 4.1 (mistral-ocr-4-1), disponibil public din 31 august la același preț, sau aliasulmistral-ocr-latest, care indică această versiune din 16 iulie. OCR 4.1 adaugă scoruri de încredere la nivel de bloc. Addendum din 3 noiembrie: Exemplul anterior citeapage.document_annotationpe fiecare pagină; în SDK-ulmistralai3.7.0, acest câmp aparține răspunsului OCR (ocr_response.document_annotation), în timp ce paginile conțin doar conținutul și imaginile lor; adnotările imaginilor se citesc dinimage.image_annotation.
Dincolo de Extracția Textului
OCR vă oferă text brut: fidel și complet, dar nediferențiat. Obțineți Markdown, nu date structurate. Adnotările fac pasul următor: extrag date structurate din documentele dumneavoastră pe baza unei scheme definite în prealabil. Descrieți ceea ce căutați, modelul extrage automat aceste informații, iar aplicația dumneavoastră primește câmpuri tipizate în loc de un zid de text pe care ar trebui să îl parseze cu expresii regulate.
Două Niveluri de Analiză
Document AI distinge între două tipuri de adnotări, în funcție de scala la care operează.
Adnotările de casetă de delimitare (bbox_annotation) se concentrează pe imaginile și graficele pe care OCR le-a izolat. Modelul de viziune procesează fiecare casetă de delimitare individual pentru a-i descrie conținutul. Într-un raport anual, acest mecanism vă permite să descrieți grafice și diagrame, să clasificați imaginile (fotografie, logo, schemă, grafic) și să extrageți conținut textual din imaginile încorporate — trei informații pe care extracția standard de text le ignorează sistematic.
Adnotările de document (document_annotation) tratează fișierul ca un întreg. Modelul analizează Markdown-ul extras împreună cu primele opt imagini, apoi returnează ceea ce ați solicitat: câmpuri structurate precum un nume, o dată sau o sumă; tipul documentului; un rezumat al conținutului; sau un răspuns la o întrebare specifică. Acesta este instrumentul pentru procesarea în lot, cel pe care îl veți integra în fluxurile de lucru pentru facturi, formulare și contracte.
Schema Pydantic Acționează ca un Contract
Adnotările se bazează pe modele Pydantic pentru a defini structura de ieșire. Fiecare atribut devine un câmp de extras, iar description sa servește drept instrucțiune pentru model: acesta are la fel de multă greutate ca și numele câmpului însuși.
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)")
Adnotarea unui Întreg Document
Apelul rămâne același ca pentru OCR: adăugați pur și simplu parametrul document_annotation_format, populat de response_format_from_pydantic_model(), care traduce modelul dumneavoastră într-o schemă pe care API-ul o poate utiliza. La returnare, adnotarea sosește sub formă de șir JSON, pe care îl revalidați cu Pydantic pentru a obține un obiect Python sigur.
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
)
)
# Adnotarea documentului este purtată de răspuns, nu de fiecare pagină
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}")
Descrierea Elementelor Vizuale Unu câte Unu
Pentru imagini, principiul este identic, dar parametrul se schimbă, iar rezultatele se citesc din page.images și nu din pagină în sine. Rețineți include_image_base64=True: fără acesta, pierdeți elementele vizuale pe care modelul tocmai le-a descris.
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
)
# Accesarea adnotărilor imaginilor
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}")
Nimic nu vă obligă să alegeți între cele două: într-un raport ilustrat, veți dori în general atât metadatele documentului, cât și descrierea graficelor sale, lucru pe care un singur apel îl poate acoperi transmițând ambele formate.
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
)
Ghidarea Extracției cu un Prompt
O schemă descrie forma așteptată, nu contextul documentului. Când câmpurile dumneavoastră sunt ambigue — multiple date, multiple sume, două secțiuni similare — document_annotation_prompt ajută la rezolvarea dubiului spunând modelului natura documentului și ce trebuie prioritizat. Într-un contract comercial francez, această propoziție de încadrare face adesea diferența dintre o extracție utilizabilă și o completare aproximativă.
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."
)
)
Puncte cheie
- Două tipuri de adnotări:
bbox_annotationpentru imagini,document_annotationpentru întregul document - Schemele Pydantic definesc structura datelor de extras
- Utilizați
response_format_from_pydantic_model()pentru a converti schema document_annotation_promptghidează extracția cu instrucțiuni contextuale- Ambele tipuri pot fi combinate într-un singur apel