Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

OCR API od Mistralu

Lekcia 4 z 16 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Jediný vstupný bod
  2. Inštalácia a konfigurácia
  3. Parametre volania
  4. Tri spôsoby odoslania dokumentu
  5. Čítanie odpovede
  6. Limity a chyby
  7. Kľúčové poznatky

Aktualizované 2. novembra 2026 — OCR. Verzia OCR 4.0 (mistral-ocr-4-0) bola vyradená 30. septembra 2026. Používaj OCR 4.1 (mistral-ocr-4-1), ktorá je všeobecne dostupná od 31. augusta za rovnakú cenu, alebo alias mistral-ocr-latest, ktorý na ňu odkazuje od 16. júla. OCR 4.1 pridáva skóre spoľahlivosti na úrovni blokov. Dodatok z 3. novembra 2026: Ak chceš odoslať lokálny PDF súbor, zakóduj ho do formátu base64 ako {"type": "document_url", "document_url": "data:application/pdf;base64,…"}. Typ document_base64, ktorý sa nachádza v starších príkladoch, v dokumentácii ani v SDK mistralai neexistuje a tieto príklady by zlyhali. Zdroje: OCR Processor · Document QnA.

Jediný vstupný bod

Všetka extrakcia dokumentov prebieha cez jeden koncový bod: /v1/ocr, alebo jeho ekvivalent v Python SDK, client.ocr.process(). Či už spracovávaš fotografiu bločka alebo 800-stranovú výročnú správu, volanie je rovnaké. Táto lekcia podrobne popisuje, ako ho nakonfigurovať, tri spôsoby, ako mu odovzdať dokument, a čo vracia.

Inštalácia a konfigurácia

Inštalácia si vyžaduje jediný príkaz:

pip install mistralai

Ďalej inicializuj klienta pomocou svojho API kľúča:

from mistralai.client import Mistral

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

Tento prístup funguje pre rýchly test v notebooku, ale riskuješ náhodné commitnutie svojho kľúča. Hneď ako kód opustí tvoj stroj, použij premennú prostredia:

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

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

V všetkých nasledujúcich lekciách budeme používať túto druhú formu.

Parametre volania

Volanie client.ocr.process() vyžaduje iba dva parametre: model, vždy nastavený na "mistral-ocr-latest", a document, ktorý popisuje súbor na spracovanie v jednej z troch foriem podrobne uvedených nižšie.

Ďalšie parametre upravujú výstup podľa tvojich potrieb:

  • table_format: Formát tabuľky (null, "markdown", "html")
  • include_image_base64: True pre prijímanie obrázkov v base64
  • bbox_annotation_format: Schéma anotácií ohraničujúcich rámcov
  • document_annotation_format: Schéma anotácií celého dokumentu
  • document_annotation_prompt: Inštrukcie vysokej úrovne pre anotáciu

Prvé dva sa týkajú samotného OCR a budeš sa im venovať v ďalších lekciách. Posledné tri súvisia s anotáciami, ktorými sa začneme zaoberať od Lekcie 9; zatiaľ si len zapamätaj, že ti umožňujú požadovať štruktúrovanú extrakciu v rámci toho istého volania bez potreby druhého round-tripu.

Tri spôsoby odoslania dokumentu

Prvý spôsob, verejná URL adresa, je najpriamejší, keď je súbor už dostupný online – publikovaná správa, príloha uložená vo verejnom úložisku:

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

Druhý spôsob je nevyhnutný pre dokumenty, ktoré sa nachádzajú na tvojom stroji alebo v súkromnom úložisku. Zakóduješ ich do formátu base64 a odošleš v tele požiadavky. Toto je predvolená metóda pre čokoľvek dôverné, keďže nie je potrebné vystavovať žiadnu URL adresu:

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

Tretí spôsob využíva Files API. Súbor nahraješ raz, získaš jeho ID a následne naňho odkazuješ vo svojich volaniach. Výhoda sa prejaví pri veľkých dokumentoch alebo keď sa ten istý súbor musí spracovať viackrát – extrakcia OCR dnes, anotácia s inou schémou zajtra: pri každom pokuse nemusíš znovu prenášať 40 MB.

# Nahranie súboru
uploaded_file = client.files.upload(
    file=open("my_document.pdf", "rb"),
    purpose="ocr"
)

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

Čítanie odpovede

Odpoveď obsahuje zoznam stránok a každá stránka nesie svoj obsah spolu s metadátami. Na overenie, či extrakcia prebehla hladko, stačí jednoduchá sluč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 spúšťať tento typ slučky na vzorovom dokumente predtým, než niečo industrializuješ: do troch sekúnd ti povie, či súčet stránok sedí, či boli detegované obrázky a či sú hlavičky správne oddelené od hlavného textu.

Limity a chyby

Používanie riadia tri obmedzenia: maximálne 50 MB na súbor, 1 000 strán na dokument a vstupné formáty PDF, PNG, JPEG, AVIF, PPTX a DOCX. K tomu sa pridáva obmedzenie rýchlosti (rate limiting) s prahom, ktorý závisí od úrovne tvojho predplatného – tento bod si over pred masívnou paralelizáciou, inak riskuješ, že tvoje volania budú v návale odmietnuté.

Tieto limity, rovnako ako problémy so sieťou, sa prejavujú ako výnimky, ktoré musíš zachytávať. Dávková úloha, ktorá sa zastaví na faktúre číslo 300, pretože jeden súbor presahuje povolenú veľkosť, je zbytočnou stratou času, ktorej sa dá vyhnúť:

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šovanie medzi týmito dvoma úrovňami výnimiek je užitočné: SDKError ti poskytne stavový kód, na základe ktorého sa rozhodneš, či skúsiť znova – pri 429 by si mal počkať a skúsiť to znova, pri 400 nikdy – zatiaľ čo všeobecný blok zachytáva lokálne problémy, ako je chýbajúci súbor alebo nemožné kódovanie.

Kľúčové poznatky

  • Koncový bod OCR je client.ocr.process() s modelom mistral-ocr-latest
  • Tri spôsoby odoslania: verejná URL, base64, nahraný súbor
  • Voliteľné parametre riadia formát tabuliek a zahrnutie obrázkov
  • Odpoveď je štruktúrovaná po stránkach s Markdownom, obrázkami a metadátami
  • Rešpektuj limity 50 MB a 1 000 strán na dokument