API:en för annoteringar
På denna sida
Uppdaterad 2 november 2026 — OCR. OCR 4.0 (
mistral-ocr-4-0) togs ur bruk den 30 september 2026. Använd OCR 4.1 (mistral-ocr-4-1), som har varit allmänt tillgänglig sedan 31 augusti till samma pris, eller aliasetmistral-ocr-latest, som har pekat på den sedan 16 juli. OCR 4.1 lägger till konfidenspoäng på blocknivå. Tillägg från 3 november: Det tidigare exemplet lästepage.document_annotationpå varje sida; imistralaiSDK 3.7.0 tillhör detta fält OCR-svaret (ocr_response.document_annotation), medan sidor endast innehåller sitt innehåll och sina bilder; bildannoteringar läses frånimage.image_annotation.
Utöver textextrahering
OCR ger dig råtext: trogen och komplett, men odifferentierad. Du får Markdown, inte data. Annoteringar tar nästa steg: de extraherar strukturerad data från dina dokument baserat på ett schema du definierar i förväg. Du beskriver vad du letar efter, modellen extraherar det automatiskt, och din applikation får typade fält istället för en vägg av text som måste parsas med reguljära uttryck.
Två analysnivåer
Document AI skiljer mellan två typer av annoteringar beroende på den skala de opererar på.
Bounding box-annoteringar (bbox_annotation) fokuserar på de bilder och grafik som OCR har isolerat. Synmodellen bearbetar varje bounding box individuellt för att beskriva dess innehåll. I en årsredovisning låter denna mekanism dig beskriva diagram och illustrationer, klassificera bilder (foto, logotyp, schematisk bild, graf) och extrahera textinnehåll från inbäddade bilder – tre informationsbitar som standardtextextrahering systematiskt förbiser.
Dokumentannoteringar (document_annotation) behandlar filen som en helhet. Modellen analyserar den extraherade Markdown-koden tillsammans med de första åtta bilderna och returnerar sedan det du bad om: strukturerade fält som ett namn, ett datum eller ett belopp; dokumenttypen; en innehållssammanfattning; eller ett svar på en specifik fråga. Detta är verktyget för bulkbearbetning, det du kopplar in i dina arbetsflöden för fakturor, formulär och kontrakt.
Pydantic-schemat fungerar som kontraktet
Annoteringar förlitar sig på Pydantic-modeller för att definiera utdatastrukturen. Varje attribut blir ett fält att extrahera, och dess description fungerar som en instruktion till modellen: den bär lika mycket tyngd som själva fältnamnet.
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)")
Annotera ett helt dokument
Anropet förblir detsamma som för OCR: du lägger helt enkelt till parametern document_annotation_format, populated av response_format_from_pydantic_model(), vilket översätter din modell till ett schema som API:et kan använda. Vid retur anländer annoteringen som en JSON-sträng, som du validerar om med Pydantic för att få ett säkert 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
)
)
# Dokumentannoteringen bärs av svaret, inte av varje sida
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}")
Beskriva visuella element ett efter ett
För bilder är principen identisk men parametern ändras, och resultaten läses från page.images snarare än från sidan själv. Notera include_image_base64=True: utan det förlorar du de visuella element som modellen just har beskrivit.
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
)
# Åtkomst till bildannoteringar
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}")
Inget tvingar dig att välja mellan de två: på en illustrerad rapport vill du oftast ha både dokumentmetadata och beskrivningen av dess diagram, vilket ett enda anrop täcker genom att skicka båda formaten.
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
)
Styra extrahering med en prompt
Ett schema beskriver den förväntade formen, inte dokumentets kontext. När dina fält är tvetydiga – flera datum, flera belopp, två liknande sektioner – hjälper document_annotation_prompt till att lösa tvivel genom att berätta för modellen dokumentets natur och vad som ska prioriteras. På ett franskt affärskontrakt gör denna raminstruktion ofta skillnaden mellan en användbar extrahering och en ungefärlig ifyllnad.
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."
)
)
Viktiga punkter
- Två typer av annoteringar:
bbox_annotationför bilder,document_annotationför hela dokumentet - Pydantic-scheman definierar strukturen på den data som ska extraheras
- Använd
response_format_from_pydantic_model()för att konvertera schemat document_annotation_promptstyr extraheringen med kontextuella instruktioner- Båda typerna kan kombineras i ett enda anrop