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

OCR API od Mistralu

Lekce 4 z 16 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Jediný vstupní bod
  2. Instalace a konfigurace
  3. Parametry volání
  4. Tři způsoby odeslání dokumentu
  5. Čtení odpovědi
  6. Limity a chyby
  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 spolehlivosti na úrovni bloků. Dodatek ze 3. listopadu 2026: Chcete-li odeslat místní soubor PDF, zakódujte jej do formátu base64 jako {"type": "document_url", "document_url": "data:application/pdf;base64,…"}. Typ document_base64 nalezený ve starších příkladech v dokumentaci ani v SDK mistralai neexistuje a tyto příklady by selhaly. Zdroje: OCR Processor · Document QnA.

Jediný vstupní bod

Veškerá extrakce dokumentů probíhá přes jediný koncový bod: /v1/ocr, nebo jeho ekvivalent v Python SDK, client.ocr.process(). Ať už zpracováváš fotografii účtenky, nebo výroční zprávu o 800 stranách, volání vypadá stejně. Tato lekce podrobně popisuje, jak ji nakonfigurovat, tři způsoby předání dokumentu a co přesně vrátí.

Instalace a konfigurace

Instalace zabere jediný příkaz:

pip install mistralai

Dále inicializuj klienta pomocí svého API klíče:

from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")

Tento přístup funguje pro rychlý test v notebooku, ale riskuješ, že klíč omylem odešleš do verze. Jakmile kód opustí tvůj počítač, použij proměnnou prostředí:

export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral

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

Ve všech následujících lekcích budeme používat právě tuto druhou formu.

Parametry volání

Volání client.ocr.process() vyžaduje pouze dva parametry: model, který vždy nastavíš na "mistral-ocr-latest", a document, který popisuje zpracovávaný soubor jedním ze tří níže uvedených způsobů.

Ostatní parametry upravují výstup podle tvých potřeb:

  • table_format: Formát tabulek (null, "markdown", "html")
  • include_image_base64: True pro přijímání obrázků v base64
  • bbox_annotation_format: Schéma anotací ohraničujících rámečků
  • document_annotation_format: Schéma anotací celého dokumentu
  • document_annotation_prompt: Pokyny vysoké úrovně pro anotaci

První dva se týkají vlastního OCR a budeš se jim věnovat v dalších lekcích. Poslední tři souvisejí s anotacemi, kterými se začneme zabývat od lekce 9; zatím si jen zapamatuj, že ti umožňují požadovat strukturovanou extrakci v rámci stejného volání, bez nutnosti druhého round-tripu.

Tři způsoby odeslání dokumentu

První, veřejná URL, je nejpřímější, když je soubor již dostupný online – například publikovaná zpráva nebo příloha uložená ve veřejném úložišti:

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://example.com/document.pdf"
    }
)

Druhý způsob je nezbytný pro dokumenty, které žijí na tvém stroji nebo v soukromém úložišti. Zakóduješ je do base64 a odešleš v těle požadavku. Toto je výchozí metoda pro cokoli důvěrného, protože není třeba vystavovat žádnou URL:

import base64

with open("my_document.pdf", "rb") as f:
    document_base64 = base64.b64encode(f.read()).decode("utf-8")

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": f"data:application/pdf;base64,{document_base64}"
    }
)

Třetí způsob využívá Files API. Soubor jednou nahraješ, získáš jeho ID a poté na něj v dalších voláních odkazuješ. Výhoda se projeví u velkých dokumentů nebo když musí být stejný soubor zpracován vícekrát – dnes extrakce OCR, zítra anotace s jiným schématem: nemusíš při každém pokusu znovu přenášet 40 MB.

# Nahrání souboru
uploaded_file = client.files.upload(
    file=open("my_document.pdf", "rb"),
    purpose="ocr"
)

# Použití nahraného souboru
ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "file_id",
        "file_id": uploaded_file.id
    }
)

Čtení odpovědi

Odpověď obsahuje seznam stránek a každá stránka nese svůj obsah spolu s metadaty. K ověření, že extrakce proběhla hladce, stačí jednoduchá smyčka:

for page in ocr_response.pages:
    print(f"Page {page.index}")
    print(f"Content: {page.markdown[:200]}...")
    print(f"Images: {len(page.images)} found")
    print(f"Header: {page.header}")
    print(f"Footer: {page.footer}")
    print(f"Dimensions: {page.dimensions}")

Zvykni si spouštět tento typ smyčky na vzorkovém dokumentu předtím, než něco industrializuješ: během tří sekund ti řekne, zda souhlasí počet stránek, zda byly detekovány obrázky a zda jsou záhlaví správně oddělena od hlavního textu.

Limity a chyby

Používání řídí tři omezení: maximálně 50 MB na soubor, 1 000 stránek na dokument a vstupní formáty PDF, PNG, JPEG, AVIF, PPTX a DOCX. K tomu přistupuje omezování rychlosti (rate limiting) s prahem závislým na úrovni tvého předplatného – to si ověř před masivní paralelizací, jinak riskuješ, že ti budou volání hromadně odmítána.

Tyto limity, stejně jako výpadky sítě, se projevují jako výjimky, které musíš zachytit. Dávková úloha, která se zastaví u faktury číslo 300, protože jeden soubor překračuje povolenou velikost, je zbytečnou ztrátou času, které se lze vyhnout:

from mistralai.client import Mistral
from mistralai.client.errors import SDKError

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

try:
    ocr_response = client.ocr.process(
        model="mistral-ocr-latest",
        document={
            "type": "document_url",
            "document_url": "https://example.com/document.pdf"
        }
    )
except SDKError as e:
    print(f"API Error: {e.status_code} - {e.message}")
except Exception as e:
    print(f"Unexpected error: {e}")

Rozlišení těchto dvou úrovní výjimek je užitečné: SDKError ti poskytne stavový kód, podle kterého se rozhodneš, zda opakovat pokus – kód 429 by se měl po prodlevě zopakovat, kód 400 nikdy – zatímco obecný blok zachytí lokální problémy, jako je chybějící soubor nebo nemožné kódování.

Klíčové poznatky

  • Koncový bod OCR je client.ocr.process() s modelem mistral-ocr-latest
  • Tři metody odeslání: veřejná URL, base64, nahraný soubor
  • Volitelné parametry řídí formát tabulek a zahrnutí obrázků
  • Odpověď je strukturována po stránkách s Markdownem, obrázky a metadaty
  • Respektuj limity 50 MB a 1 000 stránek na dokument