Przejdź do głównej treści
Polski— Wybierz język
Menu

Interfejs API adnotacji

Lekcja 9 z 16 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Więcej niż tylko ekstrakcja tekstu
  2. Dwa poziomy analizy
  3. Schemat Pydantic jako kontrakt
  4. Adnotowanie całego dokumentu
  5. Opisywanie wizualizacji jedna po drugiej
  6. Kierowanie ekstrakcją za pomocą monitu (prompt)
  7. Kluczowe wnioski

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 aliasu mistral-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ę do page.document_annotation na każdej stronie; w SDK mistralai w 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ę z image.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_annotation dla obrazów, document_annotation dla całego dokumentu
  • Schematy Pydantic definiują strukturę danych do wyekstrahowania
  • Użyj response_format_from_pydantic_model(), aby przekonwertować schemat
  • document_annotation_prompt kieruje ekstrakcją dzięki instrukcjom kontekstowym
  • Obie rodzaje można łączyć w jednym wywołaniu