Annotations-API'en
På denne side
Opdateret 2. november 2026 — OCR. OCR 4.0 (
mistral-ocr-4-0) blev udfaset den 30. september 2026. Brug OCR 4.1 (mistral-ocr-4-1), som har været generelt tilgængelig siden 31. august til samme pris, eller aliassetmistral-ocr-latest, som har peget på det siden 16. juli. OCR 4.1 tilføjer konfidensscorer på blokniveau. Tillæg fra 3. november: Det tidligere eksempel læstepage.document_annotationpå hver side; imistralaiSDK 3.7.0 hører dette felt til OCR-svaret (ocr_response.document_annotation), mens sider kun indeholder deres indhold og billeder; billedannotationer læses fraimage.image_annotation.
Ud over tekstudtrækning
OCR giver dig råtekst: trofast og komplet, men udifferentieret. Du får Markdown, ikke data. Annotationer tager næste skridt: de udtrækker strukturerede data fra dine dokumenter baseret på et skema, du definerer på forhånd. Du beskriver, hvad du leder efter, modellen udtrækker det automatisk, og din applikation modtager typede felter i stedet for en mur af tekst, som skal parses med regulære udtryk.
To analyse-niveauer
Document AI skelner mellem to typer annotationer baseret på den skala, de opererer på.
Bounding box-annotationer (bbox_annotation) fokuserer på de billeder og grafikker, som OCR har isoleret. Synsmodellen behandler hver bounding box individuelt for at beskrive dens indhold. I en årsrapport lader denne mekanisme dig beskrive diagrammer og tegninger, klassificere billeder (foto, logo, skematisk tegning, graf) og udtrække tekstligt indhold fra indlejrede billeder – tre informationer, som standard tekstudtrækning systematisk overser.
Dokumentannotationer (document_annotation) behandler filen som en helhed. Modellen analyserer den udtrukne Markdown sammen med de første otte billeder og returnerer derefter det, du bad om: strukturerede felter som et navn, en dato eller et beløb; dokumenttypen; et indholdsresumé; eller et svar på et specifikt spørgsmål. Dette er værktøjet til massebehandling, det du kobler til dine workflows for fakturaer, formularer og kontrakter.
Pydantic-skemaet fungerer som kontrakten
Annotationer afhænger af Pydantic-modeller til at definere output-strukturen. Hver attribut bliver et felt, der skal udtrækkes, og dens description fungerer som en instruktion til modellen: den bærer lige så meget vægt som selve feltnavnet.
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)")
Annotering af et helt dokument
Kaldet forbliver det samme som for OCR: du tilføjer blot parameteren document_annotation_format, udfyldt af response_format_from_pydantic_model(), som oversætter din model til et skema, som API’en kan bruge. Ved returnering ankommer annotationen som en JSON-streng, som du genvaliderer med Pydantic for at få et sikkert Python-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
)
)
# Dokumentannotationen bæres af svaret, ikke af hver side
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}")
Beskrivelse af visuelle elementer én efter én
For billeder er princippet identisk, men parameteren ændrer sig, og resultaterne læses fra page.images snarere end fra selve siden. Bemærk include_image_base64=True: uden det mister du de visuelle elementer, som modellen lige har beskrevet.
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
)
# Adgang til billedannotationer
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}")
Intet tvinger dig til at vælge mellem de to: på en illustreret rapport vil du typisk ønske både dokumentets metadata og en beskrivelse af dets diagrammer, hvilket et enkelt kald dækker ved at sende begge formater.
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
)
Styring af udtrækning med et prompt
Et skema beskriver den forventede form, ikke dokumentets kontekst. Når dine felter er tvetydige – flere datoer, flere beløb, to lignende sektioner – hjælper document_annotation_prompt med at løse tvivlen ved at fortælle modellen dokumentets art og hvad der skal prioriteres. På en fransk handelskontrakt gør denne rammesætning ofte forskellen mellem brugbar udtrækning og omtrentlig udfyldning.
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."
)
)
Vigtige pointer
- To typer annotationer:
bbox_annotationtil billeder,document_annotationtil hele dokumentet - Pydantic-skemaer definerer strukturen på de data, der skal udtrækkes
- Brug
response_format_from_pydantic_model()til at konvertere skemaet document_annotation_promptguider udtrækningen med kontekstuelle instrukser- Begge typer kan kombineres i et enkelt kald