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

Przypadki użycia adnotacji

Lekcja 12 z 16 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Adnotacje dla każdej roli
  2. Sortuj przed przetworzeniem
  3. Czytaj umowę jak prawnik
  4. Automatycznie weryfikuj zgodność
  5. Nie trać nic przed indeksowaniem
  6. Kluczowe wnioski

Aktualizacja z 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), dostępnej ogólnie od 31 sierpnia w tej samej cenie, lub aliasu mistral-ocr-latest, który wskazuje na nią od 16 lipca. OCR 4.1 dodaje wyniki pewności na poziomie bloków. Dodatkowa informacja z 3 listopada 2026 r.: Lokalny plik PDF jest przesyłany w formacie base64 jako {"type": "document_url", "document_url": "data:application/pdf;base64,…"}; typ document_base64 ze starszych przykładów nie istnieje ani w dokumentacji, ani w SDK mistralai, a te przykłady zakończyłyby się niepowodzeniem. Źródła: Procesor OCR · QnA dotyczące dokumentów. Poprawiono 3 listopada 2026 r.: Poprzedni kod odczytywał page.document_annotation strona po stronie; w SDK mistralai w wersji 3.7.0 adnotacja dokumentu jest pojedynczym polem w odpowiedzi (response.document_annotation), a adnotację obrazu odczytuje się z image.image_annotation.

Adnotacje dla każdej roli

Adnotacje Document AI przekształcają nieustrukturyzowane dokumenty w dane gotowe do działania. Mechanizm jest zawsze ten sam – schemat, monit (prompt), wywołanie – ale to, co ekstrahujesz, zmienia się radykalnie w zależności od roli. Ta lekcja przeprowadzi Cię przez cztery konkretne implementacje: klasyfikację wstępną w potoku przetwarzania, analizę klauzul umownych, sprawdzanie zgodności z przepisami oraz wzbogacanie indeksu RAG.

Sortuj przed przetworzeniem

W rzeczywistym przepływie pracy dokumenty docierają wymieszane: faktura, zamówienie, dowód osobisty, list. Zanim zastosujesz odpowiedni schemat ekstrakcji, musisz wiedzieć, z czym masz do czynienia. Adnotacja służy jako pierwszy etap sortowania. Wyliczenie TypeDocument blokuje dopuszczalne kategorie, wynik pewności pozwala przekierować wszystko poniżej progu do przeglądu przez człowieka, a jednozdaniowe podsumowanie daje operatorom wystarczający kontekst do podjęcia decyzji bez otwierania pliku.

import os
from enum import Enum
from pydantic import BaseModel, Field
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

class TypeDocument(str, Enum):
    INVOICE = "facture"
    PURCHASE_ORDER = "bon_commande"
    CONTRACT = "contrat"
    REPORT = "rapport"
    LETTER = "courrier"
    FORM = "formulaire"
    ID_DOCUMENT = "piece_identite"
    OTHER = "autre"

class Classification(BaseModel):
    document_type: TypeDocument = Field(
        ..., description="Identified document type"
    )
    confidence: float = Field(
        ..., description="Confidence score between 0 and 1"
    )
    language: str = Field(
        ..., description="Primary language (ISO 639-1 code)"
    )
    summary: str = Field(
        ..., description="One-sentence summary of the content"
    )

def classify_document(document_base64: str) -> Classification:
    """Automatically classifies a document."""
    response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "document_url",
            "document_url": f"data:application/pdf;base64,{document_base64}"
        },
        document_annotation_format=response_format_from_pydantic_model(
            Classification
        ),
        document_annotation_prompt=(
            "Identify the type of this document and provide "
            "a summary of its content."
        )
    )

    if response.document_annotation:
        return Classification.model_validate_json(
            response.document_annotation
        )

    raise ValueError("No annotation returned")

Czytaj umowę jak prawnik

Analiza umów to główny przypadek użycia w sektorze prawnym i finansowym, a właśnie tam zagnieżdżone schematy naprawdę błyszczą. Każda Clause (klauzula) niesie swój tytuł, podsumowanie treści, kategorię – poufność, rozwiązanie, zakaz konkurencji, odpowiedzialność, płatność – oraz ocenę ryzyka na trzech poziomach. Sama umowa agreguje te klauzule wraz z danymi stron, datą podpisu, czasem trwania, kwotą i właściwym prawem. Na portfelu dwustu umów z dostawcami uzyskasz w kilka godzin mapowanie, którego nikt nie miał czasu wykonać ręcznie.

Pole risk wymaga ostrzeżenia: jest to ocena wygenerowana przez model, przydatna do priorytetyzacji przeglądu przez prawnika, ale nigdy do jego zastąpienia.

from pydantic import BaseModel, Field
from typing import Optional

class Clause(BaseModel):
    title: str = Field(..., description="Title or number of the clause")
    content: str = Field(..., description="Summary of the clause content")
    clause_type: str = Field(
        ..., description="Type: confidentiality, termination, "
        "non-compete, liability, payment, other"
    )
    risk: str = Field(
        ..., description="Risk level: low, medium, high"
    )

class ContractAnalysis(BaseModel):
    parts: list[str] = Field(
        ..., description="Names of the contracting parts"
    )
    signature_date: Optional[str] = Field(
        None, description="Signature date (YYYY-MM-DD)"
    )
    duration: Optional[str] = Field(
        None, description="Contract duration"
    )
    key_clauses: list[Clause] = Field(
        ..., description="Identified main clauses"
    )
    amount: Optional[float] = Field(
        None, description="Total amount if mentioned"
    )
    jurisdiction: Optional[str] = Field(
        None, description="Applicable jurisdiction"
    )

def analyze_contract(document_base64: str) -> ContractAnalysis:
    """Analyzes a contract and extracts main clauses."""
    response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "document_url",
            "document_url": f"data:application/pdf;base64,{document_base64}"
        },
        document_annotation_format=response_format_from_pydantic_model(
            ContractAnalysis
        ),
        document_annotation_prompt=(
            "Analyze this commercial contract. Identify the parts, "
            "the main clauses, and evaluate the risk level "
            "of each clause."
        )
    )

    if response.document_annotation:
        return ContractAnalysis.model_validate_json(
            response.document_annotation
        )

    raise ValueError("No annotation returned")

Automatycznie weryfikuj zgodność

Kontrola regulacyjna jest szczególnie dobrze dostosowana do adnotacji, ponieważ kryteria są zapisane czarno na białym w prawie. W przypadku francuskiej faktury monit wymienia obowiązki do weryfikacji – obowiązkowe wzmianki (SIRET, wewnętrzny VAT wspólnotowy, warunki płatności, kary za zwłokę), formatowanie kwot, data wystawienia – a schemat wymusza dla każdego kryterium werdykt booleanowski wraz z uzasadnieniem. Otrzymujesz wynik globalny i rekomendacje usprawnień, co wystarcza, aby zablokować niezgodną fakturę, zanim trafi do obiegu płatności.

from pydantic import BaseModel, Field

class CompliancePoint(BaseModel):
    criterion: str = Field(..., description="Compliance criterion checked")
    compliant: bool = Field(..., description="True if compliant, False otherwise")
    justification: str = Field(
        ..., description="Explanation of compliance or non-compliance"
    )

class ComplianceAudit(BaseModel):
    document_type: str = Field(..., description="Type of document audited")
    compliance_points: list[CompliancePoint] = Field(
        ..., description="Compliance points checked"
    )
    global_score: float = Field(
        ..., description="Global compliance score (0-100)"
    )
    recommendations: list[str] = Field(
        ..., description="Improvement recommendations"
    )

def audit_invoice_compliance(document_base64: str) -> ComplianceAudit:
    """Verifies invoice compliance according to French rules."""
    response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "document_url",
            "document_url": f"data:application/pdf;base64,{document_base64}"
        },
        document_annotation_format=response_format_from_pydantic_model(
            ComplianceAudit
        ),
        document_annotation_prompt=(
            "Verify the compliance of this invoice according to "
            "French legal obligations: mandatory mentions "
            "(SIRET, intra-community VAT, payment terms, "
            "late payment penalties), amount formatting, issue date."
        )
    )

    if response.document_annotation:
        return ComplianceAudit.model_validate_json(
            response.document_annotation
        )

    raise ValueError("No annotation returned")

Nie trać nic przed indeksowaniem

Ostatni przypadek użycia, bardziej dyskretny, ale decydujący: przygotowanie treści do indeksu RAG. Indeks zbudowany wyłącznie na Markdown traci wszystko, co było wizualne, a Twoje wyszukiwania nigdy nie odnajdą wykresu zawierającego kluczową liczbę. Poniższa funkcja rekonstruuje, strona po stronie, tekst i opis każdego obrazu, a następnie dodaje metadane wyekstrahowane z dokumentu, tworząc pojedynczy blok gotowy do podziału na fragmenty (chunks).

def enrich_for_rag(ocr_response) -> str:
    """Enriches OCR content with annotations for RAG."""
    parts = []

    for page in ocr_response.pages:
        # Text content
        parts.append(page.markdown)

        # Image annotations (replace images with their description)
        for image in page.images:
            if image.image_annotation:
                parts.append(
                    f"[Description of {image.id}]: {image.image_annotation}"
                )

    # Document annotation: a single one, carried by the response
    if ocr_response.document_annotation:
        parts.append(
            f"[Extracted Metadata]: {ocr_response.document_annotation}"
        )

    return "\n\n".join(parts)

Dodając opisy obrazów i wyekstrahowane metadane do indeksowanej treści, nie tracisz żadnych informacji z oryginalnego dokumentu. Zauważysz, że te cztery scenariusze dzielą ten sam szkielet: to, co je wyróżnia, to schemat i monit, a nie kod wywołania.

Kluczowe wnioski

  • Automatyczna klasyfikacja kieruje dokumenty do właściwego potoku przetwarzania
  • Ekstrakcja klauzul umownych identyfikuje ryzyka i kluczowe punkty
  • Weryfikacja zgodności automatyzuje audyty regulacyjne
  • Wzbogacenie adnotacjami poprawia jakość indeksowania RAG
  • Każdy przypadek użycia sprowadza się do dobrze zaprojektowanego schematu Pydantic i dostosowanego monitu