Interfejs API adnotacji
Na tej stronie
Zaktualizowano 2 listopada 2026 r. — OCR. Wersja OCR 4.0 (
mistral-ocr-4-0) została wycofana 30 września 2026 r. Używaj OCR 4.1 (mistral-ocr-4-1), który jest ogólnie dostępny od 31 sierpnia w tej samej cenie, lub aliasumistral-ocr-latest, który wskazuje na tę wersję od 16 lipca. OCR 4.1 dodaje wyniki pewności na poziomie bloków. Dodatkowa uwaga z 3 listopada: Poprzedni przykład odwoływał się dopage.document_annotationna każdej stronie; w SDKmistralaiw wersji 3.7.0 pole to należy do odpowiedzi OCR (ocr_response.document_annotation), podczas gdy strony zawierają tylko swoją treść i obrazy; adnotacje obrazów odczytuje się zimage.image_annotation.
Więcej niż tylko ekstrakcja tekstu
OCR dostarcza surowy tekst: wierny i kompletny, ale nieustrukturyzowany. Otrzymujesz Markdown, a nie dane. Adnotacje to kolejny krok: ekstrahują one ustrukturyzowane dane z Twoich dokumentów na podstawie schematu zdefiniowanego wcześniej. Opisujesz, czego szukasz, model automatycznie to ekstrahuje, a Twoja aplikacja otrzymuje typowane pola zamiast ściany tekstu do parsowania za pomocą wyrażeń regularnych.
Dwa poziomy analizy
Document AI rozróżnia dwa rodzaje adnotacji w zależności od skali, na jakiej działają.
Adnotacje ograniczników (bbox_annotation) koncentrują się na obrazach i grafikach, które wyizolował OCR. Model wizyjny przetwarza każdy ogranicznik indywidualnie, aby opisać jego zawartość. W raporcie rocznym mechanizm ten pozwala opisywać wykresy i diagramy, klasyfikować obrazy (zdjęcie, logo, schemat, wykres) oraz ekstrahować treść tekstową z osadzonych obrazów — trzy elementy informacji, które standardowa ekstrakcja tekstu systematycznie pomija.
Adnotacje dokumentu (document_annotation) traktują plik jako całość. Model analizuje wyekstrahowany Markdown wraz z pierwszych ośmioma obrazami, a następnie zwraca to, o co poprosiłeś: ustrukturyzowane pola, takie jak nazwisko, data czy kwota; typ dokumentu; podsumowanie treści lub odpowiedź na konkretne pytanie. To narzędzie do przetwarzania wsadowego, które podłączysz do swoich przepływów pracy dotyczących faktur, formularzy i umów.
Schemat Pydantic jako kontrakt
Adnotacje opierają się na modelach Pydantic w celu zdefiniowania struktury wyjścia. Każdy atrybut staje się polem do wyekstrahowania, a jego description służy jako instrukcja dla modelu: niesie tyle samo wagi, co sama nazwa pola.
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)")
Adnotowanie całego dokumentu
Wywołanie pozostaje takie samo jak w przypadku OCR: po prostu dodajesz parametr document_annotation_format, wypełniony przez response_format_from_pydantic_model(), który tłumaczy Twój model na schemat zrozumiały dla API. Po powrocie adnotacja przychodzi jako ciąg JSON, który ponownie walidujesz za pomocą Pydantic, aby uzyskać bezpieczny obiekt Pythona.
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
)
)
# Adnotacja dokumentu jest przenoszona przez odpowiedź, a nie przez każdą stronę
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}")
Opisywanie wizualizacji jedna po drugiej
W przypadku obrazów zasada jest identyczna, ale parametr się zmienia, a wyniki odczytuje się z page.images, a nie z samej strony. Zwróć uwagę na include_image_base64=True: bez niego tracisz wizualizacje, które model właśnie opisał.
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
)
# Dostęp do adnotacji obrazów
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}")
Nic nie zmusza Cię do wyboru między tymi dwiema opcjami: w przypadku ilustrowanego raportu zazwyczaj chcesz uzyskać zarówno metadane dokumentu, jak i opis jego wykresów, co pokrywa pojedyncze wywołanie poprzez przekazanie obu formatów.
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
)
Kierowanie ekstrakcją za pomocą monitu (prompt)
Schemat opisuje oczekiwany kształt, a nie kontekst dokumentu. Gdy Twoje pola są niejednoznaczne — wiele dat, wiele kwot, dwie podobne sekcje — document_annotation_prompt pomaga rozwiać wątpliwości, informując model o naturze dokumentu i tym, co ma być priorytetem. W przypadku francuskiej umowy handlowej to zdanie ramowe często decyduje o tym, czy ekstrakcja będzie użyteczna, czy tylko przybliżona.
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."
)
)
Kluczowe wnioski
- Dwa rodzaje adnotacji:
bbox_annotationdla obrazów,document_annotationdla całego dokumentu - Schematy Pydantic definiują strukturę danych do wyekstrahowania
- Użyj
response_format_from_pydantic_model(), aby przekonwertować schemat document_annotation_promptkieruje ekstrakcją dzięki instrukcjom kontekstowym- Obie rodzaje można łączyć w jednym wywołaniu