Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

API pro anotace

Lekce 9 z 16 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Víc než jen extrakce textu
  2. Dvě úrovně analýzy
  3. Schéma Pydantic jako smlouva
  4. Anotování celého dokumentu
  5. Popis vizuálů jeden po druhém
  6. Řízení extrakce pomocí promptu
  7. Klíčové poznatky

Aktualizováno 2. listopadu 2026 — OCR. Verze OCR 4.0 (mistral-ocr-4-0) byla 30. září 2026 vyřazena z provozu. Používej OCR 4.1 (mistral-ocr-4-1), které je obecně dostupné od 31. srpna za stejnou cenu, nebo alias mistral-ocr-latest, který na něj odkazuje od 16. července. OCR 4.1 přidává skóre důvěryhodnosti na úrovni bloků. Dodatek ze 3. listopadu: Předchozí příklad četl page.document_annotation na každé stránce; v SDK mistralai verze 3.7.0 patří toto pole odpovědi OCR (ocr_response.document_annotation), zatímco stránky obsahují pouze svůj obsah a obrázky; anotace obrázků se čtou z image.image_annotation.

Víc než jen extrakce textu

OCR ti dodá surový text: věrný a úplný, ale nediferencovaný. Získáš Markdown, nikoliv data. Anotace dělají další krok: extrahují strukturovaná data z tvých dokumentů na základě schématu, které předem definuješ. Popíšeš, co hledáš, model to automaticky extrahuje a tvoje aplikace obdrží typovaná pole místo zdi textu, kterou bys musel parsovat pomocí regulárních výrazů.

Dvě úrovně analýzy

Document AI rozlišuje dva typy anotací podle měřítka, ve kterém pracují.

Anotace ohraničujících rámečků (bbox_annotation) se zaměřují na obrázky a grafiku, které OCR izolovalo. Vizionářský model zpracovává každý ohraničující rámeček jednotlivě a popisuje jeho obsah. Ve výroční zprávě ti tento mechanismus umožní popsat grafy a diagramy, klasifikovat obrázky (fotografie, logo, schéma, graf) a extrahovat textový obsah z vložených obrázků – tři informace, které standardní extrakce textu systematicky přehlíží.

Anotace dokumentu (document_annotation) zacházejí se souborem jako s celkem. Model analyzuje extrahovaný Markdown spolu s prvními osmi obrázky a vrátí to, co jsi požadoval: strukturovaná pole, jako je jméno, datum nebo částka; typ dokumentu; shrnutí obsahu; nebo odpověď na konkrétní otázku. Toto je nástroj pro hromadné zpracování, ten, který zapojíš do svých pracovních postupů pro faktury, formuláře a smlouvy.

Schéma Pydantic jako smlouva

Anotace spoléhají na modely Pydantic pro definici výstupní struktury. Každý atribut se stane polem k extrakci a jeho description slouží jako instrukce pro model: nese stejnou váhu jako samotný název pole.

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)")

Anotování celého dokumentu

Volání zůstává stejné jako u OCR: jednoduše přidáš parametr document_annotation_format, který vyplníš pomocí response_format_from_pydantic_model(). Tato funkce převede tvůj model na schéma, které API dokáže použít. Při návratu dorazí anotace jako řetězec JSON, který znovu validuješ pomocí Pydantic, abys získal bezpečný 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
    )
)

# Anotace dokumentu je součástí odpovědi, nikoliv každé stránky
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}")

Popis vizuálů jeden po druhém

U obrázků je princip totožný, ale parametr se mění a výsledky se čtou z page.images místo ze samotné stránky. Všimni si include_image_base64=True: bez toho ztratíš vizuály, které model právě popsal.

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
)

# Přístup k anotacím obrázků
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 tě nenutí vybírat si pouze jeden z těchto přístupů: u ilustrované zpravy budeš obvykle chtít jak metadata dokumentu, tak popis jeho grafů, což pokryje jediné volání předáním obou formátů.

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
)

Řízení extrakce pomocí promptu

Schéma popisuje očekávaný tvar, nikoliv kontext dokumentu. Když jsou tvá pole nejednoznačná – více dat, více částek, dvě podobné sekce – document_annotation_prompt pomáhá rozřešit pochybnosti tím, že modelu sdělí povahu dokumentu a co má upřednostnit. U francouzské obchodní smlouvy často tato rámcující věta rozhoduje mezi použitelnou extrakcí a přibližným vyplněním.

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."
    )
)

Klíčové poznatky

  • Dva typy anotací: bbox_annotation pro obrázky, document_annotation pro celý dokument
  • Schémata Pydantic definují strukturu dat k extrakci
  • Použij response_format_from_pydantic_model() pro převod schématu
  • document_annotation_prompt řídí extrakci pomocí kontextových instrukcí
  • Oba typy lze kombinovat v jediném volání